Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 78 ยท Services and Networking

Gateway API

Learn the Kubernetes Gateway API: GatewayClass, Gateway and HTTPRoute, how roles are separated, weighted traffic splitting, and how it compares with Ingress.

Ingress solved a real problem, but it was designed small: one resource, a few host and path rules, and everything else hidden in controller-specific annotations. As teams asked for header matching, traffic splitting, redirects and shared load balancers, each controller invented its own annotations, and manifests stopped being portable.

The Gateway API is the official successor. It is a family of resources (installed as custom resource definitions, not built into the core API) that models the problem in layers: who provides the infrastructure, who runs the load balancer, and who owns the routing rules for one application. In this lesson you will meet the three core resources, see how they split responsibility between teams, write a weighted canary route, and run a small route matcher to see how the rules are chosen.

The Gateway API is installed separately from Kubernetes itself. Most managed clusters offer it as an add-on, and many ingress controllers (Envoy Gateway, Istio, Cilium, NGINX Gateway Fabric, Traefik and others) implement it. Check that the CRDs exist with kubectl get crd gateways.gateway.networking.k8s.io. The manifests below are read-only on this site because there is no cluster to run them on.

The three core resources

Three layers, three owners

GatewayClass A kind of load balancer, offered by an infrastructure provider.
Gateway One running load balancer with ports and listeners.
HTTPRoute Rules that send requests to Services.

Platform team owns the top two, app teams own routes.

1 / 2

A GatewayClass is the equivalent of a StorageClass: it names a controller that knows how to build gateways. Cluster administrators or the vendor create it. Application developers rarely touch it.

YAML
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: shared-lb
spec:
  controllerName: example.com/gateway-controller

A Gateway is a request for a load balancer of that class. It declares listeners: a port, a protocol, and optionally a hostname and TLS settings.

YAML
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: public
  namespace: infra
spec:
  gatewayClassName: shared-lb
  listeners:
    - name: http
      port: 80
      protocol: HTTP
      allowedRoutes:
        namespaces:
          from: All
    - name: https
      port: 443
      protocol: HTTPS
      hostname: "*.example.com"
      tls:
        mode: Terminate
        certificateRefs:
          - name: wildcard-example-com
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              expose: "true"

Look at allowedRoutes. The platform team decides which namespaces may attach routes to each listener: only its own (Same, the default), every namespace (All), or namespaces with a particular label (Selector). That is the guard rail Ingress never had.

An HTTPRoute attaches to one or more gateways through parentRefs and holds the actual routing rules:

YAML
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: shop
  namespace: shop
spec:
  parentRefs:
    - name: public
      namespace: infra
      sectionName: https
  hostnames:
    - "shop.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - name: shop-api
          port: 8080
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: shop-web
          port: 80

Each rule has matches (all conditions inside one match must be true; the list entries are alternatives) and backendRefs pointing at Services. A sectionName on the parent reference pins the route to one listener. After applying, kubectl describe httproute shop shows conditions such as Accepted and ResolvedRefs, which tell you if the gateway took the route and found its Services.

If you have to debug a route that "does nothing", read its status.parents[].conditions first. Accepted: False with a reason like NotAllowedByListeners means the Gateway refused it, and the reason is spelled out for you.

Role separation in practice

The design assumes three kinds of people. An infrastructure provider supplies classes. A cluster operator creates gateways, owns certificates and decides which namespaces may attach. Application developers write routes in their own namespace and never need rights over the shared load balancer.

flowchart LR
  C["Client"] --> G["Gateway 'public'<br/>namespace infra"]
  G --> R1["HTTPRoute 'shop'<br/>namespace shop"]
  G --> R2["HTTPRoute 'blog'<br/>namespace blog"]
  R1 --> S1["Service shop-api"]
  R1 --> S2["Service shop-web"]
  R2 --> S3["Service blog"]

One shared Gateway, many routes owned by different teams in different namespaces.

A route may point at a Service in another namespace only if that namespace agrees, with a ReferenceGrant object created in the target namespace. Without it the route reports ResolvedRefs: False. This stops one team from silently sending traffic to another team's Service.

Matching, filters and splitting traffic

Matches can look at the path (Exact, PathPrefix, or an implementation-specific regular expression), headers, query parameters and the HTTP method. Filters change the request on the way: the standard ones add or remove headers, redirect, rewrite the URL, or mirror the request to a second backend.

The feature people notice first is the weight on a backend. Two entries with weights split traffic proportionally, with no annotation involved:

YAML
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: shop-canary
  namespace: shop
spec:
  parentRefs:
    - name: public
      namespace: infra
  hostnames: ["shop.example.com"]
  rules:
    - matches:
        - path: { type: PathPrefix, value: / }
      backendRefs:
        - name: shop-web-v1
          port: 80
          weight: 90
        - name: shop-web-v2
          port: 80
          weight: 10
    - matches:
        - headers:
            - name: x-beta
              value: "yes"
      backendRefs:
        - name: shop-web-v2
          port: 80

Weights are relative, not percentages: 90 and 10 happen to add up to 100 here, but 9 and 1 would behave the same. A weight of 0 sends no traffic. This is how a canary deployment is done at the routing layer.

When several rules could match one request, the specification gives a fixed order, so the result is predictable on every implementation: a more specific hostname wins over a wildcard, then an Exact path beats a prefix, a longer prefix beats a shorter one, a rule with a method match beats one without, and more header matches beat fewer. The next example implements a simplified version.

A route matcher you can run

This stand-in is not a Gateway controller. It models only the decision "which rule wins, and which backend gets this request", with a deterministic weighted choice so the output is stable.

Python Choosing a rule and a backend

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that /apiary falls through to the catch-all rule: a prefix match respects segment boundaries, exactly like the real specification. And the header rule beats the plain / rule because it carries more conditions, even though both use the same path.

Python Validating a route's parent attachment

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

What is real here and what is not: the resource names, fields and the rule precedence are the real Gateway API. The Python code is a toy model of the decisions; a real controller programs an actual proxy (Envoy, NGINX and so on) and reports status back on the objects.

Gateway API versus Ingress

Ingress Gateway API
Resources One GatewayClass, Gateway, routes (HTTPRoute, GRPCRoute, TLSRoute and more)
Who owns what Mixed in one object Split by role, with namespace attachment rules
Traffic splitting, header match Annotations (non-portable) Built into the spec
Protocols HTTP and HTTPS HTTP, gRPC, TLS, TCP, UDP (some experimental)
Status Feature-frozen, still supported Active development, GA for the core resources

Ingress is not going away, and for a simple site with one host it is still perfectly fine. Choose the Gateway API when several teams share a load balancer, when you need weights or header routing, or when you want manifests that move between implementations without rewriting annotations.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Who normally creates a Gateway object?

    The design splits roles. The platform team owns Gateways, certificates and the rules about which namespaces may attach routes. Application teams own HTTPRoutes.
  2. 2. A route has two backendRefs with weights 3 and 1. What share of requests goes to the first backend?

    Weights are relative. The first backend receives 3 / (3 + 1), which is 75 percent of the traffic.
  3. 3. Your HTTPRoute is in namespace shop and the Gateway listener allows routes only from the same namespace as the Gateway. What do you see?

    allowedRoutes is enforced by the Gateway. A refused route reports Accepted as False with a reason in status.parents.
  4. 4. With PathPrefix /api, does the path /apiary match?

    The specification matches on path segment boundaries, which avoids the surprise of /apiary matching /api.

Summary

  • The Gateway API splits ingress into GatewayClass (the kind), Gateway (a load balancer with listeners) and routes such as HTTPRoute (the rules).
  • allowedRoutes on a listener and ReferenceGrant objects let platform teams control who may attach or reference what.
  • Weights, header and method matches, redirects and rewrites are part of the standard, not controller annotations.
  • Precedence is defined: hostname specificity, exact before prefix, longer prefix first, then more conditions.
  • It is installed as CRDs and implemented by many controllers; Ingress remains fine for simple setups.

Next, learn how to control which Pods may talk to each other in Network Policies.