Configuring prerequisites, building, and deploying the migration pod

note

The migration steps on this page are applicable for migration from untethered to untethered and tethered to tethered deployment.

Before you begin

Back up APIM 5.x.x MySQL database

Back up your existing APIM 5.x.x MySQL database. You can restore the database from this backup in the event of an adverse situation.
Extract 6.x.x migration package

Starting with version 6.1.0, the migration package is included in the 6.x.x installer. Extract the tar xvf migrate_5x_to_6.tar.gz migration package.

Configuring prerequisites for migration

Complete the following prerequisite and configuration setup before migrating within the same deployment mode (untethered → untethered or tethered → tethered) from 5.x.x to 6.1.0 or 5.x.x to 6.2.0:

Step 1: Customize migration configuration

Customize mysql_secret.yaml

You can find the mysql_secret.yaml file at the following path: <extract_location>/migrate_5x_to_6/mysql_secret.yaml.

In mysql_secret.yaml, modify the values listed in the following table:

Key	Action
`namespace`	Set it to `default`. The namespace value used by Local Edition versions 5.3.x, 5.4.x, 5.5.x, and 5.6.x.
`username_apim5`	Set it to `masheryonprem`. Do not change this value.
`password_apim5`	Provide the MySQL password used by Local Edition versions 5.3.x, 5.4.x, 5.5.x, and 5.6.x.
`username_apim6`	Set it to `masheryonprem`. It is the username you created for deploying Local Edition 6.x.x runtime.
`password_apim6`	Provide the MySQL password used by Local Edition 6.x.x.

This information applies to LE v6.1.0+:

The value for password_apim5 and password_apim6 is encoded as a base64 value: echo -n changeme | base64

Customize migration.yaml

In migration.yaml, modify the values listed in the following table:

Key	Action
`namespace`	Set it to `default`. The namespace value used by Local Edition versions 5.3.x, 5.4.x, 5.5.x, and 5.6.x. This applies to `migration-pvc` PersistentVolumeClaim, `migration-pod`, `MYSQL_HOST_APIM5`, and `CASSANDRA_HOST`.
`image`	Set it to `us.gcr.io/mashery-cloud-operations/migration:5x-6.1` if migrating to 6.1.0, or `us.gcr.io/mashery-cloud-operations/migration:5x-6.2` if migrating to 6.2.0. The container registry and repository used by Local Edition versions 5.3.x, 5.4.x, 5.5.x, and 5.6.x.
`APIM5_RELEASE_VERSION`	Provide the version of your APIM 5 deployment. For example, `5.6.2`.
`APIM5_MODE`	Set your APIM 5 instance deployment mode to `untethered`.
`APIM6_RELEASE_VERSION`	Set the version of your APIM 6 deployment to `6.1.0` or `6.2.0`.
`APIM6_MODE`	Set your APIM 6 instance deployment mode to `tethered`.
`MYSQL_HOST_APIM6`	Provide the hostname of your MySQL service host.
`MYSQL_PORT_APIM6`	Update the MySQL service port to `3306`.
`MYSQL_DATABASE_APIM6`	Update your MySQL database to `masherysolar`.
`MYSQL_SERVICE_SSL_MODE`	Set the TLS verification mode for the APIM6 MySQL connection to `trust`. Options for your MySQL service host: `disable`: Do not use SSL/TLS. No key or certificate is required. `trust`: Only use SSL/TLS for encryption. Do not perform certificate or hostname verification. No key or certificate is required. `verify-ca`: Requires a CA certificate. Use SSL/TLS for encryption and perform certificate verification. Do not perform the hostname verification. `verify-full`: Requires a CA certificate. Use SSL/TLS for encryption, certificate verification, and hostname verification.
`MYSQL_SERVICE_MUTUAL_TLS`	This is for your MySQL service host. Set it to `disable`.
`storage`	Set it to `10Gi`. For `migration-pvc` PersistentVolumeClaim, the default value is sufficient when you have fewer than 1 million tokens.

Building and deploying the migration pod

With your prerequisites configuration in place, complete the following steps to build, deploy, and connect the migration pod.

Step 1: Build migration container images

In the extracted migration package folder, run the following command:

./docker_build_migration.sh

Step 2: Push migration container images to a registry

Log in to the container registry before pushing migration container images. In the extracted migration package folder, run the following command:

./docker_push_migration.sh

Step 3: Deploy migration pod on 5.x.x cluster

From the root of the extracted package folder, run:

./deploy_migration.sh

The migration-pod with the migration-container is deployed in the Local Edition 5.3.x, 5.4.x, 5.5.x, and 5.6.x clusters. It has access to the:

tml-sql pod and tml-nosql pod in the Local Edition 5.3.x, 5.4.x, 5.5.x, and 5.6.x cluster.
Mounted data volume and the MySQL service that is used by the Local Edition 6.1.0 or 6.2.0 cluster.

Next steps: Migrate your data

Migrate your configuration data, tokens, and CMS. Refer to Migrating your data from 5.x.x to 6.1.0 or 6.2.0 for more information.