Kubernetes Ingress Explained: Controllers, Routing, TLS and Troubleshooting

Kubernetes Ingress Explained#

Kubernetes Ingress Explained Ingress provides a controlled HTTP and HTTPS entry point for applications running behind Kubernetes Services. It can route requests by hostname or URL path, terminate TLS, redirect traffic and centralize web-routing rules. Why Kubernetes Ingress is needed You could expose every application using a separate LoadBalancer Service, but that may create many public load balancers, IP addresses and duplicated TLS configurations. Ingress allows multiple websites and APIs to share one external entry point while keeping their backend Services internal. Host-based routing Send shop.example.com and api.example.com to different Services. Path-based routing Send /api, /admin and / to different backends. TLS termination Accept HTTPS at the ingress controller using a Kubernetes TLS Secret. Central control Apply redirects, request limits, authentication and routing policies in one layer. Ingress is not the same as an ingress controller An Ingress resource is a Kubernetes API object containing desired routing rules. An ingress controller is the running software that watches those resources and configures a reverse proxy or cloud load balancer. Component | Responsibility Ingress | Stores hosts, paths, backend Services and TLS configuration. IngressClass | Identifies which controller should handle an Ingress. Ingress controller | Implements the routing rules and receives external traffic. Service | Provides a stable backend and routes traffic to healthy Pods. Ingress traffic flow 1. A user requests app.example.com 2. DNS resolves the hostname to the ingress controller’s public address. 3. The controller terminates TLS and evaluates host and path rules. 4. The matching rule forwards the request to a Kubernetes Service. 5. The Service sends traffic to one of its healthy Pod endpoints. Prerequisite Deployment and Service apiVersion: apps/v1 kind: Deployment metadata: name: web spec: replicas: 3 selector: matchLabels: app: web template: metadata: labels: app: web spec: containers: - name: web image: nginx:1.27 ports: - containerPort: 80 readinessProbe: httpGet: path: / port: 80 initialDelaySeconds: 3 periodSeconds: 5 --- apiVersion: v1 kind: Service metadata: name: web-service spec: selector: app: web ports: - name: http port: 80 targetPort: 80 Basic host-based Ingress apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: web-ingress spec: ingressClassName: nginx rules: - host: app.example.com http: paths: - path: / pathType: Prefix backend: service: name: web-service port: number: 80 The request is routed only when the hostname matches app.example.com. The Service name and port must exist in the same namespace as the Ingress.

Understanding pathType#

Understanding pathType pathType | Behavior | Example Exact | Matches the complete URL path exactly. | /login matches /login, not /login/help. Prefix | Matches path segments beginning with the configured prefix. | /api matches /api and /api/users. ImplementationSpecific | Behavior depends on the ingress controller. | Use only when controller-specific behavior is required. Path-based routing example apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: platform-ingress spec: ingressClassName: nginx rules: - host: platform.example.com http: paths: - path: /api pathType: Prefix backend: service: name: api-service port: number: 8080 - path: /admin pathType: Prefix backend: service: name: admin-service port: number: 80 - path: / pathType: Prefix backend: service: name: frontend-service port: number: 80 Route multiple hostnames spec: ingressClassName: nginx rules: - host: shop.example.com http: paths: - path: / pathType: Prefix backend: service: name: shop-service port: number: 80 - host: api.example.com http: paths: - path: / pathType: Prefix backend: service: name: api-service port: number: 8080 Configure HTTPS with a TLS Secret Create a TLS Secret from an existing certificate and private key: kubectl create secret tls app-tls \ --cert=tls.crt \ --key=tls.key Reference that Secret from the Ingress: apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: secure-web-ingress spec: ingressClassName: nginx tls: - hosts: - app.example.com secretName: app-tls rules: - host: app.example.com http: paths: - path: / pathType: Prefix backend: service: name: web-service port: number: 80 The TLS Secret must normally exist in the same namespace as the Ingress. For automated certificate issuance and renewal, many clusters use cert-manager with an ACME issuer such as Let’s Encrypt. IngressClass example apiVersion: networking.k8s.io/v1 kind: IngressClass metadata: name: nginx spec: controller: k8s.io/ingress-nginx Use ingressClassName instead of relying only on the older kubernetes.io/ingress.class annotation. Controller-specific annotations Annotations provide features that are not standardized by the Ingress API. Their names and behavior vary by controller. metadata: annotations: nginx.ingress.kubernetes.io/ssl-redirect: "true" nginx.ingress.kubernetes.io/proxy-body-size: "10m" nginx.ingress.kubernetes.io/proxy-read-timeout: "60"

Path rewrite example for ingress-nginx#

Path rewrite example for ingress-nginx apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: api-rewrite annotations: nginx.ingress.kubernetes.io/rewrite-target: /$2 spec: ingressClassName: nginx rules: - host: app.example.com http: paths: - path: /api(/|$)(.*) pathType: ImplementationSpecific backend: service: name: api-service port: number: 8080 A request to /api/users can be forwarded to the backend as /users. Test rewrites carefully because a wrong expression can cause redirects, broken assets or unexpected backend paths. Default backend A default backend handles requests that do not match any rule. Some controllers provide their own default 404 backend. You can also define one explicitly: spec: ingressClassName: nginx defaultBackend: service: name: default-web port: number: 80 Ingress versus Service type LoadBalancer Feature | Ingress | LoadBalancer Service Typical protocol | HTTP and HTTPS | TCP, UDP or HTTP depending on implementation Routing | Host and path based | Usually one Service per external address TLS | Centralized termination is common | Handled by application or external load balancer configuration Best suited for | Multiple web apps and APIs | Non-HTTP services or dedicated public exposure Ingress and the Kubernetes Gateway API Ingress remains widely used, but its API intentionally supports a limited feature set. The Kubernetes Gateway API provides more expressive, role-oriented resources such as GatewayClass, Gateway and HTTPRoute. Consider Gateway API when you need advanced traffic policies, clearer infrastructure/application ownership or broader protocol support—and confirm that your chosen controller supports it. Useful kubectl commands kubectl get ingress -A kubectl get ingressclass kubectl describe ingress web-ingress kubectl get svc,endpoints,endpointslices kubectl get secret app-tls kubectl get events --sort-by=.metadata.creationTimestamp kubectl logs -n ingress-nginx deployment/ingress-nginx-controller kubectl get svc -n ingress-nginx How to test before DNS is ready Send the expected Host header directly to the ingress address: curl -i -H 'Host: app.example.com' INGRESS_IP/ curl -kI --resolve app.example.com:443:INGRESS_IP \ app.example.com/ This helps separate DNS problems from routing, TLS or backend problems. Troubleshooting workflow 1. Confirm the controller: Verify its Pods are Running and Ready. 2. Check the controller Service: Confirm it has a reachable external IP or node address. 3. Inspect the Ingress: Verify class, host, path, backend Service and events. 4. Check the Service: Confirm the port and selector are correct. 5. Check endpoints: Empty EndpointSlices usually mean the Service has no healthy matching Pods. 6. Test with a Host header: Bypass DNS and call the ingress address directly. 7. Review controller logs: Look for rejected configuration, missing Secrets and upstream errors. 8. Verify DNS and TLS last: Confirm records, certificate hostnames and Secret contents.

Common errors and likely causes#

Common errors and likely causes Symptom | Likely cause | What to check 404 from controller | Host or path did not match | Request Host header, rule host, path and pathType. 502 or 503 | Backend unavailable | Service port, EndpointSlices, Pod readiness and controller logs. Ingress has no address | Controller or external load balancer is not configured | IngressClass, controller Pods and controller Service. TLS certificate warning | Wrong Secret, hostname mismatch or default certificate | TLS hosts, Secret namespace and certificate SANs. Redirect loop | Conflicting proxy headers or HTTPS redirects | Controller annotations, application proxy settings and load balancer TLS mode. Application assets fail | Incorrect path rewrite or base URL | Rewrite annotation and application path configuration. Security best practices • Use HTTPS and automate certificate renewal. • Restrict which namespaces or teams may create public Ingress resources. • Review controller-specific annotations because some can inject powerful proxy configuration. • Keep the ingress controller patched and run multiple replicas in production. • Use NetworkPolicies so only expected traffic can reach backend workloads. • Apply rate limiting, request-size limits and authentication where appropriate. • Do not expose controller metrics or administrative endpoints publicly. • Log requests carefully without leaking credentials, tokens or personal information. Production checklist • Controller installed, healthy and highly available • Correct IngressClass selected • DNS points to the ingress controller address • Backend Services have healthy endpoints • TLS certificate covers every configured hostname • Timeout and request-size settings match application needs • Monitoring and access logs are enabled • Configuration is stored in Git and reviewed • Fallback and rollback procedures are documented Hands-on lab kubectl create namespace ingress-lab kubectl create deployment web --image=nginx:1.27 -n ingress-lab kubectl expose deployment web --port=80 -n ingress-lab kubectl apply -f ingress.yaml kubectl get ingress -n ingress-lab kubectl describe ingress web-ingress -n ingress-lab kubectl get endpointslices -n ingress-lab curl -H 'Host: app.example.com' INGRESS_IP/

Frequently asked questions#

Frequently asked questions Question: Does Ingress send traffic directly to Pods? Ingress rules normally point to Kubernetes Services. The Service then selects and load-balances across healthy Pod endpoints. Question: Can Ingress expose TCP or UDP services? The standard Ingress API is designed for HTTP and HTTPS. Some controllers support TCP or UDP through controller-specific configuration. A LoadBalancer Service or Gateway API may be clearer for those protocols. Question: Why does my Ingress show an IP but still return 404? The controller is reachable, but the requested Host or path probably does not match a rule. Test with the correct Host header and inspect the configured paths. Question: Should I use one Ingress or many? Either can work. Separate Ingress objects often improve team ownership and deployment independence, while the controller can merge their rules into the same external entry point. Question: Is Ingress being replaced? Ingress is stable and widely supported. Gateway API is the newer option for richer and more structured traffic-management requirements. Related Melochip guides • Kubernetes Learning Path — melochip.com/posts/kubernetes-learning-path • Kubernetes Services Explained — melochip.com/posts/kubernetes-services-clusterip-nodeport-loadbalancer • Kubernetes Deployments and ReplicaSets — melochip.com/posts/kubernetes-deployments-replicasets-explained • Kubernetes Troubleshooting Guide — melochip.com/posts/kubernetes-troubleshooting-guide • Kubernetes Security Best Practices — melochip.com/posts/kubernetes-security-best-practices Official references • Kubernetes Ingress documentation — kubernetes.io/docs/concepts/services-networking/ingress/ • Ingress controllers — kubernetes.io/docs/concepts/services-networking/ingress-controllers/ • Kubernetes Gateway API — gateway-api.sigs.k8s.io/