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.
GatewayClass names the controller responsible for realizing the Gateway. API objects alone do not install that controller.
- GatewayClass to Controllercontroller name
Read the complete visual sequence
- Choose the implementation
GatewayClass names the controller responsible for realizing the Gateway. API objects alone do not install that controller.
- Expose an owned listener
The Gateway declares listeners and which routes may attach, giving infrastructure a separate ownership boundary.
- Attach an application route
HTTPRoute parentRefs asks to attach to the Gateway. The controller checks listener rules and resolves backend references.
- 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.
- Route exists
The API stores the route, but persistence does not mean a parent accepted it.
- Attachment check fails
The Gateway listener allowedRoutes rule rejects the route, so its routing rule is not programmed there.
- 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.
The implementation obtains a permitted certificate reference and key for the HTTPS listener.
- TLS Secret to TLS listenercertificate reference
Read the complete visual sequence
- Load listener credentials
The implementation obtains a permitted certificate reference and key for the HTTPS listener.
- Verify the hostname and trust
The client checks that certificate names cover api.example.test and that its issuer is trusted.
- Route decrypted HTTP
After terminating TLS, the implementation can inspect the HTTP host and path and select a route.
- 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.
- TCP reaches the listener
Network reachability succeeds before certificate identity is evaluated.
- Identity check fails
The client rejects the certificate because the requested hostname is absent from its valid names.
- 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