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

Migration documentation for interlock

This commit is contained in:
Jules Testard 2018-03-13 11:38:11 -07:00 committed by Jim Galasyn
parent 2b3631c109
commit 50c2475dce
1 changed files with 67 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
ee/ucp/interlock/migration.md Normal file
View File

@ -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.