Upgrading the gateway subsystem on Kubernetes

Upgrade the gateway subsystem to a newer version of API Connect on Kubernetes.

Before you begin

Review and complete all steps in:

Note: To upgrade a high-availability cluster, ensure that you meet the following requirements:

Gateways must be updated one at a time.
Before you start the upgrade, a single gateway must be running as primary for all gateway-peering definitions.
To upgrade multiple gateways, upgrade the primary gateway last.
Ensure that the pod with a name like gwv6-0 or gwv5-0 is the primary because it is the last node to be upgraded.
To determine which gateway is running as primary, use either
- The show gateway-peering-status command in the DataPower CLI. Access the CLI with:
```
kubectl attach -it <gateway pod name>
```
- The Gateway Peering Status display in the WebGUI (in the API Connect application domain).
To move the primary to the DataPower on which you are working, you can issue the following command:
```
gateway-peering-switch-primary <peering-object-name>
```

About this task

Upgrade the analytics subsystem by updating the version property in your analytics CR. The API Connect operator detects this change and starts the upgrade.

Gateway upgrade can result in failure of some in-flight transactions, for more information see: API transactions might fail during the upgrade of gateway pods.

Procedure

Update the gateway CR for the new version of API Connect.
1. Run the following command to edit the CR:
```
kubectl -n <namespace> edit gw <gateway CR name>
```
  where <gateway CR name> is the name of your gateway CR. The names of your gateway CRs are shown in the output of: kubectl get gw.
2. Set the spec.version property in the gateway CR to your target version:
  For example:
```
version: 10.0.8.1
```
3. If you are upgrading to a version of API Connect that requires a new license, update spec.license.
  For example:
```
license: L-DZZQ-MGVN8V
```
  For the list of licenses, see API Connect licenses.
4. Delete any template or dataPowerOverride override sections.
  
  If the CR contains an override, an upgrade is not possible.
5. Run the following command to save and apply the CR: wq
  
  When you save the updated CR, the upgrade starts automatically.
  
  Troubleshooting: If you see an error message when you attempt to save the CR, see the known upgrade issues.

Run the following command to verify that the upgrade was successful:

kubectl get apic -n <namespace>

Example output after a gateway subsystem upgrade:

NAME                                            READY   STATUS    VERSION              RECONCILED VERSION      AGE
gatewaycluster.gateway.apiconnect.ibm.com/gw1   2/2     Running   <version>  <version-build>  100m