Crossing several WSO2 major versions without losing your API estate

Overview

WSO2 API Manager upgrades that cross multiple major versions are migrations, not upgrades. Registry structure, API definitions, throttling policy models, and identity integration all change, and the migration tooling assumes a clean starting state that most long-running deployments do not have.

Challenge

The deployment was several major versions behind, with customized carbon components, hand-edited synapse configurations, and a user store integration built against an older identity model. An in-place upgrade path did not exist across that span, and the API catalog served applications across multiple campuses that could not all be coordinated for a single outage.

Environment

WSO2 API Manager and Identity Server on-premises with campus-specific tenants, integrating LDAP-backed identity and a shared student information system.

Approach

AceMQ designed a parallel-build migration: stand up the target version cleanly, migrate API definitions and subscriptions in controlled batches, and cut traffic over per tenant. Customizations were re-evaluated rather than ported, because several existed to work around behavior the newer version handles natively.

Solution

• Inventoried APIs, subscriptions, throttling policies, and customizations against target-version support
• Built the target deployment in parallel rather than attempting a multi-version in-place upgrade
• Re-evaluated each customization, retiring those that worked around now-native behavior
• Migrated API definitions and subscriptions in batches with automated verification per batch
• Reworked identity and user store integration for the newer identity model
• Cut traffic per tenant with rollback available at each step

Outcome

Technologies