Skip to content

Reproducible by construction

kong-gateway

Two Kong Gateway images from one Dockerfile, carrying three plugins Kong does not bundle — OIDC, JWT-Keycloak and path-allow. 2.8.5 reproduces what runs today; 2.8.5-oidcify is the same Kong with the abandoned OIDC plugin replaced by a maintained one. Both pinned to exact artefacts and checked by a suite that refuses to let a broken image be published.

Build it Why it exists Where it stands 
docker build --build-arg KONG_VERSION=2.8.5 -t kong-gateway:2.8.5 .
./tests/run.sh kong-gateway:2.8.5 2.8.5          # milestones, including the pre-push gate
./tests/e2e/run.sh kong-gateway:2.8.5 2.8.5      # the whole system, with a real Keycloak

What this is

One Dockerfile, parameterised by Kong version and by OIDC plugin, building three images — 2.8.5 (the legacy plugin set, as production runs it), 2.8.5-oidcify (the same Kong with a maintained OIDC plugin), and 3.9.3 — plus a gate that runs before anything is published.

The variant exists to separate two migrations that would otherwise arrive together: leaving an abandoned authentication plugin, and jumping a Kong major. Doing the first alone makes a rollback one image tag rather than a replan.

It replaces an image that had no build recipe at all: two docker commit layers on top of an official base, one tag in the registry, no history behind it. Background covers what that cost and how the sources were recovered.

  • Background

    An image built by docker commit, a base layer fetching Kong from a service shut down in 2021, and what it takes to get back to a recipe.

    Read it

  • Building

    How to build both Kong lines from one tree — and the LuaRocks trap that makes the obvious Dockerfile fail with an error that says nothing.

    Build it

  • Plugins

    What each plugin does, which version is pinned, where Kong 3.x breaks it, and one matching quirk worth checking your configuration against.

    Inspect them

  • Run it locally

    One command brings up the gateway with a real Keycloak behind it and leaves it running, with the requests worth trying first.

    Start it

  • End-to-end

    The whole system running: Keycloak issuing real tokens, an upstream to protect, and the image between them — asserting mostly what must be refused.

    Run it

  • Milestones

    Every phase of the plan is a test holding its exit criterion. What is reached, what is declared outstanding, and what that blocks.

    See the state

  • Publishing

    Which tags a release produces, why latest names exactly one line, and why deployments pin the digest instead.

    Publish safely

  • The open decision

    Two of the three plugins have no chosen Kong 3.x replacement. They sit on the authentication path, so the choice is deliberately left visible rather than made by drift.

    The decision

Two things worth knowing up front

The Kong 3.x build is not publishable, and says so

It is not broken — it is honest. Two of the three plugins have no chosen Kong 3.x replacement, so the 3.x milestones are declared XFAIL and the publish step is gated on them. A release tag publishes the 2.x line and skips 3.x without anyone having to remember.

Pin the digest, not the tag

A tag can be repushed underneath a running deployment; a digest cannot. The publish workflow prints the digest to use. See Publishing.