Merge pull request #254 from cybozu-go/mdbook

Build documents as a book using mdBook

.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 '[email protected]'
+ git commit -m 'update'
+ - name: Push to gh-pages
+ if: github.ref == 'refs/heads/main'
+ run: git push origin gh-pages

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

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
 

docs/.gitignore

@@ -0,0 +1 @@
+/book

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.

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)

docs/advanced.md

@@ -0,0 +1 @@
+# Advanced topics

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/"

docs/commands.md

@@ -0,0 +1 @@
+# Commands

docs/crd.md

@@ -0,0 +1 @@
+# Custom resources

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 |

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 |

docs/getting_started.md

@@ -0,0 +1 @@
+# Getting started

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
+
+...
+```

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

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

docs/moco-controller.md

@@ -1,6 +1,7 @@
 `moco-controller`
 ================
 
+`moco-controller` controls MySQL clusters on Kubernetes.
 ## Environment variables
 
 | Name | Required | Description |

docs/notes.md

@@ -0,0 +1 @@
+# Design notes