WIP: Backupbot Specification #258
|
@ -0,0 +1,118 @@
|
|||
# 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].
|
||||
p4u1 marked this conversation as resolved
Outdated
|
||||
|
||||
When backing up a docker stack you MUST first check if the `backupbot.backup`. It MUST be set to true, for the backup to happen.
|
||||
p4u1 marked this conversation as resolved
3wordchant
commented
Maybe remove this, seems the same as line 15 "To enable backups" Maybe remove this, seems the same as line 15 "To enable backups"
|
||||
|
||||
## Backup
|
||||
|
||||
To enable backups for a docker stack, the `backupbot.backup=true` label MUST be on any of its services. It SHOULD be declared on the first service.
|
||||
3wordchant
commented
Is the behaviour defined if one service sets Is the behaviour defined if one service sets `backupbot.backup=true` and another sets it to `backupbot.backup=false`?
|
||||
A `backupbot.backup.pre-hook` MAY be set on a service. When set the command MUST be executed inside the running container of the service before backup up files.
|
||||
By default all volumes MUST be backed up. A volume MAY be excluded from backing up 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 seperated by a comma.
|
||||
A `backupbot.backup.post-hook` MAY be set on a service. When set the command MUST be executed inside the running container of the service after backing up all files.
|
||||
3wordchant marked this conversation as resolved
3wordchant
commented
So the spec allows backing up a volume even if So the spec allows backing up a volume even if `...{volume_name}=false`? Is there any harm in changing this to "MUST"?
p4u1
commented
Changed it to "MUST" Changed it to "MUST"
|
||||
A backup implementation SHOULD provide the backup of one or multiple stacks in a `.tar.gz` format.
|
||||
|
||||
## Restore
|
||||
|
||||
A `backupbot.restore.pre-hook` MAY be set on a service. When set the command MUST be executed inside the running container of the service before restoring backup files.
|
||||
By default all files MUST be restored into their volume. A volume or path MAY be excluded from restoring.
|
||||
A `backupbot.restore.post-hook` MAY be set on a service. When set the command MUST be executed inside the running container of the service after restoring backup files.
|
||||
|
||||
moritz
commented
I think I think `{volume_name}` can be confusing in this case. Because in `backupbot.backup.volumes.{volume_name}.path` the `{volume_name}` would be for example `assets`, while in the path `/var/lib/docker/volumes/{volume_name}` it would be `appname_example_com_assets`.
Maybe writing `/var/lib/docker/volumes/{stack_name}_{volume_name}` would clearer.
|
||||
## Labels
|
||||
|
||||
### `backupbot.backup`
|
||||
|
||||
**Type:** boolean
|
||||
**Default:** false
|
||||
**Description:**
|
||||
Enables backupbot for this compose stack. The labe 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.
|
||||
|
||||
decentral1se
commented
`%s/labe/label`
`%s/backupbot/backup-bot-two`
p4u1
commented
Did Did `%s/backupbot/backups` to keep it generic
|
||||
**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 backups up those on the given volume instead of the whole volume.
|
||||
|
||||
**Example:**
|
||||
|
||||
```
|
||||
backupbot.backup.volumes.{volume_name}.path: '/var/lib/mariadb/dump.sql.gz'
|
||||
```
|
||||
|
||||
### `backupbot.backup.pre-hook`
|
||||
|
||||
**Type:** string
|
||||
**Default:** ""
|
||||
**Description:**
|
||||
p4u1 marked this conversation as resolved
Outdated
3wordchant
commented
seperated -> separated backups up -> backs up seperated -> separated
backups up -> backs up
|
||||
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 backuped.
|
||||
|
||||
**Example:**
|
||||
|
||||
```
|
||||
backupbot.backup.post-hook: "rm -rf /volume_path/dump.db"
|
||||
```
|
||||
|
||||
### `backupbot.restore.pre-hook`
|
||||
|
||||
**Type:** string
|
||||
**Default:** ""
|
||||
**Description:**
|
||||
p4u1 marked this conversation as resolved
3wordchant
commented
backuped -> backed up backuped -> backed up
|
||||
A command, that gets executed before the files are restored.
|
||||
|
||||
**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"
|
||||
```
|
[RFC-2119]
missing link?