4.2 KiB
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].
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.
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.
Volumes and paths
By default all volumes MUST be backed up. A volume MAY 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 seperated by a comma.
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.
The command MUST have access to all environment variables inside the container.
There is no guaranteed order in which different hooks MUST be executed.
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/{volume_name}, where {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 int 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 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.
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: 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: 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"