Update documentation

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
 

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

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