Kong Gateway 3.8.x breaking changes
Before upgrading, review any configuration or breaking changes in this version and prior versions that affect your current installation.
You may need to adopt different upgrade paths depending on your deployment methods, set of features in use, or custom plugins, for example.
Review the changelog for all the changes in this release.
Breaking changes and deprecations
kong.logrotate
configuration file no longer overwritten during upgrade
The kong.logrotate
configuration file will no longer be overwritten during upgrade.
When upgrading, set the environment variable DEBIAN_FRONTEND=noninteractive
on Debian/Ubuntu to avoid any interactive prompts and enable fully automatic upgrades.
log_statistics
defaults to false
for AI Proxy
A configuration validation was added to the AI Proxy plugin to prevent users from enabling log_statistics
for
providers that don’t support statistics. In addition, the default of log_statistics
was changed from
true
to false
, and a database migration is added as well for disabling log_statistics
if it
has already been enabled upon unsupported providers.
Custom plugins that used shared Redis config
In 3.8.0.0, Kong has changed and refactored the shared Redis configuration that previously was imported by require "kong.enterprise_edition.redis"
. If you created a custom plugin that is using this shared configuration or if you have a forked version of a plugin, like rate-limiting-advanced
, then you might need to do additional steps before you can upgrade to the new version of this Redis config.
Out of the box, custom plugins should still work since the old shared configuration is still available. The new config adds the cluster_max_redirections
option for Redis Cluster, and the cluster_nodes
format and sentinel_nodes
were changed. Other than that, the initialization step is no longer required.
Upgrade custom plugins using a shared Redis config
If your plugin is using a shared Redis config (for example, if you import require "kong.enterprise_edition.redis"
) you must do the following:
- Remove the
redis.init_conf(conf)
library initialization call. Whereredis
islocal redis = require "kong.enterprise_edition.redis"
. - Switch the imports of redis from
local redis = require "kong.enterprise_edition.redis"
tolocal redis = require "kong.enterprise_edition.tools.redis.v2"
.
Upgrade custom plugins using the rate limiting library
If your plugin is using rate limiting library (as in you import local ratelimiting = require("kong.tools.public.rate-limiting").new_instance("your-plugin-name")
) you must switch the imports of the following:
-
Shared Redis config: Change
local redis = require "kong.enterprise_edition.redis"
tolocal redis = require "kong.enterprise_edition.tools.redis.v2"
-
Rate limiting library: Change
local ratelimiting = require("kong.tools.public.rate-limiting").new_instance("your-plugin-name")
tolocal ratelimiting = require("kong.tools.public.rate-limiting").new_instance("your-plugin-name", { redis_config_version = "v2" })
Deprecations
sentinel_addresses
and cluster_addresses
for Redis
The following plugins switched cluster_addresses
to cluster_nodes
and sentinel_addresses
to sentinel_nodes
for Redis configuration:
- AI Rate Limiting Advanced
- GraphQL Proxy Caching Advanced
- GraphQL Rate Limiting Advanced
- Proxy Caching Advanced
- Rate Limiting Advanced
These fields are converted automatically when you run kong migrations up
. Also, any changes uploaded via decK or the Admin API using the old cluster_addresses
and sentinel_addresses
are respected and properly translated to the new fields.
Forked custom plugins aren’t automatically migrated. For more information about how to migrate custom plugins, see Custom plugins that used shared Redis config.