Skip to main content
Feedback

Migrating from 5.x.x to 6.3.0 (untethered → untethered or tethered → tethered)

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 your existing APIM 5.x.x MySQL database. You can restore the database from this backup in the event of an adverse situation.

note

Starting with version 6.1.0, the migration package is included in the 6.x.x installer. Refer to About the migration package for more information on the latest migration package.

Configuring prerequisites for migration

Complete the following prerequisites configuration steps before migrating within the same deployment mode (untethered → untethered or tethered → tethered) from 5.x.x to 6.3.0:

Step 1: Provide MySQL secrets

Refer to Providing MySQL secrets to provide the mysql-secret-apim5 and mysql-secret-cam6 credentials.

Step 2: Provide TLS setup (Conditional step)

If your MySQL connection requires TLS, refer to Providing TLS setup to configure migration-specific TLS settings.

Step 3: Customize migration configuration

Refer to Customizing migration configuration to configure migration-override.env.

Building and deploying the migration pod

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

warning

The scripts referenced in the Build and Push migration container images steps are for user reference only. You must update them to match your environment.

Step 1: Build migration container images

build-images.sh is located in the root of the 6.3.0 GA migration package folder. Do not modify this file path.

From the root of the 6.3.0 migration package, run:

./build-images.sh -c docker -i cam-le-migration-5x
  • -c docker: build tool (use podman if preferred)
  • -i cam-le-migration-5x: build only the migration image

Base images (apim-le-toolkit, apim-jre-base) are built automatically. Pass -n to reuse existing ones instead:

./build-images.sh -c docker -n -i cam-le-migration-5x

Step 2: Push migration container images to a registry

push-images.sh lives in scripts/ and sources its vars relative to itself, so run it from that directory. -r <registry> is required:

cd scripts
./push-images.sh -c docker -r <registryuri>/[repository] -i cam-le-migration-5x

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

Previously, the migration pod could only be deployed on Kubernetes, regardless of your APIM 5.x.x infrastructure. As of 6.3.0, it can also be deployed on Docker Swarm. Deploy the migration pod on whichever infrastructure matches your APIM 5.x.x source cluster, not your target infrastructure.

For example, if your APIM 5.x.x cluster runs on Docker Swarm (untethered) but you're moving to a Kubernetes-based (tethered) Local Edition 6.x.x deployment, set up the migration pod on Docker Swarm, since it needs direct access to your APIM 5.x.x cluster.

Deploy on Kubernetes (default)

note

Before deploying on Kubernetes, ensure you have set up the prerequisite secrets — providing the MySQL secrets, and configuring the migration-specific TLS settings as covered in Configuring prerequisites for migration section.

If your APIM 5.x.x cluster runs on Kubernetes, deploy the migration pod on K8s. Complete the following steps to set up the migration pod for Kubernetes-based APIM 5.x.x deployment:

Procedure

  1. Deploy the migration container.

    All scripts are located at migrate_5x_to_6/scripts/. Run all commands from this directory. The ./deploy.sh script reads the template files and automatically creates all secrets.

    cd migrate_5x_to_6/scripts
    ./deploy.sh              # Kubernetes (default)
    # or explicitly:
    ./deploy.sh --env k8s

    You can safely re-run the deploy script. It updates existing ConfigMaps and Secrets without errors.

  2. Update credentials later.

    If you need to rotate a password or update a certificate after the initial deployment, update the relevant template file and either re-run ./deploy.sh or apply only the changed file manually:

    kubectl apply -f migrate_5x_to_6/templates/k8s/mysql-secret.yaml
    kubectl apply -f migrate_5x_to_6/templates/k8s/api-secret.yaml

Deploy on Docker Swarm

note

Before deploying on Docker Swarm, ensure you have set up the prerequisite database credentials (APIM 5.x.x and CAM 6.x.x) — providing the MySQL secrets, and configuring the migration-specific TLS settings, as covered in Configuring prerequisites for migration section.

If your APIM 5.x.x cluster runs on Docker Swarm, deploy the migration pod on Swarm. Complete the following steps to set up the migration pod for Docker Swarm-based APIM 5.x.x deployment:

Procedure

Deploy the migration container:

cd migrate_5x_to_6/scripts
./deploy.sh --env swarm
warning
  • The migration_migration-data volume is retained after undeploy. Remove it only after migration is fully complete: docker volume rm migration_migration-data.
  • Secrets and configs created by create_secrets.sh are not removed by undeploy.sh. Remove them manually only when permanently decommissioning the migration environment.

Step 4: Connect to the migration pod

All migrate.py commands are run inside the migration pod. Connect to the migration pod based on your deployment mode Kubernetes or Docker Swarm:

# Kubernetes
kubectl exec -it migration-pod -- /bin/bash

# Docker Swarm — find the container name first
docker ps | grep migration
docker exec -it <container-name> /bin/bash

Then, to see all commands and flags:

migrate.py --help    # or: migrate.py -h

Next steps: Migrate your data

Migrate your configuration data, tokens, and CMS data. Follow the same steps as migrating data from 5.x.x to 6.1.0 or 6.2.0 within the same deployment mode. Refer to Migrating your data within the Migrate from 5.x.x to 6.1.0 or 6.2.0 (Same mode) section for more information.

On this Page