In order to give you better service we use cookies. By continuing to use our website, you agree to the use of cookies as described in our Cookie Policy

Are you a Kong Gateway user? We'd love your feedback. Take the Survey

Kong Logo

Migrating Kong Enterprise from 1.5.x to 2.1.x

Careful! You are browsing documentation for an outdated version of Kong Enterprise. Go here to see the documentation for the latest version.
Estimated reading time: 5 minutes

Overview

Upgrade to major, minor, and patch Kong Enterprise releases using the kong migrations commands.

You can also use the commands to migrate all Kong Gateway entities to Kong Enterprise. See Migrating from Kong Gateway to Kong Enterprise.

If you experience any issues when running migrations, contact Kong Support for assistance.

Upgrade 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.

Version Prerequisites for Migrating to Kong Enterprise 2.1

If you are not on Kong Enterprise 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 Enterprise earlier than 1.3, migrate to 1.3 first.
  • If running a version of Kong Enterprise earlier than 1.5, migrate to 1.5 first.

Upgrade 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 Advancedrate-limiting-advanced) plugin does not support the cluster strategy in hybrid mode. The redis 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.

Migrating 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.

Kong Enterprise supports the zero downtime migration model. This means that while the migration is in process, you have two Kong clusters with different versions running that are sharing the same database. This is sometimes referred to as the blue-green migration model.

The migrations are designed so that there is no need to fully copy the data. The new version of Kong Enterprise is able to use the data as it is migrated, and the old Kong cluster keeps working until it is finally time to decommission it. For this reason, the full migration is split into two commands:

  • kong migrations up: performs only non-destructive operations
  • kong migrations finish: puts the database in the final expected state (DB-less mode is not supported in Kong Enterprise)
  1. 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.
  2. Run kong migrations up.

  3. After that finishes running, both the old (1.5) and new (2.1) clusters can now run simultaneously on the same datastore. Start provisioning 2.1 nodes, but do not use their Admin API yet.

    Important: If you need to make Admin API requests, these should be made to the old cluster’s nodes. This prevents the new cluster from generating data that is not understood by the old cluster.

  4. 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.
  5. When your traffic is fully migrated to the 2.1 cluster, decommission your old 1.5 (or 2.1.x-beta) nodes.
  6. From your 2.1 cluster, run kong migrations finish. From this point onward, it is no longer possible to start nodes in the old 1.5 (or 2.1.x-beta) cluster that still points to the same datastore. Run this command only when you are confident that your migration was successful. From now on, you can safely make Admin API requests to your 2.1 nodes.

Installing 2.1 on a fresh datastore

For installing on a fresh datastore, Kong Enterprise 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]

Patch Releases

There are no migrations in upgrades between current or future patch releases of the same minor release of Kong Enterprise (for example, 1.5.0.0 to 1.5.0.1; 2.1.1.0 to 2.1.1.1, and so forth). Therefore, the upgrade process is simpler for patch releases.

Prerequisites

  • Assuming that Kong Enterprise is already running on your system, acquire the latest version from any of the available installation methods and install it, overriding your previous installation.

  • If you are planning to make modifications to your configuration, this is an opportune time to do so.

  1. Run migrations to upgrade your database schema:

    $ kong migrations up [-c configuration_file]

  2. If the command is successful, and no migration ran (no output), then you only have to reload Kong:

    $ kong reload [-c configuration_file]

Reminder: The kong reload command leverages the Nginx reload signal that seamlessly starts new workers, which then take over from old workers before they are terminated. Kong serves new requests using the new configuration without dropping existing in-flight connections.

image