Kubernetes Gateway API: the CRDs behind Gateway, HTTPRoute and the rest

What the Gateway API repository is, and what it is not

The repository contains the specification and the Custom Resource Definitions. That sentence from the README is the whole scope. There is no data plane here, no proxy binary, no reconciler that watches HTTPRoute objects and programs an Envoy or an nginx instance. If you install only this repository, you get new API types in the cluster and nothing that acts on them.

Who it is for follows from that. It is for cluster operators who want routing configuration expressed as Kubernetes objects with a role split between infrastructure and application teams, for implementers writing a controller against a common contract, and for platform engineers who are tired of provider-specific Ingress annotations. The README points readers at the API concepts and security model documents before anything else, which is a fair signal: the API is designed to be understood as a model, not copied from a snippet.

The GA story is specific. The README states that the latest supported version is v1, and that v1 has GA level support for GatewayClass, Gateway, ListenerSet, HTTPRoute, GRPCRoute, TLSRoute, TCPRoute, UDPRoute, BackendTLSPolicy and ReferenceGrant. Everything else is at some other support level and the README defers to the spec rather than listing it. That gap matters when you plan a migration: the resource you need may exist without being GA.

How the object model splits responsibilities

The mechanism is a set of CRDs with references between them. A GatewayClass names a controller implementation. A Gateway is an instance of that class and declares listeners with a port, a protocol, a hostname and TLS settings. Routes (HTTPRoute, GRPCRoute, TLSRoute, TCPRoute, UDPRoute) attach to those listeners and carry the matching and backend rules. BackendTLSPolicy configures how the gateway talks to its backends, and ReferenceGrant controls whether a route in one namespace may reference an object in another.

That last object is the part people underestimate. Cross-namespace references are denied by default, and ReferenceGrant is the explicit permission slip. The README links a security model document, which is where the reasoning lives; the CRD list alone does not explain it.

ListenerSet appears in the v1 GA list, which is worth noticing because it changes the shape of the model: instead of every listener living on the Gateway object, a listener set lets that configuration be grouped separately while still belonging to a Gateway. In a repository where the Gateway object is otherwise the single attachment point for routes, that is a structural addition rather than a convenience field.

The data flow is therefore declarative and indirect. You write a route. A controller that implements the API watches it, decides whether the route is accepted, and writes status back onto the object. The README does not describe the controller's internals because the controller is not in this repository.

Installing the CRDs and creating a first HTTPRoute

The README does not print an install command. It says to read the concepts and security model first, then use the getting started guide to install your first Gateway controller and try a guide. So the honest sequence is: install the CRDs from a release, then install a controller, then create objects.

The repository ships examples in two directories, examples/standard and examples/experimental, which reflects the channel split in the API. The README lists the v1 resource kinds but publishes no applyable YAML for them, so the only reliable manifest source is the getting started guide and the examples directories. What follows is a description of the object order, not a manifest to paste.

A GatewayClass comes first, because a Gateway must name one. It carries a controllerName that must match a controller you have actually installed; if it does not match, the class stays unaccepted and nothing downstream works.

A Gateway comes second. It names its GatewayClass and declares listeners, each with a name, a protocol and a port. The listener name matters later, because a route attaches to a listener by naming it.

An HTTPRoute comes third. It carries parentRefs pointing at the Gateway and rules with backendRefs pointing at a Service. After applying these, check the status of the Gateway and the HTTPRoute: a controller that supports the API writes acceptance conditions there. If the status stays empty, the usual cause is that no controller is watching, or the GatewayClass controllerName does not match one.

Where the specification stops and a controller begins

This is the failure mode that catches teams. The CRDs install cleanly, kubectl accepts your YAML, and traffic does not move, because nothing in this repository forwards packets. The README is explicit that getting started means installing a Gateway controller, and that conformance reports exist so users can explore which features the various implementations support.

That conformance machinery is the repository's answer to a real problem: a shared API only helps if implementations agree on behaviour. The conformance test suite lives under conformance/, and the reports directory has its own README describing submission rules. If you are choosing an implementation, the conformance reports are the closest thing to evidence available, and they are per-implementation rather than per-API.

A second boundary is versioning. The README names v1.6.1 as the release that carries the v1 support it describes, while the repository's recent releases also list v1.6.2, v1.6.1 and v1.6.0. Patch releases in a CRD repository are not cosmetic: they can change validation, and a controller built against one patch may not have been tested against another. The README does not document a rollback procedure for CRDs, and CRD downgrades are not a supported operation in Kubernetes generally, so treat the version you install as a commitment.

Gateway API compared with Ingress, and with the controllers people name

The difference from Ingress is structural, not cosmetic. Ingress is a single object with a small core and a large surface of vendor annotations. Gateway API separates the class, the gateway instance and the route into distinct objects with distinct owners, and it defines typed fields for things Ingress left to annotations, including protocol-specific routes for gRPC, TLS, TCP and UDP. The cost is more objects to manage and a controller that must understand all of them.

The alternative within the same ecosystem is a service mesh or an ingress controller's own CRDs, where routing is defined once and the vendor owns the schema. That buys tighter integration and fewer moving parts at the price of portability: your configuration is tied to that implementation.

The related searches around this project name Cilium, Traefik, nginx and Envoy. Those are implementations, not alternatives to the API. The meaningful comparison is between implementations, and the repository's own conformance reports are where that comparison starts. Note also that the search list includes a Helm chart and gateway api inference extension; neither appears in the README, so this article cannot tell you what they contain. If you need Helm-based installation, that is a packaging decision made outside this repository, and you should confirm it against the implementation you choose.

Maintenance, licence and the upgrade cost you are signing up for

The repository is not archived, and the last push was on 2026-09-23. Releases are frequent: v1.6.2 on 2026-09-03, v1.6.1 on 2026-07-16 and v1.6.0 on 2026-06-29. For a specification repository, that cadence means the API surface is still moving even where the core resources are GA.

The licence is Apache-2.0, declared in the LICENSE file at the repository root, and the source headers in the Makefile carry the same Apache 2.0 notice. Apache-2.0 is permissive and includes a patent grant. Whether that fits your distribution model is a question for your own legal review; nothing here should be read as advice on it.

Upgrade cost has two layers. The first is the CRDs: applying a newer set changes validation for objects already in the cluster, and the README documents no rollback path. The second is the controller, which is versioned independently and may lag the CRDs you install. The repository layout reflects this split: api/, apis/ and apisx/ hold the type definitions, config/ holds generated configuration, and pkg/ plus gwctl/ are Go tooling. gwctl is a CLI in the repository, and the README does not document its commands, so check the tool's own documentation before relying on it.

Editorial conclusion

Adopt Kubernetes Gateway API if you want a role-oriented, portable routing API and are prepared to pick a controller that publishes a conformance report for the version you install. Do not adopt it expecting the repository to route packets: it ships CRDs and a spec, and the README points at the getting started guide for installing your first Gateway controller. Verify two things before committing: which v1 resources your chosen controller actually supports, and whether the CRD channel you installed matches the features you plan to use, because the repository separates standard and experimental examples under examples/standard and examples/experimental.

Frequently asked questions

Official sources

1. kubernetes-sigs/gateway-api on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases