This Kubernetes Ingress and Gateway API guide provides a reusable checklist for routing traffic to services safely. It covers host and path rules, TLS secrets, DNS, health checks, controller behavior, progressive delivery, and the troubleshooting steps to use when a route returns 404, a load balancer remains pending, or a certificate does not match the requested hostname.
Overview
A Kubernetes Service provides a stable endpoint for a group of Pods, but it does not by itself decide how external HTTP or HTTPS traffic reaches that service. An Ingress resource or Gateway API configuration adds that routing layer. The controller installed in your cluster then translates those resources into a load balancer, reverse proxy, or other data-plane configuration.
The basic request path is:
- A DNS record points a hostname such as
app.example.comto the external address of the controller or Gateway. - The controller receives the request and selects a matching host and path rule.
- The rule forwards traffic to a Kubernetes Service.
- The Service selects healthy Pods through its label selector.
- The application responds, subject to TLS, readiness, and application-level health checks.
Ingress remains a practical choice for straightforward HTTP and HTTPS routing. Gateway API separates infrastructure responsibilities more explicitly: a platform team can manage a GatewayClass and Gateway, while application teams attach HTTPRoute resources. The correct choice depends on the controller, cloud integration, team boundaries, and routing features you need. Always check the documentation for the controller installed in your cluster because annotations, supported fields, and load-balancer behavior differ.
For related DNS work, see the DNS record types reference and the DNS runbook. If you are automating certificate renewal, the ACME TLS guide provides a complementary workflow.
Controller comparison
| Option | Best fit | What to verify |
|---|---|---|
| Ingress controller | Simple host and path routing with an established operational model | IngressClass, annotations, TLS integration, and cloud load-balancer settings |
| Gateway API controller | Shared infrastructure, clearer ownership, and more expressive traffic policies | Supported Gateway API resources, attachment rules, filters, and status conditions |
| Cloud-managed ingress or Gateway | Teams that want provider-integrated networking and certificates | Provisioning time, subnet or firewall requirements, identity permissions, and provider-specific fields |
Checklist by scenario
Scenario 1: Route one hostname to one service with Ingress
- Confirm the application Service exists and its port matches the container or target port.
- Confirm the Service selector matches the intended Pods.
- Install or identify an Ingress controller and set the correct
ingressClassName. - Create a DNS record for the hostname, pointing to the controller's published address.
- Define the host and path rule. Prefer an explicit host rather than relying on a catch-all rule.
- Test the route with the expected Host header and an external request.
A minimal Ingress template using the stable Kubernetes Ingress API looks like this:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web
namespace: production
spec:
ingressClassName: example
rules:
- host: app.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: web
port:
number: 80Replace the class, namespace, hostname, Service name, and port with values from your cluster. Avoid copying controller-specific annotations until you understand their effect and confirm that your controller supports them.
Scenario 2: Add HTTPS with a Kubernetes TLS secret
- Obtain a certificate whose subject or SAN covers the requested hostname.
- Create or reference a TLS Secret in the same namespace as the Ingress, unless your controller explicitly supports another arrangement.
- Add the
tlsblock and use the exact hostname in both the rule and certificate coverage. - Verify that the controller has permission to read the Secret.
- Test both certificate presentation and application routing.
spec:
tls:
- hosts:
- app.example.com
secretName: app-example-com-tls
rules:
- host: app.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: web
port:
number: 80A certificate mismatch can occur even when the Secret exists: the client may be requesting a different hostname, the certificate may be stale, or the controller may be serving a default certificate.
Scenario 3: Use Gateway API for shared routing
Gateway API commonly divides configuration into a GatewayClass, a Gateway, and one or more HTTPRoute resources. The exact API versions and supported fields depend on the Gateway API release and controller. Check the CRDs installed in the cluster before applying examples.
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: web
namespace: production
spec:
parentRefs:
- name: public-gateway
namespace: network
hostnames:
- app.example.com
rules:
- matches:
- path:
type: PathPrefix
value: /
backendRefs:
- name: web
port: 80Check the route status after applying it. A route can be syntactically valid but not accepted because of namespace permissions, an invalid parent reference, an unsupported filter, or a hostname conflict. Use the status conditions as an operational signal rather than assuming that a successful kubectl apply means traffic is ready.
Scenario 4: Prepare a canary or blue-green rollout
- Deploy the candidate version behind a separate Service or an explicitly supported traffic-splitting mechanism.
- Keep the stable route available until the candidate passes readiness, smoke, and application checks.
- Start with a narrow test surface, such as a separate hostname, header match, or controlled traffic percentage when supported.
- Observe error rates, latency, logs, and dependency behavior before increasing exposure.
- Document the rollback action: restore the previous backend, route all traffic to the stable Service, or revert the declarative change.
Do not assume that every Ingress controller supports weighted routing. Gateway API filters and controller extensions also vary. If traffic splitting is unavailable, a blue-green hostname or a deployment system with explicit rollout controls may be easier to reason about.
What to double-check
- DNS: Confirm the record points to the current external address and that no stale CNAME, A, or AAAA record sends clients elsewhere. A DNS propagation check should be performed from more than one resolver when investigating a change.
- Class and ownership: Verify the IngressClass or GatewayClass. Multiple controllers can watch different resources, and an omitted or incorrect class can leave a resource ignored.
- Service ports: Distinguish the Service port from the target port. The route normally forwards to the Service port, not directly to the container port.
- Endpoints: Confirm that the Service has ready endpoints. A selector typo can produce a valid-looking Service with no usable backends.
- Readiness: A Pod can be running while remaining unready. Review readiness probes, startup time, dependency checks, and the endpoint conditions before changing routing.
- TLS: Check Secret type, namespace, certificate dates, hostname coverage, and whether the controller reloaded the Secret after rotation.
- Network policy and firewalls: Confirm that the load balancer, nodes, Pods, and health-check source ranges can communicate on the intended ports.
- Path behavior: Confirm whether the controller preserves or rewrites the path. An application expecting
/may fail when it receives/api, depending on the configuration. - Observability: Record the controller events, resource status, access logs, application logs, and the exact request used for testing.
Useful first commands include kubectl describe ingress, kubectl get ingress -o wide, kubectl describe gateway, kubectl describe httproute, kubectl get svc,endpointslice, and kubectl get events --sort-by=.lastTimestamp. Use a request tool such as curl to inspect response headers, redirects, and certificate behavior. The curl and jq API testing guide can help structure that investigation.
Troubleshooting matrix
| Symptom | Likely checks | Next action |
|---|---|---|
| 404 response | Host header, path, class, route status, and controller logs | Test the exact hostname and confirm the request matches one declared rule |
| Load balancer pending | Cloud permissions, subnets, quotas, firewall rules, and controller events | Inspect events and provider integration before changing the manifest |
| Certificate mismatch | DNS target, requested hostname, TLS Secret, and default-certificate behavior | Inspect the certificate served for the exact hostname |
| Failed health probe | Probe path, port, protocol, readiness state, and firewall access | Test the endpoint from the probe's network perspective |
| Conflicting routes | Duplicate hostnames, overlapping paths, namespaces, and controller precedence | Make ownership explicit and remove or narrow overlapping rules |
Common mistakes
- Creating DNS records before confirming which address the controller actually publishes.
- Using a controller-specific annotation without checking its spelling, scope, or compatibility.
- Assuming a Pod's
Runningstatus means it is ready to receive production traffic. - Putting a TLS Secret in a different namespace from the Ingress without a supported cross-namespace mechanism.
- Testing by IP address and concluding that host-based routing works, even though the Host header was not correct.
- Changing several layers at once, which makes it difficult to identify whether the fault is in DNS, the load balancer, the route, the Service, or the application.
- Rolling out a new backend without a defined rollback path or a way to compare stable and candidate behavior.
Make routing changes declarative, reviewable, and reversible. For larger deployments, connect the manifests to a CI/CD workflow with validation, a staged rollout, and a documented rollback. Keep application and database compatibility in mind; the expand-and-contract migration guide covers a related deployment concern.
When to revisit
Revisit this checklist before onboarding a cluster, adding a public service, changing a hostname or path, rotating certificates, moving between cloud load balancers, introducing a second routing controller, or testing a canary release. It should also be reviewed after upgrades to Kubernetes, the Ingress controller, Gateway API CRDs, certificate tooling, or cloud networking components because supported fields and defaults can change.
As a practical maintenance routine, keep an inventory of hostnames, controllers, GatewayClasses, IngressClasses, TLS Secrets, Services, and DNS owners. Test one known-good route after infrastructure changes, then test a deliberately invalid hostname or path to confirm that failures are distinguishable. Schedule a periodic review before major planning or release cycles and whenever the team changes its deployment workflow.
Final preflight: verify DNS, class ownership, route status, Service endpoints, readiness, TLS coverage, health checks, logs, monitoring, and rollback steps. Only then promote the route or increase traffic to a new version.