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

Merge remote-tracking branch 'docker.github.io/master'

This commit is contained in:
root 2020-01-13 21:00:26 +00:00
parent 0c9b8b8c5b 279e7f79eb
commit e67fd38bf4
1 changed files with 30 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
ee/dtr/admin/upgrade.md
View File

@ -8,18 +8,11 @@ keywords: dtr, upgrade, install
>{% include enterprise_label_shortform.md %}
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:
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
because no data migration is done for patch versions.
* 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, 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.
* When upgrading from one patch version to another, you can skip patch versions because no data migration is performed for patch versions.
* When upgrading between minor versions, you ***cannot*** skip versions, however 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, make sure to upgrade one major version at a time – and also to upgrade to the earliest available minor version. It is strongly recommended that you first upgrade to the latest minor/patch version for your major version.
| Description | From | To | Supported |
|:-------------------------------------|:------|:----------|:----------|
@ -34,64 +27,66 @@ guarantees while upgrading between versions. While downgrades are not supported,
| major upgrade | x.y.z | x+1.0.0 | yes |
| 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 of peak hours
A few seconds of interruption may occur during the upgrade of a
DTR cluster, so schedule the upgrade to take place outside of peak hours
to avoid any business impacts.
## 2.5 to 2.6 upgrade
> Upgrade Best Practices
>
> There are [important changes to the upgrade process](/ee/upgrade) that, if not correctly followed, can have impact on the availability of applications running on the Swarm during upgrades. These constraints impact any upgrades coming from any version before `18.09` to version `18.09` or greater. See [Cluster Upgrade Best Practices](/ee/upgrade.md#cluster-upgrade-best-practices) for more details. Additionally, to ensure high availability during the DTR upgrade, you can also drain the DTR replicas and move their workloads to updated workers. To do this, you can join new workers as DTR replicas to your existing cluster and then remove the old replicas. See [docker/dtr join](/reference/dtr/2.7/cli/join/) and [docker/dtr remove](/reference/dtr/2.7/cli/remove/) for command options and details.
> [Important changes have been made to the upgrade process](/ee/upgrade) that, if not correctly followed, can have impact on the availability of applications running on the Swarm during upgrades. These constraints impact any upgrades coming from any version before `18.09` to version `18.09` or greater. Refer to [Cluster Upgrade Best Practices](/ee/upgrade.md#cluster-upgrade-best-practices) for more details.
>
> In addition, to ensure high availability during the DTR upgrade, drain the DTR replicas and move their workloads to updated workers. This can be done by joining new workers as DTR replicas to your existing cluster and then removing the old replicas. Refer to [docker/dtr join](/reference/dtr/2.7/cli/join/) and [docker/dtr remove](/reference/dtr/2.7/cli/remove/) for command options and details.
## 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/article/compatibility-matrix).
* You have a recent [DTR backup](disaster-recovery/create-a-backup).
* You [disable Docker content trust in UCP](/ee/ucp/admin/configure/run-only-the-images-you-trust/).
* You [meet the system requirements](install/system-requirements).
Before starting the upgrade, confirm that:
* The version of UCP in use is supported by the upgrade version of DTR. [Check the compatibility matrix](https://success.docker.com/article/compatibility-matrix).
* The [DTR backup](disaster-recovery/create-a-backup) is recent.
* [Docker content trust in UCP is disabled](/ee/ucp/admin/configure/run-only-the-images-you-trust/).
* [All system requirements are met](install/system-requirements).
### Step 1. Upgrade DTR to {{ previous_version }} if necessary
Make sure you are running DTR {{ previous_version }}. If that is not the case,
[upgrade your installation to the {{ previous_version }} version](/datacenter/dtr/{{ previous_version }}/guides/admin/upgrade/).
Confirm that you are running DTR {{ previous_version }}. If this is not the case, [upgrade your installation to the {{ previous_version }} version](/datacenter/dtr/{{ previous_version }}/guides/admin/upgrade/).
### Step 2. Upgrade DTR
Then pull the latest version of DTR:
Pull the latest version of DTR:
```bash
docker pull {{ page.dtr_org }}/{{ page.dtr_repo }}:{{ page.dtr_version }}
```
Make sure you have at least [16GB of available RAM](install/system-requirements) on the node you are running the upgrade on. If the DTR node does not have access to the internet, you can
follow the [offline installation documentation](install/install-offline)
to get the images.
Confirm that at least [16GB RAM is available](install/system-requirements) on the node on which you are running the upgrade. If the DTR node does not have access to the internet, follow the [offline installation documentation](install/install-offline) to get the images.
Once you have the latest image on your machine (and the images on the target
nodes if upgrading offline), run the upgrade command:
nodes, if upgrading offline), run the upgrade command.
> Note:
>
> The upgrade command can be run from any available node, as UCP is aware of of which worker nodes have replicas.
```bash
docker run -it --rm \
{{ page.dtr_org }}/{{ page.dtr_repo }}:{{ page.dtr_version }} upgrade
```
By default the upgrade command runs in interactive mode and prompts you for
By default, the upgrade command runs in interactive mode and prompts for
any necessary information. You can also check the
[upgrade reference page](/reference/dtr/2.7/cli/upgrade/) for other existing flags.
If you are performing the upgrade on an existing replica, pass the `--existing-replica-id` flag.
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
fails or the upgrade is interrupted for any reason, you can rerun the upgrade
command and it will resume from where it left off.
fails or the upgrade is interrupted for any reason, rerun the upgrade
command (the upgrade will resume from the point of interruption).
#### Metadata Store Migration
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](/ee/dtr/admin/manage-jobs/audit-jobs-via-ui/) for more details.
When upgrading from `2.5` to `2.6`, the system will run a `metadatastoremigration` job following 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 into the DTR web interface and navigate to **System > Job Logs** to check the status of the `metadatastoremigration` job. Refer to [Audit Jobs via the Web Interface](/ee/dtr/admin/manage-jobs/audit-jobs-via-ui/) for more details.
![](../images/migration-warning.png){: .with-border}
@ -99,7 +94,7 @@ Garbage collection is disabled while the migration is running. In the case of a
![](../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:
If the three attempts fail, it will be necessary to manually retrigger the `metadatastoremigration` job. To do this, send a `POST` request to the `/api/v0/jobs` endpoint:
```bash
curl https://<dtr-external-url>/api/v0/jobs -X POST \
@ -110,16 +105,15 @@ Alternatively, select **API** from the bottom left navigation pane of the DTR we
## Patch upgrade
A patch upgrade changes only the DTR containers and is always safer than a minor version
upgrade. The command is the same as for a minor upgrade.
A patch upgrade changes only the DTR containers and is always safer than a minor version upgrade. The command is the same as for a minor upgrade.
## DTR cache upgrade
If you have previously [deployed a cache](/ee/dtr/admin/configure/deploy-caches/), make sure to [upgrade the node dedicated for your cache](/ee/upgrade) to keep it in sync with your upstream DTR replicas. This prevents authentication errors and other weird behaviors.
If you have previously [deployed a cache](/ee/dtr/admin/configure/deploy-caches/), be sure to [upgrade the node dedicated for your cache](/ee/upgrade) to keep it in sync with your upstream DTR replicas. This prevents authentication errors and other strange behaviors.
## Download the vulnerability database
After upgrading DTR, you need to redownload the vulnerability database.
After upgrading DTR, it is necessary to redownload the vulnerability database.
[Learn how to update your vulnerability database](configure/set-up-vulnerability-scans.md#update-the-cve-scanning-database).
## Where to go next