You are browsing documentation for an outdated version.
See the latest documentation here.
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.
CPX(Current Kong Gateway X \n #40;inactive#41;)
Admin(No Admin API \n write operations)
CPY(New Kong Gateway Y)
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.
- 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
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.