v10 migration overview

Migration terminology used in this documentation

This documentation uses the following terms for migrations:

• v10 migration
  The term v10 migration includes:

  1. Migration of a v10 API Connect deployment to a v10 API Connect deployment on a different platform.
  2. Migration of a v10 API Connect deployment to a v10 API Connect deployment in a different cluster on the same platform.

     Applicable to native Kubernetes, OpenShift, and Cloud Pak for Integration.

  3. Migration of a v10 API Connect deployment to a Cloud Pak for Integration deployment.
  4. Migration of a Cloud Pak for Integration deployment to a Cloud Pak for Integration deployment on a different cluster.

     Note that Cloud Pak for Integration is deployed only on the OpenShift platform.

• Form Factor and Form Factor Migration.

  The term Form Factor is used in v10 migration to characterize a cluster deployment on a particular platform.

  Each of the migrations included in the definition for v10 migration is a movement of an existing v10 deployment to a different Form Factor.

  The term Form Factor Migration is another term for v10 migration. It refers to different software deployments. Usage of the term form factor in this documentation does not refer to any hardware form factors.

• Platform

  The term platform is used to mean either native Kubernetes, VMware virtual machine, OpenShift Container Platform, or Cloud Pak for Integration.

• Migration

  In the v10 API Connect documentation, the term migration is also used for scenarios for migrating from API Connect v5 to API Connect v10. Note that migrating from v5 to v10 is unrelated to moving a v10 deployment to a different form factor.

  To view instructions for migrating from v5 to v10, see Migrating a Version 5 deployment.

Location of v10 migration scripts

You can obtain the scripts from Fix Central. Obtain the following package:

apiconnect-operator-release-files_VERSION_NUMBER/helper_files/formFactorMigration

To access the latest version, see the What's new in the latest release page. On that page, locate the Note: You can access the latest files from <URL link>. Select the <URL link> to go directly to the Announce page on Fix Central, where you can download files for the latest version of API Connect.

Supported v10 migration paths

The supported migration paths cover two use cases:

• Migrating from a source system on one form factor to a target system on another form factor.
• Migrating from a source system on one form factor to a target system on the same form factor, when there is a change in hostnames.

v10 migration planning

Consider the following information when planning a v10 migration:

• Data migration

  There are two ways to migrate data:

  • Perform complete migration of data:

    Before starting migration steps on the target system, have the target system ready with the same or larger topology than what is present in the source system. This means the number of Gateways, Portals, and Analytics subsystems must be same or more than what is present in the source system. Start the migration process, map the endpoints between source and target systems, and complete the migration process. All data is migrated. The target system must be validated and tested.

    If you do not want to migrate data for some subsystems on the source systems, skip those endpoints in the mapping. Then, after migration is complete, manually delete the data from Cloud Manager and the API Manager UI.

  • Perform migration in more than one step

    In this scenario, at the time of migration the target API Connect target system does not have all the subsystems ready when compared to the total number of subsystems in the source system. Migration is run only for the Gateway and Portal subsystems which are available. At this point, the target system will still have some stale data related to the subsystems which are not migrated. You can then create additional subsystems (Gateways, Portals, or Analytics) on the target system, and run the necessary migration steps to complete the remaining migration process.

    • If additional Gateways or Analytics are added after completing the initial migration, you must:

      1. Add the new Gateway and Analytics related endpoints in the mapping file.
      2. Register Gateways and Portals on the target system. Complete Step 3 in Restoring the target system
      3. Update gateways in the catalog to point to new Gateway systems. Complete Step 6 in Restoring the target system

    • If additional Portals added after completing the initial migration, you must:

      1. Add the new Portal related endpoints in the mapping file.
      2. Register gateways and portals on the target system. Complete Step 3 in Restoring the target system
      3. Update portals in the catalog to point to new portal systems. Complete Step 4 in Restoring the target system
      4. Restore portal backups for each site on the namespace where the new portal is installed. Complete Step 5 in Restoring the target system

    • The stale data for which migration is not complete will remain on the target system until you install the additional subsystems and complete migration, or until you use the Cloud Manager or API Manager UI to manually delete it.

• Reuse of Gateways from the source system:
  1. Export the ingress-ca secret from source system using the -export_cert flag in Preparing the source system. The secret is saved to data/MANAGEMENT_SUBSYSTEM_NAME/ingress-ca_secret.yaml
  2. Install the ingress-ca secret manually on the target cluster. This step must be completed before you begin Installing the target system.
     • The top CR name you are going to use while installing API Connect must be used while creating the secret name and its contents.
     • The name of the ingress-ca secret must be TOP_CR_NAME-ingress-ca in case of OpenShift or CP4I. For Kubernetes, it must be ingress-ca
     • An example of an ingress-ca secret is given in the following example. Replace TOP_CR_NAME with the top CR name you are going to use to install API Connect. For Kubernetes, all the values will be just ingress-ca.
     • After modifying the contents of ingress-ca and saving the yaml, create the secret using oc create -f filename.yaml -n NAMESPACE

     apiVersion: v1
     data:
       ca.crt: CA_CRT
       tls.crt: TLS_CRT
       tls.key: TLS_KEY
     kind: Secret
     metadata:
       annotations:
         cert-manager.io/alt-names: ''
         cert-manager.io/certificate-name: TOP_CR_NAME-ingress-ca
         cert-manager.io/common-name: ingress-ca
         cert-manager.io/ip-sans: ''
         cert-manager.io/issuer-group: ''
         cert-manager.io/issuer-kind: Issuer
         cert-manager.io/issuer-name: TOP_CR_NAME-self-signed
         cert-manager.io/uri-sans: ''
       name: <TOPCR>-ingress-ca
     type: kubernetes.io/tls
     

  3. Run the migration steps, starting with Step 1 in Installing the target system. Install API Connect, using the same TOP_CR_NAME, by following the remainder of the steps in Installing the target system.
  4. When you complete Restoring the target system, do not map the source system gateways that are to be reused. Just skip them.
  5. Once the migration is complete, restart the gateways pods on the source system, wait for few minutes, and run the health check script to check the status of webhooks.
  6. Validate the APIs running on the source system gateways.
• Delta changes

  Once the migration procedure is started, any delta changes in the source system databases are not handled by the migration scripts. These changes must be handled manually.

  • To avoid delta changes, shutdown the Postgres database in the management subsystem. See Shutting down the Postgres database.
  • If there are delta changes to the management database after saving the configuration for the source system, you can optionally take another backup of the Management subsystem, just prior to restoring the Management subsystem. See Restoring the target system.
• Sizing

  Before installing the target API Connect system, make sure proper capacity planning is done to handle the production work loads. Ensure you have sufficient memory, CPU, and disk size as needed, based on the deployment profile being installed.

• Expected migration time

  The time required to complete migration can depend on the following:

  • The size of management database. Backup and restore are dependent on this size.
  • Migration of the Portal and Gateway data in all the provider orgs depends on:
    • Number of provider orgs
    • Number of catalogs in these provider orgs
    • Whether Portals are configured for these catalogs
    • Total number of APIs published
  • Creation of Portal sites and restore of Portal backup depends on:
    • Deployment profile (n1, n3 etc) being used
    • Disk performance
    • Total number of Portal sites being create or restored
    • The amount of customization in a Portal site. Customization plays a role in the time needed to restore.