The rolling upgrade strategy is a Kong Gateway upgrade option specifically designed
for DB-less mode, data planes running in hybrid mode, and Konnect.
This strategy is meant for nodes that don’t use a database and are independent of each other.
This guide refers to the old version as cluster X and the new version as cluster Y.
The rolling upgrade is a process of continuously adding new nodes of version Y, while shutting
down nodes of version X.
API --> LB & LB & LB & LB
LB -.-> CPX
LB -.90%.-> CPX2
LB -.-> CPX3
LB --> CPY
LB --10%--> CPY2
LB --> CPY3
CPX -.- yml
CPX2 -.- yml
CPX3 -.- yml
CPY -.- yml
CPY2 -.- yml
CPY3 -.- yml
style API stroke:none
style CPX stroke-dasharray:3
style CPX2 stroke-dasharray:3
style CPX3 stroke-dasharray:3
linkStyle 3,7,8,9,13,14,15 stroke:#b6d7a8
Figure 1: The diagram shows a Kong Gateway upgrade using the rolling strategy with no database.
New nodes are gradually deployed and pointed to the
kong.yml file, while traffic is gradually rerouted to the new nodes.
- Review the general upgrade guide to prepare for the upgrade and review your options.
- You have a DB-less deployment or you need to upgrade the data planes (DPs) in a hybrid mode deployment, or Konnect DPs.
Upgrade using the rolling method
The following steps are intended as a guideline.
The exact execution of these steps will vary depending on your environment.
Stop any Kong Gateway configuration updates (for example, Admin API calls to
This is critical to guarantee data consistency between cluster X and cluster Y.
Back up data from the current cluster X by following the
declarative configuration backup instructions.
Evaluate factors that may impact the upgrade, as described in Upgrade considerations.
You may have to consider customization of both
kong.conf and Kong Gateway configuration data.
- Evaluate any changes that have happened between releases:
Deploy a new Kong Gateway cluster of version Y:
Install a new cluster running version Y as instructed in the
Kong Gateway Installation Options.
Provision the new cluster Y with the same-sized resource capacity as that of
the current cluster X.
Perform staging tests against version Y to make sure it works for all use cases.
For example, does the Key Authentication plugin authenticate requests properly?
If it is a data plane node, ensure the communication with the control node succeeds.
If the outcome is not as expected, look over the
upgrade considerations and the
again to see if you missed anything.
Continuously install and launch more Y nodes.
Divert traffic from old cluster X to new cluster Y.
This is usually done gradually and incrementally, depending on the risk profile of the deployment.
Any load balancers that support traffic splitting will work here, such as DNS, Nginx, Kubernetes rollout mechanisms, and so on.
If any issues arise, roll back by setting all traffic to cluster X, investigate the issues,
and repeat the steps above.
- When there are no more issues, decommission the old cluster X to complete the upgrade.
Write updates to Kong Gateway can now be performed, though we suggest you keep monitoring metrics for a while.