Skip to content

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@AMecea
Mile Rosu authored and AMecea committed Jan 29, 2019
1 parent 4d7c9bb commit 64fce07
Show file tree
Hide file tree
Showing 10 changed files with 109 additions and 185 deletions.
42 changes: 12 additions & 30 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,60 +1,46 @@
# MySQL Operator

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

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

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

## Goals and status

The main goals of this operator are:

1. Easily deploy mysql clusters in kubernetes (cluster-per-service model)
1. Easily deploy MySQL clusters in Kubernetes (cluster-per-service model)
2. Friendly to devops (monitoring, availability, scalability and backup stories solved)
3. Out-of-the-box backups (scheduled and on demand) and point-in-time recovery
4. Support for cloning in cluster and across clusters
4. Support for cloning in cluster and across clusters.

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.
The operator is to be considered alpha and not suitable for critical production workloads. We, Presslabs, sucessfully use it at the moment for some non-critical production workloads.

## Contributing

We welcome all contributions in the form of new issues for feature requests, bugs or directly pull
requests. We are open to discuss ideas to improve the operator and would also love to find out where
and how it is used. The discussion related to the project should happen on Kubernetes Community
[Slack](https://kubernetes.slack.com/messages/CEKQXFR0E/). The current developers of the project can
be reached via [email](mailto:ping@presslabs.com) too.
We welcome all contributions in the form of new issues for feature requests, bugs or even pull requests. We are open to discuss ideas on how to improve the operator and would also love to find out where and how it's used. The discussion related to this project should happen on the Kubernetes Community [Slack](https://kubernetes.slack.com/messages/CEKQXFR0E/). The current maintainers of this project can be reached via [email](mailto:ping@presslabs.com), too.

## Documentation

More documentation can be found in [docs](docs/README.md)

## Controller deploy

To deploy this controller, use the provided helm chart, by running:
To deploy this controller, use the provided helm chart by running:

```shell
helm repo add presslabs https://presslabs.github.io/charts
helm install presslabs/mysql-operator --name mysql-operator
```

For more information about chart values see chart [README](hack/charts/mysql-operator/README.md).
This chart will deploy the controller along with an
[orchestrator](https://github.com/github/orchestrator) cluster.
For more information about chart values see chart [README](hack/charts/mysql-operator/README.md). This chart will deploy the controller together with an [orchestrator](https://github.com/github/orchestrator) cluster.

__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.
__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. To upgrade, check the [0.2.x upgrade notes](#v02x-upgrade) as some additional steps are required.

## Controller upgrade

Maybe upgrading the MySQL operator to a newer version requires additional steps that has to be done.
Those steps can be found in the operator documentation at [upgrades](docs/operator-upgrades.md)
section.
Maybe upgrading the MySQL operator to a newer version requires additional steps. Those steps can be found in the operator's documentation at [upgrades](docs/operator-upgrades.md) section.

## Deploying a cluster

Expand All @@ -66,12 +52,8 @@ kubectl apply -f https://raw.githubusercontent.com/presslabs/mysql-operator/mast

## Tech considerations

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

## License

This project is licensed under Apache 2.0 license. Read the [LICENSE](LICENSE) file in the top
distribution directory, for the full license text.
This project is licensed under Apache 2.0 license. Read the [LICENSE](LICENSE) file in the top distribution directory for the full license text.
21 changes: 8 additions & 13 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,13 @@
# Documentation

MySQL Operator documentation.
MySQL operator documentation

## Table of content

* [Getting started](getting-started.md), provides an overview over deploying and using MySQL
Operator
* [Deploy a MySQL cluster](deploy-mysql-cluster.md), describes in detail how a cluster can be
installed and configured.
* [Configure backups](backups.md), this section shows how to configure and take backups of a
cluster.
* [Recurrent backups](cluster-recurrent-backups.md), it describe how to setup recurrent backups for
the cluster.
* [Restore a cluster](cluster-recover.md), it describes how to restore a cluster from a backup.
* [How to integrate](integrate-operator.md) the operator with your deployment setup. This presents
a simple way of using MySQL Operator and helm to deploy your application.
* [Orchestrator](orchestrator.md), describes how to access orchestrator for more details.
* [Getting started](getting-started.md) provides an overview over deploying and using the MySQL operator
* [Deploy a MySQL cluster](deploy-mysql-cluster.md) describes in detail how a cluster can be installed and configured
* [Configure backups](backups.md) shows how to configure and take backups of a cluster
* [Recurrent backups](cluster-recurrent-backups.md) describes how to setup recurrent backups for the cluster
* [Restore a cluster](cluster-recover.md) explains how to restore a cluster from a backup
* [How to integrate](integrate-operator.md) the operator with your deployment setup. This presents a simple way of using the MySQL operator and helm to deploy your application
* [Orchestrator](orchestrator.md) shows you how to access the orchestrator for more details.
16 changes: 8 additions & 8 deletions docs/backups.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: MySQL Operator Backups
linktitle: MySQL Operator Backups
description: MySQL Operator provides effortless backups, while keeping the cluster highly-available.
title: MySQL operator Backups
linktitle: MySQL operator Backups
description: MySQL operator provides effortless backups while keeping the cluster highly-available.
categories: [mysql operator]
keywords: [mysql operator]
menu:
Expand All @@ -13,13 +13,13 @@ aliases: []
toc: true
---

Backups are stored on object storage services like S3 or google cloud storage.
Backups are stored on object storage services like S3 or Google Cloud Storage.

In order to be able to store backup, the secret defined under `backupBucketSecretName` must the credentials to store those backups.
In order to be able to store a backup, the secret defined under `backupBucketSecretName` must have the credentials to store those backups.
The backups are uploaded using [Rclone](https://rclone.org/).
The contents of the secret are used to generate an rclone.conf in [hack/docker/mysql-helper/docker-entrypoint.sh](https://github.com/presslabs/mysql-operator/blob/master/hack/docker/mysql-helper/docker-entrypoint.sh).
The contents of the secret are used to generate a rclone.conf in [hack/docker/mysql-helper/docker-entrypoint.sh](https://github.com/presslabs/mysql-operator/blob/master/hack/docker/mysql-helper/docker-entrypoint.sh).

### Setup backup to S3
### Setup a backup on S3

You need to specify the `backupBucketURL` for the cluster to an URL like `s3://BUCKET_NAME`, and a secret.

Expand Down Expand Up @@ -53,7 +53,7 @@ Then run this command:
$ kubectl apply -f example-backup-secret.yaml
```

### Setup backup to gcloud
### Setup a backup to Google Cloud
You need to specify the `backupBucketURL` for the cluster to an URL like `gs://BUCKET_NAME`, and a secret.

Create a file named `example-backup-secret.yaml` and copy into it the following YAML code:
Expand Down
17 changes: 6 additions & 11 deletions docs/cluster-recover.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: MySQL Operator recover
linktitle: Recurrent Backups and Initialization
description: MySQL Operator provides a way to recreate clusters from snapshots
title: MySQL Cluster Recovery
linktitle: MySQL cluster recovery
description: MySQL operator provides a way to recreate clusters from snapshots.
categories: [mysql operator]
keywords: [mysql operator]
menu:
Expand All @@ -13,15 +13,11 @@ aliases: []
toc: true
---

The MySQL Operator provides a way to recreate a cluster based on a backup (snapshot). Just create a
new cluster with a new name which has `iniBucketURL` field pointed to the right backup.
The MySQL operator provides a way to recreate a cluster based on a backup (snapshot). Just create a new cluster with a new name which has `iniBucketURL` field pointed to the right backup.

## Initialize a cluster from a backup

To initialize a new cluster from a backup just set the `initBucketURL` to the backup that you want
to use. The credentails for connecting to storage provider should be set in the secret specified
into `initBucketSecretName` field , the same as for `backupSecretName` presented in [Backup]({{< ref
"./backups.md" >}}) section. Those fields can point to the same secret.
To initialize a new cluster from a backup just set the `initBucketURL` to the backup that you want to use. The credentails for connecting to the storage provider should be set in the secret specified in the `initBucketSecretName` field , the same as for `backupSecretName` presented in the [Backup]({{< ref "./backups.md" >}}) section. These fields can point to the same secret.


``` yaml
Expand All @@ -36,5 +32,4 @@ spec:
initBucketSecretName: backup-secret
```
This configuration gives you a new cluster that is initialized from the
specified backup `gs://bucket_name/path/to/backup.xbackup.gz`.
This configuration gives you a new cluster that is initialized from the specified backup `gs://bucket_name/path/to/backup.xbackup.gz`.
20 changes: 6 additions & 14 deletions docs/cluster-recurrent-backups.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: MySQL Operator recurrent backups
title: MySQL Operator Recurrent Backups
linktitle: Recurrent Backups for MySQL cluster
description: MySQL Operator provides effortless recurrent backups while keeping the cluster highly-available.
description: MySQL operator provides effortless recurrent backups while keeping the cluster highly available.
categories: [mysql operator]
keywords: [mysql operator]
menu:
Expand All @@ -14,24 +14,16 @@ toc: true
---


In the [Backups]({{< ref "./backups.md" >}}) section we take backups on demand. However,
a cluster can be configured to take recurrent backups. Also, a cluster can be
initialized from an existing backup.
In the [Backups]({{< ref "./backups.md" >}}) section we take backups on demand. However, a cluster can be configured to take recurrent backups. Also, a cluster can be initialized from an existing backup.

To be able to store backups, the secret defined under
`backupBucketSecretName` must contain the credentials needed to access storage
provider(e.g GCS, AWS, etc.)
To be able to store backups, the secret defined under `backupBucketSecretName` must contain the credentials needed to access the storage provider(e.g GCS, AWS, etc.)


### Setup recurrent backups for MySQL cluster

You need to specify the `backupBucketURL` in the cluster spec to an URL like
`s3://BUCKET_NAME`, and the secret with storage credentials (`backupSecretName`).
You need to set the `backupBucketURL` in the cluster spec as an URL like `s3://BUCKET_NAME`, and the secret with storage credentials (`backupSecretName`).

See the example below to configure a cluster that has recurrent backups that
runs once per day at midnight. To schedule a backup set `backupSchedule` field that is under
crontab format. For more details about CRON format can be found
[here](https://godoc.org/github.com/robfig/cron).
See the example below to configure a cluster that has recurrent backups that runs once per day at midnight. To schedule a backup set `backupSchedule` field that is under crontab format. For more details about CRON format can be found [here](https://godoc.org/github.com/robfig/cron).

``` yaml
apiVersion: mysql.presslabs.org/v1alpha1
Expand Down
Loading

0 comments on commit 64fce07

Please sign in to comment.