Upgrading Analytics subsystem on native Kubernetes

Upgrade the Analytics subsystem to the latest version of API Connect.

About this task

Attention: Upgrading to v10.0.5.x from v10.0.4-ifix3 or later, or v10.0.1.7 or later, will result in the deletion of existing analytics data. If you want to retain your analytics data then you must export it before upgrade. For instructions on exporting see Additional considerations for upgrading analytics from a version prior to 10.0.5.0.

When upgrading to a new mod release, the version must be changed to the latest mod release version on each CR. This change will be picked up by the operator, and the operator will then start the upgrade.

Procedure

  1. Update the analytics CR for the new version of API Connect.
    1. Run the following command to edit the CR:
      kubectl -n $NAMESPACE edit a7s <CLUSTERNAME>

      where CLUSTERNAME is the name specified in the subsystem CR at installation time.

    2. If upgrading from v10.0.4-ifix3, or upgrading from v10.0.1.7-eus (or higher): Add an allowUpgrade attribute and set it to true:
      spec:
        allowUpgrade: true

      The allowUpgrade attribute enables the upgrade to 10.0.5.x. Because the upgrade to 10.0.5.x deletes your existing analytics data, the attribute is required to prevent an accidental upgrade. You must also delete any template section from your analytics CR. See Additional considerations for upgrading analytics from a version prior to 10.0.5.0

    3. Update the API Connect version in the CR:

      For example:

      version: 10.0.5.7
    4. If you are upgrading to a version of API Connect that requires a new license, update the license value now.

      For example:

      license: L-RJON-CEBLEH

      For the list of licenses, see API Connect licenses.

    5. Save your changes to the CR.

      When you save the updated CR, the upgrade starts automatically.

      Known issue: Webhook error for incorrect license.

      If you did not update the license ID in the CR, then when you save your changes, the following webhook error might display:

      admission webhook "vmanagementcluster.kb.io" denied the request: 
      ManagementCluster.management.apiconnect.ibm.com "management" is invalid: 
      spec.license.license: Invalid value: "L-RJON-BYGHM4": 
      License L-RJON-BYGHM4 is invalid for the chosen version 10.0.5.7. 
      Please refer license document https://ibm.biz/apiclicenses

      To resolve the error, see API Connect licenses for the list of the available license IDs and select the appropriate License IDs for your deployment. Update the CR with the new license value as in the following example, and then save and apply your changes again.

  2. Run the following command to verify that the upgrade was successful:
    kubectl get apic -n <namespace>

    Example output after upgrading the analytics subsystem:

    NAME                                                      READY   STATUS    VERSION              RECONCILED VERSION      AGE
    analyticscluster.analytics.apiconnect.ibm.com/analytics   5/5     Running   <version>   <version-build>   121m
    
  3. Optional: If upgrading to v10.0.5.3 (or later) from an earlier 10.0.5.x release: Review and configure the new inter-subsystem communication features: Optional post-upgrade steps for upgrade to 10.0.5.3 (or later) from earlier 10.0.5 release.
  4. If upgrading from v10.0.4-ifix3, or upgrading from v10.0.1.7-eus (or higher): Re-enable analytics data collection as explained in Enabling Analytics after upgrading.

    If you are upgrading from 10.0.5.x, skip this step.