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

Addressed engineering feedback

This commit is contained in:
Maria Bermudez 2019-04-04 16:18:40 -07:00
parent bf746b4529
commit 603b14f1f0
3 changed files with 19 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
ee/dtr/admin/configure/external-storage/nfs.md
View File

@ -55,7 +55,7 @@ To support **NFS v4**, more NFS options have been added to the CLI. See [New Fea
#### DTR 2.6.4
In DTR 2.6.4, a new flag, `--storage-migrated`, [has been added to `docker/dtr reconfigure`](/reference/dtr/2.6/cli/reconfigure/) which lets you indicate the migration status of your storage data during a reconfigure. [Upgrade to 2.6.4](/reference/dtr/2.6/cli/upgrade/) and follow [Best practice for data migration in 2.6.4](/ee/dtr/admin/configure/external-storage/storage-backend-migration/#best-practice-for-data-migration) when switching storage backends.
In DTR 2.6.4, a new flag, `--storage-migrated`, [has been added to `docker/dtr reconfigure`](/reference/dtr/2.6/cli/reconfigure/) which lets you indicate the migration status of your storage data during a reconfigure. [Upgrade to 2.6.4](/reference/dtr/2.6/cli/upgrade/) and follow [Best practice for data migration in 2.6.4](/ee/dtr/admin/configure/external-storage/storage-backend-migration/#best-practice-for-data-migration) when switching storage backends. The following shows you how to reconfigure DTR using an NFSv4 volume as a storage backend:
```bash
docker run --rm -it \

7
ee/dtr/admin/configure/external-storage/s3.md
View File

@ -133,19 +133,14 @@ DTR supports the following S3 regions:
## Update your S3 settings on the web interface
When running 2.5.x (with experimental garbage collection) or 2.6.0-2.6.3, there is an issue with [changing your S3 settings on the web interface](/ee/dtr/release-notes#version-26) which leads to erased metadata. Make sure to [back up your DTR metadata](/ee/dtr/admin/disaster-recovery/create-a-backup/#back-up-dtr-metadata) before you proceed.
When running 2.5.x (with experimental garbage collection) or 2.6.0-2.6.4, there is an issue with [changing your S3 settings on the web interface](/ee/dtr/release-notes#version-26) which leads to erased metadata. Make sure to [back up your DTR metadata](/ee/dtr/admin/disaster-recovery/create-a-backup/#back-up-dtr-metadata) before you proceed.
## Restore DTR with S3
To [restore DTR using your previously configured S3 settings](https://success.docker.com/article/dtr-26-lost-tags-after-reconfiguring-storage#restoretocloudstorage), use `docker/dtr restore` with `--dtr-use-default-storage` to keep your metadata.
#### DTR 2.6.4
In DTR 2.6.4, a new flag, `--storage-migrated`, [has been added to `docker/dtr reconfigure`](/reference/dtr/2.6/cli/reconfigure/) which lets you indicate the migration status of your storage data during a reconfigure. [Upgrade to 2.6.4](/reference/dtr/2.6/cli/upgrade/) and follow [Best practice for data migration in 2.6.4](/ee/dtr/admin/configure/external-storage/storage-backend-migration/#best-practice-for-data-migration) when switching storage backends.
## Where to go next
- [Switch storage backends](storage-backend-migration.md)
- [Create a backup](/ee/dtr/admin/disaster-recovery/create-a-backup/)
- [Restore from a backup](/ee/dtr/admin/disaster-recovery/restore-from-backup/)
- [Configure where images are stored](index.md)

44
ee/dtr/admin/configure/external-storage/storage-backend-migration.md
View File

@ -4,62 +4,52 @@ description: Storage backend migration for Docker Trusted Registry
keywords: dtr, storage drivers, local volume, NFS, Azure, S3,
---
Starting in DTR 2.6, switching storage backends initializes a new metadata store and erases your existing tags. This helps facilitate online garbage collection, which has been introduced in 2.5 as an experimental feature. In earlier versions, DTR would subsequently start a `tagmigration` job to rebuild tag metadata from the file layout in the image layer store. This job has been discontinued, as your storage backend could get out of sync with your DTR metadata, like your manifests and existing repositories. As best practice, DTR storage backends and metadata should always be moved, backed up, and restored together.
Starting in DTR 2.6, switching storage backends initializes a new metadata store and erases your existing tags. This helps facilitate online garbage collection, which has been introduced in 2.5 as an experimental feature. In earlier versions, DTR would subsequently start a `tagmigration` job to rebuild tag metadata from the file layout in the image layer store. This job has been discontinued for DTR 2.5.x (with garbage collection) and DTR 2.6, as your storage backend could get out of sync with your DTR metadata, like your manifests and existing repositories. As best practice, DTR storage backends and metadata should always be moved, backed up, and restored together.
## DTR 2.6.4 and above
In DTR 2.6.4, a new flag, `--storage-migrated`, [has been added to `docker/dtr reconfigure`](/reference/dtr/2.6/cli/reconfigure/) which lets you indicate the migration status of your storage data during a reconfigure.
In DTR 2.6.4, a new flag, `--storage-migrated`, [has been added to `docker/dtr reconfigure`](/reference/dtr/2.6/cli/reconfigure/) which lets you indicate the migration status of your storage data during a reconfigure. If you are not worried about losing your existing tags, you can skip the recommended steps below and [perform a reconfigure](/reference/dtr/2.6/cli/reconfigure/).
### Best practice for data migration
Docker recommends the following steps for your storage backend and metadata migration:
1. Disable garbage collection by selecting "Never" under **System > Garbage Collection**, so blobs referenced in the backup that you create continue to exist. See [Garbage collection](/ee/dtr/admin/configure/garbage-collection/) for more details.
1. Disable garbage collection by selecting "Never" under **System > Garbage Collection**, so blobs referenced in the backup that you create continue to exist. See [Garbage collection](/ee/dtr/admin/configure/garbage-collection/) for more details. Make sure to keep it disabled while you're performing the metadata backup and migrating your storage data.
![](/ee/dtr/images/garbage-collection-0.png){: .img-fluid .with-border}
2. [Back up your existing metadata](/ee/dtr/admin/disaster-recovery/create-a-backup/#back-up-dtr-metadata). See [docker/dtr backup](/reference/dtr/2.6/cli/backup/) for CLI command description and options.
3. Migrate the contents of your current storage backend to the new one you are switching to. For example, upload your NFS contents to an S3 bucket if you're switching from NFS to S3.
3. Migrate the contents of your current storage backend to the new one you are switching to. For example, upload your current storage data to your new NFS server.
4. [Restore DTR from your backup](/ee/dtr/admin/disaster-recovery/restore-from-backup/) and specify your new storage backend. See [docker/dtr destroy](/reference/dtr/2.6/cli/destroy/) and [docker/dtr restore](/reference/dtr/2.6/cli/backup/) for CLI command descriptions and options.
5. Run garbage collection in "blob" mode. You can either SSH into a DTR node, or [use a UCP client bundle](/ee/ucp/user-access/cli/) to run the following command:
5. With DTR restored from your backup and your storage data migrated to your new backend, garbage collect any dangling blobs using the following API request:
```bash
docker exec -it dtr-jobrunner-<replica_id> sh
```
> See [Find your replica ID](/ee/dtr/admin/disaster-recovery/create-a-backup/#find-your-replica-id) for tips on determining your replica ID.
Within the running container, type `/bin/job_executor` to start the `job_executor` binary.
```bash
curl -u <username>:$TOKEN -X POST "https://<dtr-url>/api/v0/jobs" -H "accept: application/json" -H "content-type: application/json" -d "{ \"action": \"onlinegc_blobs\" }"
```
On success, you should get a `202 Accepted` response with a job `id` and other related details.
This ensures any blobs which are not referenced in your previously created backup get destroyed.
```bash
/bin/job_executor
/ # onlinegc blobs
```
> Note that the first line results in a display of the binary name, its usage, and available commands including `onlinegc`. To learn more about a command, run `<command_name>` --help.
Running garbage collection in blob mode destroys any new blobs which are not referenced in your previously created backup.
### Alternative options for data migration
### Alternative option for data migration
- If you have a long maintenance window, you can skip some steps from above and do the following:
1. Put DTR in "read-only" mode. To do so, send the following API request:
1. Put DTR in "read-only" mode using the following API request:
```bash
curl -u <username>:$TOKEN -X POST "https://<dtr-url>/api/v0/meta/settings" -H "accept: application/json" -H "content-type: application/json" -d "{ \"readOnlyRegistry\": true }"
```
On success, you should get a `202 Accepted` response.
2. Migrate the contents of your current storage backend to the new one you are switching to. For example, upload your NFS contents to an S3 bucket if you're switching from NFS to S3.
2. Migrate the contents of your current storage backend to the new one you are switching to. For example, upload your current storage data to your new NFS server.
3. [Reconfigure DTR](/reference/dtr/2.6/cli/reconfigure) while specifying the `--storage-migrated` flag to preserve your existing tags.
3. [Reconfigure DTR](/reference/dtr/2.6/cli/reconfigure) while specifying the `--storage-migrated` flag to preserve your existing tags.
- If you are not worried about inconsistencies in data, skip steps 1 and 2 and perform a reconfigure.
## DTR 2.6.0-2.6.3 and DTR 2.5 (with experimental garbage collection)
## DTR 2.6.0-2.6.4 and DTR 2.5 (with experimental garbage collection)
Make sure to [perform a backup](/ee/dtr/admin/disaster-recovery/create-a-backup/#back-up-dtr-data) before you change your storage backend when running DTR 2.5 (with online garbage collection) and 2.6.0-2.6.3. If you encounter an issue with lost tags, refer to the following resources:
* For changes to reconfigure and restore options in DTR 2.6, see [docker/dtr reconfigure](/reference/dtr/2.6/cli/reconfigure/) and [docker/dtr restore](/reference/dtr/2.6/cli/restore).
@ -67,7 +57,7 @@ Make sure to [perform a backup](/ee/dtr/admin/disaster-recovery/create-a-backup/
* For NFS-specific changes, see [Use NFS](nfs.md).
* For S3-specific changes, see [Learn how to configure DTR with Amazon S3](s3.md).
Upgrade to [DTR 2.6.4](#dtr-264-and-above) and follow [best practice for data migration](#best-practice-for-data-migration) to avoid the wiped tags issue.
Upgrade to [DTR 2.6.4](#dtr-264-and-above) and follow [best practice for data migration](#best-practice-for-data-migration) to avoid the wiped tags issue when moving from one NFS serverto another.
## Where to go next