Configuration reference

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.

Default ingress class

By default, the Helm chart adds --ingress.class=haproxy to the ingress controller. That means that it will use Ingress resources only if they specify ingressClassName: haproxy. You can disable this by setting --set controller.ingressClass=null when calling helm install.

This change was introduced in version 1.6.

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:

bash
helm install haproxy-kubernetes-ingress haproxytech/kubernetes-ingress \
--create-namespace \
--namespace haproxy-controller \
--set controller.ingressClass=haproxy
bash
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.

If this page was useful, please, Leave the feedback.