You are browsing documentation for an older version. See the latest documentation here.

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:

1. Remove the redis.init_conf(conf) library initialization call. Where redis is local redis = require "kong.enterprise_edition.redis".
2. Switch the imports of redis from local redis = require "kong.enterprise_edition.redis" to local 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" to local 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") to local 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.