release: 0.13.0

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 - [Scheduled](#scheduled)
 - [Released](#released)
-    - [0.13.0rc1](#0130rc1)
+    - [0.13.0](#0130---20180322)
     - [0.12.2](#0122---20180228)
     - [0.12.1](#0121---20180118)
     - [0.12.0](#0120---20180116)
@@ -28,10 +28,7 @@ a detailed changeset of their content.
 This section describes publicly available releases and a detailed changeset of
 their content.
 
-## [0.13.0rc1]
-
-- **rc1 release date**: February 28th 2018
-- **Stable release date (target)**: March 14th 2018
+## [0.13.0] - 2018/03/22
 
 This release introduces two new core entities that will improve the way you
 configure Kong: **Routes** & **Services**. Those entities replace the "API"
@@ -41,8 +38,8 @@ separation of concerns and allowing for plugins to be applied to specific
 
 As usual, major version upgrades require database migrations and changes to
 the NGINX configuration file (if you customized the default template).
-Please take a few minutes to read the [Upgrade
-Path](https://github.com/Kong/kong/blob/master/UPGRADE.md) for
+Please take a few minutes to read the [0.13 Upgrade
+Path](https://github.com/Kong/kong/blob/master/UPGRADE.md#upgrade-to-013x) for
 more details regarding breaking changes and migrations before planning to
 upgrade your Kong cluster.
 
@@ -56,8 +53,8 @@ upgrade your Kong cluster.
 ##### Configuration
 
 - :warning: The `proxy_listen` and `admin_listen` configuration values have a
-  new syntax.  This syntax is more aligned with that of NGINX and is more
-  powerful while also simpler.  As a result, the following configuration values
+  new syntax. This syntax is more aligned with that of NGINX and is more
+  powerful while also simpler. As a result, the following configuration values
   have been removed because superfluous: `ssl`, `admin_ssl`, `http2`,
   `admin_http2`, `proxy_listen_ssl`, and `admin_listen_ssl`.
   [#3147](https://github.com/Kong/kong/pull/3147)
@@ -76,10 +73,12 @@ upgrade your Kong cluster.
   they reach their limit again. There is no such data deletion in PosgreSQL.
   [def201f](https://github.com/Kong/kong/commit/def201f566ccf2dd9b670e2f38e401a0450b1cb5)
 
-### Changed
+### Changes
 
 ##### Dependencies
 
+- **Note to Docker users**: The `latest` tag on Docker Hub now points to the
+  **alpine** image instead of CentOS. This also applies to the `0.13.0` tag.
 - The Openresty version shipped with our default packages has been bumped to
   `1.13.6.1`. The 0.13.0 release should still be compatible with the OpenResty
   `1.11.2.x` series for the time being.
@@ -89,10 +88,13 @@ upgrade your Kong cluster.
 - Bumped [lua-resty-http](https://github.com/pintsized/lua-resty-http) to
   `0.12`.
   [#3196](https://github.com/Kong/kong/pull/3196)
-- Bumped [lua-multipart](https://github.com/Kong/lua-multipart) to `0.5.4`.
-  [#3154](https://github.com/Kong/kong/pull/3054)
+- Bumped [lua-multipart](https://github.com/Kong/lua-multipart) to `0.5.5`.
+  [#3318](https://github.com/Kong/kong/pull/3318)
+- Bumped [lua-resty-healthcheck](https://github.com/Kong/lua-resty-healthcheck)
+  to `0.4.0`.
+  [#3321](https://github.com/Kong/kong/pull/3321)
 
-### Added
+### Additions
 
 ##### Configuration
 
@@ -147,12 +149,25 @@ upgrade your Kong cluster.
   "required", since they have a default value.
   [#3209](https://github.com/Kong/kong/pull/3209)
 
-### Fixed
+### Fixes
+
+##### Core
+
+- Fix an issue causing nodes in a cluster to use the default health checks
+  configuration when the user configured them from another node (event
+  propagated via the cluster).
+  [#3319](https://github.com/Kong/kong/pull/3319)
+- Increase the default load balancer wheel size from 100 to 10.000. This allows
+  for a better distribution of the load between Targets in general.
+  [#3296](https://github.com/Kong/kong/pull/3296)
 
 ##### Admin API
 
 - Fix several issues with application/multipart MIME type parsing of payloads.
-  [#3054](https://github.com/Kong/kong/pull/3054)
+  [#3318](https://github.com/Kong/kong/pull/3318)
+- Fix several issues with the parsing of health checks configuration values.
+  [#3306](https://github.com/Kong/kong/pull/3306)
+  [#3321](https://github.com/Kong/kong/pull/3321)
 
 [Back to TOC](#table-of-contents)
 
@@ -2364,7 +2379,7 @@ First version running with Cassandra.
 
 [Back to TOC](#table-of-contents)
 
-[0.13.0rc1]: https://github.com/Kong/kong/compare/0.12.2...0.13.0rc1
+[0.13.0]: https://github.com/Kong/kong/compare/0.12.3...0.13.0
 [0.12.2]: https://github.com/Kong/kong/compare/0.12.1...0.12.2
 [0.12.1]: https://github.com/Kong/kong/compare/0.12.0...0.12.1
 [0.12.0]: https://github.com/Kong/kong/compare/0.11.2...0.12.0

UPGRADE.md

@@ -36,6 +36,179 @@ starts new workers, which take over from old workers before those old workers
 are terminated. In this way, Kong will serve new requests via the new
 configuration, without dropping existing in-flight connections.
 
+## Upgrade to `0.13.x`
+
+This version comes with **new model entities**, **database migrations**, and
+**nginx configuration changes**.
+
+This section will only highlight the breaking changes that you need to be
+aware of, and describe a recommended upgrade path. We recommend that you
+consult the full [0.13.0
+Changelog](https://github.com/Kong/kong/blob/master/CHANGELOG.md) for a
+complete list of changes and new features.
+
+See below the breaking changes section for a detailed list of steps recommended
+to **run migrations** and upgrade from a previous version of Kong.
+
+#### 1. Breaking Changes
+
+- **Note to Docker users**: The `latest` tag on Docker Hub now points to the
+  **alpine** image instead of CentOS. This also applies to the `0.13.0` tag.
+
+##### Dependencies
+
+- Support for Cassandra 2.1 was deprecated in 0.12.0, and has been dropped
+  starting with 0.13.0.
+- Various dependencies have been bumped. Once again, consult the Changelog for
+  a detailed list.
+
+##### Configuration
+
+- The `proxy_listen` and `admin_listen` configuration values have a new syntax.
+  See the configuration file or the [0.13.x
+  documentation](https://getkong.org/docs/0.13.x/configuration/) for insights
+  on the new syntax.
+- The nginx configuration file has changed, which means that you need to update
+  it if you are using a custom template. The changes are detailed in a diff
+  included below.
+
+<details>
+<summary><strong>Click here to see the nginx configuration changes</strong></summary>
+<p>
+
+```diff
+diff --git a/kong/templates/nginx_kong.lua b/kong/templates/nginx_kong.lua
+index 5639f319..62f5f1ae 100644
+--- a/kong/templates/nginx_kong.lua
++++ b/kong/templates/nginx_kong.lua
+@@ -51,6 +51,8 @@ init_worker_by_lua_block {
+     kong.init_worker()
+ }
+
++
++> if #proxy_listeners > 0 then
+ upstream kong_upstream {
+     server 0.0.0.1;
+     balancer_by_lua_block {
+@@ -61,7 +63,9 @@ upstream kong_upstream {
+
+ server {
+     server_name kong;
+-    listen ${{PROXY_LISTEN}}${{PROXY_PROTOCOL}};
++> for i = 1, #proxy_listeners do
++    listen $(proxy_listeners[i].listener);
++> end
+     error_page 400 404 408 411 412 413 414 417 /kong_error_handler;
+     error_page 500 502 503 504 /kong_error_handler;
+
+@@ -70,8 +74,7 @@ server {
+
+     client_body_buffer_size ${{CLIENT_BODY_BUFFER_SIZE}};
+
+-> if ssl then
+-    listen ${{PROXY_LISTEN_SSL}} ssl${{HTTP2}}${{PROXY_PROTOCOL}};
++> if proxy_ssl_enabled then
+     ssl_certificate ${{SSL_CERT}};
+     ssl_certificate_key ${{SSL_CERT_KEY}};
+     ssl_protocols TLSv1.1 TLSv1.2;
+@@ -149,10 +152,14 @@ server {
+         }
+     }
+ }
++> end
+
++> if #admin_listeners > 0 then
+ server {
+     server_name kong_admin;
+-    listen ${{ADMIN_LISTEN}};
++> for i = 1, #admin_listeners do
++    listen $(admin_listeners[i].listener);
++> end
+
+     access_log ${{ADMIN_ACCESS_LOG}};
+     error_log ${{ADMIN_ERROR_LOG}} ${{LOG_LEVEL}};
+@@ -160,8 +167,7 @@ server {
+     client_max_body_size 10m;
+     client_body_buffer_size 10m;
+
+-> if admin_ssl then
+-    listen ${{ADMIN_LISTEN_SSL}} ssl${{ADMIN_HTTP2}};
++> if admin_ssl_enabled then
+     ssl_certificate ${{ADMIN_SSL_CERT}};
+     ssl_certificate_key ${{ADMIN_SSL_CERT_KEY}};
+     ssl_protocols TLSv1.1 TLSv1.2;
+@@ -189,4 +195,5 @@ server {
+         return 200 'User-agent: *\nDisallow: /';
+     }
+ }
++> end
+```
+
+</p>
+</details>
+
+##### Plugins
+
+- The galileo plugin is considered deprecated and not enabled by default
+  anymore. It is still shipped with Kong 0.13.0, but you must enable it by
+  specifying it in the `custom_plugins` configuration property, like so:
+  `custom_plugins = galileo` (or via the `KONG_CUSTOM_PLUGINS` environment
+  variable).
+- The migrations will remove and re-create the rate-limiting and
+  response-ratelimiting tables storing counters. This means that your counters
+  will reset.
+
+#### 2. Deprecation Notices
+
+Starting with 0.13.0, the "API" entity is considered **deprecated**. While
+still supported, we will eventually remove the entity and its related endpoints
+from the Admin API. Services and Routes are the new first class citizen
+entities that new users (or users upgrading their clusters) should configure.
+
+You can read more about Services and Routes in the [Proxy
+Guide](https://getkong.org/docs/0.13.x/proxy/) and the [Admin API
+Reference](https://getkong.org/docs/0.13.x/admin-api/).
+
+#### 3. Suggested Upgrade Path
+
+You can now start migrating your cluster from `0.12.x` to `0.13`. If you are
+doing this upgrade "in-place", against the datastore of a running 0.12 cluster,
+then for a short period of time, your database schema won't be fully compatible
+with your 0.12 nodes anymore. This is why we suggest either performing this
+upgrade when your 0.12 cluster is warm and most entities are cached, or against
+a new database, if you can migrate your data. If you wish to temporarily make
+your APIs unavailable, you can leverage the
+[request-termination](https://getkong.org/plugins/request-termination/) plugin.
+
+The path to upgrade a 0.12 datastore is identical to the one of previous major
+releases:
+
+1. If you are planning on upgrading Kong while 0.12 nodes are running against
+   the same datastore, make sure those nodes are warm enough (they should have
+   most of your entities cached already), or temporarily disable your APIs.
+2. Provision a 0.13 node and configure it as you wish (environment variables/
+   configuration file). Make sure to point this new 0.13 node to your current
+   datastore.
+3. **Without starting the 0.13 node**, run the 0.13 migrations against your
+   current datastore:
+
+```
+$ kong migrations up [-c kong.conf]
+```
+
+As usual, this step should be executed from a **single node**.
+
+4. You can now provision a fresh 0.13 cluster pointing to your migrated
+   datastore and start your 0.13 nodes.
+5. Gradually switch your traffic from the 0.12 cluster to the new 0.13 cluster.
+   Remember, once your database is migrated, your 0.12 nodes will rely on
+   their cache and not on the underlying database. Your traffic should switch
+   to the new cluster as quickly as possible.
+6. Once your traffic is fully migrated to the 0.13 cluster, decommission
+   your 0.12 cluster.
+
+You have now successfully upgraded your cluster to run 0.13 nodes exclusively.
+
 ## Upgrade to `0.12.x`
 
 As it is the case most of the time, this new major version of Kong comes with

kong-0.13.0rc2-0.rockspec → kong-0.13.0-0.rockspec

@@ -1,9 +1,9 @@
 package = "kong"
-version = "0.13.0rc2-0"
+version = "0.13.0-0"
 supported_platforms = {"linux", "macosx"}
 source = {
   url = "git://github.com/Kong/kong",
-  tag = "0.13.0rc2"
+  tag = "0.13.0"
 }
 description = {
   summary = "Kong is a scalable and customizable API Management Layer built on top of Nginx.",
@@ -16,7 +16,7 @@ dependencies = {
   "penlight == 1.5.4",
   "lua-resty-http == 0.12",
   "lua-resty-jit-uuid == 0.0.7",
-  "multipart == 0.5.4",
+  "multipart == 0.5.5",
   "version == 0.2",
   "kong-lapis == 1.6.0.1",
   "lua-cassandra == 1.2.3",
@@ -30,7 +30,7 @@ dependencies = {
   "lua-resty-dns-client == 2.0.0",
   "lua-resty-worker-events == 0.3.1",
   "lua-resty-mediador == 0.1.2",
-  "lua-resty-healthcheck == 0.3.0",
+  "lua-resty-healthcheck == 0.4.0",
 }
 build = {
   type = "builtin",

kong.conf.default

@@ -101,7 +101,7 @@
 # Note bis: see https://www.nginx.com/resources/admin-guide/proxy-protocol/
 # for more details about the `proxy_protocol` parameter.
 
-#admin_listen = 127.0.0.1:8000, 127.0.0.1:8443 ssl
+#admin_listen = 127.0.0.1:8001, 127.0.0.1:8444 ssl
                          # Comma-separated list of addresses and ports on
                          # which the Admin interface should listen.
                          # The Admin interface is the API allowing you to

kong/core/balancer.lua

@@ -575,35 +575,50 @@ end
 --------------------------------------------------------------------------------
 -- Called on any changes to an upstream.
 -- @param operation "create", "update" or "delete"
--- @param upstream Upstream table with `id` and `name` fields
-local function on_upstream_event(operation, upstream)
+-- @param upstream_data table with `id` and `name` fields
+local function on_upstream_event(operation, upstream_data)
+  local upstream_id = upstream_data.id
+  local upstream_name = upstream_data.name
 
   if operation == "create" then
 
     singletons.cache:invalidate_local("balancer:upstreams")
 
+    local upstream = get_upstream_by_id(upstream_id)
+    if not upstream then
+      log(ERR, "upstream not found for ", upstream_id)
+      return
+    end
+
     local _, err = create_balancer(upstream)
     if err then
-      log(CRIT, "failed creating balancer for ", upstream.name, ": ", err)
+      log(CRIT, "failed creating balancer for ", upstream_name, ": ", err)
     end
 
   elseif operation == "delete" or operation == "update" then
 
     singletons.cache:invalidate_local("balancer:upstreams")
-    singletons.cache:invalidate_local("balancer:upstreams:" .. upstream.id)
-    singletons.cache:invalidate_local("balancer:targets:"   .. upstream.id)
+    singletons.cache:invalidate_local("balancer:upstreams:" .. upstream_id)
+    singletons.cache:invalidate_local("balancer:targets:"   .. upstream_id)
 
-    local balancer = balancers[upstream.id]
+    local balancer = balancers[upstream_id]
     if balancer then
       stop_healthchecker(balancer)
     end
 
     if operation == "delete" then
-      balancers[upstream.id] = nil
+      balancers[upstream_id] = nil
+
     else
+      local upstream = get_upstream_by_id(upstream_id)
+      if not upstream then
+        log(ERR, "upstream not found for ", upstream_id)
+        return
+      end
+
       local _, err = create_balancer(upstream, true)
       if err then
-        log(ERR, "failed recreating balancer for ", upstream.name, ": ", err)
+        log(ERR, "failed recreating balancer for ", upstream_name, ": ", err)
       end
     end