diff --git a/ee/dtr/admin/install/index.md b/ee/dtr/admin/install/index.md index d0a4aabfda..f5265e1fba 100644 --- a/ee/dtr/admin/install/index.md +++ b/ee/dtr/admin/install/index.md @@ -8,24 +8,21 @@ redirect_from: --- Docker Trusted Registry (DTR) is a containerized application that runs on a -swarm managed by Docker Universal Control Plane (UCP). It can be installed +swarm managed by the Universal Control Plane (UCP). It can be installed on-premises or on a cloud infrastructure. -Use these instructions to install DTR. - ## Step 1. Validate the system requirements -The first step in installing DTR, is ensuring your -infrastructure has all the [requirements DTR needs to run](system-requirements.md). +Before installing DTR, make sure your +infrastructure meets the [system requirements](./system-requirements) that DTR needs to run. ## Step 2. Install UCP Since DTR requires Docker Universal Control Plane (UCP) -to run, you need to install UCP on all the nodes where you plan to install DTR. -[Learn how to install UCP](/datacenter/ucp/2.2/guides/admin/install.md). +to run, you need to [install UCP](../ucp/admin/install/) on all the nodes where you plan to install DTR. DTR needs to be installed on a worker node that is being managed by UCP. -You can't install DTR on a standalone Docker Engine. +You cannot install DTR on a standalone Docker Engine. ![](../../images/install-dtr-1.svg) @@ -65,12 +62,12 @@ DTR, so that UCP is automatically reconfigured to trust DTR. ## Step 4. Check that DTR is running In your browser, navigate to the Docker **Universal Control Plane** -web UI, and navigate to the **Applications** screen. DTR should be listed +web interface, and navigate to the **Applications** screen. DTR should be listed as an application. -![](../../images/install-dtr-3.png){: .with-border} +![](../../images/create-repository-1.png){: .with-border} -You can also access the **DTR web UI**, to make sure it is working. In your +You can also access the **DTR web interface**, to make sure it is working. In your browser, navigate to the address where you installed DTR. ![](../../images/install-dtr-4.png){: .with-border} @@ -131,7 +128,7 @@ To add replicas to a DTR cluster, use the `docker/dtr join` command: 3. Check that all replicas are running. In your browser, navigate to the Docker **Universal Control Plane** - web UI, and navigate to the **Applications** screen. All replicas should + web interface, and navigate to the **Applications** screen. All replicas should be displayed. ![](../../images/install-dtr-6.png){: .with-border} diff --git a/ee/dtr/admin/upgrade.md b/ee/dtr/admin/upgrade.md index 53068b05c4..4a82f49c98 100644 --- a/ee/dtr/admin/upgrade.md +++ b/ee/dtr/admin/upgrade.md @@ -4,20 +4,19 @@ description: Learn how to upgrade your Docker Trusted Registry keywords: dtr, upgrade, install --- -{% assign previous_version="2.4" %} +{% assign previous_version="2.5" %} -DTR uses [semantic versioning](http://semver.org/) and we aim to achieve specific -guarantees while upgrading between versions. We never support downgrading. We -support upgrades according to the following rules: +DTR uses [semantic versioning](http://semver.org/) and Docker aims to achieve specific +guarantees while upgrading between versions. While downgrades are not supported, Docker supports upgrades according to the following rules: -* When upgrading from one patch version to another you can skip patch versions +* When upgrading from one patch version to another, you can skip patch versions because no data migration is done for patch versions. -* When upgrading between minor versions, you can't skip versions, but you can - upgrade from any patch versions of the previous minor version to any patch +* When upgrading between minor versions, you ***cannot*** skip versions, but you can + upgrade from any patch version of the previous minor version to any patch version of the current minor version. -* When upgrading between major versions you also have to upgrade one major - version at a time, but you have to upgrade to the earliest available minor - version. We also strongly recommend upgrading to the latest minor/patch +* When upgrading between major versions, make sure to upgrade one major + version at a time – and also upgrade to the earliest available minor + version. We strongly recommend upgrading to the latest minor/patch version for your major version first. | Description | From | To | Supported | @@ -34,14 +33,14 @@ support upgrades according to the following rules: | major upgrade skipping minor version | x.y.z | x+1.y+1.z | no | There may be at most a few seconds of interruption during the upgrade of a -DTR cluster. Schedule the upgrade to take place outside business peak hours -to ensure the impact on your business is close to none. +DTR cluster. Schedule the upgrade to take place outside of peak hours +to avoid any business impacts. ## Minor upgrade Before starting your upgrade, make sure that: * The version of UCP you are using is supported by the version of DTR you -are trying to upgrade to. [Check the compatibility matrix](https://success.docker.com/Policies/Compatibility_Matrix). +are trying to upgrade to. [Check the compatibility matrix](https://success.docker.com/article/compatibility-matrix). * You have a recent [DTR backup](disaster-recovery/create-a-backup.md). * You [disable Docker content trust in UCP](/ee/ucp/admin/configure/run-only-the-images-you-trust/). @@ -73,7 +72,7 @@ docker run -it --rm \ By default the upgrade command runs in interactive mode and prompts you for any necessary information. You can also check the -[reference documentation](/reference/dtr/2.5/cli/index.md) for other existing flags. +[reference documentation](/reference/dtr/2.6/cli/index.md) for other existing flags. The upgrade command will start replacing every container in your DTR cluster, one replica at a time. It will also perform certain data migrations. If anything @@ -85,6 +84,25 @@ command and it will resume from where it left off. A patch upgrade changes only the DTR containers and it's always safer than a minor upgrade. The command is the same as for a minor upgrade. +## 2.5 to 2.6 upgrade + +When upgrading from `2.5` to `2.6`, the system will run a `metadatastoremigration` job after a successful upgrade. This involves migrating the blob links for your images which is necessary for online garbage collection. With `2.6`, you can log in to the DTR web interface and navigate to **System > Job Logs** to check the status of the `metadatastoremigration` job. See [Audit Jobs via the Web Interface](../manage-jobs/audit-jobs-via-ui/) for more details. + +![](../images/migration-warning.png){: .with-border} + +Garbage collection is disabled while the migration is running. In the case of a failed `metadatastoremigration`, the system will retry twice. + +![](../images/migration-error.png){: .with-border} + +If the three attempts fail, you will have to retrigger the `metadatastoremigration` job manually. To do so, send a `POST` request to the `/api/v0/jobs` endpoint: + +```bash +curl https:///api/v0/jobs -X POST \ +-u username:accesstoken -H 'Content-Type':'application/json' -d \ +'{"action": "metadatastoremigration"}' +``` +Alternatively, select **API** from the bottom left navigation pane of the DTR web interface and use the Swagger UI to send your API request. + ## Download the vulnerability database After upgrading DTR, you need to re-download the vulnerability database. @@ -93,3 +111,4 @@ After upgrading DTR, you need to re-download the vulnerability database. ## Where to go next - [Release notes](../release-notes.md) +- [Garbage collection in v2.5](../../../v18.03/ee/dtr/admin/configure/garbage-collection.md) diff --git a/ee/dtr/images/migration-error.png b/ee/dtr/images/migration-error.png new file mode 100644 index 0000000000..58ac6a5bc3 Binary files /dev/null and b/ee/dtr/images/migration-error.png differ diff --git a/ee/dtr/images/migration-warning.png b/ee/dtr/images/migration-warning.png new file mode 100644 index 0000000000..84efb52e98 Binary files /dev/null and b/ee/dtr/images/migration-warning.png differ