Ingress path and host routing — the cluster URL space

Ingress path and host routing defines the cluster URL space. The path types are Prefix, Exact, and ImplementationSpecific. The host-based routing uses the host field. This lesson walks the routing, the path types, and the operational discipline.

The host-based routing

The Ingress can route based on the host:

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

The Ingress routes based on the Host header. The controller uses the host to match the rule.

flowchart LR
    A[External client] -->|Host: billing.example.com| B[Ingress controller]
    A -->|Host: auth.example.com| B
    B -->|billing.example.com| C[Service billing]
    B -->|auth.example.com| D[Service auth]

The host-based routing is the basis of multi-tenant clusters.

The path types

The Ingress supports three path types:

• Prefix: matches the URL path prefix. The path /api matches /api, /api/v1, /api/v1/users.
• Exact: matches the exact URL path. The path /api/v1 matches only /api/v1.
• ImplementationSpecific: the path type is implementation-specific. The path type depends on the controller.

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

The path types are the operator’s contract with the controller.

The rewrite rules

The Ingress controller can rewrite the URL before forwarding:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: rewrite
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  rules:
    - host: example.com
      http:
        paths:
          - path: /api/v1
            pathType: Prefix
            backend:
              service:
                name: api
                port:
                  number: 80

The rewrite rule transforms /api/v1/users to /users before forwarding to the backend. The rewrite rule is controller-specific.

The default backend

The Ingress can have a default backend:

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

The default backend handles requests that do not match any rule. The default backend is the cluster’s fallback.

The failure modes

The Ingress routing’s failure modes:

• Path mismatch: the path type is wrong. The fix is to verify the path type.
• Host mismatch: the host is wrong. The fix is to verify the host.
• Rewrite error: the rewrite rule is wrong. The fix is to verify the rewrite rule.
• Default backend missing: the default backend is not configured. The fix is to set the default.
• Backend not ready: the backend Service has no Pods. The fix is to verify the backend.

The operational discipline

The Ingress routing’s operational discipline:

• Document the routing. The routing is the cluster’s URL space.
• Audit the routing at every change. The routing is critical configuration.
• Test the routing in staging. The routing must work for the workload.
• Monitor the routing’s metrics. The metrics are the leading indicator.
• Plan the routing’s evolution. The routing can be replaced with Gateway API.
• Document the troubleshooting. The troubleshooting is the cluster’s operational reference.

Quiz

Production discipline

• The Ingress routing is the cluster’s URL space. The cluster operator must treat it as critical configuration.
• Document the routing. The routing is the cluster’s URL space.
• Audit the routing at every change. The routing is critical configuration.
• Test the routing in staging. The routing must work for the workload.
• Monitor the routing’s metrics. The metrics are the leading indicator.
• Plan the routing’s evolution. The routing can be replaced with Gateway API.
• Document the troubleshooting. The troubleshooting is the cluster’s operational reference.
• Train the operations team on the routing diagnostics. The diagnostics are the team’s tools.
• Use a CI check for the routing. The CI check can catch the routing error at every change.