1 - What is AMU?
AMU (API Connect Migration Utility) — also called the migration-cli — is IBM's command-line tool for moving your IBM API Connect configuration from one deployment to another. It handles the heavy lifting: reading your existing data, transforming it into the target format, and loading it into the new system via REST API calls.
Think of AMU as a two-step bridge between your old and new API Connect environments:
Source system
(backup/archive)
↓
AMU unpack
Extract & convert
↓
YAML files
(canonical format)
↓
AMU push
Publish via API
↓
Target v10
system
Core idea AMU never modifies your source system. It reads a backup archive, writes YAML files you can inspect and edit, and only then pushes them to the target. You are always in control of the intermediate data.
2 - The Two Migration Paths
Path A — v5 → v10
Moving from API Connect v5 (the legacy DataPower Gateway / V5-compatible gateway deployment) to a fresh IBM API Connect v10 environment. This is a platform upgrade that also involves gateway technology changes.The utility connects to the source API Connect environment and extracts supported assets, Maps source identifiers to target identifiers, Resolves environment-specific differences, Updates references and dependencies, Validates data consistency and Removes unsupported configurations where required then after transformation, the utility imports the processed artifacts into the target IBM API Connect v10 environment.
Path B — v10 → v10
AMU is designed primarily for IBM API Connect v10 to the conversion of APIs and Products from the V5 Compatible Gateway (v5c) format to the API Gateway format. During the migration process, the port-to-apigw-v10 command analyzes and converts supported gateway-specific policies, configurations, and assembly definitions, preparing the exported assets for deployment on API Gateway in the target IBM API Connect v10 environment. This capability is commonly used when modernizing existing v5c-based API implementations and standardizing on API Gateway within API Connect v10.
Both paths use the same two-phase pattern (unpack then push), but the commands, archive formats, supported artifacts, and edge cases differ significantly.
3 - Path A: v5 → v10 Migration
Where it starts — the v5 backup archive
Your v5 system is backed up as a .tar.gz file (the v5 backup archive). Optionally, you may also have a PDUR archive for Provider and Developer User Registries. AMU reads both files using the archive:unpack command.
Phase 1 — Unpack (archive:unpack)
1 Run the unpack command
apicm archive:unpack v5-backup.tar.gz [pdur-backup.tar.gz]
2 AMU loads the v5 database
The tool reads provider orgs, catalogs, APIs, products, apps, subscriptions, consumer orgs, members, user registries, TLS profiles, OAuth providers, and policies from the v5 archive and stores them in a local SQLite staging database (v5data.db).
3 AMU converts the data
Every v5 object is mapped to the v10 (v2018+) YAML format. Role names are remapped (e.g. admin → administrator, prodmgr → community-manager), APIs are converted to OpenAPI 3 where possible, and V5-compatible gateway policies are translated to API Gateway equivalents.
4 Output — a cloud/ directory
AMU writes a structured folder tree under cloud/ containing all your configuration as editable YAML files, ready to review, customise, and push.
Gateway compatibility note v5 used V5-compatible gateway APIs. v10 uses the new DataPower API Gateway. AMU translates what it can automatically, but some policy constructs (e.g. custom gateway scripts) may need manual adjustment after unpacking.
The cloud/ output structure
After unpacking, the directory looks like this:
cloud/
configuration-mappings.yaml
cloud-settings.yaml
topology.yaml
resources/
user-registries/
tls-profiles/
...
provider-orgs/
MyOrg/
org-settings.yaml
org-members.yaml
catalogs/
Sandbox/
catalog-settings.yaml
consumer-orgs/
apps/
...
draft-apis/
draft-products/
Phase 2 — Push (archive:push)
Push to Cloud Manager: Creates and migrates provider-level resources such as Provider Organizations, users, and identity mappings in the target API Connect environment.
Push to API Manager: Imports Catalogs, APIs, Products, Consumer Organizations, Applications, and Subscriptions while preserving relationships and dependencies.
5 Dry-run validation
apicm archive:push <cloud/api manager server> cloud/ --dry-run validates everything without writing to the target.
6 Push to target v10
apicm archive:push <cloud/api manager server> cloud/ authenticates against the v10 management server and replays all objects via REST API calls.
Key flags for v5 → v10
| Flag |
What it does |
--provider-orgs |
Unpack only the listed provider orgs (useful for incremental or selective migrations) |
--sluggify-no-checksum |
Disables the checksum suffix added to resource names — use if your target has known naming constraints |
--apigw-only |
Push only API Gateway products (skips V5-compatible products) |
--no-drafts |
Skips draft APIs and products during push |
--dry-run |
Validates without writing — always run this first |
--catalogs |
Limit push to specific catalogs |
4 - Path B: v10 → v10 Migration
Where it starts — the v10 backup archive
Your source v10 system is backed up as a single archive (the v10 backup archive). This archive contains the same logical objects as before, but in a different format — it is no longer a SQL/BoltDB export but a structured archive of the v10 management layer. AMU reads it using the archive:unpack-v10 command.
Phase 1 — Unpack (archive:unpack-v10)
1 Run the unpack-v10 command
apicm archive:unpack-v10 v10-backup.tar.gz
2 AMU processes the v10 archive
The tool extracts provider orgs, catalogs, spaces, APIs, products, apps, subscriptions, consumer orgs, members, keystore/truststore entries, user registries, TLS profiles, OAuth providers, and gateway extensions. Only API Gateway artifacts are extracted by default.
3 Output — a cloud-v10/ directory
AMU writes a cloud-v10/ folder tree with the same logical structure as cloud/ but using the v10 API model schemas. The directory is separate to allow both migration types to coexist in one workspace.
Phase 2 — port-to-apigw-v10 (archive:port-to-apigw-v10)
4 Port to v5 Gateway to API Gateway v10
apicm archive:port-to-apigw-v10 cloud-v10/ the conversion of APIs and Products from the V5 Compatible Gateway (v5c) format to the API Gateway format.
Phase 3 — Push (archive:push-v10)
5 Push to target v10
apicm archive:push-v10 <server> cloud-v10/ replays all extracted objects to the new v10 system.
Advanced v10 → v10 scenarios
Subscription migration
By default, subscriptions are recreated. Use --move-subscriptions during push to move subscriptions with their original subscription IDs preserved (requires target platform support).
Partial migrations
Use --catalogs, --spaces, and --products flags on push to target only a subset of the extracted data — ideal for phased cut-overs.
Key flags for v10 → v10
| Flag |
Phase |
What it does |
--provider-orgs |
unpack |
Extract only the listed provider orgs |
--move-provider-orgs |
unpack |
Extract a porg for cross-cloud-manager move (requires encryption file) |
--reserved-instance |
unpack |
Activate Reserved Instance mode |
--unpack-all |
unpack |
Extract all orgs even those with no API Gateway products |
--catalogs |
push |
Limit push to specific catalogs |
--spaces |
push |
Limit push to specific spaces within a catalog |
--products |
push |
Limit push to specific products (name:version) |
--move-subscriptions |
push |
Move subscriptions preserving original IDs |
--move-provider-org |
push |
Activate cross-cloud-manager porg move mode |
--dry-run |
push |
Validate without writing to target |
--overwrite |
push |
Overwrite existing objects on the target |
--no-drafts |
push |
Skip draft APIs and products |
--drafts-only |
push |
Push only draft APIs and products |