Kong v0.11.0 Release Notes
Release Date: 2017-08-16 // over 6 years ago-
โ The latest and greatest version of Kong features improvements all over the ๐ board for a better and easier integration with your infrastructure!
๐ The highlights of this release are:
- Support for regex URIs in routing, one of the oldest requested features from the community.
- ๐ Support for HTTP/2 traffic from your clients.
- ๐ Kong does not depend on Serf anymore, which makes deployment and networking requirements considerably simpler.
- ๐ A better integration with orchestration tools thanks to the support for non FQDNs in Kong's DNS resolver.
๐ As per usual, our major releases include datastore migrations which are ๐ฅ considered breaking changes. Additionally, this release contains numerous ๐ฅ breaking changes to the deployment process and proxying behavior that you should be familiar with.
We strongly advise that you read this changeset thoroughly, as well as the โฌ๏ธ 0.11 Upgrade Path โฌ๏ธ if you are planning to upgrade a Kong cluster.
๐ฅ Breaking changes
๐ง Configuration
- โก๏ธ :warning: Numerous updates were made to the Nginx configuration template. If you are using a custom template, you must apply those modifications. See the 0.11 Upgrade Path for a complete list of changes to apply.
๐ Migrations & Deployment
- :warning: Migrations are not executed automatically by
kong start
anymore. Migrations are now a manual process, which must be executed via thekong migrations
command. In practice, this means that you have to runkong migrations up [-c kong.conf]
in one of your nodes before starting your Kong nodes. This command should be run from a single node/container to avoid several nodes running migrations concurrently and potentially corrupting your database. Once the migrations are up-to-date, it is considered safe to start multiple Kong nodes concurrently. #2421 - :warning: :fireworks: Serf is not a dependency anymore. Kong nodes now
handle cache invalidation events via a built-in database polling mechanism.
See the new "Datastore Cache" section of the configuration file which
contains 3 new documented properties:
db_update_frequency
,db_update_propagation
, anddb_cache_ttl
. If you are using Cassandra, you should pay a particular attention to thedb_update_propagation
setting, as you should not use the default value of0
. #2561
Core
- โ :warning: Kong now requires OpenResty
1.11.2.4
. OpenResty's LuaJIT can now be built with Lua 5.2 compatibility. #2489 #2790 - โ :warning: Previously, the
X-Forwarded-*
andX-Real-IP
headers were trusted from any client by default, and forwarded upstream. With the introduction of the newtrusted_ips
property (see the below "Added" section) and to enforce best security practices, Kong does not trust any client IP address by default anymore. This will make Kong not forward incomingX-Forwarded-*
headers if not coming from configured, trusted IP addresses blocks. This setting also affects the APIcheck_https
field, which itself relies on trustedX-Forwarded-Proto
headers only. #2236 - :warning: The API Object property
http_if_terminated
is now set tofalse
by default. For Kong to evaluate the clientX-Forwarded-Proto
header, you must now configure Kong to trust the client IP (see above change), and you must explicitly set this value totrue
. This affects you if you are doing SSL termination somewhere before your requests hit Kong, and if you have configuredhttps_only
on the API, or if you use a plugin that requires HTTPS traffic (e.g. OAuth2). #2588 - โ :warning: The internal DNS resolver now honours the
search
andndots
configuration options of yourresolv.conf
file. Make sure that DNS resolution is still consistent in your environment, and consider eventually not using FQDNs anymore. #2425
Admin API
- โ :warning: As a result of the Serf removal, Kong is now entirely stateless,
and as such, the
/cluster
endpoint has disappeared. #2561 - โ :warning: The Admin API
/status
endpoint does not return a count of the database entities anymore. Instead, it now returns adatabase.reachable
boolean value, which reflects the state of the connection between Kong and the underlying database. Please note that this flag does not reflect the health of the database itself. #2567
๐ Plugin development
- โ :warning: The upstream URI is now determined via the Nginx
$upstream_uri
variable. Custom plugins using thengx.req.set_uri()
API will not be taken into consideration anymore. One must now set thengx.var.upstream_uri
variable from the Lua land. #2519 - โ :warning: The
hooks.lua
module for custom plugins is dropped, along with thedatabase_cache.lua
module. Database entities caching and eviction has been greatly improved to simplify and automate most caching use-cases. See the Plugins Development Guide and the 0.11 Upgrade Path for more details. #2561 - โ :warning: To ensure that the order of execution of plugins is still the same
for vanilla Kong installations, we had to update the
PRIORITY
field of some of our bundled plugins. If your custom plugin must run after or before a specific bundled plugin, you might have to update your plugin'sPRIORITY
field as well. The complete list of plugins and their priorities is available on the Plugins Development Guide. #2489 #2813
๐ Deprecated
CLI
- ๐ The
kong compile
command has been deprecated. Instead, prefer using the newkong prepare
command. #2706
๐ Changed
Core
- ๐ Performance around DNS resolution has been greatly improved in some cases. #2625
- Secret values are now generated with a kernel-level, Cryptographically Secure PRNG. #2536
- The
.kong_env
file created by Kong in its running prefix is now written without world-read permissions. #2611
๐ Plugin development
- The
marshall_event
function on schemas is now ignored by Kong, and can be safely removed as the new cache invalidation mechanism natively handles safer events broadcasting. #2561
โ Added
Core
- ๐ :fireworks: Support for regex URIs! You can now define regexes in your
APIs
uris
property. Those regexes can have capturing groups which can be extracted by Kong during a request, and accessed later in the plugins (useful for URI rewriting). See the Proxy Guide for documentation on how to use regex URIs. #2681 - ๐ :fireworks: Support for HTTP/2. A new
http2
directive now enables HTTP/2 traffic on theproxy_listen_ssl
address. #2541 - ๐ง :fireworks: Support for the
search
andndots
configuration options of yourresolv.conf
file. #2425 - Kong now forwards new headers to your upstream services:
X-Forwarded-Host
,X-Forwarded-Port
, andX-Forwarded-Proto
. #2236 - Support for the PROXY protocol. If the new
real_ip_header
configuration property is set toreal_ip_header = proxy_protocol
, then Kong will append theproxy_protocol
parameter to the Nginxlisten
directive of the Kong proxy port. #2236 - ๐ Support for BDR compatibility in the PostgreSQL migrations. Thanks @AlexBloor for the patch! #2672
๐ง Configuration
- ๐ Support for DNS nameservers specified in IPv6 format. #2634
- ๐ง A few new DNS configuration properties allow you to tweak the Kong DNS resolver, and in particular, how it handles the resolution of different record types or the eviction of stale records. #2625
- ๐ง A new
trusted_ips
configuration property allows you to define a list of trusted IP address blocks that are known to send trustedX-Forwarded-*
headers. Requests from trusted IPs will make Kong forward those headers upstream. Requests from non-trusted IP addresses will make Kong override theX-Forwarded-*
headers with its own values. In addition, this property also sets the ngx_http_realip_moduleset_real_ip_from
directive(s), which makes Kong trust the incomingX-Real-IP
header as well, which is used for operations such as rate-limiting by IP address, and that Kong forwards upstream as well. #2236 - You can now configure the ngx_http_realip_module from the Kong
configuration. In addition to
trusted_ips
which sets theset_real_ip_from
directives(s), two new properties,real_ip_header
andreal_ip_recursive
allow you to configure the ngx_http_realip_module directives bearing the same name. #2236 - ๐ง Ability to hide Kong-specific response headers. Two new configuration
fields:
server_tokens
andlatency_tokens
will respectively toggle whether theServer
andX-Kong-*-Latency
headers should be sent to downstream clients. #2259 - ๐ New configuration property to tune handling request body data via the
client_max_body_size
andclient_body_buffer_size
directives (mirroring their Nginx counterparts). Note these settings are only defined for proxy requests; request body handling in the Admin API remains unchanged. #2602 - 0๏ธโฃ New
error_default_type
configuration property. This setting is to specify a MIME type that will be used as the error response body format when Nginx encounters an error, but noAccept
header was present in the request. The default value istext/plain
for backwards compatibility. Thanks @therealgambo for the contribution! #2500 - ๐ New
nginx_user
configuration property, which interfaces with the Nginxuser
directive. Thanks @depay for the contribution! #2180
CLI
- ๐ New
kong prepare
command to prepare the Kong running prefix (creating log files, SSL certificates, etc...) and allow for Kong to be started via thenginx
binary. This is useful for environments like containers, where the foreground process should be the Nginx master process. Thekong compile
command has been deprecated as a result of this addition. #2706
Admin API
- ๐ Ability to retrieve plugins added to a Consumer via two new endpoints:
/consumers/:username_or_id/plugins/
and/consumers/:username_or_id/plugins/:plugin_id
. #2714 - ๐ Support for JSON
null
inPATCH
requests to unset a value on any entity. #2700
๐ Plugins
- ๐ jwt: Support for RS512 signed tokens. Thanks @sarraz1 for the patch! #2666
- rate-limiting/response-ratelimiting: Optionally hide informative response headers. #2087
- aws-lambda: Define a custom response status when the upstream
X-Amz-Function-Error
header is "Unhandled". Thanks @erran for the contribution! #2587 - ๐ aws-lambda: Add new AWS regions that were previously unsupported. #2769
- hmac: New option to validate the client-provided SHA-256 of the request body. Thanks @vaibhavatul47 for the contribution! #2419
- ๐ hmac: Added support for
enforce_headers
option and added HMAC-SHA256, HMAC-SHA384, and HMAC-SHA512 support. #2644 - ๐ง statsd: New metrics and more flexible configuration. Support for prefixes, configurable stat type, and added metrics. #2400
- ๐ง datadog: New metrics and more flexible configuration. Support for prefixes, configurable stat type, and added metrics. #2394
๐ Fixed
Core
- Kong now ensures that your clients URIs are transparently proxied upstream. No percent-encoding/decoding or querystring stripping will occur anymore. #2519
- ๐ Fix an issue where Kong would match an API with a shorter URI (from its
uris
value) as a prefix instead of a longer, matching prefix from another API. #2662 - ๐ Fix an edge-case where an API with multiple
uris
andstrip_uri = true
would not always strip the client URI. #2562 - HTTP
400
errors thrown by Nginx are now correctly caught by Kong and return a native, Kong-friendly response. #2476
๐ง Configuration
- Octothorpes (
#
) can now be escaped (\#
) and included in the Kong configuration values such as your datastore passwords or usernames. #2411
Admin API
- The
data
response field of the/upstreams/{upstream}/targets/active
Admin API endpoint now returns a list ([]
) instead of an object ({}
) when no active targets are present. #2619
๐ Plugins
- ๐ The
unique
constraint on OAuth2client_secrets
has been removed. #2447 - ๐ The
unique
constraint on JWT Credentialssecrets
has been removed. #2548 - oauth2: When requesting a token from
/oauth2/token
, one can now pass theclient_id
as a request body parameter, whileclient_id:client_secret
is passed via the Authorization header. This allows for better integration with some OAuth2 flows proposed out there, such as from Cloudflare Apps. Thanks @cedum for the patch! #2577 - ๐ง datadog: Avoid a runtime error if the plugin is configured as a global plugin but the downstream request did not match any configured API. Thanks @kjsteuer for the fix! #2702
- ๐ Logging plugins: the produced logs
latencies.kong
field used to omit the time Kong spent in its Load Balancing logic, which includes DNS resolution time. This latency is now included inlatencies.kong
. #2494