# Backup UCP and DTR

The playbooks support backing up the swarm, UCP, DTR metadata and DTR images.

# Backup configuration variables

The following table shows the variables related to backing up UCP and DTR. All these variables are defined in the file group_vars/all/backups. All the data that is backed up is streamed over an SSH connection to the backup server. Currently, the playbooks only support the use of the Ansible box as the backup server.

Table 21. Backup variables

# Backing up the Swarm

When you backup the swarm, your services and stack definitions are backed up together with the networks definitions. However, Docker volumes or their contents will not be backed up. (If Docker volumes are defined in stacks, they will be re-created when you restore the stacks, but their content will be lost). You can backup the swarm using the playbook named backup_swarm.yml which is located in the playbooks folder on your Ansible server. The playbook is invoked as follows:

# ansible-playbook -i hosts playbooks/backup_swarm.yml

This playbook creates two archives in the folder specified by the variable backup_dest in group_vars/all/backups. By default, the file is named using the following pattern:

<backup_dest>/backup_swarm_<vmname>_<timestamp>.tgz
<backup_dest>/backup_swarm_<vmname>_<timestamp>.vars.tgz

<vmname> is the name of the host (in the inventory) that was used to take the backup, and <timestamp> is the time at which the backup was taken. The file with the extension .vars.tgz contains information regarding the system that was backed up.

You can override the generated file name by defining the variable backup_name on the command line when running the playbook. In the example below:

# ansible-playbook -i hosts playbooks/backup_swarm.yml -e backup_name=my_swarm_backup

The generated files won't have <vmname> or <timestamp> appended:

<backup_dest>/my_swarm_backup.tgz
<backup_dest>/my_swarm_backup.vars.tgz

Warning: Online versus offline backups: By default, the playbook performs online backups. You can take offline backups by setting the variable swarm_backup_offline to "true". The playbook will then stop the Docker daemon on the machine used to take the backup (a manager or UCP node). Before it does so, the playbook will verify that enough managers are running in the cluster to maintain the quorum. If this is not the case, the playbook will exit with an error. For more information, see the Docker documentation at https://docs.docker.com/engine/swarm/admin_guide/#recover-from-disaster

# Backing up the Universal Control Plane (UCP)

When you backup UCP, you save the data/metadata outlined in Table 22:

Table 22. UCP data backed up

To make a backup of UCP, use playbook/backup_ucp.yml as follows:

# ansible-playbook -i vm_host playbooks/backup_ucp.yml

This playbook creates two archives in the folder specified by the variable backup_dest in group_vars/all/backups. By default, the files are named using the following pattern:

<backup_dest>/backup_ucp_<ucpid>_<vmname>_<timestamp>.tgz
<backup_dest>/backup_ucp_<ucpid>_<vmname>_<timestamp>.vars.tgz

<ucpid> is the ID of the UCP instance, <vmname> is the name of the host (in the inventory) that was used to take the backup, and <timestamp> is the time at which the backup was taken. The file with the extension .vars.tgz contains information regarding the system which was backed up.

You can override the generated file name by defining the variable backup_name on the command line when running the playbook. In the example below:

# ansible-playbook -i hosts playbooks/backup_ucp.yml -e backup_name=my_ucp_backup

The generated files won't have <vmname> or <timestamp> appended:

<backup_dest>/my_ucp_backup.tgz
<backup_dest>/my_ucp_backup.vars.tgz

Warning: To create a consistent backup, the backup command temporarily stops the UCP containers running on the node where the backup is being performed. User resources, such as services, containers, and stacks are not affected by this operation and will continue to operate as expected. Any long-lasting docker exec, docker logs, docker events, or docker attach operations on the affected manager node will be disconnected.

For more information on UCP backup, see the Docker documentation at https://docs.docker.com/ee/ucp/admin/backups-and-disaster-recovery/

# Backing up the Docker Trusted Registry (DTR)

When you backup DTR, you save the data/metadata outlined in Table 23:

Table 23. DTR data backed up

To make a backup of DTR metadata, use playbook/backup_dtr_metadata.yml

# ansible-playbook -i vm_host playbooks/backup_dtr_metadata.yml

This playbook creates two archives in the folder specified by the variable backup_dest in group_vars/all/backups. By default, the file is named using the following pattern:

<backup_dest>/backup_dtr_meta_<replica_id>_<vmname>_<timestamp>.tgz
<backup_dest>/backup_dtr_meta_<replica_id>_<vmname>_<timestamp>.vars.tgz

<replica_id> is the ID of the DTR replica that was backed up, <vmname> is the name of the host (in the inventory) that was used to take the backup, and <timestamp> is the time at which the backup was taken. The file with the extension .vars.tgz contains information regarding the system that was backed up.

You can override the generated file name by defining the variable backup_name on the command line when running the playbook. In the example below:

# ansible-playbook -i hosts playbooks/backup_dtr_metadata.yml -e backup_name=my_dtr_metadata_backup

The generated files won't have <vmname> or <timestamp> appended:

<backup_dest>/my_dtr_metadata_backup.tgz
<backup_dest>/my_dtr_metadata_backup.vars.tgz

For more information on DTR backups, see the Docker documentation at https://docs.docker.com/ee/dtr/admin/disaster-recovery/

# Backing up DTR data (images)

To make a backup of the images that are inventoried in DTR and stored on the NFS server, use playbooks/backup_dtr_images.yml

# ansible-playbook -i vm_host playbooks/backup_dtr_images.yml

This playbook creates two archives in the folder specified by the variable backup_dest in group_vars/all/backups. By default, the files are named using the following pattern:

<backup_dest>/backup_dtr_data_<replica_id>_<vmname>_<timestamp>.tgz
<backup_dest>/backup_dtr_data_<replica_id>_<vmname>_<timestamp>.vars.tgz

<replica_id> is the ID of the DTR replica that was backed up, <vmname> is the name of the host (in the inventory) that was used to take the backup, and <timestamp> is the time at which the backup was taken.

You can override the generated file names by defining the variable backup_name on the command line when running the playbook, as shown in the example below:

# ansible-playbook -i hosts playbooks/backup_dtr_images.yml -e backup_name=my_dtr_data_backup

The generated files won't have <vmname> or <timestamp> appended:

<backup_dest>/my_dtr_data_backup.tgz
<backup_dest>/my_dtr_data_backup.vars.tgz

For more information on DTR backups, see the Docker documentation at https://docs.docker.com/ee/dtr/admin/disaster-recovery/

# Backing up other metadata, including passwords

The backup playbooks do not backup the sensitive data in your group_vars/all/vault file. The information stored in the .vars.tgz files includes backups of the following files:

• hosts, a copy of the hosts file at the time the backup was taken
• vars, a copy of your group_vars/all/vars file at the time the backup was taken
• meta.yml, a generated file containing information pertaining to the backup

The meta.yml file contains the following information:

backup_node="<node that took the backup>"
replica_id="<ID of DTR replica if DTR backup>"
backup_source=""
ucp_version="<UCP version if UCP backup>"
dtr_version="<DTR version of DTR backup>"

# Backup Utility

The script backup.sh can be used to take a backup of the swarm, UCP, DTR metadata and the DTR images in one go. You can pass this script an argument (tag) that will be used to prefix the backup filenames, thereby overriding the default naming. Table 24 shows the file names produced by backup.sh based on the argument passed in the command line.

Table 24. Backup utility

In addition, the backup.sh script accepts an optional switch that will let you specify the location of the password file that will be passed to the ansible-playbook commands in the script. This is required if you have encrypted the group_vars/all/vault file. The general syntax for this script is as follows:

./backup.sh [ -v <Vault Password File> ] [ tag ]

# Related playbooks

• playbooks/backup_swarm.yml is used to back up the swarm data
• playbooks/backup_ucp.yml is used to back up UCP
• playbooks/backup_dtr_meta.yml is used to back up DTR metadata
• playbooks/backup_dtr_images.yml is used to back up DTR images