Kong Gateway 3.2.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, custom plugins, for example.

Plugins

For breaking changes to plugins, see the Kong Gateway Changelog for your Kong Gateway version.

PostgreSQL SSL version bump

The default PostgreSQL SSL version has been bumped to TLS 1.2.

This causes changes to pg_ssl_version (set through kong.conf):

• The default value is now tlsv1_2.
• pg_ssl_version previously accepted any string. In this version, it requires one of the following values: tlsv1_1, tlsv1_2, tlsv1_3 or any.

This mirrors the setting ssl_min_protocol_version in PostgreSQL 12.x and onward. See the PostgreSQL documentation for more information about that parameter.

To use the default setting in kong.conf, verify that your Postgres server supports TLS 1.2 or higher versions, or set the TLS version yourself.

TLS versions lower than tlsv1_2 are already deprecated and are considered insecure from PostgreSQL 12.x onward.

Changes to the Kong-Debug header

Added the allow_debug_header configuration property to kong.conf to constrain the Kong-Debug header for debugging. This option defaults to off.

If you were previously relying on the Kong-Debug header to provide debugging information, set allow_debug_header: on in kong.conf to continue doing so.

JWT plugin

The JWT plugin now denies any request that has different tokens in the JWT token search locations.

Session library upgrade

The lua-resty-session library has been upgraded to v4.0.0. This version includes a full rewrite of the session library.

This upgrade affects the following:

• Session plugin
• OpenID Connect plugin
• SAML plugin
• Any session configuration that uses the Session or OpenID Connect plugin in the background, including sessions for Kong Manager and Dev Portal.

All existing sessions are invalidated when upgrading to this version. For sessions to work as expected in this version, all nodes must run Kong Gateway 3.2.x or later. If multiple data planes run different versions, every time a user hits a different DP, even for the same endpoint, the previous session is invalidated.

For that reason, we recommend that during upgrades, proxy nodes with mixed versions run for as little time as possible. During that time, the invalid sessions could cause failures and partial downtime.

You can expect the following behavior:

• After upgrading the control plane: Existing Kong Manager and Dev Portal sessions will be invalidated and all users will be required to log back in.
• After upgrading the data planes: Existing proxy sessions will be invalidated. If you have an IdP configured, users will be required to log back into the IdP.

Session configuration parameter changes

The session library upgrade includes new, changed, and removed parameters. Here’s how they function:

• The new parameter idling_timeout, which replaces cookie_lifetime, has a default value of 900. Unless configured differently, sessions expire after 900 seconds (15 minutes) of idling.
• The new parameter absolute_timeout has a default value of 86400. Unless configured differently, sessions expire after 86400 seconds (24 hours).
• All renamed parameters will still work by their old names.
• Any removed parameters will not work anymore. They won’t break your configuration, and sessions will continue to function, but they will not contribute anything to the configuration.

Existing session configurations will still work as configured with the old parameters.

Do not change any parameters to the new ones until all CP and DP nodes are upgraded.

After you have upgraded all of your CP and DP nodes to 3.2 and ensured that your environment is stable, we recommend updating parameters to their new renamed versions, and cleaning out any removed parameters from session configuration to avoid unpredictable behavior.

Session plugin

The following parameters and the values that they accept have changed. For details on the new accepted values, see the Session plugin documentation.

SAML plugin

The following parameters and the values that they accept have changed. For details on the new accepted values, see the SAML plugin documentation.

OpenID Connect plugin

The following parameters and the values that they accept have changed. For details on the new accepted values, see the OpenID Connect plugin documentation.