Pre-upgrade preparation and checks on Kubernetes

1. Load the image-tool image for the new API Connect version into your local Docker registry:

   docker load < apiconnect-image-tool-<version>.tar.gz 

   Ensure that the registry has sufficient disk space for the files.

2. If your Docker registry requires repositories to be created before images can be pushed, create the repositories for each of the images that the image tool lists. If your Docker registry does not require creation of repositories, skip to step 3.c.
   1. Run the following command to get a list of the images from image-tool:

      docker run --rm apiconnect-image-tool-<version> version --images

   2. From the output of each entry of the form <image-name>:<image-tag>, use your Docker registry repository create command to create a repository for <image-name>.
      For example, in AWS ECR the command for each <image-name> is:

      aws ecr create-repository --repository-name <image-name>

3. Upload the image:
   • If you do not need to authenticate with the docker registry, use:

     docker run --rm apiconnect-image-tool-<version> upload <registry-url>

   • If you need to authenticate and your docker registry accepts the username and password arguments, use:

     docker run --rm apiconnect-image-tool-<version> upload <registry-url> --username <username> --password <password>

   • Otherwise, if you need the image-tool to use your local Docker credentials (for example, with IBM Container Registry), first authenticate with your Docker registry, and then upload images with the command:

     docker run --rm -v ~/.docker:/root/.docker --user 0 apiconnect-image-tool-<version> upload <registry-url>

     Review the following installation notes for your environment:

     • Alternative Docker command for macOS if Docker is configured to use osxkeychain
     • Docker authentication notes
     • Providing a certificate for verification, or disabling TLS verification

   If necessary, you can populate a remote container registry with repositories. Then you can push the images from the local registry to the remote registry.

Create a directory called helper_files and extract the contents of helper_files.zip from the release_files.zip into the helper_files directory.

Beginning with version 10.0.8.0, API Connect includes the Consume Catalog feature. If you are upgrading to 10.0.8.0 or later from 10.0.5.x or 10.0.7.0 and do not use cert-manager, you must provide a certificate for the Consumer Catalog during the upgrade.

1. Create a certificate.
2. Update the management CR and add the following endpoint for the Consumer Catalog with the secret name for the new certificate:

     consumerCatalogEndpoint:
       hosts:
       - name: consumer-catalog.<domain>
         secretName: <custom-management-consumer-catalog-endpoint>

1. Get the name of the pgcluster:

   kubectl get pgcluster -n <management namespace>

   The response displays the name of the postgres cluster that is running in the specified namespace.

2. Check the status of the pgcluster:

   kubectl get pgcluster <pgcluster_name> -n <APIC_namespace> -o yaml | grep status -A 2 | tail -n3

   A successful response looks like the following example, where the state is Initialized:

   status:
       message: Cluster has been initialized
       state: pgcluster Initialized

   Important: If the pgcluster returns any other state, then do not proceed with the upgrade.

   • If backup or restore jobs are running, wait until they complete and then check the status again. Do not proceed with the upgrade until the status is Initialized.
   • If all background jobs are complete but the pgcluster does not return state: pgcluster Initialized, then contact IBM Support for assistance.

1. Verify that the apicops utility is installed and that you have the latest version by running the following command:

   apicops --version

   For more information about the apicops utility, see The API Connect operations tool: apicops.

2. Run the following command to set the KUBECONFIG environment variable.

   export KUBECONFIG=</path/to/kubeconfig>

3. Run the apicops pre-upgrade-check check for the management, portal, and analytics subsystems:
   • Management subsystem:

     apicops system:pre-upgrade-check management -n <namespace>

     Before upgrading, run the following command to check for encryption issues and invalid gateway extensions:

     For a full check (requires admin password to verify topology):

     apicops preupgrade -n <namespace>

     To skip topology verification (no admin password needed):

     apicops preupgrade --no-topology -n <namespace>

   • Portal subsystem:

     apicops system:pre-upgrade-check portal -n <namespace>

   • Analytics subsystem:

     apicops system:pre-upgrade-check analytics -n <namespace>

   If your API Connect deployment is working correctly, the output shows no error messages.

   If the pre-upgrade check returns any errors, then collect the output and open a support case.

For more information about this requirement, see Analytics persistent queue enablement requires extra PV.