« Changelog History


Kong v0.12.0 Release Notes

Release Date: 2018-01-16 // over 6 years ago

  • 🚀 This major release focuses on two new features we are very excited about: health checks and hash based load balancing!

    We also took this as an opportunity to fix a few prominent issues, sometimes at the expense of breaking changes but overall improving the flexibility and 🚀 usability of Kong! Do keep in mind that this is a major release, and as such, that we require of you to run the migrations step, via the kong migrations up command.

    ⬆️ Please take a few minutes to thoroughly read the 0.12 Upgrade ⬆️ Path for more details regarding breaking changes and migrations before planning to ⬆️ upgrade your Kong cluster.

    🗄 Deprecation notices

    🗄 Starting with 0.12.0, we are announcing the deprecation of older versions 👍 of our supported databases:

    • 👌 Support for PostgreSQL 9.4 is deprecated. Users are advised to upgrade to 9.5+
    • 👌 Support for Cassandra 2.1 and below is deprecated. Users are advised to upgrade to 2.2+

    🚀 Note that the above deprecated versions are still supported in this release, but will be dropped in subsequent ones.

    💥 Breaking changes

    Core
    • ⚠ :warning: The required OpenResty version has been bumped to 1.11.2.5. If you are installing Kong from one of our distribution packages, you are not affected by this change. #3097
    • ⚠ :warning: As Kong now executes subsequent plugins when a request is being short-circuited (e.g. HTTP 401 responses from auth plugins), plugins that run in the header or body filter phases will be run upon such responses from the access phase. We consider this change a big improvement in the Kong run-loop as it allows for more flexibility for plugins. However, it is unlikely, but possible that some of these plugins (e.g. your custom plugins) now run in scenarios where they were not previously expected to run. #3079
    Admin API
    • ⚠ :warning: By default, the Admin API now only listens on the local interface. We consider this change to be an improvement in the default security policy of Kong. If you are already using Kong, and your Admin API still binds to all interfaces, consider updating it as well. You can do so by updating the admin_listen configuration value, like so: admin_listen = 127.0.0.1:8001. Thanks @pduldig-at-tw for the suggestion and the patch. #3016

    :red_circle: Note to Docker users: Beware of this change as you may have to ensure that your Admin API is reachable via the host's interface. You can use the -e KONG_ADMIN_LISTEN argument when provisioning your container(s) to update this value; for example, -e KONG_ADMIN_LISTEN=0.0.0.0:8001.

    • :warning: To reduce confusion, the /upstreams/:upstream_name_or_id/targets/ has been updated to not show the full list of Targets anymore, but only the ones that are currently active in the load balancer. To retrieve the full history of Targets, you can now query /upstreams/:upstream_name_or_id/targets/all. The /upstreams/:upstream_name_or_id/targets/active endpoint has been removed. Thanks @hbagdi for tackling this backlog item! #3049
    • 🚚 :warning: The orderlist property of Upstreams has been removed, along with any confusion it may have brought. The balancer is now able to fully function without it, yet with the same level of entropy in its load distribution. #2748
    CLI
    • 🗄 :warning: The $ kong compile command which was deprecated in 0.11.0 has been removed. #3069
    🔌 Plugins
    • ⚠ :warning: In logging plugins, the request.request_uri field has been renamed to request.url. #2445 #3098

    ➕ Added

    Core
    • :fireworks: Support for health checks! Kong can now short-circuit some of your upstream Targets (replicas) from its load balancer when it encounters too many TCP or HTTP errors. You can configure the number of failures, or the HTTP status codes that should be considered invalid, and Kong will monitor the failures and successes of proxied requests to each upstream Target. We call this feature passive health checks. Additionally, you can configure active health checks, which will make Kong perform periodic HTTP test requests to actively monitor the health of your upstream services, and pre-emptively short-circuit them. Upstream Targets can be manually taken up or down via two new Admin API endpoints: /healthy and /unhealthy. #3096
    • :fireworks: Support for hash based load balancing! Kong now offers consistent hashing/sticky sessions load balancing capabilities via the new hash_* attributes of the Upstream entity. Hashes can be based off client IPs, request headers, or Consumers! #2875
    • 🔌 :fireworks: Logging plugins now log requests that were short-circuited by Kong! (e.g. HTTP 401 responses from auth plugins or HTTP 429 responses from rate limiting plugins, etc.) Kong now executes any subsequent plugins once a request has been short-circuited. Your plugin must be using the kong.tools.responses module for this behavior to be respected. #3079
    • Kong is now compatible with OpenResty up to version 1.13.6.1. Be aware that the recommended (and default) version shipped with this release is still 1.11.2.5. #3070
    CLI
    • $ kong start now considers the commonly used /opt/openresty prefix when searching for the nginx executable. #3074
    Admin API
    • Two new endpoints, /healthy and /unhealthy can be used to manually bring upstream Targets up or down, as part of the new health checks feature of the load balancer. #3096
    🔌 Plugins
    • 🔊 logging plugins: A new field upstream_uri now logs the value of the upstream request's path. This is useful to help debugging plugins or setups that aim at rewriting a request's URL during proxying. Thanks @shiprabehera for the patch! #2445
    • 🔊 tcp-log: Support for TLS handshake with the logs recipients for secure transmissions of logging data. #3091
    • 👍 jwt: Support for JWTs passed in cookies. Use the new config.cookie_names property to configure the behavior to your liking. Thanks @mvanholsteijn for the patch! #2974
    • oauth2
      • New config.auth_header_name property to customize the authorization header's name. Thanks @supraja93 #2928
      • New config.refresh_ttl property to customize the TTL of refresh tokens, previously hard-coded to 14 days. Thanks @bob983 for the patch! #2942
      • Avoid an error in the logs when trying to retrieve an access token from a request without a body. Thanks @WALL-E for the patch. #3063
    • ldap: New config.header_type property to customize the authorization method in the Authorization header. Thanks @francois-maillard for the patch! #2963

    🛠 Fixed

    CLI
    • 🛠 Fix a potential vulnerability in which an attacker could read the Kong configuration file with insufficient permissions for a short window of time while Kong is being started. #3057
    • 🌲 Proper log message upon timeout in $ kong quit. #3061
    Admin API
    • 👍 The /certificates endpoint now properly supports the snis parameter in PUT and PATCH requests. Thanks @hbagdi for the contribution! #3040
    • 👍 Avoid sending the HTTP/1.1 415 Unsupported Content Type response when receiving a request with a valid Content-Type, but with an empty payload. #3077
    🔌 Plugins

    Back to TOC