From 50c2475dce8f0f41a107fc8046f9a52cccbc1574 Mon Sep 17 00:00:00 2001 From: Jules Testard Date: Tue, 13 Mar 2018 11:38:11 -0700 Subject: [PATCH] Migration documentation for interlock --- ee/ucp/interlock/migration.md | 67 +++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 ee/ucp/interlock/migration.md diff --git a/ee/ucp/interlock/migration.md b/ee/ucp/interlock/migration.md new file mode 100644 index 0000000000..b4b0d99834 --- /dev/null +++ b/ee/ucp/interlock/migration.md @@ -0,0 +1,67 @@ +# Migration + +In Docker EE UCP 2.X, the layer 7 routing of the platform was implemented using HRM. Starting with Docker EE UCP 3.X, the layer 7 routing is now implemented using Interlock. This article describes the process in which the migration from HRM to Interlock happens. + +For context, let me recap on the HRM to interlock migration process: + +0. HRM service is already enabled and configured by the customer. +1. Migration from 2.2.4 to 3.0 starts +2. Reconcilation process for interlock starts and HRM service is inspected. +3. An interlock config is created from the HRM service spec and deployed as a docker config +4. The HRM service is removed. +5. The interlock service is deployed. +6. The interlock extension and proxy service are deployed by the interlock service. + +Currently, this process is not atomic, so any failure along the way will not result in the reversal of previous steps. In any case, if a failure occurs today the migration would need manual fixing to operate normally again. + +In the following section, I cover different failure points, how to diagnostic, and to solve (when possible) from a customer/support standpoint. + +### Before starting migration + +**TODO**: Information [on interlock manual deploymenbt](https://beta.docs.docker.com/ee/ucp/interlock/install/manual-deployment/#deployment) is incorrect. Please update with procedure in this PR: https://github.com/docker/orca/issues/12227. + +#### Migration check procedure + +Record which of your HRM-enabled applications are routable through HRM by doing a curl request: + + - For HTTP apps: ```curl -vs http://${CLUSTER_ID}:${HRM_HTTP_PORT}/ -H "Host: ${HOSTNAME}"``` + - For HTTPS apps: ```curl -vs http://${HOSTNAME}:${HRM_HTTPS_PORT}"``` + +When the migration, check that all applications that where routable before the migration still are. + +#### Failure happens during step 1 before step 2 + +Not related to HRM interlock migration + +#### Failure happens during step 2 before step 3 + +Codepath: https://github.com/docker/orca/blob/master/agent/agent/components/interlockservice/interlockservice.go + + - **Diagnostic**: Only happens if the HRM service gets deleted somehow after being detected as present but before the migration to interlock starts. + - **Resolution**: Follow the *manual hrm migration* procedure. + +#### Failure happens during step 3 before step 4 + + - **Diagnostic**: `ucp-hrm` is still present, but the config `com.docker.ucp.interlock.conf-1` could not be created. Could happen due to name conflicts. + - **Resolution**: Follow the *manual hrm migration* procedure. + +#### Failure happens during step 4 before step 5 + + - **Diagnostic**: `ucp-hrm` failed to remove. The ucp interlock config is already created. Only happens if the service delete operation for the `ucp-hrm` service fails for some reason (unlikely). + - **Resolution**: Follow the *manual hrm migration* procedure, but replace the interlock swarm config name from `com.docker.ucp.interlock.conf-1` to `com.docker.ucp.interlock.conf-2`. + +#### Failure happens during step 5 before step 6 + + - **Diagnostic**: The `ucp-interlock` service failed to deploy. Only happens if the service create operation for the `ucp-interlock` service fails for some reason (unlikely). + - **Resolution**: Enable interlock through the UI, making sure that the `PublishedPort` and `PublishedSSLPort` match the http and https ports you were using with HRM. + +#### Failure happens during step 6 + + - **Diagnostic**: The `ucp-interlock-extension` or `ucp-interlock-proxy` services failed to deploy. May happen if there is a port conflict. + - **Resolution**: Disable and then re-enable interlock through the UI, making sure that the `PublishedPort` and `PublishedSSLPort` match the http and https ports you were using with HRM. + +#### Manual Migration procedure + + 1. delete the `ucp-hrm` service. + 2. Enable interlock manually (https://beta.docs.docker.com/ee/ucp/interlock/install/manual-deployment/), but instead of creating a new overlay network called `ucp-interlock`, reuse the existing `ucp-hrm`. + 3. Wait until the service named `ucp-interlock-proxy` is deployed with all replicas and then try the *migration check procedure* again.