IngressClass and defaults — managing multiple controllers

The IngressClass is the resource that ties an Ingress to a controller. The cluster can have multiple IngressClasses for different controllers. This lesson walks the IngressClass, the defaults, and the operational discipline.

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 controller field is the controller’s identifier. The name field is the IngressClass’s name.

The Ingress references the IngressClass:

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 ingressClassName field is the IngressClass’s name. The controller watches Ingresses with its IngressClass.

The default IngressClass

The cluster can have a default IngressClass:

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: nginx
  annotations:
    ingressclass.kubernetes.io/is-default-class: "true"
spec:
  controller: k8s.io/ingress-nginx

The annotation marks the IngressClass as the default. An Ingress without an ingressClassName field is assigned to the default IngressClass.

flowchart LR
    A[Ingress without ingressClassName] --> B[Default IngressClass nginx]
    B --> C[nginx controller]
    D[Ingress with ingressClassName: traefik] --> E[traefik controller]

The default IngressClass is the cluster’s “implicit” controller. The cluster operator can set the default via the annotation.

Multiple controllers

The cluster can have multiple IngressClasses for different controllers:

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

The Ingresses choose the controller:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: billing
spec:
  ingressClassName: nginx
  rules:
    ...
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: auth
spec:
  ingressClassName: traefik
  rules:
    ...

The use cases:

• Migration: the new controller is added while the old controller is still running.
• Workload separation: some workloads use the nginx controller; others use the Traefik controller.
• Multi-tenancy: different teams use different controllers.

The failure modes

The IngressClass’s failure modes:

• Default missing: no IngressClass is marked as default. The Ingress without ingressClassName has no controller. The fix is to set the default.
• Multiple defaults: two IngressClasses are marked as default. The admission controller rejects the second one. The fix is to keep only one default.
• Controller missing: the IngressClass’s controller is not installed. The Ingress is not served. The fix is to install the controller.
• Wrong controller: the Ingress is routed to the wrong controller. The fix is to verify the ingressClassName.

The operational discipline

The IngressClass’s operational discipline:

• Document the IngressClasses. The IngressClass is the cluster’s HTTP gateway configuration.
• Set the default carefully. The default is the cluster’s implicit controller.
• Audit the IngressClasses at every change. The IngressClass is critical configuration.
• Test the IngressClasses in staging. The IngressClasses must work for the workload.
• Plan the IngressClass’s evolution. The IngressClass can be replaced with Gateway API.
• Document the troubleshooting. The troubleshooting is the cluster’s operational reference.

Quiz

Production discipline

• The IngressClass is the cluster’s HTTP gateway configuration. The cluster operator must treat it as critical configuration.
• Document the IngressClasses. The IngressClass is the cluster’s HTTP gateway configuration.
• Set the default carefully. The default is the cluster’s implicit controller.
• Audit the IngressClasses at every change. The IngressClass is critical configuration.
• Test the IngressClasses in staging. The IngressClasses must work for the workload.
• Plan the IngressClass’s evolution. The IngressClass can be replaced with Gateway API.
• Document the troubleshooting. The troubleshooting is the cluster’s operational reference.
• Train the operations team on the IngressClass diagnostics. The diagnostics are the team’s tools.
• Use a CI check for the IngressClass. The CI check can catch the missing IngressClass at every change.