« Changelog History


Kong v2.5.0 Release Notes

  • 🚀 > Release date: 2021-07-13

    🚀 This is the final release of Kong 2.5.0, with no breaking changes with respect to the 2.x series.

    🚀 This release includes Control Plane resiliency to database outages and the new declarative_config_string config option, among other features and fixes.

    Distribution

    • 📦 :warning: Since 2.4.1, Kong packages are no longer distributed through Bintray. Please visit the installation docs for more details.

    Dependencies

    • ⬆️ Bumped openresty from 1.19.3.1 to 1.19.3.2 #7430
    • ⬆️ Bumped luasec from 1.0 to 1.0.1 #7126
    • ⬆️ Bumped luarocks from 3.5.0 to 3.7.0 #7043
    • ⬆️ Bumped grpcurl from 1.8.0 to 1.8.1 #7128
    • ⬆️ Bumped penlight from 1.9.2 to 1.10.0 #7127
    • ⬆️ Bumped lua-resty-dns-client from 6.0.0 to 6.0.2 #7539
    • ⬆️ Bumped kong-plugin-prometheus from 1.2 to 1.3 #7415
    • ⬆️ Bumped kong-plugin-zipkin from 1.3 to 1.4 #7455
    • ⬆️ Bumped lua-resty-openssl from 0.7.2 to 0.7.3 #7509
    • ⬆️ Bumped lua-resty-healthcheck from 1.4.1 to 1.4.2 #7511
    • ⬆️ Bumped hmac-auth from 2.3.0 to 2.4.0 #7522
    • 📌 Pinned lua-protobuf to 0.3.2 (previously unpinned) #7079

    🚚 All Kong Gateway OSS plugins will be moved from individual repositories and centralized into the main Kong Gateway (OSS) repository. We are making a gradual transition, starting with the 🔌 grpc-gateway plugin first:

    • 🚚 Moved grpc-gateway inside the Kong repo. #7466

    ➕ Additions

    Core

    • ⚡️ Control Planes can now send updates to new data planes even if the control planes lose connection to the database. #6938
    • Kong now automatically adds cluster_cert(cluster_mtls=shared) or cluster_ca_cert(cluster_mtls=pki) into lua_ssl_trusted_certificate when operating in Hybrid mode. Before, Hybrid mode users needed to configure lua_ssl_trusted_certificate manually as a requirement for Lua to verify the Control Plane’s certificate. See Starting Data Plane Nodes in the Hybrid Mode guide for more information. #7044
    • New declarative_config_string option allows loading a declarative config directly from a string. See the Loading The Declarative Configuration File section of the DB-less and Declarative Configuration guide for more information. #7379

    PDK

    • The Kong PDK now accepts tables in the response body for Stream subsystems, just as it does for the HTTP subsystem. Before developers had to check the subsystem if they wrote code that used the exit() function before calling it, because passing the wrong argument type would break the request response. #7082

    🔌 Plugins

    • hmac-auth: The HMAC Authentication plugin now includes support for the @request-target field in the signature string. Before, the plugin used the request-line parameter, which contains the HTTP request method, request URI, and the HTTP version number. The inclusion of the HTTP version number in the signature caused requests to the same target but using different request methods(such as HTTP/2) to have different signatures. The newly added request-target field only includes the lowercase request method and request URI when calculating the hash, avoiding those issues. See the HMAC Authentication documentation for more information. #7037
    • syslog: The Syslog plugin now includes facility configuration options, which are a way for the plugin to group error messages from different sources. See the description for the facility parameter in the Parameters section of the Syslog documentation for more information. #6081. Thanks, jideel!
    • Prometheus: The Prometheus plugin now exposes connected data planes' status on the control plane. New metrics include the following: data_plane_last_seen, data_plane_config_hash and data_plane_version_compatible. These metrics can be useful for troubleshooting when data planes have inconsistent configurations across the cluster. See the Available metrics section of the Prometheus plugin documentation for more information. 98
    • Zipkin: The Zipkin plugin now includes the following tags: kong.route,kong.service_name and kong.route_name. See the Spans section of the Zipkin plugin documentation for more information. 115

    Hybrid Mode

    • 👍 Kong now exposes an upstream health checks endpoint (using the status API) on the data plane for better observability. #7429
    • 👀 Control Planes are now more lenient when checking Data Planes' compatibility in Hybrid mode. See the Version compatibility section of the Hybrid Mode guide for more information. #7488
    • 🚀 This release starts the groundwork for Hybrid Mode 2.0 Protocol. This code isn't active by default in Kong 2.5, but it allows future development. #7462

    🛠 Fixes

    Core

    • When using DB-less mode, select_by_cache_key now finds entities by using the provided field directly in select_by_key and does not complete unnecessary cache reads. #7146
    • 🔌 Kong can now finish initialization even if a plugin’s init_worker handler fails, improving stability. #7099
    • TLS keepalive requests no longer share their context. Before when two calls were made to the same "server+hostname" but different routes and using a keepalive connection, plugins that were active in the first call were also sometimes (incorrectly) active in the second call. The wrong plugin was active because Kong was passing context in the SSL phase to the plugin iterator, creating connection-wide structures in that context, which was then shared between different keepalive requests. With this fix, Kong does not pass context to plugin iterators with the certificate phase, avoiding plugin mixups.#7102
    • The HTTP status 405 is now handled by Kong's error handler. Before accessing Kong using the TRACE method returned a standard NGINX error page because the 405 wasn’t included in the error page settings of the NGINX configuration. #6933. Thanks, yamaken1343!
    • ⚡️ Custom ngx.sleep implementation in init_worker phase now invokes update_time in order to prevent time-based deadlocks #7532
    • Proxy-Authorization header is removed when it is part of the original request or when a plugin sets it to the same value as the original request #7533
    • 🔌 HEAD requests don't provoke an error when a Plugin implements the response phase #7535

    Hybrid Mode

    • Control planes no longer perform health checks on CRUD upstreams’ and targets’ events. #7085
    • To prevent unnecessary cache flips on data planes, Kong now checks dao:crud events more strictly and has a new cluster event, clustering:push_config for configuration pushes. These updates allow Kong to filter invalidation events that do not actually require a database change. Furthermore, the clustering module does not subscribe to the generic invalidations event, which has a more broad scope than database entity invalidations. #7112
    • Data Planes ignore null fields coming from Control Planes when doing schema validation. #7458
    • 🔊 Kong now includes the source in error logs produced by Control Planes. #7494
    • Data Plane config hash calculation and checking is more consistent now: it is impervious to changes in table iterations, hashes are calculated in both CP and DP, and DPs send pings more immediately and with the new hash now #7483

    Balancer

    • All targets are returned by the Admin API now, including targets with a weight=0, or disabled targets. Before disabled targets were not included in the output when users attempted to list all targets. Then when users attempted to add the targets again, they recieved an error message telling them the targets already existed. #7094
    • ⚡️ Upserting existing targets no longer fails. Before, because of updates made to target configurations since Kong v2.2.0, upserting older configurations would fail. This fix allows older configurations to be imported. #7052
    • The last balancer attempt is now correctly logged. Before balancer tries were saved when retrying, which meant the last retry state was not saved since there were no more retries. This update saves the failure state so it can be correctly logged. #6972
    • ⚡️ Kong now ensures that the correct upstream event is removed from the queue when updating the balancer state. #7103

    CLI

    • The prefix argument in the kong stop command now takes precedence over environment variables, as it does in the kong start command. #7080

    🔧 Configuration

    • 🔧 Declarative configurations now correctly parse custom plugin entities schemas with attributes called "plugins". Before when using declarative configurations, users with custom plugins that included a "plugins" field would encounter startup exceptions. With this fix, the declarative configuration can now distinguish between plugins schema and custom plugins fields. #7412
    • 🔧 The stream access log configuration options are now properly separated from the HTTP access log. Before when users used Kong with TCP, they couldn’t use a custom log format. With this fix, proxy_stream_access_log and proxy_stream_error_log have been added to differentiate stream access log from the HTTP subsystem. See proxy_stream_access_log and proxy_stream_error in the Configuration Property Reference for more information. #7046

    Migrations

    • Kong no longer assumes that /?/init.lua is in the Lua path when doing migrations. Before, when users created a custom plugin in a non-standard location and set lua_package_path = /usr/local/custom/?.lua, migrations failed. Migrations failed because the Kong core file is init.lua and it is required as part of kong.plugins.<name>.migrations. With this fix, migrations no longer expect init.lua to be a part of the path. #6993
    • Kong no longer emits errors when doing ALTER COLUMN operations in Apache Cassandra 4.0. #7490

    PDK

    • ⚡️ With this update, kong.response.get_XXX() functions now work in the log phase on external plugins. Before kong.response.get_XXX() functions required data from the response object, which was not accessible in the post-log timer used to call log handlers in external plugins. Now these functions work by accessing the required data from the set saved at the start of the log phase. See kong.response in the Plugin Development Kit for more information. #7048
    • 🔌 External plugins handle certain error conditions better while the Kong balancer is being refreshed. Before when an instance_id of an external plugin changed, and the plugin instance attempted to reset and retry, it was failing because of a typo in the comparison. #7153. Thanks, ealogar!
    • 🚀 With this release, kong.log's phase checker now accounts for the existence of the new response pseudo-phase. Before users may have erroneously received a safe runtime error for using a function out-of-place in the PDK. #7109
    • Kong no longer sandboxes the string.rep function. Before string.rep was sandboxed to disallow a single operation from allocating too much memory. However, a single operation allocating too much memory is no longer an issue because in LuaJIT there are no debug hooks and it is trivial to implement a loop to allocate memory on every single iteration. Additionally, since the string table is global and obtainable by any sandboxed string, its sandboxing provoked issues on global state. #7167
    • The kong.pdk.node function can now correctly iterates over all the shared dict metrics. Before this fix, users using the kong.pdk.node function could not see all shared dict metrics under the Stream subsystem. #7078

    🔌 Plugins

    • 🚚 All custom plugins that are using the deprecated BasePlugin class have to remove this inheritance.
    • LDAP-auth: The LDAP Authentication schema now includes a default value for the config.ldap_port parameter that matches the documentation. Before the plugin documentation Parameters section included a reference to a default value for the LDAP port; however, the default value was not included in the plugin schema. #7438
    • Prometheus: The Prometheus plugin exporter now attaches subsystem labels to memory stats. Before, the HTTP and Stream subsystems were not distinguished, so their metrics were interpreted as duplicate entries by Prometheus. https://github.com/Kong/kong-plugin-prometheus/pull/118
    • 🔌 External Plugins: the return code 127 (command not found) is detected and appropriate error is returned #7523