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 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.
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 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"