Ingress fundamentals — the cluster HTTP gateway

Ingress is the cluster HTTP gateway. The Ingress resource defines the routing rules; the Ingress controller implements the rules. The controller is a load balancer that fronts multiple Services. This lesson walks the Ingress, the architecture, and the operational discipline.

What Ingress is

Ingress is a Kubernetes API object that defines HTTP routing rules. The rules are implemented by the Ingress controller:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: billing
spec:
  rules:
    - host: billing.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: billing
                port:
                  number: 80

The Ingress routes HTTP traffic to the backend Service based on the host and the path. The Ingress controller implements the rules.

flowchart LR
    A[External client] -->|HTTPS| B[LoadBalancer]
    B -->|HTTPS| C[Ingress controller]
    C -->|host: billing.example.com| D[Service: billing]
    D -->|kube-proxy| E[Pod]
    C -->|host: auth.example.com| F[Service: auth]
    F -->|kube-proxy| G[Pod]

The Ingress controller is the cluster’s HTTP gateway. The controller can serve multiple Services on a single IP.

The Ingress controller

The Ingress controller is a Deployment that implements the Ingress rules. The standard controllers are:

• ingress-nginx: the de-facto standard.
• Traefik: the cloud-native controller.
• HAProxy: the high-performance controller.
• Contour: the Envoy-based controller.
• GKE Ingress: the GKE-managed controller.

The cluster operator must choose a controller and install it. The controller is the implementation of the Ingress.

The IngressClass

The IngressClass is the resource that ties an Ingress to a controller:

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: nginx
spec:
  controller: k8s.io/ingress-nginx

The IngressClass is referenced by the Ingress:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: billing
spec:
  ingressClassName: nginx
  rules:
    - host: billing.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: billing
                port:
                  number: 80

The cluster operator can have multiple IngressClasses for different controllers. The cluster’s default IngressClass is set in the cluster’s configuration.

The traffic flow

The traffic flow for an Ingress:

sequenceDiagram
    autonumber
    participant EC as External client
    participant LB as LoadBalancer
    participant IC as Ingress controller
    participant S as Service
    participant P as Pod
    EC->>LB: HTTPS billing.example.com
    LB->>IC: forward
    IC->>IC: terminate TLS
    IC->>IC: route based on host/path
    IC->>S: forward to backend Service
    S->>P: kube-proxy -> Pod
    P->>P: handle request
    P->>S: response
    S->>IC: response
    IC->>LB: response
    LB->>EC: response

The Ingress controller terminates TLS, routes based on host and path, and forwards to the backend Service.

The TLS termination

The Ingress can terminate TLS:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: billing
spec:
  tls:
    - hosts:
        - billing.example.com
      secretName: billing-tls
  rules:
    - host: billing.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: billing
                port:
                  number: 80

The TLS secret holds the certificate and the key. The Ingress controller reads the secret and terminates TLS.

The failure modes

The Ingress’s failure modes:

• Controller down: the Ingress controller is unavailable. The fix is to restart the controller.
• Backend Service down: the backend Service has no Pods. The fix is to verify the backend.
• TLS error: the TLS certificate is invalid. The fix is to update the certificate.
• Routing error: the Ingress routes to the wrong backend. The fix is to verify the rules.
• Default backend missing: the Ingress has no default backend. The fix is to set the default backend.

The operational discipline

The Ingress’s operational discipline:

• Document the Ingress controller. The controller is the cluster’s HTTP gateway.
• Monitor the controller’s metrics. The metrics are the leading indicator.
• Test the Ingress in staging. The Ingress must work for the workload.
• Plan the Ingress’s evolution. The Ingress can be replaced with Gateway API.
• Document the troubleshooting. The troubleshooting is the cluster’s operational reference.

Quiz

Production discipline

• The Ingress controller is the cluster’s HTTP gateway. The cluster operator must treat it as critical infrastructure.
• Document the controller. The controller is the cluster’s HTTP gateway.
• Monitor the controller’s metrics. The metrics are the leading indicator.
• Test the Ingress in staging. The Ingress must work for the workload.
• Plan the Ingress’s evolution. The Ingress can be replaced with Gateway API.
• Document the troubleshooting. The troubleshooting is the cluster’s operational reference.
• Train the operations team on the controller’s diagnostics. The diagnostics are the team’s tools.
• Plan the Ingress’s evolution. The Ingress is the cluster’s HTTP gateway; the operator must plan for the future.