docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

document dtr backup/restore better (#1787) 

* document dtr backup/restore better

fix #1722

* little things

* improvements

* tweaks
This commit is contained in:
Viktor Stanchev 2017-02-17 14:29:36 -08:00 committed by Joao Fernandes
parent d9e2d542ca
commit 7d096a094a
2 changed files with 103 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

121
datacenter/dtr/2.2/guides/admin/backups-and-disaster-recovery.md
View File

@ -4,10 +4,10 @@ keywords: docker, registry, high-availability, backup, recovery
title: DTR backups and recovery
---
When you use Docker Trusted Registry on a production setting, you should first
configure it for high availability.
The next step is creating a backup policy and disaster recovery plan.
DTR replicas rely on having a majority available at any given time for writes to
succeed. Therefore if a majority of replicas are permanently lost, the only way
to restore DTR to a working state is to recover from backups. This is why it's
very important to perform periodic backups.
## DTR data persistence
@ -17,6 +17,9 @@ Docker Trusted Registry persists:
that is replicated through all DTR replicas.
* **Repository metadata**: the information about the repositories and
images deployed. This information is replicated through all DTR replicas.
* **Access control**: permissions for teams and repos.
* **Notary data**: notary tags and signatures.
* **Scan results**: security scanning results for images.
* **Certificates and keys**: the certificates, public keys, and private keys
that are used for mutual TLS communication.
@ -33,21 +36,38 @@ command creates a backup of DTR:
* Configurations,
* Repository metadata,
* Access control,
* Notary data,
* Scan results,
* Certificates and keys used by DTR.
These files are added to a tar archive, and the result is streamed to stdout.
This data is added to a tar archive, and the result is streamed to stdout. This
is done while DTR is running without shutting down any containers.
Things DTR's backup command doesn't back up:
* The vulnerability database (if using image scanning)
* Image contents
* Users, orgs, teams
There is no way to back up the vulnerability database. You can re-download it
after restoring or re-apply your offline tar update if offline.
The backup command does not create a backup of Docker images. You should
implement a separate backup policy for the Docker images, taking in
consideration whether your DTR installation is configured to store images on the
filesystem or using a cloud provider.
filesystem or using a cloud provider. During restore, you need to separately
restore the image contents.
The backup command also doesn't create a backup of the users and organizations.
That data is managed by UCP, so when you create a UCP backup you're creating
a backup of the users and organizations metadata.
a backup of the users and organizations. For this reason, when restoring DTR,
you must do it on the same UCP cluster (or one created by restoring from
backups) or else all DTR resources such as repos will be owned by non-existent
users and will not be usable despite technically existing in the database.
When creating a backup, the resulting .tar file contains sensitive information
like private keys. You should ensure the backups are stored securely.
such as private keys. You should ensure the backups are stored securely.
You can check the
[reference documentation](../../reference/cli/backup.md), for the
@ -71,6 +91,23 @@ Where:
* `--existing-replica-id` is the id of the replica to backup,
* `--ucp-username`, and `--ucp-password` are the credentials of a UCP administrator.
To avoid having to pass the password as a command line parameter, you may
instead use the following approach in bash:
```none
$ read -sp 'ucp password: ' PASS; UCP_PASSWORD=$PASS docker run -i --rm -e UCP_PASSWORD docker/dtr backup \
--ucp-url <ucp-url> \
--ucp-insecure-tls \
--existing-replica-id <replica-id> \
--ucp-username <ucp-admin> > /tmp/backup.tar
```
This puts the password into a shell variable which is then passed into the
docker client command with the -e flag which in turn relays the password to the
DTR bootstrapper.
## Testing backups
To validate that the backup was correctly performed, you can print the contents
of the tar file created:
@ -78,27 +115,59 @@ of the tar file created:
$ tar -tf /tmp/backup.tar
```
The structure of the archive should look something like this:
```none
dtr-backup-v2.2.1/
dtr-backup-v2.2.1/rethink/
dtr-backup-v2.2.1/rethink/properties/
dtr-backup-v2.2.1/rethink/properties/0
...
```
To really test that the backup works, you must make a copy of your UCP cluster
by backing it up and restoring it onto separate machines. Then you can restore
DTR there from your backup and verify that it has all the data you expect to
see.
## Restore DTR data
You can restore a DTR node from a backup using the `restore`
command.
This command performs a fresh installation of DTR, and reconfigures it with
the configuration created during a backup.
You can restore a DTR node from a backup using the `restore` command.
The command starts by installing DTR, restores the configurations stored on
etcd, and then restores the repository metadata stored on RethinkDB. You
can use the `--config-only` option, to only restore the configurations stored
on etcd.
Note that backups are tied to specific DTR versions and are guaranteed to work
only with those DTR versions. You can backup/restore across patch versions
at your own risk, but not across minor versions as those require more complex
migrations.
This command does not restore Docker images. You should implement a separate
restore procedure for the Docker images stored in your registry, taking in
consideration whether your DTR installation is configured to store images on
the filesystem or using a cloud provider.
Before restoring DTR, make sure that you are restoring it on the same UCP
cluster or you've also restored UCP using its restore command. DTR does not
manage users, orgs or teams so if you try to
restore DTR on a cluster other than the one it was backed up on, DTR
repositories will be associated with users that don't exist and it will appear
as if the restore operation didn't work.
Note that to restore DTR, you must first remove any left over containers from
the previous installation. To do this, see the [uninstall
documentation](../install/uninstall.md).
The restore command performs a fresh installation of DTR, and reconfigures it with
the configuration created during a backup. The command starts by installing DTR.
Then it restores the configurations from the backup and then restores the
repository metadata. Finally, it applies all of the configs specified as flags to
the restore command.
After restoring DTR, you must make sure that it's configured to use the same
storage backend where it can find the image data. If the image data was backed
up separately, you must restore it now.
Finally, if you are using security scanning, you must re-fetch the security
scanning database through the online update or by uploading the offline tar. See
the [security scanning configuration](../admin/configure/set-up-vulnerability-scans.md)
for more detail.
You can check the
[reference documentation](../../reference/cli/backup.md), for the
backup command to learn about all the available flags.
[reference documentation](../../reference/cli/restore.md), for the
restore command to learn about all the available flags.
As an example, to install DTR on the host and restore its
state from an existing backup:
@ -121,6 +190,12 @@ Where:
* `--ucp-username`, and `--ucp-password` are the credentials of a UCP administrator,
* `--dtr-load-balancer` is the domain name or ip where DTR can be reached.
Note that if you want to avoid typing your password into the terminal you must pass
it in as an environment variable using the same approach as for the backup command:
```none
$ read -sp 'ucp password: ' PASS; UCP_PASSWORD=$PASS docker run -i --rm -e UCP_PASSWORD docker/dtr restore ...
```
## Where to go next

17
datacenter/dtr/2.2/guides/admin/install/uninstall.md
View File

@ -4,18 +4,8 @@ keywords: docker, dtr, install, uninstall
title: Uninstall Docker Trusted Registry
---
Uninstalling DTR is a two-step process. You first scale your DTR deployment down
to a single replica. Then you uninstall the last DTR replica, which permanently
removes DTR and deletes all its data.
Start by [scaling down your DTR deployment](../configure/set-up-high-availability.md) to a
single replica.
When your DTR deployment is down to a single replica, you can use the
`docker/dtr destroy` command to permanently remove DTR and all its data:
1. Use ssh to log into any node that is part of UCP.
2. Uninstall DTR:
Uninstalling DTR can be done by simply removing all data associated with each
replica. To do that, you just run the destroy command once per replica:
```none
docker run -it --rm \
@ -23,6 +13,9 @@ docker run -it --rm \
--ucp-insecure-tls
```
You will be prompted for the UCP URL, UCP credentials and which replica to
destroy.
To see what options are available in the destroy command, check the
[destroy command reference documentation](../../../reference/cli/destroy.md).