Kong Gateway 3.6.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

General

If you are using ngx.var.http_* in custom code to access HTTP headers, the behavior of that variable changed slightly when the same header is used multiple times in a single request. Previously, it would return the first value only; now it returns all the values, separated by commas. Kong Gateway’s PDK header getters and setters work as before.

Wasm

To avoid ambiguity with other Wasm-related nginx.conf directives, the prefix for Wasm shm_kv nginx.conf directives was changed from nginx_wasm_shm_ to nginx_wasm_shm_kv_. #11919

Admin API

The listing endpoints for consumer groups (/consumer_groups) and consumers (/consumers) now respond with paginated results. The JSON key for the list has been changed to data instead of consumer_groups or consumers.

Configuration changes

The default value of the dns_no_sync option has been changed to off.

TLS changes

3.6.0.0

The recent OpenResty bump includes TLS 1.3 and deprecates TLS 1.1. If you still need to support TLS 1.1, set the ssl_cipher_suite setting to old.

In OpenSSL 3.2, the default SSL/TLS security level has been changed from 1 to 2. This means the security level is set to 112 bits of security. As a result, the following are prohibited:

  • RSA, DSA, and DH keys shorter than 2048 bits
  • ECC keys shorter than 224 bits
  • Any cipher suite using RC4
  • SSL version 3 Additionally, compression is disabled.

3.6.1.0

TLSv1.1 and lower is now disabled by default in OpenSSL 3.x.

Kong Manager Enterprise

As of Kong Gateway 3.6, Kong Manager uses the session management mechanism in the OpenID Connect plugin. admin_gui_session_conf is no longer required when authenticating with OIDC. Instead, session-related configuration parameters are set in admin_gui_auth_conf (like session_secret).

See the migration guide for more information.

Plugin changes

  • ACME (acme), Rate Limiting (rate-limiting), and Response Rate Limiting (response-ratelimiting)
    • Standardized Redis configuration across plugins. The Redis configuration now follows a common schema that is shared across other plugins. #12300 #12301
  • Azure Functions (azure-functions):
    • The Azure Functions plugin now eliminates the upstream/request URI and only uses the routeprefix configuration field to construct the request path when requesting the Azure API.
  • OAS Validation (oas-validation)
    • The plugin now bypasses schema validation when the content type is not application/json.
  • Proxy Cache Advanced (proxy-cache-advanced)
    • Removed the undesired proxy-cache-advanced/migrations/001_035_to_050.lua file, which blocked migration from OSS to Enterprise. This is a breaking change only if you are upgrading from a Kong Gateway version between 0.3.5 and 0.5.0.
  • SAML (saml)
    • Adjusted the priority of the SAML plugin to 1010 to correct the integration between the SAML plugin and other consumer-based plugins.

Known issues

The following is a list of known issues that may be fixed in a future release.

Operating system requirements

Kong Gateway 3.6.0.0 requires a higher limit on the number of file descriptions to function properly. It will not start properly with a limit set to 1024 or lower. We recommend using ulimit on your operating system to set it to at least 4096 using ulimit -n 4096.

Issue fixed in 3.6.1.0: Although a higher limit on file descriptors (uname -n) is recommended in general for Kong Gateway, you can upgrade to 3.6.1.0 to start with a default of 1024 again.

HTTP/2 requires Content-Length for plugins that read request body

Kong 3.6.x has introduced a regression for plugins that read the body of incoming requests. Clients must specify a Content-Length header that represents the length of the request body. Not including this header, or relying on Transfer-Encoding: chunked will result in an HTTP response with the error code 500.

Currently known affected plugins:

Issue fixed in 3.6.1.1: Reverted the hard-coded limitation of the ngx.read_body() API in OpenResty upstreams’ new versions when downstream connections are in HTTP/2 or HTTP/3 stream modes.

Previous Kong Gateway 3.5.x breaking changes

Next Kong Gateway 3.7.x breaking changes