Upgrading Gateway subsystem on native Kubernetes
Upgrade the Gateway subsystem to the latest version of API Connect.
Before you begin
- Complete all steps in Upgrading subsystems on native Kubernetes prior to the step that links to this topic.
- Ensure your upgrade path is supported.
- To ensure operator compatibility, upgrade the API Connect management subsystem before you upgrade the DataPower gateway subsystem. This requirement applies to all upgrade scenarios.
- When you upgrade a cluster of gateway pods
in Kubernetes, a small number of API transactions may fail. During the upgrade, Kubernetes removes
the pod from the load balancer configuration, deletes the pod and then starts a new pod. The steps
are repeated for each pod. Socket hang ups occur on transactions that are in process at the time the
pod is killed.
The number of transactions that fail depends on the rate of incoming transactions and the length of time needed to complete each transaction. Typically the number of failures is a very small percentage. This behavior is expected during an upgrade. If the failure level is not acceptable, schedule the upgrade during an off-hours maintenance window.
Note also that DataPower Gateway supports long-lived connections such as such as GraphQL subscriptions or other websockets connections. These long-lived connections might not be preserved when upgrading. Workloads with long-lived connections are more vulnerable to failed API transactions during upgrading.
You can limit the number of failed API transactions during the upgrade by using the DataPower Operator's
lifecycle
property to configure thepreStop
container lifecycle hook on the gateway pods. This approach mitigates the risk of API failures during the rolling update of the gateway StatefulSet by sleeping the pod for a span of time, allowing in-flight transactions to complete prior to the SIGTERM being delivered to the container. While this feature does not guarantee that no in-flight APIs would fail, it does provide some mitigation for in-flight transactions that can complete successfully within the configured time window. For more information, see Delaying SIGTERM with preStop in the DataPower documentation. - When upgrading a high-availability cluster, ensure that you meet the following requirements:
- Gateways must be updated one at a time.
- Before starting the upgrade, a single gateway must be running as primary for all gateway-peering definitions.
- When upgrading multiple gateways, the primary gateway must be upgraded 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, or use the Gateway Peering Status display in the Web GUI in the API Connect application domain by running the following command:kubectl attach -it <podname>
To move the primary to the DataPower on which you're currently working, you can issue the following command:
command.gateway-peering-switch-primary <peering-object-name>
About this task
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.