kong-summit-glow

By on March 22, 2018

Kong CE 0.13.0 released

After a release candidate cycle of several weeks, the Kong team is very happy to announce the promotion of the final, stable release of Kong CE 0.13.0!

Download and try now Kong CE 0.13.0.

CE 0.13.0

The highlights of 0.13.0 are:

  • 🎆 The introduction of Services and Routes as new core entities. Those entities replace the “API” entity and simplify the setup of non-naive use-cases. They provide better separation of concerns and allow for plugins to be applied to specific endpoints.
  • 🎆 A new syntax for the proxy_listen and admin_listen directives allows you to disable the Proxy or the Admin API at once, meaning the separation of Kong control-planes and data-planes has never been that easy! Explanation and configuration details are covered on this post.
  • 🎆 The new endpoints such as /routes and /services are built with much improved support for form-urlencoding payloads, and produce friendlier responses. Expect existing endpoints to move towards this new implementation in the future and greatly improve the Admin API usability.
  • Fix several issues with our DNS resolver, health checks configuration, and application/multipart MIME type parsing.
  • Docker: the latest and 0.13.0 Docker Hub tags now point to the alpine image.

See the 0.13.0 Changelog for a complete list of changes in this release.

If you are already running Kong, consult the 0.13 Upgrade Path for a complete list of breaking changes, and suggested no-downtime upgrade path.

Services and Routes

With the “API” entity out of the picture, how are Services and Routes going to replace them, and why are they better? Let’s answer that with an example:

Consider a microservice in front of which we want to use Kong to take advantage of its authentication and rate limiting capabilities. Nothing out of the ordinary here!

Prior to Kong 0.13.0, proxying traffic to that API via Kong meant creating an API with matching rules and an upstream URL, like so:

$ curl -X POST http://<kong-ip>:8001/apis \
  -d "name=my-service" \
  -d "hosts=my-service.com" \
  -d "upstream_url=https://service.com"

And applying authentication and rate-limiting to that API was as simple as a couple of HTTP requests:

$ curl -X POST http://<kong-ip>:8001/apis/my-service/plugins \
  -d "name=key-auth"

$ curl -X POST http://<kong-ip>:8001/apis/my-service/plugins \
  -d "name=rate-limiting" \
  -d "config.minute=1000"

Great, now what’s the problem with that? Well, the simplicity of this model starts playing against us a soon as we introduce a (very common) scenario: applying different plugins per endpoint.

Applying plugins per endpoints in 0.12.x and below

What if our microservice exposes /foo and /expensive? Both endpoints require authentication, but the second one should also be rate-limited. Because the API entity defines all matching rules (i.e. endpoints) and points to your upstream microservice at the same time, we end up in a situation where we need to duplicate our API entity if we want to apply different plugins for each endpoint. Put in picture:

A diagram hilighting the shortcoming of the Kong 0.12.x data model.

Applying plugins per endpoint in Kong 0.12.x and prior. In red, the duplicated attributes.

In red, we can see all of the duplication that occurs when we follow this approach: two APIs, each with a different matching rule for the request URL but an identical upstream URL. And a duplicated basic-auth plugin, to ensure that all requests going to each of these “twin APIs” are authenticated.

Applying plugins per endpoints in 0.13.0

Enter Services and Routes. A Service is the equivalent of the API entity, minus its matching rules (or, more accurately, minus all attributes related to client requests). How do you proxy a client request to a Service then?, you may ask. By associating a Route to said Service, of course! Here is what the previous use-case translates to with Services and Routes:

A diagram representing plugins applied to specific endpoints with Kong 0.13.0

Applying plugins per endpoints is much easier with Kong 0.13.0

Now, the difference between APIs and Services/Routes is becoming evident: Services and Routes provide the separation of concerns between downstream clients and upstream services that APIs could not. This type of (common) use-case becomes easier to reason about, and we benefit from extra granularity when applying plugins. These new entities considerably improve usability and flexibility at the same time.

We also believe that their names are more appropriate than that of the API entity. Nowadays, we see Kong in front of monolithic and legacy APIs, but also in front of more recent service-oriented architectures or fleets of microservices. The term “API”, on top of being potentially mingled with the Admin API component, was also too narrow. Instead,

  • A Service reflects better the notion of “upstream service” or “backend” that you wish Kong to sit in front of. This could be a monolithic API, or a billing microservice, or even a serverless function!
  • A Route, in the context of a reverse-proxy, naturally implies that it is client-facing, and that requests matching one will eventually get proxied or “routed” somewhere.

You can read more about Services and Routes by reading the Proxy Guide or the Admin API reference. And finally, if you are already running Kong, fear not, for the API entity is deprecated, but not removed! All of your existing configuration will still work as of 0.13.0.

Conclusion

Services and Routes are the major new feature of Kong CE 0.13.0, but the release also ships with many other improvements, including a new configuration syntax for the proxy_listen and admin_listen directives, which allows for the separation control and data plane nodes!

Happy Konging!