diff --git a/.github/workflows/mdbook.yaml b/.github/workflows/mdbook.yaml new file mode 100644 index 000000000..d2d4f18e8 --- /dev/null +++ b/.github/workflows/mdbook.yaml @@ -0,0 +1,41 @@ +name: CI +on: + pull_request: + push: + branches: + - 'main' +jobs: + build: + name: Build book + runs-on: ubuntu-20.04 + steps: + - uses: actions/checkout@v2 + - run: make book + - uses: actions/upload-artifact@v2 + with: + name: book + path: docs/book + retention-days: 1 + publish: + name: Publish book on GitHub Pages + runs-on: ubuntu-20.04 + needs: build + steps: + - uses: actions/checkout@v2 + with: + ref: gh-pages + - run: rm -rf * + - uses: actions/download-artifact@v2 + with: + name: book + - run: ls -R + - run: git add . + - run: git status -sb + - name: Commit changes + run: | + git config --global user.name 'Cybozu Neco' + git config --global user.email 'cybozu-neco@users.noreply.github.com' + git commit -m 'update' + - name: Push to gh-pages + if: github.ref == 'refs/heads/main' + run: git push origin gh-pages diff --git a/Makefile b/Makefile index c76b38a43..96434af5e 100644 --- a/Makefile +++ b/Makefile @@ -4,6 +4,7 @@ CTRL_RUNTIME_VERSION := $(shell awk '/sigs.k8s.io\/controller-runtime/ {print su KUSTOMIZE_VERSION = 4.1.3 CRD_TO_MARKDOWN_VERSION = 0.0.3 MYSQLSH_VERSION = 8.0.25-1 +MDBOOK_VERSION = 0.4.8 OS_VERSION := $(shell . /etc/os-release; echo $$VERSION_ID) # Test tools @@ -61,6 +62,11 @@ apidoc: crd-to-markdown $(wildcard api/*/*_types.go) $(CRD_TO_MARKDOWN) --links docs/links.csv -f api/v1beta1/mysqlcluster_types.go -f api/v1beta1/job_types.go -n MySQLCluster > docs/crd_mysqlcluster.md $(CRD_TO_MARKDOWN) --links docs/links.csv -f api/v1beta1/backuppolicy_types.go -f api/v1beta1/job_types.go -n BackupPolicy > docs/crd_backuppolicy.md +.PHONY: book +book: mdbook + rm -rf docs/book + cd docs; $(MDBOOK) build + .PHONY: check-generate check-generate: $(MAKE) manifests generate apidoc @@ -150,9 +156,16 @@ $(KUSTOMIZE): tar -C bin -xzf - CRD_TO_MARKDOWN := $(shell pwd)/bin/crd-to-markdown +.PHONY: crd-to-markdown crd-to-markdown: ## Download crd-to-markdown locally if necessary. $(call go-get-tool,$(CRD_TO_MARKDOWN),github.com/clamoriniere/crd-to-markdown@v$(CRD_TO_MARKDOWN_VERSION)) +MDBOOK := $(shell pwd)/bin/mdbook +.PHONY: mdbook +mdbook: ## Donwload mdbook locally if necessary + mkdir -p bin + curl -fsL https://github.com/rust-lang/mdBook/releases/download/v$(MDBOOK_VERSION)/mdbook-v$(MDBOOK_VERSION)-x86_64-unknown-linux-gnu.tar.gz | tar -C bin -xzf - + # go-get-tool will 'go get' any package $2 and install it to $1. PROJECT_DIR := $(shell dirname $(abspath $(lastword $(MAKEFILE_LIST)))) define go-get-tool diff --git a/README.md b/README.md index d27a6a820..01fbe42af 100644 --- a/README.md +++ b/README.md @@ -106,11 +106,9 @@ $ make stop ## Documentation -- [`docs/setup.md`](docs/setup.md) for installing MOCO. -- [`docs/usage.md`](docs/usage.md) is the user manual of MOCO. -- [`examples`](examples/) directory contains example MySQLCluster manifests. +See https://cybozu-go.github.io/moco/ -[`docs`](docs/) directory also contains other design or specification documents. +[`examples`](examples/) directory contains example MySQLCluster manifests. ## Docker images diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 000000000..5a0bf0317 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +/book diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..a04db30ff --- /dev/null +++ b/docs/README.md @@ -0,0 +1,4 @@ +# MOCO documentation + +This is the documentation site for [MOCO](https://github.com/cybozu-go/moco). +MOCO is a Kubernetes operator for MySQL created and maintained by Cybozu. diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 000000000..3ad054107 --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,34 @@ +# Summary + +[MOCO](README.md) + +# User manual + +- [Getting started](getting_started.md) + - [Deploying MOCO](setup.md) + - [Installing kubectl-moco](install-plugin.md) +- [Usage](usage.md) +- [Advanced topics](advanced.md) + - [Building your own imge](custom-mysqld.md) +- [Troubleshooting](troubles.md) + +# References + +- [Custom resources](crd.md) + - [MySQLCluster](crd_mysqlcluster.md) + - [BackupPolicy](crd_backuppolicy.md) +- [Commands](commands.md) + - [kubectl-moco](kubectl-moco.md) + - [moco-controller](moco-controller.md) + - [moco-backup](moco-backup.md) +- [Metrics](metrics.md) + +# Developer documents + +- [Design notes](notes.md) + - [Goals](design.md) + - [Reconciliation](reconcile.md) + - [Clustering](clustering.md) + - [Backup and restore](backup.md) + - [Upgrading mysqld](upgrading.md) + - [Security](security.md) diff --git a/docs/advanced.md b/docs/advanced.md new file mode 100644 index 000000000..5d0c11672 --- /dev/null +++ b/docs/advanced.md @@ -0,0 +1 @@ +# Advanced topics diff --git a/docs/book.toml b/docs/book.toml new file mode 100644 index 000000000..0f45a339c --- /dev/null +++ b/docs/book.toml @@ -0,0 +1,10 @@ +[book] +language = "en" +multilingual = false +src = "." +title = "MOCO Documentation" + +[output.html] +git-repository-url = "https://github.com/cybozu-go/moco" +edit-url-template = "https://github.com/cybozu-go/moco/edit/main/docs/{path}" +site-url = "/moco/" diff --git a/docs/commands.md b/docs/commands.md new file mode 100644 index 000000000..61c515e7b --- /dev/null +++ b/docs/commands.md @@ -0,0 +1 @@ +# Commands diff --git a/docs/crd.md b/docs/crd.md new file mode 100644 index 000000000..045c9d29d --- /dev/null +++ b/docs/crd.md @@ -0,0 +1 @@ +# Custom resources diff --git a/docs/crd_backuppolicy.md b/docs/crd_backuppolicy.md index 43261ab75..58b65743e 100644 --- a/docs/crd_backuppolicy.md +++ b/docs/crd_backuppolicy.md @@ -68,7 +68,7 @@ JobConfig is a set of parameters for backup and restore job Pods. | ----- | ----------- | ------ | -------- | | serviceAccountName | ServiceAccountName specifies the ServiceAccount to run the Pod. | string | true | | bucketConfig | Specifies how to access an object storage bucket. | [BucketConfig](#bucketconfig) | true | -| workVolume | WorkVolume is the volume source for the working directory. Since the backup or restore task can use a lot of bytes in the working directory, You should always give a volume with enough capacity.\n\nThe recommended volume source is a generic ephemeral volume. https://kubernetes.io/docs/concepts/storage/ephemeral-volumes/#generic-ephemeral-volumes | corev1.VolumeSource | true | +| workVolume | WorkVolume is the volume source for the working directory. Since the backup or restore task can use a lot of bytes in the working directory, You should always give a volume with enough capacity.\n\nThe recommended volume source is a generic ephemeral volume. https://kubernetes.io/docs/concepts/storage/ephemeral-volumes/#generic-ephemeral-volumes | [corev1.VolumeSource](https://pkg.go.dev/k8s.io/api/core/v1#VolumeSource) | true | | threads | Threads is the number of threads used for backup or restoration. | int | false | | memory | Memory is the amount of memory requested for the Pod. | *[resource.Quantity](https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#Quantity) | false | | maxMemory | MaxMemory is the amount of maximum memory for the Pod. | *[resource.Quantity](https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#Quantity) | false | diff --git a/docs/crd_mysqlcluster.md b/docs/crd_mysqlcluster.md index 8ceb018cf..6e92e8699 100644 --- a/docs/crd_mysqlcluster.md +++ b/docs/crd_mysqlcluster.md @@ -26,7 +26,7 @@ BackupStatus represents the status of the last successful backup. | Field | Description | Scheme | Required | | ----- | ----------- | ------ | -------- | | time | The time of the backup. This is used to generate object keys of backup files in a bucket. | [metav1.Time](https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Time) | true | -| elapsed | Elapsed is the time spent on the backup. | metav1.Duration | true | +| elapsed | Elapsed is the time spent on the backup. | [metav1.Duration](https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration) | true | | sourceIndex | SourceIndex is the ordinal of the backup source instance. | int | true | | sourceUUID | SourceUUID is the `server_uuid` of the backup source instance. | string | true | | binlogFilename | BinlogFilename is the binlog filename that the backup source instance was writing to at the backup. | string | true | @@ -205,7 +205,7 @@ JobConfig is a set of parameters for backup and restore job Pods. | ----- | ----------- | ------ | -------- | | serviceAccountName | ServiceAccountName specifies the ServiceAccount to run the Pod. | string | true | | bucketConfig | Specifies how to access an object storage bucket. | [BucketConfig](#bucketconfig) | true | -| workVolume | WorkVolume is the volume source for the working directory. Since the backup or restore task can use a lot of bytes in the working directory, You should always give a volume with enough capacity.\n\nThe recommended volume source is a generic ephemeral volume. https://kubernetes.io/docs/concepts/storage/ephemeral-volumes/#generic-ephemeral-volumes | corev1.VolumeSource | true | +| workVolume | WorkVolume is the volume source for the working directory. Since the backup or restore task can use a lot of bytes in the working directory, You should always give a volume with enough capacity.\n\nThe recommended volume source is a generic ephemeral volume. https://kubernetes.io/docs/concepts/storage/ephemeral-volumes/#generic-ephemeral-volumes | [corev1.VolumeSource](https://pkg.go.dev/k8s.io/api/core/v1#VolumeSource) | true | | threads | Threads is the number of threads used for backup or restoration. | int | false | | memory | Memory is the amount of memory requested for the Pod. | *[resource.Quantity](https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#Quantity) | false | | maxMemory | MaxMemory is the amount of maximum memory for the Pod. | *[resource.Quantity](https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#Quantity) | false | diff --git a/docs/getting_started.md b/docs/getting_started.md new file mode 100644 index 000000000..69a5d543e --- /dev/null +++ b/docs/getting_started.md @@ -0,0 +1 @@ +# Getting started diff --git a/docs/install-plugin.md b/docs/install-plugin.md new file mode 100644 index 000000000..e585ac56c --- /dev/null +++ b/docs/install-plugin.md @@ -0,0 +1,30 @@ +# Installing kubectl-moco + +[kubectl-moco](kubectl-moco.md) is a plugin for `kubectl` to control MySQL clusters of MOCO. + +Pre-built binaries are available on [GitHub releases](https://github.com/cybozu-go/moco/releases) for Windows, Linux, and MacOS. + +Download one of the binaries for your OS and place it in a directory of `PATH`. + +```console +$ curl -fsL -o /path/to/bin/kubectl-moco https://github.com/cybozu-go/moco/releases/latest/download/kubectl-moco-linux-amd64 +$ chmod a+x /path/to/bin/kubectl-moco +``` + +Check the installation by running `kubectl moco -h`. + +```console +$ kubectl moco -h +the utility command for MOCO. + +Usage: + kubectl-moco [command] + +Available Commands: + credential Fetch the credential of a specified user + help Help about any command + mysql Run mysql command in a specified MySQL instance + switchover Switch the primary instance + +... +``` diff --git a/docs/links.csv b/docs/links.csv index d48142837..e2bc8125b 100644 --- a/docs/links.csv +++ b/docs/links.csv @@ -1,12 +1,14 @@ -metav1.ObjectMeta,https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#ObjectMeta -MySQLClusterConditionType,https://pkg.go.dev/github.com/cybozu-go/moco/api/v1beta1#MySQLClusterConditionType +batchv1beta1.ConcurrencyPolicy,https://pkg.go.dev/k8s.io/api/batch/v1beta1#ConcurrencyPolicy corev1.ConditionStatus,https://pkg.go.dev/k8s.io/api/core/v1#ConditionStatus -metav1.Time,https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Time -metav1.ListMeta,https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#ListMeta +corev1.EnvFromSource,https://pkg.go.dev/k8s.io/api/core/v1#EnvFromSource +corev1.EnvVar,https://pkg.go.dev/k8s.io/api/core/v1#EnvVar corev1.PersistentVolumeClaimSpec,https://pkg.go.dev/k8s.io/api/core/v1#PersistentVolumeClaimSpec corev1.PodSpec,https://pkg.go.dev/k8s.io/api/core/v1#PodSpec corev1.ServiceSpec,https://pkg.go.dev/k8s.io/api/core/v1#ServiceSpec -batchv1beta1.ConcurrencyPolicy,https://pkg.go.dev/k8s.io/api/batch/v1beta1#ConcurrencyPolicy +corev1.VolumeSource,https://pkg.go.dev/k8s.io/api/core/v1#VolumeSource +metav1.Duration,https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration +metav1.ListMeta,https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#ListMeta +metav1.ObjectMeta,https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#ObjectMeta +metav1.Time,https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Time +MySQLClusterConditionType,https://pkg.go.dev/github.com/cybozu-go/moco/api/v1beta1#MySQLClusterConditionType resource.Quantity,https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#Quantity -corev1.EnvFromSource,https://pkg.go.dev/k8s.io/api/core/v1#EnvFromSource -corev1.EnvVar,https://pkg.go.dev/k8s.io/api/core/v1#EnvVar diff --git a/docs/moco-backup.md b/docs/moco-backup.md index 39a6aa78c..6e5315110 100644 --- a/docs/moco-backup.md +++ b/docs/moco-backup.md @@ -1,6 +1,6 @@ # `moco-backup` -`moco-backup` command is used in `github.com/cybozu-go/moco-backup` container. +`moco-backup` command is used in `ghcr.io/cybozu-go/moco-backup` container. Normally, users need not take care of this command. ## Environment variables diff --git a/docs/moco-controller.md b/docs/moco-controller.md index 319fcacb5..021c491dc 100644 --- a/docs/moco-controller.md +++ b/docs/moco-controller.md @@ -1,6 +1,7 @@ `moco-controller` ================ +`moco-controller` controls MySQL clusters on Kubernetes. ## Environment variables | Name | Required | Description | diff --git a/docs/notes.md b/docs/notes.md new file mode 100644 index 000000000..2ebcf2706 --- /dev/null +++ b/docs/notes.md @@ -0,0 +1 @@ +# Design notes