Ingress controllers and Gateway API: routing objects versus data planes
Separate Ingress and Gateway API resources from the controllers that implement them. Trace HTTPS routing and diagnose host, certificate, route and backend failures.
TL;DR: Ingress describes HTTP routing intent; an installed controller implements that intent using a proxy or load balancer. Gateway API offers a more expressive, role-oriented model. Neither an Ingress nor an HTTPRoute forwards traffic merely by existing in the API.
Follow one HTTPS request
A browser resolves shop.example.com to an entry address, establishes a TLS connection with the configured endpoint, and sends an HTTP request containing a host and path. The data plane selects a route and forwards toward a backend Service or its endpoints, depending on the implementation.
The Kubernetes resource expresses part of that configuration. The controller watches it, checks whether it belongs to the controller's class and provisions or configures the forwarding components. A wrong class can leave a perfectly valid resource unhandled.
Control-plane reconciliation is the dotted configuration path. Customer requests take the data-plane path. Keeping them separate explains why a controller restart need not immediately terminate established traffic, while a failed configuration update can prevent a new route from becoming usable.
Ingress is supported, with a bounded API
The Kubernetes Ingress documentation states that the API is frozen and recommends Gateway API for new capabilities. Frozen means no further API development; it does not mean the Ingress API has been removed. Controller support and lifecycle are separate questions that must be checked for the specific implementation.
An Ingress commonly declares host/path routing and TLS settings. Controller-specific annotations can extend behavior, but they reduce portability. Two implementations may accept the same object and differ in supported annotations, path rewriting or connection handling.
Gateway API separates responsibilities
| Resource | Typical responsibility | Question to answer during diagnosis |
|---|---|---|
| GatewayClass | Infrastructure-level controller selection | Which implementation owns this class? |
| Gateway | Listeners and traffic entry policy | Was the listener accepted and programmed? |
| HTTPRoute | Application routing rules | Is the route attached to an allowed parent? |
| ReferenceGrant | Permission for supported cross-namespace references | Is the reference permitted by the target namespace? |
The Gateway API introduction describes this role-oriented design. Infrastructure owners can manage shared entry points while application owners manage permitted routes. Exact feature support still depends on the controller and its conformance profile.
Work through a misleading 404
A new checkout route returns 404, but a request made directly to the backend works. Start by confirming which component produced the 404. Proxy access logs and response headers can help, although headers alone may be misleading or intentionally hidden.
Verify the client reached the intended address and sent the expected host. Calling a load-balancer IP without the intended host may match no route. For HTTPS, certificate selection uses the TLS server name before HTTP host/path routing happens, so a test must preserve both where relevant.
Then inspect route status, class selection and listener attachment. If the route is accepted, check exact path matching and any rewrite rule. Finally inspect the backend Service's port and EndpointSlices. A healthy backend says little about whether the external request matched the route that points to it.
TLS termination changes the downstream contract
When TLS terminates at the edge, the next hop may use HTTP or a separately protected TLS connection. Establish the intended encryption boundary. Forwarded host and scheme headers must be trusted only from known proxies; accepting arbitrary client-supplied forwarding headers can produce incorrect redirects or security decisions.
Certificate availability is also a lifecycle problem. A valid TLS secret today can expire during a later quiet period. Monitor issuance, renewal and the certificate actually presented by the data plane. Updating the Kubernetes Secret is only part of the propagation path.
An external DNS change has its own cache behavior. Even after a new gateway is healthy, clients may continue using the previous address until cached answers expire. Plan overlap during migration using the old TTL, not just the new TTL you set at cutover.
Choose a migration that you can verify
For an existing Ingress installation, inventory annotations and behaviors before translating objects to Gateway API. Map routing, timeouts, redirects, TLS handling and authentication requirements to supported features. Test representative requests and error paths against the new controller before moving the hostname.
Keep the old path available for the planned transition window, and identify how traffic returns if the new path fails. A rollback that depends on immediate global DNS propagation is unreliable. When an implementation supports weighted routing, verify its actual traffic distribution as part of the migration.
Self-check: an HTTPRoute exists, its backend Service has ready Pods, and the route is still unreachable. What remains unproven?
Whether the required CRDs and controller are installed, the route's parent accepts it, the listener is programmed, references are permitted, and DNS/TLS reach that listener. Inspect status conditions rather than equating object creation with active routing.
Use Service and EndpointSlice diagnosis for the backend half, and canary exposure when the gateway will control rollout traffic.