Improve README and add an example script

README.md

@@ -1,16 +1,41 @@
 # kube-backup
 
-Utility container for Kubernetes to backup databases and files from other containers.
+Utility container for Kubernetes to backup databases and files from other containers. Currently
+it can use `kubectl exec` to backup database and files form within containers and store the 
+backup files in an AWS S3 bucket.
 
-Available on [Docker Hub](https://hub.docker.com/r/whereisaaron/kube-backup/).
+Docker/Kubernetes images Available on [Docker Hub](https://hub.docker.com/r/whereisaaron/kube-backup/).
 
-*This is an early prototype. it kinda works. sometimes.*
+Source code is available on [Github](https://github.com/whereisaaron/kube-backup). Please
+make comments and contribute improvements on Github.
 
+*This is an early prototype, test with care and please report issues or contribute improvements*
+
+## Example use cases
+
+These examples assume you have created a `kube-backup` Secret with AWS credentials and an
+S3 bucket name in the namespace where you are running 'kube-backup'. See the 
+[deploy directory](https://github.com/whereisaaron/kube-backup/tree/master/deploy)
+for an example deployment.
+
+Back up a files using `tar` in a container. It assumes `bash`, `tar`, and `gzip` is available.
 ```
-kubectl run -it --rm kube-backup --image whereisaaron/kube-backup --namespace=kube-backup --restart='Never' -- \
- --task=backup-mysql-exec --namespace=default --pod=my-mysql-pod --container=mysql
+kubectl run --attach --rm kube-backup --image whereisaaron/kube-backup:0.1.1 -- \
+ --task=backup-files-exec --namespace=default --pod=my-pod --container=website --files-path=/var/www
 ```
 
+Back up a database using `mysqldump` run in the MySQL container. It assumes the environment variables
+based on the [offical MySQL container images](https://hub.docker.com/_/mysql/) and `gzip` is available.
+```
+kubectl run --attach --rm kube-backup --image whereisaaron/kube-backup:0.1.1 -- \
+ --task=backup-mysql-exec --namespace=default --pod=my-pod --container=mysql
+```
+
+## Usage
+
+The `kube-backup` container runs the `kube-backup.sh` script. You can supply any
+of the following arguments, or set the equivalent (but currently undocumented)
+environment variables.
 ```
 Usage:
   kube-backup.sh --task=<task name> [options...]
@@ -25,10 +50,49 @@ Usage:
   kube-backup.sh --help
   kube-backup.sh --version
 
+Notes:
   --secret is the default secret for all secrets (kubeconfig, AWS, Slack) 
   --timestamp allows two backups to share the same timestamp
   --s3-bucket if not specified, will be taken from the AWS secret
   --s3-prefix is inserted at the beginning of the S3 prefix
   --backup-name will replace e.g. the database name or file path
   --dry-run will do everything except the actual backup
 ```
+
+## Scripting
+
+You can run or schedule backups of multi-container stateful applications using
+a script like below. By synchronising the timestamp for the backups, you can 
+ensure the backup files in up in the same directory in S3.
+
+```
+#!/bin/bash
+
+#
+# Backup MySQL database and website files
+# - Use a synchronised timestamp so backups go into the same S3 directory
+# - Use randomised deployment names in case any old/stuck deployments exist
+#
+
+TIMESTAMP=$(date +%Y%m%d-%H%M)
+run_name () { 
+  echo "kb-$(cat /dev/urandom | tr -dc 'a-z0-9' | head -c 4)" 
+}
+#EXTRA_OPTS='--dry-run'
+
+CMD='kubectl run --attach --rm --image=whereisaaron/kube-backup:0.1.1 --namespace=kube-backup'
+
+$CMD $(run_name) -- $EXTRA_OPTS \
+  --task=backup-mysql-exec \
+  --timestamp=${TIMESTAMP} \
+  --namespace=default \
+  --selector=app=myapp,env=dev,component=mysql 
+
+$CMD $(run_name) -- $EXTRA_OPTS \
+  --task=backup-files-exec \
+  --timestamp=${TIMESTAMP} \
+  --namespace=default \
+  --selector=app=myapp,env=dev,component=website \
+  --files-path=/var/www/assets \
+  --backup-name=assets
+```

bin/kube-backup.sh

@@ -35,6 +35,7 @@ Usage:
   ${script_name} --help
   ${script_name} --version
 
+Notes:
   --secret is the default secret for all secrets (kubeconfig, AWS, Slack) 
   --timestamp allows two backups to share the same timestamp
   --s3-bucket if not specified, will be taken from the AWS secret

doc/backup-website-and-mysql.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+
+#
+# Backup MySQL database and website files
+# - Use a synchronised timestamp so backups go into the same S3 directory
+# - Use randomised deployment names in case any old/stuck deployments exist
+#
+
+TIMESTAMP=$(date +%Y%m%d-%H%M)
+run_name () { 
+  echo "kb-$(cat /dev/urandom | tr -dc 'a-z0-9' | head -c 4)" 
+}
+#EXTRA_OPTS='--dry-run'
+
+CMD='kubectl run --attach --rm --image=whereisaaron/kube-backup:0.1.1 --namespace=kube-backup'
+
+$CMD $(run_name) -- $EXTRA_OPTS \
+  --task=backup-mysql-exec \
+  --timestamp=${TIMESTAMP} \
+  --namespace=default \
+  --selector=app=myapp,env=dev,component=mysql 
+
+$CMD $(run_name) -- $EXTRA_OPTS \
+  --task=backup-files-exec \
+  --timestamp=${TIMESTAMP} \
+  --namespace=default \
+  --selector=app=myapp,env=dev,component=website \
+  --files-path=/var/www/assets \
+  --backup-name=assets