PermalinkMigrating Kong Enterprise from 1.5.x to 2.1.x
PermalinkOverview
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 (OSS) entities to Kong Gateway. See Migrating from Kong Gateway to Kong Enterprise.
If you experience any issues when running migrations, contact Kong Support for assistance.
PermalinkUpgrade Path for Kong Enterprise Releases
Kong adheres to semantic versioning, which makes a distinction between major, minor, and patch versions. The upgrade path for major and minor versions differs depending on the previous version from which you are migrating.
PermalinkVersion Prerequisites for Migrating to Kong Enterprise 2.1
If you are not on Kong Gateway 1.5.x, you must first incrementally upgrade to 1.5.x before upgrading to 2.1.x. Zero downtime is possible but not guaranteed if you are upgrading incrementally between versions, from 0.36.x to 1.3.x to 1.5.x. Plan accordingly.
- If running a version of Kong Gateway earlier than 1.3, migrate to 1.3 first.
- If running a version of Kong Gateway earlier than 1.5, migrate to 1.5 first.
PermalinkUpgrade Considerations and Breaking Changes
Before upgrading, review this list for any configuration or breaking changes that affect your current installation.
- If you are adding a new plugin to your installation, you need to run
kong migrations up
with the plugin name specified. For example,KONG_PLUGINS=oauth2
. - The Portal Application Registration plugin was in beta status for both 1.5.x and 2.1.x beta versions. Using the plugin in a 2.1.x production environment requires a fresh installation and configuration of the plugin. The 2.1.x plugin requires authentication to be configured separately on the same Service. See authorization provider strategy.
- The Rate Limiting Advanced plugin does not
support the
cluster
strategy in hybrid mode. Theredis
strategy must be used instead. - Hybrid mode. If you are currently running 1.5.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) need to be installed on both the Control Plane and the Data Plane in Hybrid mode.
- Custom plugins and entities. If you have custom plugins and entities, there are some breaking changes and extra steps you need to take when migrating to 2.1.x.
- 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.
PermalinkMigrating from 1.5.x (or 2.1.x-beta) to 2.1.x
Note: There is not an upgrade migration path from 1.5.x to 2.1.x-beta.
Due to internal changes, the table schemas used by Kong 2.1.x are incompatible
with those used by Kong 1.5.x. Migrating using the usual commands kong
migrations up
and kong migrations finish
will require a small window of
downtime, since the old and new versions cannot use the database at the same
time.
Alternatively, if you are able to perform a rolling restart of your Kong 1.5.x cluster you can use the following steps to cache entities and continue serving traffic while the upgrade is performed:
- Update the Kong 1.5.x cluster and set the
db_cache_warmup_entities
configuration value. Specify all the entities Kong has configured. -
Perform a rolling restart of the Kong 1.5.x nodes to pick up this new configuration value:
$ kong restart [-c configuration_file]
Monitor the
pg_stat_statements
on the Postgres server to ensure no additional entities need to be warmed in the cache (added to thedb_cache_warmup_entities
configuration). - From this point onward, it is no longer possible to start nodes in the old 1.5 (or 2.1.x-beta) cluster or access its admin API. Traffic will continue to be served.
- Download 2.1.x, and configure it to point to the same datastore as your old 1.5.x (or 2.1.x-beta) cluster.
- Run
kong migrations up
on the 2.1.x cluster. - Run
kong migrations finish
on the 2.1.x cluster. From now on, you can safely make Admin API requests to your 2.1 nodes. - Start provisioning 2.1 nodes.
- Gradually divert traffic away from your old nodes, and redirect traffic to your 2.1 cluster. Monitor your traffic to make sure everything is going smoothly.
- When your traffic is fully migrated to the 2.1 cluster, decommission your old 1.5 (or 2.1.x-beta) nodes.
PermalinkInstalling 2.1 on a fresh datastore
For installing on a fresh datastore, Kong Gateway 2.1 has the
kong migrations bootstrap
command. Run the following commands to
prepare a new 2.1 cluster from a fresh datastore. By default, the kong
CLI tool
loads the configuration from /etc/kong/kong.conf
, but you can optionally use
the -c
flag to indicate the path to your configuration file:
$ kong migrations bootstrap [-c /path/to/kong.conf]
$ kong start [-c /path/to/kong.conf]