Introduction to Kong

Kong is an API gateway. In concrete terms it is a proxy that receives HTTP requests, decides which upstream service each one belongs to, applies a chain of plugins to it, and forwards it onward. Once it is in the path of every request, it becomes the natural place to answer the questions that every API needs answered exactly once: who is calling, are they allowed, how many times may they call, what should the upstream see, and what should be written down afterwards.

By the end of this chapter you will be able to explain what problem a gateway solves that a reverse proxy does not, describe how a request travels through Kong’s internals, choose between Kong’s deployment modes for a given situation, and name the five entity types that everything else in the course is built from.

The problem a gateway solves

A reverse proxy in front of your services solves load balancing and TLS termination. A gateway solves those too, but adds a layer that is about contracts rather than about traffic.

Consider what happens when three teams publish three APIs. Without a gateway, each API carries its own authentication check, its own rate limiter, its own request logging, and its own idea of what an API key looks like. That is three implementations of the same policy, written by three teams who never spoke to each other. The moment an organisation-wide policy appears - “no client may exceed a hundred requests a minute” - there is nowhere to put it.

A gateway gives that policy one home. The rules live in configuration next to the routes, not in code next to each service, so they are applied uniformly and audited uniformly.

The other thing a gateway does is terminate the trust boundary. Internal services can be written assuming that everything arriving has already been authenticated and normalised, because the gateway guarantees it. That removes a great deal of defensive code from the services themselves.

The five entities

Almost everything in Kong is one of these five things, or something attached to one of them.

A Service is an upstream. It holds a protocol, a host, a port, and optionally a path, plus the timeouts and retry count used when talking to it. A Service knows where traffic goes, and nothing about which traffic.

A Route is a matcher. It holds the path, host, method and header conditions that select a request, and it points at exactly one Service. A Route knows which traffic, and nothing about where it goes.

Keeping these two separate is the first thing to internalise, because it is what lets one Service answer to several Routes - a public /v1/orders and an internal /internal/orders can both point at the same upstream while carrying entirely different plugins.

A Plugin is a piece of behaviour. Kong ships with plugins for authentication (key-auth, basic-auth, jwt, oauth2), for policy (rate-limiting, ip-restriction, acl, request-size-limiting), for transformation (request-transformer, response-transformer), for traffic shaping (cors, request-termination), and for observability (prometheus, http-log, tcp-log). A plugin can be attached globally, to a Service, to a Route, or to a Consumer, and the more specific scope wins.

A Consumer is an identity. It is not a user account - Kong does not authenticate people. It is the thing that owns credentials and that limits and logs are attributed to. Two consumers are payments-service and reporting-job, each with its own API key.

An Upstream is a pool of addresses behind one logical name, together with the load-balancing algorithm and health checks used to pick between them. A Service points at an Upstream when the upstream is a fleet rather than a single host.

That is the whole model. Everything in the rest of the course is these five entities in different combinations.

How a request travels through Kong

The path of a request is worth understanding once, because most surprising behaviour comes from it.

client
  |
  v
[ proxy listener ]                 Kong listens on 8000 (HTTP) / 8443 (HTTPS)
  |
  v
[ router ]                         Matches the request against all Routes
  |                                Finds exactly one Service, or returns 404
  v
[ plugin chain ]                   Runs in priority order for that scope
  |                                access phase: auth, rate limit, transforms
  v
[ balancer ]                       Picks a target from the Upstream
  |                                Uses the health checks and the algorithm
  v
[ upstream service ]               Your actual application
  |
  v
[ plugin chain ]                   response phase: transforms, logging
  |
  v
[ client ]

Two details in that diagram cause most surprises.

First, the router matches before any plugin runs. A request that matches no Route is rejected with 404 and a body of no Route matched with those values - it never reaches a plugin, so an authentication plugin cannot produce a 401 for a request that has no Route at all. If you are debugging an unexpected 404, check the Route matching first.

Second, plugins are ordered by priority, not by the order you wrote them. Kong assigns each plugin a fixed priority number, and the chain runs in ascending priority. Authentication runs early so that an unauthenticated request is rejected before it consumes a rate-limit token or a worker connection. When two plugins at the same scope both want to run, the one with the lower priority number goes first.

Choosing a deployment mode

Kong 3.x runs in one of three modes. The choice determines where configuration lives and how you scale.

Database-less mode is the simplest. There is no database at all. The entire configuration is one YAML file, and Kong loads it at startup and on reload. This is the right mode for a small deployment, for Kubernetes where the configuration comes from an operator, and for any case where you want configuration to be a Git artifact. It is also the mode you will use throughout this course, because it makes configuration reviewable.

_format_version: "3.0"
services:
  - name: example-service
    url: http://example.internal:8080
    routes:
      - name: example-route
        paths:
          - /example

Traditional (database) mode stores configuration in PostgreSQL. You change it through the Admin API and the changes persist. This is the mode to choose when several people or several systems need to edit configuration at runtime - a GUI, a Terraform provider, an internal portal - and the database becomes the source of truth.

Hybrid mode splits the gateway in two. A control plane owns the configuration and exposes the Admin API; one or more data planes handle the actual traffic and receive configuration from the control plane. You configure the control plane with role = control_plane and each data plane with role = data_plane plus the address of the control plane. The data planes are stateless and horizontally scalable, which is exactly what you want when a gateway fronts your most important traffic.

# Control plane
KONG_ROLE=control_plane \
KONG_DATABASE=postgres \
KONG_ADMIN_LISTEN=0.0.0.0:8001 \
KONG_CLUSTER_LISTEN=0.0.0.0:8005

# Data plane
KONG_ROLE=data_plane \
KONG_DATABASE=off \
KONG_CLUSTER_CONTROL_PLANE=control-plane.internal:8005 \
KONG_CLUSTER_DATA_PLANE_TOKEN=<shared-token>

A useful detail from the source: in hybrid mode the control plane cannot use in-memory storage, because the data planes need a real database behind it, and the admin listener must be explicitly specified because the control plane’s only job is to serve the Admin API.

What Kong is not

It is worth being clear about the boundaries, because “gateway” is a word that gets stretched.

Kong is not an authentication server. It can verify a JWT, check an API key, or delegate to an OAuth 2.0 provider, but it does not issue and manage user accounts. Kong’s own oauth2 plugin issues tokens to clients of your APIs; it is not your identity provider. If you need users, keep a proper identity system and have Kong validate against it.

Kong is not a service mesh. A mesh handles east-west traffic between services and gives you mutual TLS and fine-grained service-to-service policy. Kong handles north-south traffic - traffic entering your system from outside - and gives you one place to manage your public API. The two compose: a mesh can sit inside a gateway, and the boundary between them is simply where traffic crosses your public edge.

Kong is not a replacement for good service design. A gateway that has to rewrite every request into shape because the services underneath are inconsistent is evidence of a design problem, not a gateway feature.

A first look at the plugin model

Plugins are where most of Kong’s value lives, and they are worth understanding as a model rather than as a list.

A plugin has a scope - global, Service, Route or Consumer - and a configuration. The same plugin can be attached at several scopes with different configuration, and the most specific applicable scope is the one that takes effect. That is what makes the following configuration meaningful:

_format_version: "3.0"
services:
  - name: orders
    url: http://orders.internal:8080
    routes:
      - name: orders-public
        paths:
          - /orders
plugins:
  - name: rate-limiting
    config:
      minute: 1000
      limit_by: service
  - name: rate-limiting
    service: orders
    config:
      minute: 100
      limit_by: service

Here orders is limited to a hundred requests a minute while every other service gets a thousand, and neither configuration needs to know about the other.

Practice

Here is a realistic situation. A company has moved from three services to thirty. They want one place to enforce authentication, per-team rate limits, and consistent request logging. They also want to be able to add a new service to the gateway without a code change, and they want the gateway to survive losing a single node.

Given the three deployment modes described above, which would you choose, and what is the single strongest reason for that choice?

KongDeployment ModesHybrid ModeArchitecture

Approach:

The question is really asking whether the reader can connect a requirement to a mode, and can name the deciding factor rather than listing features. The four requirements pull in different directions: consistent policy across teams pushes toward one control point; adding services without code change pushes toward declarative configuration; surviving the loss of a node pushes toward multiple data planes.

The decisive observation is that the first requirement - “one place to enforce authentication, per-team rate limits and consistent logging” - is a requirement about where configuration is decided, not about where traffic is served. Those are two different things, and the mode that separates them is hybrid mode.

Steps:

  1. Separate the two questions. Where is the configuration decided, and where is the traffic served? A mode that answers both with the same answer cannot satisfy “one place to enforce policy” and “survive losing a node” at once.

  2. Rule out database-less mode. It satisfies “add a service without a code change” beautifully - configuration is a YAML file and the whole thing is a Git artifact. But there is no control point: every node holds its own copy of the configuration, so a policy change has to be rolled out to every node, and there is no single place where “the policy” lives. Thirty services and per-team limits make that operationally painful.

  3. Rule out traditional mode as the final answer. It gives you the single control point and the Admin API, and it is the natural choice if an internal portal or Terraform needs to edit configuration at runtime. But in traditional mode every node that serves traffic also serves the Admin API and holds the configuration, so scaling out means replicating database-backed nodes, and losing one node is still a partial outage rather than a non-event.

  4. Choose hybrid mode. The control plane holds the configuration in PostgreSQL and is the only thing that exposes the Admin API. The data planes are pure traffic handlers: they receive configuration from the control plane and hold no state worth losing.

  5. Map each requirement onto the architecture.

    • “One place to enforce authentication, per-team rate limits, consistent logging” becomes configuration on the control plane, applied to every data plane automatically.
    • “Add a service without a code change” becomes an Admin API call or a declarative config change against the control plane.
    • “Survive losing a single node” becomes a matter of running more than one data plane behind a load balancer. Data planes are stateless, so a failed one is removed from the pool and the rest carry on.
  6. Note the trade-off you accepted. Hybrid mode has more moving parts and a split configuration model, so it costs more to operate than database-less mode. That cost is worth paying at thirty services with per-team policy, and it would be wasted on three services with one team.

Answer:

Hybrid mode. The control plane holds the configuration in PostgreSQL and serves the Admin API; the data planes serve traffic and hold no state worth losing.

The deciding reason is that the requirements split into two independent questions - where configuration is decided and where traffic is served - and hybrid mode is the only one that answers them separately. The single control plane gives the organisation one enforcement point for authentication, per-team rate limits and logging, so a policy change is one change; the data planes are stateless and horizontally scalable, so losing a node is an event the load balancer absorbs.

Database-less mode was rejected because it has no control point: every node carries its own copy of the policy, so “one place to enforce” is not satisfiable and a policy change becomes a fleet-wide rollout. Traditional mode was rejected as the final answer because it couples the control point to the traffic-serving nodes, which makes scaling out and node loss more expensive than they need to be.

Found an issue with this content?

Tell us what could be improved.