In-place upgrade for Kong Gateway

The in-place upgrade strategy is a Kong Gateway upgrade option used primarily for traditional mode deployments and for control planes in hybrid mode. An in-place upgrade reuses the existing database.

In comparison to dual-cluster upgrades, the in-place upgrade uses less resources, but causes business downtime.

This guide refers to the old version as cluster X and the new version as cluster Y. For this upgrade method, you have to shut down cluster X, then configure the new cluster Y to point to the database.

 
flowchart TD
    DB[(Database)]
    CPX(Current Kong Gateway X \n #40;inactive#41;)
    Admin(No Admin API \n write operations)
    CPY(New Kong Gateway Y)
    API(API requests)

    CPX -.X.-> DB
    API --> CPY
    CPY --kong migrations up \n kong migrations finish--> DB
    Admin -.X.- CPX & CPY

    style CPX stroke-dasharray:3
    style Admin fill:none!important,stroke:none!important,color:#d44324!important
    linkStyle 0,3,4 stroke:#d44324!important,color:#d44324!important
  

Figure 1: The diagram shows an in-place upgrade workflow, where the current cluster X is directly replaced by a new cluster Y. The database is reused by the new cluster Y, and the current cluster X is shut down once all nodes are migrated. No Admin API write operations can be performed during the upgrade.

There is business downtime as cluster X is stopped during the upgrade process. You must carefully review the upgrade considerations in advance.

Important: We do not recommend using this strategy unless Kong Gateway is deployed under an extremely resource-constrained environment, or unless you can’t obtain new resources in a timely manner for a dual-cluster upgrade.

The current cluster X can be substituted in place with the new cluster Y. However, this strategy does not prevent you from deploying the new cluster Y on a different machine.

The following steps are intended as a guideline. The exact execution of these steps will vary depending on your environment.

Prerequisites

• Review the general upgrade guide to prepare for the upgrade and review your options.
• You have a traditional deployment or you need to upgrade the control planes (CPs) in a hybrid mode deployment.
• You can’t perform dual-cluster upgrades due to resource limitations.

Prepare the upgrade

1. Stop any Kong Gateway configuration updates (e.g. Admin API calls). 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 backup guide.

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:

   • Breaking changes
   • Full changelog

Switch the cluster

1. Stop the Kong Gateway nodes of the old cluster X but keep the database running. This will create a period of downtime until the upgrade completes.

2. Install a new cluster running version Y as instructed in the Kong Gateway Installation Options and point it at the existing database for cluster X.

   Provision the new cluster Y with the same-sized resource capacity as that of the current cluster X.

3. Migrate the database to the new version by running kong migrations up.

4. When complete, run kong migrations finish.

5. Start the new cluster Y.

6. (LTS upgrades or 2.x to 3.x upgrades only) Using the decK file created during backup, convert your entity configuration and sync the converted file to your newly installed version.

Once this is done, actively monitor all proxy metrics. If you run into any issues, roll back the upgrade. Prioritize the database-level restoration method over the application-level method.

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.

Caution: When adding new plugins to the existing installation (either manually or via the extension of bundled plugins), the kong migrations finish or kong migrations up must be run with the -f flag to forcefully upgrade the plugin schemas.