Skip to content

Commit d960717

Browse files
AMeceaAMecea
committed
Add basic documentation for the operator
1 parent 9bd1527 commit d960717

File tree

11 files changed

+978
-226
lines changed

11 files changed

+978
-226
lines changed

‎README.md‎

Lines changed: 33 additions & 224 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
1-
__NOTE__: MySQL Operator 0.2.x requires at least Kubernetes 1.11.x (or 1.10.x with alpha features) while version 0.1.x is known to work with Kubernetes up 1.9.x. For upgrading check the [0.2.x upgrade notes](#v02x-upgrade) since some manual seps are required.
2-
31
# MySQL Operator
42

5-
MySQL Operator enables bulletproof MySQL on Kubernetes. It manages all the necessary resources for deploying and managing a highly available MySQL cluster. It provides efortless backups, while keeping the cluster highly-available.
3+
MySQL Operator enables bulletproof MySQL on Kubernetes. It manages all the necessary resources for
4+
deploying and managing a highly available MySQL cluster. It provides efortless backups, while
5+
keeping the cluster highly-available.
66

7-
MySQL Operator was developed by the awesome engineering team at [Presslabs](https://www.presslabs.com/),
8-
a Managed WordPress Hosting provider.
7+
MySQL Operator was developed by the awesome engineering team at
8+
[Presslabs](https://www.presslabs.com/), a Managed WordPress Hosting provider.
99

10-
For more open-source projects, check [Presslabs Code](https://www.presslabs.org/).
10+
For more open-source projects, check [Presslabs Code](https://www.presslabs.com/code/).
1111

1212
## Goals and status
1313

@@ -18,251 +18,60 @@ The main goals of this operator are:
1818
3. Out-of-the-box backups (scheduled and on demand) and point-in-time recovery
1919
4. Support for cloning in cluster and across clusters
2020

21-
The operator is to be considered alpha and not suited for critical production workloads. We (Presslabs) sucessfully use it at the moment for some non-critical production workloads.
21+
The operator is to be considered alpha and not suited for critical production workloads. We
22+
(Presslabs) sucessfully use it at the moment for some non-critical production workloads.
2223

2324
## Contributing
2425

25-
We welcome all contributions in the form of new issues for feature requests, bugs or directly pull requests.
26-
We are open to discuss ideas to improve the operator and would also love to find out where and how it is used.
27-
The discussion related to the project should happen on [Gitter](https://gitter.im/PressLabs/mysql-operator).
28-
The current developers of the project can be reached via [email](mailto:[email protected]) too.
26+
We welcome all contributions in the form of new issues for feature requests, bugs or directly pull
27+
requests. We are open to discuss ideas to improve the operator and would also love to find out where
28+
and how it is used. The discussion related to the project should happen on Kubernetes Community
29+
[Slack](https://kubernetes.slack.com/messages/CEKQXFR0E/). The current developers of the project can
30+
be reached via [email](mailto:[email protected]) too.
2931

30-
## Controller deploy
32+
## Documentation
3133

32-
Install helm. New to helm? Check https://github.com/helm/helm#install
34+
More documentation can be found in [docs](docs/README.md)
3335

34-
Install kubectl. For more details, see: https://kubernetes.io/docs/tasks/tools/install-kubectl/
36+
## Controller deploy
3537

3638
To deploy this controller, use the provided helm chart, by running:
39+
3740
```shell
3841
helm repo add presslabs https://presslabs.github.io/charts
3942
helm install presslabs/mysql-operator --name mysql-operator
4043
```
4144

4245
For more information about chart values see chart [README](hack/charts/mysql-operator/README.md).
43-
This chart will deploy the controller along with an [orchestrator](https://github.com/github/orchestrator) cluster.
46+
This chart will deploy the controller along with an
47+
[orchestrator](https://github.com/github/orchestrator) cluster.
48+
49+
__NOTE__: MySQL Operator 0.2.x requires at least Kubernetes 1.11.x (or 1.10.x with alpha features)
50+
while version 0.1.x is known to work with Kubernetes up 1.9.x. For upgrading check the [0.2.x
51+
upgrade notes](#v02x-upgrade) since some manual seps are required.
4452

45-
### v0.2.x upgrade
53+
## Controller upgrade
4654

47-
1. Scale to 0 the current operator deployment. This won't affect your running databases.
48-
2. Upgrade your cluster control plane to 1.11
49-
3. Update the installed CRDs: `kubectl apply -f https://raw.githubusercontent.com/presslabs/mysql-operator/master/hack/02x-crds.yaml`
50-
4. Upgrade the mysql-operator `helm upgrade mysql-operator presslabs/mysql-operator`
51-
5. Scale the operator deployment up
52-
6. Now you can upgrade you nodes as well.
53-
7. Enjoy!
55+
Maybe upgrading the MySQL operator to a newer version requires additional steps that has to be done.
56+
Those steps can be found in the operator documentation at [upgrades](docs/operator-upgrades.md)
57+
section.
5458

5559
## Deploying a cluster
56-
__tl;dr__
5760

5861

5962
```shell
6063
kubectl apply -f https://raw.githubusercontent.com/presslabs/mysql-operator/master/examples/example-cluster-secret.yaml
6164
kubectl apply -f https://raw.githubusercontent.com/presslabs/mysql-operator/master/examples/example-cluster.yaml
6265
```
6366

64-
#### More details:
65-
66-
Before creating a cluster, you need a secret that contains the ROOT_PASSWORD key.
67-
An example for this secret can be found at [examples/example-cluster-secret.yaml](examples/example-cluster-secret.yaml).
68-
69-
Create a file named `example-cluster-secret.yaml` and copy into it the following YAML code:
70-
71-
```yaml
72-
apiVersion: v1
73-
kind: Secret
74-
metadata:
75-
name: my-secret
76-
type: Opaque
77-
data:
78-
# root password is required to be specified
79-
ROOT_PASSWORD: bm90LXNvLXNlY3VyZQ==
80-
```
81-
#### Note.
82-
`ROOT_PASSWORD` must be base64 encoded.
83-
84-
Now, to create a cluster you need just a simple YAML file that defines it.
85-
An example can be found at [examples/example-cluster.yaml](examples/example-cluster.yaml).
86-
87-
Create a file named `example-cluster.yaml` and copy into it the following YAML code:
88-
89-
```yaml
90-
apiVersion: mysql.presslabs.org/v1alpha1
91-
kind: MysqlCluster
92-
metadata:
93-
name: my-cluster
94-
spec:
95-
replicas: 2
96-
secretName: my-secret
97-
```
98-
99-
To deploy the cluster, run:
100-
101-
```shell
102-
kubectl apply -f example-cluster-secret.yaml
103-
kubectl apply -f example-cluster.yaml
104-
```
105-
106-
For a more in depth configuration, check [examples](examples/).
107-
108-
### To list the deployed clusters use
109-
```shell
110-
$ kubectl get mysql
111-
NAME AGE
112-
my-cluster 1m
113-
```
114-
115-
### To check cluster state use
116-
```shell
117-
$ kubectl describe mysql my-cluster
118-
...
119-
Status:
120-
Ready Nodes: 2
121-
Conditions:
122-
Last Transition Time: 2018-03-28T10:20:23Z
123-
Message: Cluster is ready.
124-
Reason: statefulset ready
125-
Status: True
126-
Type: Ready
127-
...
128-
```
129-
130-
## Backups
131-
132-
Backups are stored on object storage services like S3 or google cloud storage.
133-
In order to be able to store backup, the secret defined under `backupBucketSecretName` must the credentials to store those backups.
134-
The backups are uploaded using [Rclone](https://rclone.org/).
135-
The contents of the secret are used to generate an rclone.conf in [hack/docker/mysql-helper/docker-entrypoint.sh](hack/docker/mysql-helper/docker-entrypoint.sh).
136-
137-
### Setup backup to S3
138-
139-
You need to specify the `backupBucketUri` for the cluster to an uri like `s3://BUCKET_NAME`, and a secret.
140-
141-
```yaml
142-
apiVersion: v1
143-
kind: Secret
144-
metadata:
145-
name: my-cluster-backup-secret
146-
type: Opaque
147-
data:
148-
AWS_ACCESS_KEY_ID: #
149-
AWS_SECRET_KEY: #
150-
# Optional, the AWS region to connect
151-
# AWS_REGION: us-east1
152-
# Optional, specify the storage class
153-
# AWS_STORAGE_CLASS: standard
154-
# Optional, canned ACL to use
155-
# AWS_ACL:
156-
# Optional, the S3 provider to use (default: AWS)
157-
# S3_PROVIDER: AWS
158-
# Optional, the S3 endpoint to use (for when you use a different S3_PROVIDER)
159-
# S3_ENDPOINT:
160-
```
161-
162-
Then run this command:
163-
164-
```yaml
165-
apiVersion: v1
166-
kind: Secret
167-
metadata:
168-
name: my-cluster-backup-secret
169-
type: Opaque
170-
data:
171-
GCS_SERVICE_ACCOUNT_JSON_KEY: #
172-
GCS_PROJECT_ID: #
173-
```
174-
175-
Then run this command:
176-
177-
```shell
178-
kubectl apply -f example-backup-secret.yaml
179-
```
180-
181-
#### Note
182-
`GCS_SERVICE_ACCOUNT_JSON_KEY` and `GCS_PROJECT_ID` must be base64 encoded.
183-
184-
### Requesting a backup
185-
186-
You need to create a file named `example-backup.yaml` and copy into it the following YAML code:
187-
188-
```yaml
189-
apiVersion: mysql.presslabs.org/v1alpha1
190-
kind: MysqlBackup
191-
metadata:
192-
name: my-cluster-backup
193-
spec:
194-
clusterName: my-cluster
195-
```
196-
197-
Run the following command:
198-
199-
```shell
200-
kubectl apply -f example-backup.yaml
201-
```
202-
203-
You need to specify the `backupBucketUri` for the corresponding cluster to an URI like `gs://BUCKET_NAME` and `backupSecretName`.
204-
Open the file named `example-cluster.yaml` and copy into it the following YAML code:
205-
206-
```yaml
207-
apiVersion: mysql.presslabs.org/v1alpha1
208-
kind: MysqlCluster
209-
metadata:
210-
name: my-cluster
211-
spec:
212-
replicas: 2
213-
secretName: my-secret
214-
backupSecretName: my-cluster-backup-secret
215-
backupUri: gs://pl-test-mysql-operator/
216-
```
217-
218-
Then run the following command:
219-
220-
```shell
221-
kubectl apply -f example-cluster.yaml
222-
```
223-
224-
### Listing all backups
225-
```shell
226-
$ kubectl get mysqlbackup
227-
NAME AGE
228-
my-cluster-backup 1m
229-
my-cluster-auto-backup-20180402-1604 1d
230-
```
231-
232-
### Checking the backup state
233-
```shell
234-
$ kubectl describe backup my-cluster-backup
235-
...
236-
Status:
237-
Completed: true
238-
Conditions:
239-
Last Transition Time: 2018-03-21T16:02:56Z
240-
Message:
241-
Reason:
242-
Status: True
243-
Type: Complete
244-
...
245-
```
246-
247-
## Access orchestrator
248-
To connect to orchestrator dashboard you have to port forward orchestrator port
249-
3000 to your local machine. Ensure it's a healthy pod if using raft:
250-
251-
```shell
252-
kubectl port-forward mysql-operator-orchestrator-0 3000
253-
```
254-
255-
Then type `localhost:3000` in a browser.
256-
25767
## Tech considerations
25868

259-
This project uses Percona Server for MySQL 5.7 because of backup improvements
260-
(eg. backup locks), monitoring improvements and some serviceability improvements
261-
(eg. utility user). Although we could have used MariaDB, our primary focus being WordPress,
262-
we wanted a drop-in rather than a fork. In the future we might support MariaDB if that can
263-
be implemented in a compatible way.
69+
This project uses Percona Server for MySQL 5.7 because of backup improvements (eg. backup locks),
70+
monitoring improvements and some serviceability improvements (eg. utility user). Although we could
71+
have used MariaDB, our primary focus being WordPress, we wanted a drop-in rather than a fork. In the
72+
future we might support MariaDB if that can be implemented in a compatible way.
26473

26574
## License
26675

267-
This project is licensed under Apache 2.0 license. Read the [LICENSE](LICENSE) file in the
268-
top distribution directory, for the full license text.
76+
This project is licensed under Apache 2.0 license. Read the [LICENSE](LICENSE) file in the top
77+
distribution directory, for the full license text.

‎docs/README.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Documentation
2+
3+
MySQL Operator documentation.
4+
5+
## Table of content
6+
7+
* [Getting started](getting-started.md), provides an overview over deploying and using MySQL
8+
Operator
9+
* [Deploy a MySQL cluster](deploy-mysql-cluster.md), describes in detail how a cluster can be
10+
installed and configured.
11+
* [Configure backups](backups.md), this section shows how to configure and take backups of a
12+
cluster.
13+
* [Recurrent backups](cluster-recurrent-backups.md), it describe how to setup recurrent backups for
14+
the cluster.
15+
* [Restore a cluster](cluster-recover.md), it describes how to restore a cluster from a backup.
16+
* [How to integrate](integrate-operator.md) the operator with your deployment setup. This presents
17+
a simple way of using MySQL Operator and helm to deploy your application.
18+
* [Orchestrator](orchestrator.md), describes how to access orchestrator for more details.

0 commit comments

Comments
 (0)