Kong Gateway

Last reviewed Aug 26, 2026 · 943 words

Kong Gateway is an API gateway, not a homelab reverse proxy, and most self-hosters who ask about it want Traefik or Caddy instead. If your goal is "put TLS in front of my containers", stop here and read the reverse proxy showdown. If your goal is to sit in front of APIs and enforce authentication, rate limits, request transformation, and per-consumer policy in one place, Kong is the most mature open-source option, and it runs in a single 512 MB container with no database once you know the one setting that makes that possible.

Run it DB-less, and most of the "steep configuration curve" disappears

Kong has two modes. With a Postgres database, configuration is done live through the Admin API and stored in the DB; with KONG_DATABASE=off, the entire configuration is one YAML file read at startup. The catalogue's "Postgres typically required" con was true for years and is now a choice. DB-less mode is what I run, and it turns Kong into something you manage like any other config-as-code service: edit the file, commit it, restart.

services:
  kong:
    image: kong:latest
    environment:
      KONG_DATABASE: "off"
      KONG_DECLARATIVE_CONFIG: /kong/kong.yml
      KONG_PROXY_LISTEN: "0.0.0.0:8000, 0.0.0.0:8443 ssl"
      KONG_ADMIN_LISTEN: "127.0.0.1:8001"
    volumes:
      - ./kong.yml:/kong/kong.yml:ro
    ports:
      - "8000:8000"
      - "8443:8443"
    restart: unless-stopped

Pin the image tag to the major version you tested against rather than latest; Kong's majors do change plugin config schemas. What you lose in DB-less mode: the Admin API becomes read-only, plugins that need shared state across nodes are unavailable (the cluster policy for rate limiting, for example, so use local or point the plugin at Redis), and Kong Manager's editing features are disabled. For one or two nodes that is no loss at all.

Four ports, and one of them must never be public

An exposed Admin API on a Postgres-backed Kong is full control of every route and plugin, with no authentication by default. The compose above binds it to localhost inside the container; if you need remote admin, reach it over Tailscale or put Kong's own key-auth plugin in front of a loopback route to it. The Kong docs describe that second pattern, and it is the correct way to do it.

The declarative file is the real interface

Everything Kong does is expressed as services (upstreams), routes (matching rules), consumers (API clients), and plugins (attached to any of the above, or global). A complete, working configuration that proxies an internal API, requires an API key, and rate-limits each key to 60 requests per minute:

_format_version: "3.0"
services:
  - name: orders-api
    url: http://orders:8080
    routes:
      - name: orders
        paths: ["/orders"]
        strip_path: false
consumers:
  - username: mobile-app
    keyauth_credentials:
      - key: replace-with-a-long-random-key
plugins:
  - name: key-auth
    service: orders-api
  - name: rate-limiting
    service: orders-api
    config:
      minute: 60
      policy: local

Send GET /orders without the apikey header and Kong returns 401; send 61 requests in a minute and it returns 429 with RateLimit-Remaining headers. Adding a cors plugin, a prometheus plugin for metrics, request-transformer to inject headers, or ip-restriction is another 3 to 6 lines each. The decK tool (deck gateway sync kong.yml) diffs and applies the same file against a DB-backed Kong if you later grow into one, so the file format is a stable investment either way.

Which plugins you actually get for free

The Apache-2.0 gateway ships with the authentication plugins most people need (key-auth, basic-auth, jwt, hmac-auth, oauth2), traffic control (rate-limiting, request-size-limiting, proxy-cache), request and response transformation, logging to files, HTTP endpoints, and syslog, and observability (prometheus, zipkin). The "some plugins enterprise-only" con bites in one specific place: OpenID Connect. The openid-connect plugin, the one that lets Kong validate tokens against Authentik or Keycloak and enforce scopes, is commercial. Open-source workarounds exist (a community OIDC plugin, or validating the issuer's JWTs with the free jwt plugin after fetching its public key), but if OIDC at the gateway is the requirement, evaluate APISIX, whose OIDC plugin is Apache-licensed, before committing.

Kong on Kubernetes is a different install

The Kong Ingress Controller turns the same gateway into a Kubernetes Ingress and Gateway API implementation, configured through CRDs instead of the YAML above, with a Helm chart to install it. It is excellent and it is a much bigger commitment: a controller and gateway pair, CRDs to learn, and Kong's own reconciliation loop. Do not start there for a single-server deployment; the container above proves out your config in an afternoon, and the CRDs map onto it almost one-to-one later.

What I'd do

If you have APIs to protect, run the DB-less container above with a pinned major version, put kong.yml in git, terminate TLS in Caddy in front of port 8000 (Kong can do TLS itself, but Caddy's certificate automation is nicer), and add plugins one at a time while watching the prometheus metrics. Add Postgres only when a second node needs shared rate-limit counters or a colleague needs the Admin API. If you have no APIs to protect and want a proxy for the house, this is the wrong tool and Traefik is the right one.