Upgrade Kong Gateway 3.1.x
Upgrade to major, minor, and patch Kong Gateway
releases using the kong migrations
commands.
You can also use the commands to migrate all Kong Gateway open-source entities to Kong Gateway (Enterprise). See Migrating from Kong Gateway (OSS) to Kong Gateway.
If you experience any issues when running migrations, contact Kong Support for assistance.
Upgrade path for Kong Gateway releases
Kong adheres to semantic versioning, which makes a distinction between major, minor, and patch versions.
The upgrade to 3.1.x is a minor upgrade. The lowest version that Kong 3.1.x supports migrating from is 3.0.x.
Important: Blue-green migration in traditional mode for versions below 2.8.2 to 3.0.x is not supported. The 2.8.2 release includes blue-green migration support. If you want to perform migrations for traditional mode with no downtime, upgrade to 2.8.2, then migrate to 3.1.x.
While you can upgrade directly to the latest version, be aware of any breaking changes between the 2.x and 3.x series noted in this document (both this version and prior versions) and in the open-source (OSS) and Enterprise Gateway changelogs. Since Kong Gateway is built on an open-source foundation, any breaking changes in OSS affect all Kong Gateway packages.
Kong Gateway does not support directly upgrading from 1.x to 3.1.x. If you are running 1.x, upgrade to 2.8.2 and then 3.0.x first at minimum, then upgrade to 3.1.x from there.
In either case, you can review the upgrade considerations, then follow the database migration instructions.
Upgrade path for Kong Gateway 3.1.x
The following table outlines various upgrade path scenarios to 3.1.x depending on the Kong Gateway version you are currently using:
Current version | Topology | Direct upgrade possible? | Upgrade path |
---|---|---|---|
2.x | Traditional | No | Upgrade to 2.8.2.x (required for blue/green deployments only), then upgrade to 3.0.x, and then upgrade to 3.1.x. |
2.x | Hybrid | No | Upgrade to 2.8.2.x, then upgrade to 3.0.x, and then upgrade to 3.1.x. |
2.x | DB less | No | Upgrade to 3.0.x, and then upgrade to 3.1.x. |
3.0.x | Traditional | Yes | Upgrade to 3.1.x. |
3.0.x | Hybrid | Yes | Upgrade to 3.1.x. |
3.0.x | DB less | Yes | Upgrade to 3.1.x. |
Upgrade considerations and breaking changes
Before upgrading, review this list for any configuration or breaking changes that affect your current installation.
Kong for Kubernetes considerations
The Helm chart automates the upgrade migration process. When running helm upgrade
,
the chart spawns an initial job to run kong migrations up
and then spawns new
Kong pods with the updated version. Once these pods become ready, they begin processing
traffic and old pods are terminated. Once this is complete, the chart spawns another job
to run kong migrations finish
.
While the migrations themselves are automated, the chart does not automatically ensure that you follow the recommended upgrade path. If you are upgrading from more than one minor Kong Gateway version back, check the upgrade path recommendations.
Although not required, users should upgrade their chart version and Kong Gateway version independently. In the event of any issues, this will help clarify whether the issue stems from changes in Kubernetes resources or changes in Kong Gateway.
For specific Kong for Kubernetes version upgrade considerations, see Upgrade considerations
Kong deployment split across multiple releases
The standard chart upgrade automation process assumes that there is only a single Kong Gateway release
in the Kong Gateway cluster, and runs both migrations up
and migrations finish
jobs.
If you split your Kong Gateway deployment across multiple Helm releases (to create proxy-only and admin-only nodes, for example), you must set which migration jobs run based on your upgrade order.
To handle clusters split across multiple releases, you should:
-
Upgrade one of the releases with:
helm upgrade RELEASENAME -f values.yaml \ --set migrations.preUpgrade=true \ --set migrations.postUpgrade=false
-
Upgrade all but one of the remaining releases with:
helm upgrade RELEASENAME -f values.yaml \ --set migrations.preUpgrade=false \ --set migrations.postUpgrade=false
-
Upgrade the final release with:
helm upgrade RELEASENAME -f values.yaml \ --set migrations.preUpgrade=false \ --set migrations.postUpgrade=true
This ensures that all instances are using the new Kong Gateway package before running
kong migrations finish
.
Hybrid mode considerations
Important: If you are currently running in hybrid mode, upgrade the control plane first, and then the data planes.
- If you are currently running 2.8.x in classic (traditional) mode and want to run in hybrid mode instead, follow the hybrid mode installation instructions after running the migration.
- Custom plugins (either your own plugins or third-party plugins that are not shipped with Kong Gateway) need to be installed on both the control plane and the data planes in hybrid mode. Install the plugins on the control plane first, and then the data planes.
- The Rate Limiting Advanced plugin does not
support the
cluster
strategy in hybrid mode. Theredis
strategy must be used instead.
Template changes
There are changes in the Nginx configuration file between every minor and major version of Kong Gateway starting with 2.0.x.
In 3.0.x, the deprecated alias of Kong.serve_admin_api
was removed.
If your custom Nginx templates still use it, change it to Kong.admin_content
.
Upgrade from 3.0.x to 3.1.x
Traditional mode
- Clone your database.
- Download 3.1.x, and configure it to point to the cloned data store.
Run
kong migrations up
andkong migrations finish
. - Start the 3.1.x cluster.
- Now both the old (3.0.x) and new (3.1.x) clusters can now run simultaneously. Start provisioning 3.1.x nodes.
- Gradually divert traffic away from your old nodes, and into your 3.1.x cluster. Monitor your traffic to make sure everything is going smoothly.
- When your traffic is fully migrated to the 3.1.x cluster, decommission your old nodes.
Hybrid mode
Perform a rolling upgrade of your cluster:
- Download 3.1.x.
- Decommission your existing 3.0.x control plane. Your existing 3.0.x data planes can continue to handle proxy traffic during this time, even with no active control plane.
- Configure the new 3.1.x control plane to point to the same data store as
your old control plane. Run
kong migrations up
andkong migrations finish
. - Start the new 3.1.x control plane.
- Start new 3.1.x data planes.
- Gradually divert traffic away from your 3.0.x data planes, and into the new 3.1.x data planes. Monitor your traffic to make sure everything is going smoothly.
- When your traffic is fully migrated to the 3.1.x cluster, decommission your old 3.0.x data planes.