You are browsing documentation for an older version. See the latest documentation here.
In-place upgrade
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 API stroke:none style CPX stroke-dasharray:3 style Admin fill:none,stroke:none,color:#d44324 linkStyle 0,3,4 stroke:#d44324,color:#d44324
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 are not able to 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.
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.
Upgrade using the in-place 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 (e.g. Admin API calls). This is critical to guarantee data consistency between cluster X and cluster Y.
-
Back up data from the current cluster X by following the Backup guide.
-
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:
-
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.
-
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.
-
Migrate the database to the new version by running
kong migrations up
. -
When complete, run
kong migrations finish
. -
Start the new cluster Y.
-
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.