From 9b6c34319a508cd885493061bc0555c41854a7f2 Mon Sep 17 00:00:00 2001 From: Andy Goldstein Date: Fri, 20 Oct 2017 15:29:59 -0400 Subject: [PATCH] Add initial doc on hooks. Signed-off-by: Andy Goldstein --- docs/concepts.md | 5 +++++ docs/hooks.md | 27 +++++++++++++++++++++++++++ 2 files changed, 32 insertions(+) create mode 100644 docs/hooks.md diff --git a/docs/concepts.md b/docs/concepts.md index 1049020e5..8bf82bc37 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -22,6 +22,10 @@ This section gives a quick overview of the Ark operation types. ### 1. Backups The *backup* operation (1) uploads a tarball of copied Kubernetes resources into cloud object storage and (2) uses the cloud provider API to make disk snapshots of persistent volumes, if specified. [Annotations][8] are cleared for PVs but kept for all other object types. +You can optionally specify hooks that should be executed during the backup. For example, you may +need to tell a database to flush its in-memory buffers to disk prior to taking a snapshot. You can +find more information about hooks [here][11]. + Some things to be aware of: * *Cluster backups are not strictly atomic.* If API objects are being created or edited at the time of backup, they may or not be included in the backup. In practice, backups happen very quickly and so the odds of capturing inconsistent information are low, but still possible. @@ -71,3 +75,4 @@ This allows *restore* functionality to work in a cluster migration scenario, whe [8]: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/ [9]: #api-types [10]: api-types/ +[11]: hooks.md diff --git a/docs/hooks.md b/docs/hooks.md new file mode 100644 index 000000000..5e206cb8e --- /dev/null +++ b/docs/hooks.md @@ -0,0 +1,27 @@ +# Hooks + +Heptio Ark currently supports executing commands in containers in pods during a backup. + +## Backup Hooks + +When performing a backup, you can specify one or more commands to execute in a container in a pod +when that pod is being backed up. There are two ways to specify hooks: annotations on the pod +itself, and in the Backup spec. + +### Specifying Hooks As Pod Annotations + +You can use the following annotations on a pod to make Ark execute a hook when backing up the pod: + +| Annotation Name | Description | +| --- | --- | +| `hook.backup.ark.heptio.com/container` | The container where the command should be executed. Defaults to the first container in the pod. Optional. | +| `hook.backup.ark.heptio.com/command` | The command to execute. If you need multiple arguments, specify the command as a JSON array, such as `["/usr/bin/uname", "-a"]` | +| `hook.backup.ark.heptio.com/on-error` | What to do if the command returns a non-zero exit code. Defaults to Fail. Valid values are Fail and Continue. Optional. | +| `hook.backup.ark.heptio.com/timeout` | How long to wait for the command to execute. The hook is considered in error if the command exceeds the timeout. Defaults to 30s. Optional. | + +### Specifying Hooks in the Backup Spec + +Please see the documentation on the [Backup API Type][1] for how to specify hooks in the Backup +spec. + +[1]: api-types/backup.md