Upgrading from webMethods API Management to API Connect v12.1.1 OVA with apicupgrade CLI
Introduction
IBM API Connect supports upgrading webMethods API Management deployments to API Connect v12. With API Connect v12.1.1, the apicupgrade utility introduces support for upgrading directly to VMware (OVA) deployments, extending the existing support for Kubernetes and Red Hat OpenShift Container Platform (OCP) environments.
This blog explores the VMware (OVA) deployment model in IBM API Connect, explains how it differs from traditional installer-based deployments, and provides an overview of the upgrade workflow using the apicupgrade utility.
What's New in API Connect v12.1.1?
When the apicupgrade utility was introduced in API Connect v12.1.0.x, it enabled customers to upgrade from webMethods API Management to API Connect deployments running on Kubernetes and Red Hat OpenShift Container Platform (OCP).
With API Connect v12.1.1, this capability has been extended to include VMware (OVA) deployments. Organizations can now use the same apicupgrade workflow to upgrade webMethods API Management deployments directly to an OVA-based API Connect environment.
From Installer-Based Deployments to API Connect OVA
If you're coming from the webMethods API Management world, you're accustomed to deploying products such as API Gateway, Developer Portal, and API Control Plane by running the Software AG installer, selecting the required components, configuring installation directories, and managing configuration files. Each product is installed and managed independently on the underlying operating system.
IBM API Connect VMware (OVA) adopts a different deployment model. Instead of installing individual software components, each API Connect subsystem is provided as a pre built Open Virtualization Appliance (OVA) that is imported directly into VMware vSphere. Each subsystem, including API Manager, webMethods API Gateway, Developer Portal, and Analytics, runs in its own virtual machine.
The OVA image includes the operating system, an embedded Kubernetes platform, and the API Connect software stack, eliminating the need to install or manage these components separately. After importing the appliance and completing the initial bootstrap configuration, the subsystem is ready to be configured using the apicup command-line utility.
For webMethods administrators, the biggest change is not the upgrade process itself, but the deployment model. Instead of configuring software installed on a host operating system, you're configuring and managing pre-built virtual appliances.
The following table compares the traditional webMethods deployment model with the API Connect OVA approach.
| Concept |
webMethods Installer-based |
API Connect VMware OVA |
| Unit of deployment |
Individual component installed to a directory on a host OS |
Pre-built virtual machine image (OVA) imported into VMware vSphere. One VM per subsystem. |
| Operating system |
User managed — RHEL, Windows, etc. |
Baked into the OVA image. Not user-managed. |
| Container orchestration |
None — components run as processes |
Single-node Kubernetes is embedded inside each OVA. |
| Configuration tool |
Software AG Installer wizard and config files (e.g. custom-wrapper.conf) |
apicup CLI — the API Connect configuration utility. Sets hostnames, certificates, installs subsystems. |
| One component per product |
API Gateway, Portal, Control Plane are separate products you install independently |
Each is a separate subsystem with its own OVA VM, all registered with a central API Manager |
| Where the apicupgrade tool runs |
N/A |
apicupgrade binary must run inside the target OVA VM — not from your local machine. API Gateway migration runs from the Webmethods API Gateway VM, developer portal from the Developer Portal VM, Control Plane from the Federated API Management VM. |
| Encrypting secrets |
Config files / SAG installer properties |
Kubernetes secrets inside the embedded K8s, managed via apicup commands |
| Traffic cutover |
Update load balancer or DNS to point to a new host IP |
Same concept — update DNS to point to the OVA VM's IP (or the IP of a load balancer fronting it) |
Upgrade Workflow
Developer Portal - Assets and Consumption Metrics
The Developer Portal upgrade follows a backup → download → restore workflow.
The apicupgrade utility creates a backup of the source Developer Portal, including portal assets, users, applications, communities, themes, and configuration data. The backup is restored to the target API Connect v12 Developer Portal, after which consumption metrics are upgraded separately to preserve usage data.
Once the upgraded portal has been validated, DNS is updated to redirect traffic to the target v12 Developer Portal. The Developer Portal is upgraded first so that API publishing can resume immediately after the API Gateway upgrade.
API Gateway - Core Assets
The API Gateway upgrade uses a direct data copy mechanism to securely transfer runtime configuration from the source Gateway to the target API Connect v12 Gateway.
Before the transfer begins, the target Gateway is prepared for data copy and the source Gateway is placed into quiesce mode to ensure data consistency. The apicupgrade utility then copies the runtime data over a mutually authenticated TLS (mTLS) connection and performs a passman upgrade to migrate encrypted assets such as keystores, truststores, OAuth credentials, backend passwords, and other secrets.
After the upgrade is complete, the Gateway is returned to its normal operating configuration, restarted, and validated before DNS is updated to redirect runtime API traffic to the target v12 Gateway.
API Gateway - Analytics
Gateway analytics are upgraded independently after the runtime traffic has been redirected to the target Gateway, eliminating the need for additional downtime.
The apicupgrade utility imports transactional event data from the source OpenSearch or Elasticsearch datastore into the API Connect v12 Analytics subsystem. For large analytics repositories, the upgrade can be performed in time-based batches using the --start-time and --end-time options
API Control Plane - Core and Insights
The API Control Plane is upgraded after the Developer Portal and API Gateway have been successfully migrated to API Connect v12.
During the core upgrade, the source Control Plane is placed into quiesce mode while the target Federated API Management (FAM) subsystem imports runtime definitions, registrations, and configuration data. Once the core upgrade is complete, Insights data can be upgraded separately without requiring the source Control Plane to remain in quiesce mode.
Conclusion
API Connect v12.1.1 extends the capabilities of the apicupgrade utility by introducing support for VMware (OVA) deployments, enabling organizations to upgrade directly from webMethods API Management to an OVA-based API Connect environment. This enhancement provides a consistent upgrade experience across Kubernetes, OpenShift, and OVA deployments while allowing customers to preserve their existing APIs, applications, configurations, and other critical data.
Although the overall upgrade workflow remains consistent, upgrading to an OVA deployment introduces a different deployment model and component-specific upgrade mechanisms. The upgrade must be performed in the prescribed order, with each subsystem following its own data transfer process. Understanding this workflow helps ensure a smooth and successful upgrade.
For complete upgrade procedures, supported deployment topologies, prerequisites, and configuration requirements, refer to the IBM API Connect product documentation.
Reference