v10 migration overview

Location of v10 migration scripts

You can obtain the scripts from Fix Central, search for apiconnect-operator-release-files_<version_number>. The scripts are located in the helper_files/formFactorMigration directory:

apiconnect-operator-release-files_VERSION_NUMBER/helper_files/formFactorMigration

On Kubernetes, OpenShift, and Cloud Pak for Integration, the migration scripts are run from a client computer that has access to the Kubernetes or OpenShift cluster. Scripts are supported on Linux and macOS.

On VMware, the migration scripts are run directly on the API Connect VMs.

v10 migration planning

Consider the following information when you plan your 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 system, skip those endpoints in the mapping. Then, after migration is complete, manually delete the data from Cloud Manager and the API Manager UI on the source system.

  • Perform migration in more than one step

    In this scenario, at the time of migration the 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 that are available on the target system. At this point, the target system will still have some stale data related to the subsystems that 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 to the source system 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 on Kubernetes, OpenShift, and Cloud Pak for Integration.
      3. Update the gateways in the catalog to point to the new Gateway systems. Complete Step 6 in Restoring the target system on Kubernetes, OpenShift, and Cloud Pak for Integration.

    • If additional Portals are added to the source system 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 on Kubernetes, OpenShift, and Cloud Pak for Integration.
      3. Update the portals in the catalog to point to the new portal systems. Complete Step 4 in Restoring the target system on Kubernetes, OpenShift, and Cloud Pak for Integration.
      4. Restore portal backups for each site on the namespace where the new portal is installed. Complete Step 5 in Restoring the target system on Kubernetes, OpenShift, and Cloud Pak for Integration.

    • 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 the 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 on Kubernetes, OpenShift, and Cloud Pak for Integration.
     • If using top-level CR on OpenShift: The top-level 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 using top-level CR, or CP4I. For Kubernetes or OpenShift using individual subsystems, it must be ingress-ca.
     • An example of an ingress-ca secret is given in the following example. If top-level CR is used, replace TOP_CR_NAME with the top-level CR name you are going to use to install API Connect. For Kubernetes or OpenShift using individual subsystems, 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 on Kubernetes, OpenShift, and Cloud Pak for Integration. Install API Connect, using the same TOP_CR_NAME (if using top-level CR), by following the remainder of the steps in Installing the target system on Kubernetes, OpenShift, and Cloud Pak for Integration.
  4. When you complete Restoring the target system on Kubernetes, OpenShift, and Cloud Pak for Integration, 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, shut down the Postgres database in the management subsystem.

    If you shutdown Postgres, you won't be able to login to the any of the API Connect UIs, or Toolkit CLI.

  • 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 on Kubernetes, OpenShift, and Cloud Pak for Integration.
• Sizing

  Before installing the API Connect target system, make sure proper capacity planning is done to handle the production workloads. 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 the 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.