IngressClass

An Ingress resource can target a specific ingress controller instance, which is useful when running multiple ingress controllers in the same cluster. To target a specific ingress controller, you must first install that ingress controller with a unique class name.

Configure the controller’s class name Jump to heading #

There are two ways to assign a class name to an ingress controller:

• define an IngressClass resource
• set the --ingress.class argument

The IngressClass resource is available in Kubernetes 1.18+ and is the official method.

Define an IngressClass resource Jump to heading #

Create an IngressClass resource with its spec.controller field set to the name of the ingress controller you want to use:

ingress-class.yml
yaml
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: haproxy
spec:
  controller: haproxy.org/ingress-controller

ingress-class.yml
yaml
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: haproxy
spec:
  controller: haproxy.org/ingress-controller

Set the --ingress.class argument Jump to heading #

You can set the class name via the --ingress.class argument during installation:

nix
helm install haproxy-kubernetes-ingress haproxytech/kubernetes-ingress \
  --create-namespace \
  --namespace haproxy-controller \
  --set controller.ingressClass=haproxy

nix
helm install haproxy-kubernetes-ingress haproxytech/kubernetes-ingress \
  --create-namespace \
  --namespace haproxy-controller \
  --set controller.ingressClass=haproxy

Set IngressClassName Jump to heading #

To target an ingress controller from within an Ingress resource, add an IngressClassName field:

yaml
kind: Ingress
apiVersion: networking.k8s.io/v1
metadata:
  name: test
spec:
  ingressClassName: haproxy
  rules:
    - host: test.k8s.local
      http:
        paths:
          - path: /
            backend:
              serviceName: http-echo
              servicePort: http

yaml
kind: Ingress
apiVersion: networking.k8s.io/v1
metadata:
  name: test
spec:
  ingressClassName: haproxy
  rules:
    - host: test.k8s.local
      http:
        paths:
          - path: /
            backend:
              serviceName: http-echo
              servicePort: http

Set ingress.class Jump to heading #

The ingress.class annotation is the legacy way to target an Ingress Controller. For example, consider the following Ingress object in which we use ingress.class to target the haproxy ingress controller:

yaml
kind: Ingress
apiVersion: networking.k8s.io/v1
metadata:
  name: test
  annotations:
    ingress.class: haproxy
spec:
  rules:
    - host: test.k8s.local
      http:
        paths:
          - path: /
            backend:
              serviceName: http-echo
              servicePort: http

yaml
kind: Ingress
apiVersion: networking.k8s.io/v1
metadata:
  name: test
  annotations:
    ingress.class: haproxy
spec:
  rules:
    - host: test.k8s.local
      http:
        paths:
          - path: /
            backend:
              serviceName: http-echo
              servicePort: http

Eligibility rules Jump to heading #

• If the --ingress.class argument of the controller is not configured:
  • Accept Ingress resource when neither ingress.class annotation nor ingressClassName fields are set.
  • Accept Ingress resource when ingress.class annotation is not set but ingressClassName field matches.
• If the --ingress.class argument of the controller is configured:
  • Accept Ingress resource when neither ingress.class annotation nor ingressClassName fields are set but controller argument --EmptyIngressClass is enabled.
  • Accept Ingress resource when –ingress.class argument is equal to ingress.class annotation.
  • Accept Ingress resource when ingressClassName field matches.
• Ignore Ingress resource otherwise.