Estimated reading time:
Prerequisites for Migrating to 1.5
- If running a version of Kong Enterprise earlier than 1.3, migrate to 1.3 first.
- If running a version of Kong Community Gateway earlier than 1.5, upgrade to Kong 1.5 before upgrading to Kong Enterprise 1.5.
Changes and Configuration to Consider before Upgrading
- If using RBAC with Kong Manager, it will be necessary to manually add the Session Plugin configuration values.
- Kong Manager and the Admin API must share the same domain in order to use the SameSite directive. If they are on separate domains,
cookie_samesite must be set to
“off”. Learn more in Session Security
- Kong Manager must be served over HTTPS in order for the Secure directive to work. If using Kong Manager with only HTTP, e.g. on
cookie_secure must be set to
false. Learn more in Session Security
- The Kong Developer Portal has undergone a number of Breaking Changes, if you are currently using the Developer Portal, it will no longer work without manually migrating files, or enabling Legacy Mode. Learn more in Kong Developer Portal - Whats new in 1.5
- The Upstream TLS plugin was deprecated in version 1.3, and removed in version 1.5. If you have configured this plugin, remove the plugin before upgrading to version 1.5. Otherwise, Kong Enterprise will fail to start due to the missing plugin.
Migration Steps from 1.3 to 1.5
Kong Enterprise 1.5 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 Enterprise 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 using 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 Enterprise 1.5).
- Download 1.5, and configure it to point to the same datastore as your old
(1.3) cluster. Run
kong migrations up.
- Once that finishes running, both the old and new (1.5) clusters can now run
simultaneously on the same datastore. Start provisioning 1.5 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.5 cluster. Monitor your traffic to make sure everything
is going smoothly.
- When your traffic is fully migrated to the 1.5 cluster, decommission your
- From your 1.5 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.5 nodes.
Migrating Developer Portal from 1.3 to 1.5
Below are the Developer Portal migrations required to move from Kong Enterprise 1.3 to Kong Enterprise 1.5.
You can make these changes with our templates repository using the Kong Portal CLI, or directly in the Kong Editor. We suggest using the templates/CLI in order to take advantage of source control. Links to the templates repository, as well as the portal CLI, can be found below.
Note: This action is irreversible, therefore it is highly recommended to have a backup of production data.
Kong Enterprise 1.5 includes a command to migrate all Kong Community Gateway entities to Kong Enterprise. The following steps will guide you through the migration process.
First, download Kong Enterprise 1.5 and configure it to point to the same datastore as your Kong Community Gateway 1.5 node. The migration command expects the datastore to be up to date on any pending migration:
$ kong migrations up [-c config]
$ kong migrations finish [-c config]
Once all Kong Enterprise migrations are up to date, the migration command can be run as:
$ kong migrations migrate-community-to-enterprise [-c config] [-f] [-y]
Confirm now that all the entities are now available on your Kong Enterprise 1.5 node.