forked from toolshed/docs.coopcloud.tech
137 lines
4.4 KiB
Markdown
137 lines
4.4 KiB
Markdown
# Specification
|
|
|
|
## Summary
|
|
|
|
Creating automated backups of docker swarm services is an often needed task. This specification describes how backups can be configured via [service labels](https://docs.docker.com/compose/compose-file/compose-file-v3/#labels-1) in a standardised way.
|
|
|
|
## Requirements
|
|
|
|
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in [RFC-2119](https://datatracker.ietf.org/doc/html/rfc2119).
|
|
|
|
## Backup
|
|
|
|
To enable backups for a docker stack, the `backupbot.backup=true` label MUST be set on one of its services. The label MUST NOT be set multiple times for a docker stack. Otherwise the implementation MUST show an error. The label SHOULD be declared on the main service.
|
|
|
|
### Volumes and paths
|
|
|
|
By default all volumes MUST be backed up. A volume MUST be excluded from the backup when `backupbot.backup.volumes.{volume_name}=false` is set, where `{volume_name}` is the name of the volume.
|
|
By default all files MUST be backed up on a volume. `backupbot.backup.volumes.{volume_name}.path` MAY be set to limit the paths for that volume. The value MUST be a valid path relative to the volume root. It MAY contain multiple paths which get separated by a comma. When the label is set only the given paths MUST be backed up.
|
|
|
|
### Pre/Post Hooks
|
|
|
|
A `backupbot.backup.pre-hook` and `backupbot.backup.post-hook` MAY be set on a service. When set the command MUST be executed inside the running container of the service before/after backing up files.
|
|
There is no guaranteed order in which different hooks MUST be executed.
|
|
|
|
TODO: escaping
|
|
|
|
### Output
|
|
|
|
A backup implementation SHOULD provide the backup of one or multiple stacks in a `.tar.gz` format. In that case each volume MUST be in `/var/lib/docker/volumes/{stack_name}_{volume_name}`, where `{stack_name}` is the name of the docker stack and `{volume_name}` is the name of each volume that got backed up.
|
|
|
|
## Restore
|
|
|
|
By default all files MUST be restored into their volume. A volume or path MAY be excluded from restoring. When restoring a backup from a `.tar.gz` it expects the directory layout as described in the [backup output](#output) section.
|
|
|
|
### Pre/Post Hooks
|
|
|
|
A `backupbot.restore.pre-hook` and `backupbot.restore.post-hook` MAY be set on a service. When set the command MUST be executed inside the running container of the service before/after restoring the files.
|
|
There is no guaranteed order in which different hooks MUST be executed.
|
|
|
|
## Labels
|
|
|
|
### `backupbot.backup`
|
|
|
|
**Type:** boolean
|
|
**Default:** false
|
|
**Description:**
|
|
Enables backups for this compose stack. The label should be added to the main service of the compose stack.
|
|
|
|
**Example:**
|
|
|
|
```
|
|
backupbot.backup: true
|
|
```
|
|
|
|
### `backupbot.backup.volumes.{volume_name}`
|
|
|
|
**Type:** boolean
|
|
**Default:** true
|
|
**Description:** When set to false the volume is excluded from backups.
|
|
|
|
**Example:**
|
|
|
|
```
|
|
backupbot.backup.volumes.{volume_name}: false
|
|
```
|
|
|
|
### `backupbot.backup.volumes.{volume_name}.path`
|
|
|
|
**Type:** string
|
|
**Default:** ""
|
|
**Description:**
|
|
A comma seperated list of paths. When one or more paths are set, it only backs up those on the given volume instead of the whole volume.
|
|
|
|
**Example 1:**
|
|
|
|
```
|
|
backupbot.backup.volumes.{volume_name}.path: '/var/lib/mariadb/dump.sql.gz'
|
|
```
|
|
|
|
**Example 2:**
|
|
```
|
|
backupbot.backup.volumes.{volume_name}.path: '/var/lib/myapp/foo,/var/lib/myapp/bar'
|
|
```
|
|
|
|
### `backupbot.backup.pre-hook`
|
|
|
|
**Type:** string
|
|
**Default:** ""
|
|
**Description:**
|
|
A command, that gets executed before the files are backed up.
|
|
|
|
**Example:**
|
|
|
|
```
|
|
backupbot.backup.pre-hook: 'mysqldump -u root -p"$(cat /run/secrets/db_root_password)" -f /volume_path/dump.db'
|
|
```
|
|
|
|
### `backupbot.backup.post-hook`
|
|
|
|
**Type:** string
|
|
**Default:** ""
|
|
**Description:**
|
|
A command, that gets executed after the files are backed up.
|
|
|
|
**Example:**
|
|
|
|
```
|
|
backupbot.backup.post-hook: "rm -rf /volume_path/dump.db"
|
|
```
|
|
|
|
### `backupbot.restore.pre-hook`
|
|
|
|
**Type:** string
|
|
**Default:** ""
|
|
**Description:**
|
|
A command, that gets executed before the files are restored.
|
|
Note, that there is no guaranteed order in which multiple hooks get executed.
|
|
|
|
**Example:**
|
|
|
|
```
|
|
backupbot.restore.pre-hook: "lock db"
|
|
```
|
|
|
|
### `backupbot.restore.post-hook`
|
|
|
|
**Type:** string
|
|
**Default:** ""
|
|
**Description:**
|
|
A command, that gets executed after the files are restored.
|
|
|
|
**Example:**
|
|
|
|
```
|
|
backupbot.restore.post-hook: "sqldump dump.sql && unlock db && rm dump.sql"
|
|
```
|