From 57a5b254772d3b5c4c2d6987f99d9d53cd9722dc Mon Sep 17 00:00:00 2001 From: Jan Steffen Date: Wed, 30 Sep 2020 12:40:26 +0200 Subject: [PATCH] Update documentation --- README.md | 48 +++++++++++++++--- .../backup_v1alpha1_consulbackupplan.yaml | 25 +++++++--- .../backup_v1alpha1_mongodbbackupplan.yaml | 49 +++++++++++++++++-- 3 files changed, 107 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index ad4753c..eb51df3 100644 --- a/README.md +++ b/README.md @@ -13,19 +13,55 @@ Find the helm chart for the backup-operator at the [Kubism.io Helm Charts](https://kubism.github.io/charts/#chart-backup-operator). -TODO +### Backup for MongoDB -### Backups for MongoDB +Let's assume you want to backup a MongoDB replicaset. The only MongoDB +specific configuration required is the [MongoDB URI](https://docs.mongodb.com/manual/reference/connection-string/). +However you'll want to insert the sensitive data using environment variables. -TODO +For example, let's assume you have two pre-existing secrets: -### Backups for Consul +* secret containing the password for the MongoDB user +* secret containing the S3 credentials (and optional encryption key for [SSE feature](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingServerSideEncryption.html)) -The backup of consul to S3 is supported at the moment. See example configuration in [`backup_v1alpha1_consulbackupplan.yaml`](./config/samples/backup_v1alpha1_consulbackupplan.yaml). +**Note:** The below YAML mixes both [kubernetes environment composition](https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/#using-environment-variables-inside-of-your-config) +in the `env` section and job environment substitution in the other parts. + +The you might compose a `MongoDBBackupPlan` as in [`backup_v1alpha1_mongodbbackupplan.yaml`](./config/samples/backup_v1alpha1_mongodbbackupplan.yaml). + +The above specification will create a `CronJob` with the same name and the above +`env` and also create a `Secret` with the rest of the specification and mount it +into the `CronJob` as well. + +### Backup for Consul + +For Consul the procedure is the same as above. However instead of providing +the URI, the `ConsulBackupPlan` requires the follow fields: `address`, `username` and `password`, +which hopefully are self-explanatory. + +See example configuration in [`backup_v1alpha1_consulbackupplan.yaml`](./config/samples/backup_v1alpha1_consulbackupplan.yaml). ## Design -TODO +A common procedure of any production environments are backups. +For this purpose we developed a [backup operator](https://github.com/kubism/backup-operator), +which can be used to setup a `CronJob`, which will take care of the backup for you. + +The plan specification consists of several fields and an environment specification. +This duality is very important as **environment variables should be used to pass +sensitive data** to the resulting `CronJob`. + +The operator will spawn a vanilla `CronJob` and setup the environment as specified +by you. Once the job runs it will use environment substitution to replace any +variables in your specification. + +Therefore you should use the `valueFrom.secretKeyRef` to provide the sensitive +parts of your environment. + +The backup job will also push metrics into a prometheus pushgateway, if configured. + +Once a job is finished, it will make sure to remove obsolete backups as specified +by your `retention`. ## Development diff --git a/config/samples/backup_v1alpha1_consulbackupplan.yaml b/config/samples/backup_v1alpha1_consulbackupplan.yaml index 7019eb2..2d6b1c9 100644 --- a/config/samples/backup_v1alpha1_consulbackupplan.yaml +++ b/config/samples/backup_v1alpha1_consulbackupplan.yaml @@ -3,9 +3,9 @@ kind: ConsulBackupPlan metadata: name: consulbackupplan-sample spec: - schedule: "* * * * *" + schedule: "0 22 * * *" activeDeadlineSeconds: 3600 - retention: 2 + retention: 3 address: "localhost:8500" username: $CONSUL_HTTP_USERNAME password: $CONSUL_HTTP_PASSWORD @@ -16,14 +16,27 @@ spec: useSSL: true accessKeyID: $S3_ACCESS_KEY_ID secretAccessKey: $S3_SECRET_ACCESS_KEY + encryptionKey: $S3_ENCRYPTION_KEY env: - name: CONSUL_HTTP_USERNAME value: "user" - name: CONSUL_HTTP_PASSWORD - value: "password" + valueFrom: + secretKeyRef: + key: consul-password + name: my-consul-credentials - name: S3_ACCESS_KEY_ID - value: "abc" + valueFrom: + secretKeyRef: + name: my-s3-credentials + key: S3_ACCESS_KEY_ID - name: S3_SECRET_ACCESS_KEY - value: "abc" + valueFrom: + secretKeyRef: + name: my-s3-credentials + key: S3_SECRET_ACCESS_KEY - name: S3_ENCRYPTION_KEY - value: "256bit" + valueFrom: + secretKeyRef: + name: my-s3-credentials + key: S3_ENCRYPTION_KEY diff --git a/config/samples/backup_v1alpha1_mongodbbackupplan.yaml b/config/samples/backup_v1alpha1_mongodbbackupplan.yaml index 2d1072b..66bdd43 100644 --- a/config/samples/backup_v1alpha1_mongodbbackupplan.yaml +++ b/config/samples/backup_v1alpha1_mongodbbackupplan.yaml @@ -1,7 +1,50 @@ apiVersion: backup.kubism.io/v1alpha1 kind: MongoDBBackupPlan metadata: - name: mongodbbackupplan-sample + name: my-mongodb-backup spec: - # Add fields here - foo: bar + schedule: "0 22 * * *" + activeDeadlineSeconds: 3600 + retention: 3 + uri: "$MONGODB_URI" + pushgateway: + url: my-pushgateway:9102 + destination: + s3: + endpoint: my-s3:9000 + bucket: my-mongodbbackup + useSSL: true + accessKeyID: $S3_ACCESS_KEY_ID + secretAccessKey: $S3_SECRET_ACCESS_KEY + encryptionKey: $S3_ENCRYPTION_KEY + env: + - name: MONGODB_USERNAME + value: myuser + - name: MONGODB_PASSWORD + valueFrom: + secretKeyRef: + key: mongodb-password + name: my-mongodb-credentials + - name: MONGODB_DATABASE + value: mydatabase + - name: MONGODB_HOSTS + value: my-mongodb-primary-0.my-mongodb-headless:27017,my-mongodb-secondary-0.my-mongodb-headless:27017,my-mongodb-secondary-1.my-mongodb-headless:27017 + - name: MONGODB_OPTIONS + value: ?replicaSet=rs0 + - name: MONGODB_URI + value: mongodb://$(MONGODB_USERNAME):$(MONGODB_PASSWORD)@$(MONGODB_HOSTS)/$(MONGODB_DATABASE)$(MONGODB_OPTIONS) + - name: S3_ACCESS_KEY_ID + valueFrom: + secretKeyRef: + name: my-s3-credentials + key: S3_ACCESS_KEY_ID + - name: S3_SECRET_ACCESS_KEY + valueFrom: + secretKeyRef: + name: my-s3-credentials + key: S3_SECRET_ACCESS_KEY + - name: S3_ENCRYPTION_KEY + valueFrom: + secretKeyRef: + name: my-s3-credentials + key: S3_ENCRYPTION_KEY