Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Kubernetes Ingress: Path Types, Controller Annotations, and TLS Termination

Prefix matching is element-wise, the controller answers its own 404s, and the TLS Secret has to live in the same namespace. What each status code says about which layer failed.

~6 min readKubernetes
#Kubernetes#Ingress#Networking#TLS
3D illustration of an ingress gateway splitting host and path routes to services behind a TLS padlock

Quick Summary

An Ingress is a routing declaration: host and path rules mapping HTTP requests to Services, plus a TLS section naming a Secret. It does nothing on its own. An Ingress controller — ingress-nginx, Traefik, HAProxy, a cloud provider's own — watches Ingress objects, configures a shared reverse proxy, and is the component that actually terminates TLS and forwards traffic. kubectl get ingress showing an address means a controller claimed the object; showing nothing means no controller with that ingressClassName is running.

pathType decides how paths match, and it is required in networking.k8s.io/v1. Prefix matches element by element: /api matches /api and /api/v1 but not /apiv1. Exact matches only the literal path. ImplementationSpecific hands the decision to the controller, which is where regular expressions and annotation-driven rewrites live. A missing or wrong pathType is the most common reason a rule does not fire.

TLS terminates at the controller: the secretName in spec.tls must be a kubernetes.io/tls Secret in the same namespace with tls.crt and tls.key, and the controller serves that certificate for the listed hosts. Backend TLS is separate (backend-protocol: HTTPS in ingress-nginx), and certificate issuance is cert-manager's job, not the Ingress's. This guide covers the rule structure, path type semantics, annotations that change behaviour, TLS termination and re-encryption, and the status codes that identify which layer failed.

Basic Syntax & Core Signatures

yaml
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: api annotations: nginx.ingress.kubernetes.io/ssl-redirect: "true" nginx.ingress.kubernetes.io/proxy-body-size: "8m" nginx.ingress.kubernetes.io/proxy-read-timeout: "60" spec: ingressClassName: nginx tls: - hosts: [api.example.com] secretName: api-tls rules: - host: api.example.com http: paths: - path: /v1 pathType: Prefix backend: service: name: api port: number: 80 - path: /legacy pathType: Exact backend: service: name: legacy port: name: http defaultBackend: # unmatched hosts/paths service: name: fallback port: number: 80
bash
kubectl get ingressclass kubectl get ingress -A kubectl describe ingress api # rules, TLS, and the resolved endpoints kubectl get ingress api -o jsonpath='{.status.loadBalancer.ingress}' kubectl -n ingress-nginx logs deploy/ingress-nginx-controller --tail=100
yaml
# Regex rewrite (ingress-nginx): strip /api prefix before forwarding metadata: annotations: nginx.ingress.kubernetes.io/use-regex: "true" nginx.ingress.kubernetes.io/rewrite-target: /$2 spec: rules: - host: api.example.com http: paths: - path: /api(/|$)(.*) pathType: ImplementationSpecific backend: { service: { name: api, port: { number: 80 } } }
yaml
# Re-encrypt to the backend metadata: annotations: nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"

Key Comparison Table

pathType/api matchesDoes not matchRegex
Prefix/api, /api/, /api/v1/users/apiv1, /APINo
Exact/api only/api/, /api/v1No
ImplementationSpecificController-definedController-definedingress-nginx: with use-regex
NeedWhere it is configured
Route by host and pathspec.rules
Terminate TLSspec.tls + a kubernetes.io/tls Secret
Redirect HTTP to HTTPSssl-redirect annotation (ingress-nginx)
Request body sizeproxy-body-size
Timeoutsproxy-read-timeout, proxy-send-timeout
IP allowlistwhitelist-source-range / allowlist-source-range
Rate limitlimit-rps, limit-burst
Sticky sessionsaffinity: cookie + session-cookie-name
Basic authauth-type: basic, auth-secret
Rewrite pathrewrite-target (needs use-regex for capture groups)
ResponseLayer that produced it
404 from the controller's default pageNo rule matched (host or path)
404 from your appRule matched; the app has no such route
503 Service Temporarily UnavailableService or endpoints missing/empty
502 Bad GatewayBackend unreachable, or TLS mismatch to the backend
504 Gateway TimeoutBackend too slow for proxy-read-timeout
413 Request Entity Too Largeproxy-body-size too small
400 The plain HTTP request was sent to HTTPS portTLS enforced, client used HTTP
default backend - 404Controller served its fallback

Practical Edge Cases & Deep Dives

1. Prefix matching is element-wise, not string-prefix

yaml
path: /api pathType: Prefix

This matches /api, /api/, and /api/v1/items, but not /apiv1 — the comparison happens per path segment, which is what most people want and few expect. A rule written as path: / with Prefix catches everything, so a specific rule placed after it in a different Ingress may lose: controllers order rules internally (ingress-nginx sorts by host and path length), but two Ingresses on the same host with overlapping paths are resolved by creation timestamp, which is fragile. Keep all routes for a host in one Ingress object, or use one host per team.

bash
$ kubectl describe ingress api | sed -n '/Rules:/,/Annotations:/p' Host Path Backends api.example.com /v1 api:80 (10.244.1.9:8080,10.244.2.3:8080)

The endpoint list in describe is the fastest proof that a rule resolves to a live backend; an empty list is a Service problem, not an Ingress one.

2. The 404 that is not yours

bash
$ curl -sI https://api.example.com/v1/health HTTP/2 404 server: nginx $ kubectl get ingress api -o jsonpath='{.spec.rules[0].http.paths[0].path}{"\n"}' /v1/

A trailing slash mismatch — the rule is /v1/ while the request is /v1 — produces a 404 from the controller with its own server: header (nginx for ingress-nginx, envoy for others). Distinguish the two sources by the body: the controller's 404 is a plain HTML page or default backend - 404, while the application's 404 is your framework's JSON. A 404 on some paths and 200 on others from the same host means the rule exists and the path matching is the problem, not the backend.

3. TLS: termination, secrets, and issued certificates

bash
$ kubectl get secret api-tls -o jsonpath='{.type}' kubernetes.io/tls $ kubectl get secret api-tls -o jsonpath='{.data.tls\.crt}' | base64 -d | openssl x509 -noout -subject -dates -ext subjectAltName

The Secret must be of type kubernetes.io/tls with tls.crt (leaf plus intermediates) and tls.key. A common failure is a certificate whose SAN list lacks the host in spec.tls.hosts, which browsers reject even though the controller serves it. Another is a name mismatch between the Ingress namespace and the Secret namespace: secretName is namespace-local, so an Ingress in prod cannot reference a certificate in cert-manager.

yaml
# cert-manager issues into a Secret that the Ingress references metadata: annotations: cert-manager.io/cluster-issuer: letsencrypt-prod spec: tls: - hosts: [api.example.com] secretName: api-tls # cert-manager creates and renews this

For end-to-end encryption, backend-protocol: HTTPS makes the controller re-encrypt to the Service, which then needs a certificate the controller trusts (proxy-ssl-verify, proxy-ssl-secret to pin a CA). Passthrough (no termination) requires the TLS SNI-based route and is controller-specific; in ingress-nginx it is a separate mechanism, not a field on the Ingress.

4. Rewrites, prefixes, and the redirect loop

yaml
# Strip /api before forwarding: request /api/v1/items -> backend /v1/items nginx.ingress.kubernetes.io/use-regex: "true" nginx.ingress.kubernetes.io/rewrite-target: /$2 # path: /api(/|$)(.*)

Two rules interact badly here. First, use-regex makes every path in that Ingress a regular expression, which changes the meaning of other literal paths in the same object. Second, an application that itself redirects to an absolute path can create a loop when the prefix is stripped: the app returns Location: /login, the client requests /login, no rule matches /login, and the controller answers 404 — or the rewrite sends it back to /api/login. The workable pattern is to keep the public path and the backend path identical, or to configure the app with a base path matching the public one.

5. Multiple Ingresses on one host, and the winning rule

bash
$ kubectl get ingress -A -o custom-columns=NS:.metadata.namespace,NAME:.metadata.name,HOST:.spec.rules[*].host,CREATED:.metadata.creationTimestamp

Controllers merge rules from all Ingresses that share a class. When two Ingresses declare the same host and path, ingress-nginx picks the oldest by creation timestamp, silently. Nothing warns, and a typo in one team's Ingress can shadow another's route for as long as it exists. Host-level ownership by namespace (one host per Ingress) removes the ambiguity; kubectl describe on each candidate shows which one the controller chose, because only one will have the endpoints attached.

6. Reading the controller's logs and the request id

bash
kubectl -n ingress-nginx logs deploy/ingress-nginx-controller -f | grep -E ' 404 | 503 | 502 ' # 10.244.0.1 - - [15/Nov/2026:07:12:44 +0000] "GET /v1/items HTTP/2.0" 503 0.001 # [api-v1-items-abc] [] 10.244.2.3:8080, 10.244.1.9:8080 : connect() failed

The log line names the upstream addresses and the failure (no live upstreams, connect() failed, upstream timed out), which separates "no endpoints" from "endpoints exist but refuse connections". Request-level access logs also prove whether the request reached the controller at all — a request that never appears there was stopped by DNS, a firewall, or a different load balancer in front.

Common Runtime & Configuration Mistakes

SymptomCauseFix
Ingress has no addressNo controller with that ingressClassNameInstall a controller; check get ingressclass
404 from the controllerpathType/path/host mismatch or wrong classCompare with describe; match exactly
404 with the app's JSON bodyRule matched, app route missingFix the app or the path
503 with endpoints listedBackend refuses connectionsCheck targetPort and the app listener
503 with no endpointsSelector or readinessFix the Service/readiness
502 on HTTPS backendBackend cert not trusted, or plain HTTP expectedbackend-protocol, proxy-ssl-verify
413 on uploadsproxy-body-size default 1mRaise the annotation
504 after exactly 60sproxy-read-timeoutRaise it, or fix the slow backend
Certificate warning for a hostSAN list missing the hostReissue with the host, check spec.tls.hosts
Secret not foundWrong namespaceSecret must be in the Ingress namespace
Rewrite produces a redirect loopPrefix stripped, app redirects to an absolute pathKeep paths aligned, or set a base path
Some routes randomly 404Two Ingresses own the same hostOne Ingress per host

An Ingress is a declaration that only a running controller can honour, and every failure belongs to one of three layers: no controller claimed the object, the rule did not match the request, or the rule matched and the Service behind it had no reachable endpoint. The controller's access log and kubectl describe ingress name the layer in one line each, which is faster than changing annotations and hoping.

Try matching browser tools

All tools

Small utilities that fit Kubernetes work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Kubernetes guides

More in Kubernetes

All Kubernetes guides

The guides filed next to this one in Kubernetes, in library order.