Estimated reading time:
Prerequisites for Migrating to 0.35
- If running Kong Enterprise 0.34, it is necessary to upgrade to 0.34-1 first before migrating to 0.35. (Likewise, if running a version of Kong Enterprise earlier than 0.34, it is first necessary to upgrade to 0.34 before 0.34-1.)
- If running Kong versions 0.14 or 0.15, you must upgrade to Kong 1.0 before upgrading to Kong Enterprise 0.35. You cannot upgrade to Kong Enterprise 0.34 first.
- If running Kong version 0.13 or older, you can either upgrade to Kong 1.0 or Kong Enterprise 0.34 before upgrading to Kong Enterprise 0.35.
- If the datastore still has
API entities instead of
Routes, upgrading to 0.35 will not be possible.
APIs were deprecated in release 0.32 and are now removed from Kong. It is possible to convert
Routes and then remove the
APIs on the 0.34 node. See Migrating APIs to Services
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
- Instances where the Portal and Files API are on different hostnames require that they at least share a common root, and that the
cookie_domain setting of the Portal session configuration be that common root. For example, if the Portal itself is at
portal.kong.example and the Files API is at
rbac_role_endpoints will be updated to adhere to changes in the Dev Portal API. This only applies to Portal-related endpoints that were present in or set by Kong Manager; any user-generated endpoints will need to be updated manually. The endpoints that will be updated automatically are as follows:
'/portal/*' => '/developers/*', '/files/*'
'/portal/developers' => '/developers/*'
'/portal/developers/*' => '/developers/*'
'/portal/developers/*/*' => '/developers/*/*'
'/portal/developers/*/email' => '/developers/*/email'
'/portal/developers/*/meta' => '/developers/*/meta'
'/portal/developers/*/password' => '/developers/*/password'
'/portal/invite' => '/developers/invite'
Migration Steps from 0.34 to 0.35
Kong 0.35 introduces a new, improved migrations framework. The full migration is now split into two steps, which are performed via commands
kong migrations up and
kong migrations finish.
For a no-downtime migration from a 0.34 cluster to a 0.35 cluster:
- Download 0.35, and configure it to point to the same datastore as your 0.34 cluster.
kong migrations up. Both 0.34 and 0.35 nodes can now run simultaneously on the same datastore.
Start provisioning 0.35 nodes, but do not use their Admin API yet.
⚠️ Important: When doing a Blue/Green upgrade in a 0.34 cluster where RBAC is enabled, if you make an Admin API request from a new 0.35 node, from then on, Admin API calls will only work from the new 0.35 node. This is because the new token will be hashed in the database and will fail on the old 0.34 nodes since they do not know how to verify the hashed token. Note also that Admins are present in a new cluster only after running
kong migrations finish.
- Gradually divert traffic away from your 0.34 nodes, and into your 0.35 cluster. Monitor your traffic to make sure everything is going smoothly.
- When your traffic is fully migrated to the 0.35 cluster, decommission your 0.34 nodes.
- From your 0.35 cluster, run:
kong migrations finish. From this point on, it will not be possible to start 0.34 nodes 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 0.35 nodes.
At any step of the way, you may run
kong migrations list to get a report of the state of migrations. It will list whether there are missing migrations, if there are pending migrations (which have already started in the
kong migrations up step and later need to finish in the
kong migrations finish step) or if there are new migrations available. The status code of the process will also change accordingly:
0 - migrations are up-to-date
1 - failed inspecting the state of migrations (e.g. database is down)
3 - database needs bootstrapping: you should run
kong migrations bootstrap to install on a fresh datastore.
4 - there are pending migrations: once your old cluster is decommissioned you should run
kong migrations finish (step 5 above).
5 - there are new migrations: you should start a migration sequence (beginning from step 1 above).
Migration Steps from Kong 1.0 to Kong Enterprise 0.35
Note: This action is irreversible, therefore it is highly recommended to have a backup of production data.
Kong Enterprise 0.35 includes a command to migrate all Kong entities to Kong Enterprise. The following steps will guide you through the migration process.
First download Kong Enterprise 0.35, and configure it to point to the same datastore as your Kong 1.0 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 0.35 node.