You are browsing documentation for an older version. See the latest documentation here.

Rolling upgrade

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.

  2. flowchart TD
  3.     yml[fa:fa-file kong.yml]
  4.     CPX(Current 
  5.     Node X)
  6.     CPX2(Current 
  7.     Node X)
  8.     CPX3(Current 
  9.     Node X)
  10.     CPY(New 
  11.     Node Y)
  12.     CPY2(New 
  13.     Node Y)
  14.     CPY3(New 
  15.     Node Y)
  16.     LB(Load balancer)
  17.     API(API requests)
  19.     API --> LB & LB & LB & LB
  20.     LB -.-> CPX
  21.     LB -.90%.-> CPX2
  22.     LB -.-> CPX3
  23.     LB --> CPY
  24.     LB --10%--> CPY2
  25.     LB --> CPY3
  26.     CPX -.- yml
  27.     CPX2 -.- yml
  28.     CPX3 -.- yml
  29.     CPY -.- yml
  30.     CPY2 -.- yml
  31.     CPY3 -.- yml
  33.     style API stroke:none
  34.     style CPX stroke-dasharray:3
  35.     style CPX2 stroke-dasharray:3
  36.     style CPX3 stroke-dasharray:3
  37.     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.

Prerequisites

  • 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.

  1. Stop any Kong Gateway configuration updates (for example, Admin API calls to :8001/config). This is critical to guarantee data consistency between cluster X and cluster Y.

  2. Back up data from the current cluster X by following the declarative configuration backup instructions.

  3. 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.

  4. Evaluate any changes that have happened between releases:

  5. Deploy a new Kong Gateway cluster of version Y:

    1. 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.

    2. 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 breaking changes again to see if you missed anything.

    3. Continuously install and launch more Y nodes.

  6. 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.

  7. If any issues arise, roll back by setting all traffic to cluster X, investigate the issues, and repeat the steps above.

  8. 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.