- Include metadatastoremigration section for 2.5 to 2.6 upgrade

- Add relevant screenshots
- Update instructions on using the Swagger UI for DTR API requests
- Add link to v2.5 garbage collection page

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}

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://<dtr-external-url>/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)