Contour: the Kubernetes ingress controller that speaks three APIs

Three configuration APIs and the reasons for each

Contour is an ingress controller that deploys the Envoy proxy as a reverse proxy and load balancer, and it supports dynamic configuration updates while keeping a lightweight profile. The interesting design decision is that it does not pick one configuration API. It supports three, and the README gives a reason for each.

Ingress is described as a stable upstream API that enables basic ingress use cases. It is the compatibility floor: whatever you deploy today against Ingress keeps working, and it is what you use when you do not need anything more.

HTTPProxy is Contour's own Custom Resource Definition. The README says it expands on the Ingress API to allow a richer user experience and to solve shortcomings in the original design. This is the API to reach for when you want weighted routing, header manipulation, delegation across teams or anything else the Ingress spec cannot express without annotations.

Gateway API is the third, managed by the Kubernetes SIG-Network community, and the README frames it as an attempt to evolve Kubernetes service networking APIs in a vendor-neutral way. A controller that supports it alongside the other two means an Ingress-only cluster and a Gateway-API cluster can share the same controller.

Prerequisites that are easy to miss

The prerequisites section is two sentences and one of them matters. Kubernetes support is version-dependent, so the README points to a compatibility matrix hosted on the project site rather than naming versions in the repository. That is the right place to look, because the Go module file already tells you what the code is built against: it requires `go 1.27` and depends on `k8s.io/api` and `k8s.io/client-go` at v0.37.0, with `sigs.k8s.io/controller-runtime` at v0.25.1 and `sigs.k8s.io/gateway-api` at v1.3.0.

The second sentence is the one people hit: RBAC must be enabled on your cluster. There is no fallback mode, and a cluster with role-based access control turned off will not run this. The examples directory even includes both `root-rbac/` and `namespaced/` variants, which tells you the project expects you to make that choice deliberately.

The README says getting started is as simple as one command and links to a Getting Started document for it. The command itself is not on the front page, so if you want the one-liner, you are going to the site rather than the repository.

Contour as the control plane in front of Envoy

The dependency list makes the architecture explicit. `github.com/envoyproxy/go-control-plane` at v0.14.0 with the Envoy API at v1.39.0 means Contour programs Envoy through the control-plane API rather than generating configuration files for it. That is what makes the README's claim of dynamic configuration updates plausible: when an HTTPProxy changes, Contour pushes a new configuration to the running proxy instead of waiting for a reload.

The rest of the module file is a fair map of what a controller of this kind needs. `sigs.k8s.io/controller-runtime` for the reconcile loop, `sigs.k8s.io/kustomize/kyaml` for YAML handling, `prometheus/client_golang` and `grpc-ecosystem/go-grpc-prometheus` for metrics, `ginkgo` and `gomega` alongside `testify` for tests, and `github.com/tsaarni/certyaml` for certificate work.

Deployment targets are modest: the Makefile sets `IMAGE_PLATFORMS ?= linux/amd64,linux/arm64` and pushes to `ghcr.io/projectcontour`. Multi-architecture support is the default rather than a special build, which matters more now that arm64 nodes are ordinary.

The build produces a static binary in a scratch image

The `Dockerfile` is worth reading if you are deciding how to distribute this internally. It cross-compiles from a pinned Go base image, with `CGO_ENABLED` defaulting to 0 in the Makefile, and then verifies the result rather than assuming it:

RUN ldd contour 2>&1 | grep 'not a dynamic executable'

That check fails the build if the binary is not static. The final stage is `FROM scratch` with the single binary copied to `/bin/contour`, so the shipped image contains no shell and no package manager. That is a small image by construction rather than by trimming.

The Makefile also shows how releases are wired. `CONTOUR_E2E_IMAGE ?= ghcr.io/projectcontour/contour:main` is the default end-to-end test image, `CONTOUR_E2E_TEST_FOCUS` matches specific test specs by regular expression, and `CONTOUR_UPGRADE_FROM_VERSION` is resolved by a shell script under `test/scripts/`, which is how the project tests upgrades from a previous release. The GATEWAY_API_VERSION variable is derived from `go.mod` rather than duplicated, so the Gateway API version the tests use cannot drift from the one the code compiles against.

The examples directory answers questions the README does not

Sixteen example directories sit under `examples/`, and their names read like a list of operational questions: `gatekeeper/`, `gateway/`, `gateway-provisioner/`, `global-external-auth/`, `grafana/`, `prometheus/`, `ratelimit/`, `tracing/`, `namespaced/`, `root-rbac/`, `render/`, `optional-features/` and `kind/`.

Several of those are the answer to questions the front page raises indirectly. External authentication for a whole cluster is a `global-external-auth/` concern. Prometheus metrics and Grafana dashboards exist as worked examples rather than as an aspiration. Rate limiting is demonstrated. `render/` suggests manifests you can generate output from, and `kind/` implies a local cluster workflow for trying changes.

For a project whose README is four short sections, this directory is where the actual usage lives. There is also a `design/` directory and a `site/` directory for the documentation website, plus `changelogs/` and `RELEASES.md` for history.

Governance, audit history and release cadence

This is a CNCF project, and it has the institutional detail that implies. The README points to a Code of Conduct, a `CONTRIBUTING.md` that covers the developer certificate of origin the project requires, community meetings with published notes and recordings, and governance kept in a separate community repository along with the roadmap. Security reporting goes to a dedicated Contour security team mailing list, with `SECURITY.md` for the policy.

The security history is documented rather than implied. A third-party audit by Cure53 from December 2020 is committed to the repository as a PDF, which is an unusual thing to find in a source tree and speaks well of the project's transparency about its own past.

Release cadence is regular. The recent tags are v1.33.5, v1.33.6 and v1.33.7, published on 2026-05-28, 2026-08-12 and 2026-09-07, and the last push was on 2026-09-21. The minor version line suggests a monthly or near-monthly train. The licence is Apache 2.0, with a `LICENSE` file at the root and the badge in the README.

Editorial conclusion

Contour fits clusters where Envoy is already the proxy of choice, where teams want richer routing than plain Ingress allows, or where Gateway API adoption is underway and a controller that speaks both is worth the extra API surface. It is a heavier choice than a bare Ingress controller for simple workloads, and the deciding practical question is RBAC, which the README states must be enabled. Check the compatibility matrix for your Kubernetes version first, then read the Getting Started document, since the repository README stops at the claim that getting started is one command without showing it.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. projectcontour/contour on GitHub
3. Project website
4. README
5. Releases