Skip to main content
Feedback

Building and deploying the migration pod for different deployment modes

With your prerequisites configuration in place, complete the following steps to build, push, deploy, and connect the migration pod, then run the preflight checklist before migrating entities.

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 CAM Platform API secrets and MySQL secrets, and configuring the migration-specific TLS settings as covered in Configuring prerequisites for migration across deployment modes.

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 secrets — providing the CAM Platform API secrets and MySQL secrets, and configuring the migration-specific TLS settings as covered in Configuring prerequisites for migration across deployment modes.

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

Step 5: Preflight checklist

Before you start migrating entities, perform these mandatory steps from inside the migration pod.

  1. Check connectivity.

    Ensure all four connections migrate.py --connection are reachable. If a connection fails, check the host and port values in migration-override.env and confirm whether the migration pod can reach that host.

    The following is sample output of migrate.py --connection when all endpoints are reachable:

    --- Connection status ---
    Target           Status   Message
    ---------------- -------- ----------------------------------------
    APIM5_DB         OK       Connection successful
    CAM6_DB          OK       Connection successful
    APIM5_API        OK       Connection successful
    CAM_SAAS_API     OK       Connection successful
    Connection status check finished

  2. One-time setup (prerequisite)

    Before your first entity migration, run this one-time setup:

    migrate.py --prerequisite

    You can also re-run it if needed. This creates the migration_entity_mapping table in the APIM 5.x.x database by default. The table name is configurable in the migration-override.env file. Without this table, no migration command can run.

Next steps: Migrate your data

Migrate your entities - organization, role, member, trust store, identity store, HTTPS client profile, domain, API definition, error set, endpoint, package, plan, application, and package key. Refer to Migrating your data for more information.

On this Page