Estimated reading time:
This guide will inform you about breaking changes you should be aware of
when upgrading, as well as take you through the correct sequence of steps
in order to obtain a no-downtime migration in different upgrade
Kong adheres to semantic versioning, which makes a
as well as breaking changes.
distinction between “major”, “minor” and “patch” versions. The upgrade path
will be different on which previous version from which you are migrating.
If you are upgrading from 0.x, this is a major upgrade. If you are
upgrading from 1.0.x, 1.1.x, or 1.2.x, this is a minor upgrade. Both
scenarios are explained below.
1. Breaking Changes
If you are using the provided binary packages, all necessary dependencies
are bundled. If you are building your dependencies by hand, you should
be aware of the following changes:
- The required OpenResty version has been bumped to
126.96.36.199. If you are
installing Kong from one of our distribution packages, you are not affected
by this change.
- From this version on, the new
module is required to be built into OpenResty for Kong to function
properly. If you are installing Kong from one of our distribution packages,
you are not affected by this change.
Note: if you are not using one of our distribution packages and compiling
OpenResty from source, you must still apply Kong’s OpenResty
patches (and, as highlighted above,
compile OpenResty with the new lua-kong-nginx-module). Our new
repository will allow you to do both easily.
- Bugfixes in the router may, in some edge-cases, result in different Routes
being matched. It was reported to us that the router behaved incorrectly in
some cases when configuring wildcard Hosts and regex paths (e.g.
#3094). It may be so that you are
subject to these bugs without realizing it. Please ensure that wildcard Hosts
and regex paths Routes you have configured are matching as expected before
- Upstream connections are now only kept-alive for 100 requests or 60 seconds
(idle) by default. Previously, upstream connections were not actively closed
by Kong. This is a (non-breaking) change in behavior inherited from Nginx
1.15, and configurable via new configuration properties.
upstream_keepalive configuration property is deprecated, and replaced
by the new
nginx_http_upstream_keepalive property. Its behavior is almost
identical, but the notable difference is that the latter leverages the
feature added in Kong 0.14.0.
2. Suggested Upgrade Path
The lowest version that Kong 1.3 supports migrating from is 0.14.1. if you
are migrating from a previous 0.x release, please migrate to 0.14.1 first.
For upgrading from 0.14.1 to Kong 1.3, the steps for upgrading are the same as
upgrading from 0.14.1 to Kong 1.0. Please follow the steps described in the
“Migration Steps from 0.14” in the Suggested Upgrade Path for Kong
Kong 1.3 supports the no-downtime migration model. This means that while the
migration is ongoing, you will have two Kong clusters running, sharing the
same database. (This is sometimes called the Blue/Green migration model.)
The migrations are designed so that there is no need to fully copy
the data, but this also means that they are designed in such a way so that
the new version of Kong is able to use the data as it is migrated, and to do
it in a way so that the old Kong cluster keeps working until it is finally
time to decommission it. For this reason, the full migration is now split into
two steps, which are performed via commands
kong migrations up (which does
only non-destructive operations) and
kong migrations finish (which puts the
database in the final expected state for Kong 1.2).
- Download 1.3, and configure it to point to the same datastore as your old
(1.0 - 1.2) cluster. Run
kong migrations up.
- Once that finishes running, both the old and new (1.3) clusters can now run
simultaneously on the same datastore. Start provisioning 1.3 nodes, but do
not use their Admin API yet. If you need to perform Admin API requests,
these should be made to the old cluster’s nodes. The reason is to prevent
the new cluster from generating data that is not understood by the old
- Gradually divert traffic away from your old nodes, and into
your 1.3 cluster. Monitor your traffic to make sure everything
is going smoothly.
- When your traffic is fully migrated to the 1.3 cluster, decommission your
- From your 1.3 cluster, run:
kong migrations finish. From this point on,
it will not be possible to start nodes in the old cluster pointing to the
same datastore anymore. Only run this command when you are confident that
your migration was successful. From now on, you can safely make Admin API
requests to your 1.3 nodes.
Upgrade Path for Patch Releases
There are no migrations in upgrades between current or
future patch releases of the same minor release of Kong
(e.g. 1.0.0 to 1.0.1, 1.0.1 to 1.0.4, etc.). Therefore, the
upgrade process is simpler.
Assuming that Kong is already running on your system, acquire the latest
version from any of the available installation
methods and proceed to install it, overriding
your previous installation.
If you are planning to make modifications to your configuration, this is a
good time to do so.
Then, run migration to upgrade your database schema:
$ kong migrations up [-c configuration_file]
If the command is successful, and no migration ran
(no output), then you only have to
$ kong reload [-c configuration_file]
kong reload leverages the Nginx
reload signal that seamlessly
starts new workers, which take over from old workers before those old workers
are terminated. In this way, Kong will serve new requests via the new
configuration, without dropping existing in-flight connections.
Installing 1.3 on a Fresh Datastore
The following commands should be used to prepare a new 1.3 cluster from a fresh
$ kong migrations bootstrap [-c config]
$ kong start [-c config]