Skip to main content
Feedback

Migrating your data

The data migration steps on this page are applicable for migration from 5.x.x to 6.3.0.

warning

Local Edition 6.1.0 and later no longer support untethered deployment. Migration from 5.x.x (untethered) to 6.3.0 (tethered) is a one-way process. There is no rollback to untethered mode once migration is complete.

Before you begin

Before migrating your data, ensure you have completed prerequisites and built, pushed, and deployed the migration pod, including the preflight checklist.

  1. Check connectivity. Run migrate.py --connection to ensure all four connections are reachable.

  2. Run the one-time prerequisite setup: migrate.py --prerequisite.

Migrate entities in the order listed below (Phases 1-5), and do not skip ahead. Not every step depends on the one immediately before it — some steps have no dependencies, while others depend on a specific earlier step, as noted at the start of each step. After each step, run --status to confirm there are no failures before moving on. If failures exist, re-run the same command. Failed entities are retried automatically, and already-migrated ones are skipped.

Phase 1: User and access

Step 1: Migrate organization

This step has no dependencies and must be completed first. Roles and members belong to organizations, so organizations must be migrated to the target environment (CAMLE 6.x.x DB) before roles and members can be created.

To migrate the Organization entity, run the following command:

# Step 1 — Organization
migrate.py --organization
migrate.py --organization --status

Running migrate.py --organization automatically handles both root organizations and sub-organizations in the correct order.

Step 2: Migrate role

This step depends on the Organization migration. Complete migrating organization before running this step.

Roles are created under a specific organization, so the organization must exist on the target before roles can be migrated. Members are then assigned to these roles, so roles must be migrated before members.

To migrate the Role entity, run the following command:

# Step 2 — Role (after organization)
migrate.py --role
migrate.py --role --status

Step 3: Migrate member

This step depends on the Organization and Role migration. Complete migrating organization and role before running this step. Before running this step, manually create a valid administrator user on the Cloud API Management (SaaS) target via the Cloud API Management SaaS Control Center. The migration will fail without it.

Members are assigned to organizations and roles, so both must exist in the target environment before members can be migrated.

To migrate the Member entity, run the following command:

# Step 3 — Member (after role + organization; create SaaS admin user first)
migrate.py --member
migrate.py --member --status
  • Developer Portal users cannot log in until they reset their password. There is a 24-hour restriction on password changes after account creation in Cloud API Management (SaaS).
  • Cloud API Management (SaaS) users log in via Platform, not the Developer Portal.

Phase 2: Certificates and TLS

note

A loader sync is required after completing trust store and identity store migration in this phase, before you can proceed to HTTPS Client Profile. The steps for this are covered later in this phase, after Step 5.

Step 4: Migrate trust store

This step has no dependencies on other entities but requires CAM6_AREA_ID to be set in migration-override.env before running.

Trust store runs in two phases:

  1. First run: Copies each certificate to the CAMLE 6.x.x DB. The UUID is assigned by the CAM 6.x.x loader and is not yet available.
  2. After loader sync, re-run: The migration tool reads the UUIDs assigned by the loader and records them. You cannot migrate HTTPS client profile until the migration of the trust store is complete.

Re-runs are always safe. Unlike other entities, the Trust store does not support retrying a single certificate using --uuid. If a certificate fails, re-run the Trust store to retry all failed certificates. Any certificates renewed in the APIM 5.x.x DB are automatically picked up on every re-run.

To migrate the trust store entity, run the following command:

# Step 4 — Trust store
migrate.py --trust_store
migrate.py --trust_store --status

Step 5: Migrate identity store

Set CAM6_AREA_ID in migration-override.env before running this step. This step has no dependencies on other entities.

To migrate the Identity Store entity, run the following command:

# Step 5 — Identity Store
migrate.py --identity_store
migrate.py --identity_store --status

Run loader job, re-run trust store and identity store

After completing the identity store migration, run a loader sync, and then re-run the migration for both the trust store and the identity store before proceeding to migrate the HTTPS client profile. Trust store and identity store certificates are written directly to the CAMLE 6.x.x database and will not be visible to Cloud API Management (SaaS) until the loader job syncs them.

Run the job below and wait for it to complete:

kubectl create job --from=cronjob/loader-job-full manual-full-apimload-job-certs
kubectl get jobs -w | grep manual-full-apimload-job-certs

Step 6: Migrate HTTPS client profile

This step depends on completing trust store and identity store migration, including the loader sync and re-run (to record the UUIDs assigned by the loader) described in Run loader job and re-run trust store and identity store section.

# Step 6 — HTTPS Client Profile
# Re-run trust_store and identity_store first to record target UUIDs assigned by the loader
migrate.py --trust_store
migrate.py --identity_store
migrate.py --https_client_profile
migrate.py --https_client_profile --status
  • Profiles with no identity store assigned migrate successfully.
  • Each Trust store entry is resolved individually. Profiles with some unresolvable trust entries still migrate with the remaining resolved trusts.
  • Trust store entries are migrated as part of the HTTPS Client Profile. No separate migration command is needed.

Phase 3: API Catalog

Step 7: Migrate domain

This step has no dependencies on other entities. Migrate all domains before proceeding to migrate API definition.

# Step 7 — Domain
migrate.py --domain
migrate.py --domain --status

Step 8: Migrate API definition

This step depends on the Domain migration. Complete migrating domain before running this step.

# Step 8 — API Definition (after domain)
migrate.py --api_definition
migrate.py --api_definition --status

Step 9: Migrate error set

This step depends on the API Definition migration. Complete migrating API definition before running this step. Error Messages are migrated automatically as part of this step; no separate command is needed.

  • To migrate error sets for a single service, run --api_definition_id.
  • To migrate a single error set, run --uuid.
# Step 9 — Error Set (after api_definition; includes Error Messages)
migrate.py --error_set
migrate.py --error_set --status

Step 10: Migrate endpoint

This step depends on the API Definition migration. Complete migrating API Definition before running this step.

# Step 10 — Endpoint (after api_definition)
migrate.py --endpoint
migrate.py --endpoint --status

Phase 4: Packaging

Step 11: Migrate package

This step depends on the API Definition migration. Complete migrating API Definition before running this step.

# Step 11 — Package (after api_definition)
migrate.py --package
migrate.py --package --status

Step 12: Migrate plan

This step depends on the Package migration. Complete migrating package before running this step.

# Step 12 — Plan (after package)
migrate.py --plan
migrate.py --plan --status

Phase 5: Applications and keys

Step 13: Migrate application

This step depends on the Member migration. Complete migrating member before running this step.

# Step 13 — Application (after member)
migrate.py --application
migrate.py --application --status

Step 14: Migrate package key

This step depends on the Package and Application migration. Complete migrating package and application before running this step.

# Step 14 — Package Key (after package + application)
migrate.py --package_key
migrate.py --package_key --status

Next steps: Perform post-migration

After completing the data migration, proceed with the post-migration steps. Refer to Performing post-migration steps for more information.

On this Page