Appearance

Ingress, Gateway API, and TLS

Separate route declarations, controller installation, certificate termination, and backend reachability.

What you will understand

  • Explain why route resources need a controller implementation
  • Compare Ingress with Gateway API ownership boundaries
  • Trace TLS termination and diagnose route attachment

Builds on: NetworkPolicy and isolation

Mental model: declare a route, supply a working implementation

An internal Service discovers and forwards to backends. Publishing HTTP outside the cluster adds another boundary: an implementation must receive external traffic, interpret the HTTP host and path, and forward to a backend Service. Ingress is a Kubernetes API for declaring that HTTP routing intent. Creating an Ingress object alone installs no proxy and opens no public network path. An Ingress controller observes the object and configures its associated traffic-handling implementation.

An IngressClass identifies the implementation responsible for a group of Ingresses. The Ingress API is stable but feature-frozen; controller annotations often expose additional provider-specific behavior. Treat such annotations as implementation configuration rather than portable Kubernetes semantics. A route that works on one controller can behave differently on another if it relies on rewrites, regular expressions or special timeout annotations.

Gateway API is an additional API family, normally installed as CRDs with an implementation. It separates infrastructure ownership from application routes. A GatewayClass identifies a controller, a Gateway declares listeners and attachment policy, and an HTTPRoute declares host and path matching plus backend references. These boundaries let an infrastructure team manage public listeners while application teams manage their own routes. Cross-namespace route-to-Gateway attachment is governed by the listener’s allowedRoutes; cross-namespace backend or certificate references normally require a ReferenceGrant in the target namespace. An object reference is not automatically authority to use another team’s resource.

Attach an application route to an owned listener

Follow GatewayClass, Gateway, HTTPRoute and backend reference reconciliation.

Ownership viewStep 1 of 4
Choose the implementationGatewayClass names the controller responsible for realizing the Gateway. API objects alone do not install that controller.. GatewayClass, Selects controller implementation, active. Gateway public, Listener and allowedRoutes, idle. HTTPRoute api, Host api.example.test; path /api, idle. Controller, Evaluates attachment and references, active. Service api, Backend Service port 80, idleGatewayClass: Selects controller implementation
GatewayClassSelects controller implementationIn focus
Gateway public: Listener and allowedRoutes
Gateway publicListener and allowedRoutesContext
HTTPRoute api: Host api.example.test; path /api
HTTPRoute apiHost api.example.test; path /apiContext
Controller: Evaluates attachment and references
ControllerEvaluates attachment and referencesIn focus
Service api: Backend Service port 80
Service apiBackend Service port 80Context
GatewayClassSelects controller implementationIn focus
Gateway publicListener and allowedRoutesContext
HTTPRoute apiHost api.example.test; path /apiContext
ControllerEvaluates attachment and referencesIn focus
Service apiBackend Service port 80Context
Animation controls
Speed
0.5×
1×
2×
Explore a scenario
Normal behavior
Gateway rejects attachment
Choose the implementation

GatewayClass names the controller responsible for realizing the Gateway. API objects alone do not install that controller.

Read the complete visual sequence
  1. Choose the implementation

    GatewayClass names the controller responsible for realizing the Gateway. API objects alone do not install that controller.

  2. Expose an owned listener

    The Gateway declares listeners and which routes may attach, giving infrastructure a separate ownership boundary.

  3. Attach an application route

    HTTPRoute parentRefs asks to attach to the Gateway. The controller checks listener rules and resolves backend references.

  4. Report accepted configuration

    Status conditions describe attachment and references. Ready endpoints and external reachability are still needed for successful requests.

Gateway rejects attachment

The listener does not allow this route namespace or kind.

  1. Route exists

    The API stores the route, but persistence does not mean a parent accepted it.

  2. Attachment check fails

    The Gateway listener allowedRoutes rule rejects the route, so its routing rule is not programmed there.

  3. Inspect parent conditions

    Repair the attachment policy with the listener owner rather than changing a healthy backend Pod.

About this model

Gateway API CRDs and a compatible controller are already installed; all references are same-namespace.

Walkthrough: follow acceptance before following packets

This HTTPRoute assumes the Gateway API CRDs, a compatible implementation, a Gateway named public in the same namespace, and a working api Service. The Gateway must permit this route to attach to its listener. It does not create that Gateway or its external address.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api
spec:
  parentRefs:
    - name: public
  hostnames:
    - api.example.test
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - name: api
          port: 80        # Service port, not container targetPort.

Inspect route status conditions and parent status before changing the application. Accepted and ResolvedRefs explain whether the route attached and its references resolved; the Gateway’s own conditions and addresses explain another part of the path. An accepted route still needs a reachable implementation, permitted network traffic, ready endpoints and a functioning backend. Status is evidence about a particular reconciliation boundary, not a universal end-to-end health assertion.

For HTTPS, the listener usually terminates TLS using a certificate and private key from a referenced Secret. The certificate’s names must cover the client’s hostname, and the client must trust its issuer. TLS termination authenticates and encrypts the client-to-listener connection; it does not automatically encrypt the proxy-to-backend hop. Backend TLS needs separate supported configuration and verification. Never infer end-to-end encryption from a padlock at the browser.

TLS ends where it is terminated

Follow hostname verification, listener TLS termination and a separately configured backend hop.

Flow viewStep 1 of 4
Load listener credentialsThe implementation obtains a permitted certificate reference and key for the HTTPS listener.. Client, Requests api.example.test, idle. TLS listener, Certificate and private key, active. TLS Secret, kubernetes.io/tls, active. HTTP router, Matches host and path, idle. Backend Service, HTTP unless configured otherwise, idleClient: Requests api.example.test
ClientRequests api.example.testContext
TLS listener: Certificate and private key
TLS listenerCertificate and private keyIn focus
TLS Secret: kubernetes.io/tls
TLS Secretkubernetes.io/tlsIn focus
HTTP router: Matches host and path
HTTP routerMatches host and pathContext
Backend Service: HTTP unless configured otherwise
Backend ServiceHTTP unless configured otherwiseContext
ClientRequests api.example.testContext
TLS listenerCertificate and private keyIn focus
TLS Secretkubernetes.io/tlsIn focus
HTTP routerMatches host and pathContext
Backend ServiceHTTP unless configured otherwiseContext
Animation controls
Speed
0.5×
1×
2×
Explore a scenario
Normal behavior
Wrong certificate name
Load listener credentials

The implementation obtains a permitted certificate reference and key for the HTTPS listener.

Read the complete visual sequence
  1. Load listener credentials

    The implementation obtains a permitted certificate reference and key for the HTTPS listener.

  2. Verify the hostname and trust

    The client checks that certificate names cover api.example.test and that its issuer is trusted.

  3. Route decrypted HTTP

    After terminating TLS, the implementation can inspect the HTTP host and path and select a route.

  4. Open a separate backend connection

    The router connects to the backend using its configured protocol. Listener TLS does not automatically encrypt this connection.

Wrong certificate name

The listener is reachable but presents a certificate for a different hostname.

  1. TCP reaches the listener

    Network reachability succeeds before certificate identity is evaluated.

  2. Identity check fails

    The client rejects the certificate because the requested hostname is absent from its valid names.

  3. Repair identity and trust

    Use the intended hostname, covering certificate and trusted CA, then verify again without disabling checks.

About this model

HTTP routing after listener termination; passthrough TLS is intentionally outside this example.

Practice: vary one hostname and one layer at a time

kubectl get gatewayclass
kubectl get gateways,httproutes
kubectl describe httproute api
kubectl get service api
kubectl get endpointslices -l kubernetes.io/service-name=api
# Replace the address with the lab listener address, if installed.
curl -v -H 'Host: api.example.test' http://127.0.0.1:8080/api

A plain kind cluster may have neither Gateway API CRDs nor a route controller. In that case, the networking lab first uses port-forwarding for local access and marks controller installation as an optional extension. A missing resource type is an installation boundary; adding more HTTPRoute YAML will not install its CRD. A pending external address may be a LoadBalancer implementation boundary, rather than a route syntax problem.

For an HTTPS extension, use a local training CA and a certificate covering api.example.test. Use curl --resolve to set the destination address while preserving the hostname used for TLS verification and HTTP routing. Supply the local CA using --cacert. Disabling certificate verification may help isolate a trust problem briefly, but it does not validate the final secure configuration. Keep private keys out of shell transcripts and committed manifests.

Pitfalls: HTTP, TLS and TCP are different match points

A hostname mismatch can select the wrong virtual host even when the destination IP is correct. A TLS handshake may fail before an HTTP path is visible. A route can return 404 because no rule matches, while an implementation-generated 503 may indicate no usable upstream. These exact response conventions vary by controller, so inspect its logs and status rather than treating every code as proof. Test the backend Service internally before changing external routing rules.

Check your understanding

An HTTPS route serves a valid certificate, but forwards to the backend over plain HTTP. Is the backend hop encrypted?

No. The listener has terminated the client’s TLS session. Encryption of the separate backend connection requires its own supported TLS configuration, trust settings and backend server support. Confirm both connections independently when the requirement is encryption across the entire traffic path.

Next, connect a Pod to persistent storage. Like routing, storage depends on both declarative API objects and an installed implementation that can realize them.

Primary documentation

Go to the source

Reviewed 2026-10-27 · Kubernetes 1.37 · Related local exercise

Search the book

Search loads when you open it.