Installation

Install on premises

On this page

This guide shows you how to install HAProxy Kubernetes Ingress Controller into an on-premises Kubernetes cluster. You can install either with Helm or kubectl.

Pre-installation checklist Jump to heading

  • A running Kubernetes cluster
  • The helm command-line tool
  • The kubectl command-line tool

Choose one of the following installation methods:

Install with Helm Jump to heading

Helm values file

The following examples use --set invocations to configure the ingress controller. When installing with Helm, you can instead use a Helm values file to provide your configuration values. Using a Helm values file can provide for better traceability of configuration changes and reduce the complexity of Helm installation commands.

You can install with Helm using either the HTTPS or OCI repository:

  1. Add the HAProxy Technologies Helm repository:

    nix
    helm repo add haproxytech https://haproxytech.github.io/helm-charts
    nix
    helm repo add haproxytech https://haproxytech.github.io/helm-charts

  2. Update your list of Helm charts:

    nix
    helm repo update
    nix
    helm repo update

  3. Install the latest version of the ingress controller:

    nix
    helm install haproxy-kubernetes-ingress haproxytech/kubernetes-ingress \
      --create-namespace \
      --namespace haproxy-controller
    nix
    helm install haproxy-kubernetes-ingress haproxytech/kubernetes-ingress \
      --create-namespace \
      --namespace haproxy-controller

  1. Install the latest version of the ingress controller:

    nix
    helm install haproxy-kubernetes-ingress oci://ghcr.io/haproxytech/helm-charts/kubernetes-ingress \
      --create-namespace \
      --namespace haproxy-controller
    nix
    helm install haproxy-kubernetes-ingress oci://ghcr.io/haproxytech/helm-charts/kubernetes-ingress \
      --create-namespace \
      --namespace haproxy-controller

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.

Install a Specific Version Jump to heading

You can choose which version of the Helm chart to use, and you can choose which version of the Docker image to use.

Install a specific version of the Helm chart Jump to heading

You can choose which version of the Helm chart to use.

Caution

Note that this sets the version of the Helm chart, not the version of the haproxytech/kubernetes-ingress Docker image. To set the version of the Docker image, see install a specific version of the Docker image.

  1. Add the HAProxy Technologies Helm repository:

    nix
    helm repo add haproxytech https://haproxytech.github.io/helm-charts
    nix
    helm repo add haproxytech https://haproxytech.github.io/helm-charts

  2. Update your list of charts:

    nix
    helm repo update
    nix
    helm repo update

  3. To see available versions, use helm search repo with the --versions flag to list all of the available versions of the Helm chart:

    nix
    helm search repo --versions
    nix
    helm search repo --versions
    output
    text
    NAME                          	CHART VERSION	APP VERSION	DESCRIPTION                                             
    haproxytech/kubernetes-ingress	1.44.0       	3.1.0-rc1  	A Helm chart for HAProxy Kubernetes Ingress Con...
    haproxytech/kubernetes-ingress	1.43.0       	3.1.0-rc1  	A Helm chart for HAProxy Kubernetes Ingress Con...
    haproxytech/kubernetes-ingress	1.42.0       	3.0.4      	A Helm chart for HAProxy Kubernetes Ingress Con...
    haproxytech/kubernetes-ingress	1.41.0       	3.0.1      	A Helm chart for HAProxy Kubernetes Ingress Con...
    haproxytech/kubernetes-ingress	1.40.1       	3.0.1      	A Helm chart for HAProxy Kubernetes Ingress Con...
    haproxytech/kubernetes-ingress	1.40.0       	3.0.0      	A Helm chart for HAProxy Kubernetes Ingress Con...
    output
    text
    NAME                          	CHART VERSION	APP VERSION	DESCRIPTION                                             
    haproxytech/kubernetes-ingress	1.44.0       	3.1.0-rc1  	A Helm chart for HAProxy Kubernetes Ingress Con...
    haproxytech/kubernetes-ingress	1.43.0       	3.1.0-rc1  	A Helm chart for HAProxy Kubernetes Ingress Con...
    haproxytech/kubernetes-ingress	1.42.0       	3.0.4      	A Helm chart for HAProxy Kubernetes Ingress Con...
    haproxytech/kubernetes-ingress	1.41.0       	3.0.1      	A Helm chart for HAProxy Kubernetes Ingress Con...
    haproxytech/kubernetes-ingress	1.40.1       	3.0.1      	A Helm chart for HAProxy Kubernetes Ingress Con...
    haproxytech/kubernetes-ingress	1.40.0       	3.0.0      	A Helm chart for HAProxy Kubernetes Ingress Con...

  4. Specify the --version on the helm install command. To install the ingress controller using version 1.42.0 of the Helm chart, for example:

    nix
    helm install haproxy-kubernetes-ingress haproxytech/kubernetes-ingress \
      --version 1.42.0 \
      --create-namespace \
      --namespace haproxy-controller
    nix
    helm install haproxy-kubernetes-ingress haproxytech/kubernetes-ingress \
      --version 1.42.0 \
      --create-namespace \
      --namespace haproxy-controller

  1. Specify the --version on the helm install command. To install the ingress controller using version 1.42.0 of the Helm chart, for example:

    nix
    helm install haproxy-kubernetes-ingress oci://ghcr.io/haproxytech/helm-charts/kubernetes-ingress \
      --version 1.42.0 \
      --create-namespace \
      --namespace haproxy-controller
    nix
    helm install haproxy-kubernetes-ingress oci://ghcr.io/haproxytech/helm-charts/kubernetes-ingress \
      --version 1.42.0 \
      --create-namespace \
      --namespace haproxy-controller

Install a specific version of the Docker image Jump to heading

  1. See haproxytech/kubernetes-ingress tags for a list of available Docker image tags for the haproxytech/kubernetes-ingress image.

  2. Then, use a specific tag when you call helm install. For example, for the tag version 3.0:

    nix
    helm install haproxy-kubernetes-ingress haproxytech/kubernetes-ingress \
      --create-namespace \
      --namespace haproxy-controller \
      --set controller.image.tag=3.0
    nix
    helm install haproxy-kubernetes-ingress haproxytech/kubernetes-ingress \
      --create-namespace \
      --namespace haproxy-controller \
      --set controller.image.tag=3.0
    nix
    helm install haproxy-kubernetes-ingress oci://ghcr.io/haproxytech/helm-charts/kubernetes-ingress \
      --create-namespace \
      --namespace haproxy-controller \
      --set controller.image.tag=3.0
    nix
    helm install haproxy-kubernetes-ingress oci://ghcr.io/haproxytech/helm-charts/kubernetes-ingress \
      --create-namespace \
      --namespace haproxy-controller \
      --set controller.image.tag=3.0

Install with preset NodePort values Jump to heading

By default, the ingress controller creates a Kubernetes service that assigns random NodePort ports. You can see this by calling kubectl get service kubernetes-service. In the example below, the ingress controller listens on port 30706 for HTTP traffic and 30675 for HTTPS traffic. Port 31441 publishes the HAProxy Stats page.

nix
kubectl get service haproxy-kubernetes-ingress --namespace haproxy-controller
nix
kubectl get service haproxy-kubernetes-ingress --namespace haproxy-controller
output
text
NAME                         TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)                                     AGE
haproxy-kubernetes-ingress   NodePort    10.97.154.7      <none>        80:30706/TCP,443:30675/TCP,1024:31441/TCP   32s
output
text
NAME                         TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)                                     AGE
haproxy-kubernetes-ingress   NodePort    10.97.154.7      <none>        80:30706/TCP,443:30675/TCP,1024:31441/TCP   32s

You can choose specific NodePort ports instead by setting the controller.service.nodePort.http, controller.service.nodePort.https, and controller.service.nodePort.stat Helm chart fields.

nix
helm install haproxy-kubernetes-ingress haproxytech/kubernetes-ingress \
  --create-namespace \
  --namespace haproxy-controller \
  --set controller.service.nodePorts.http=30000 \
  --set controller.service.nodePorts.https=30001 \
  --set controller.service.nodePorts.stat=30002 \
  --set controller.service.nodePorts.prometheus=30003
nix
helm install haproxy-kubernetes-ingress haproxytech/kubernetes-ingress \
  --create-namespace \
  --namespace haproxy-controller \
  --set controller.service.nodePorts.http=30000 \
  --set controller.service.nodePorts.https=30001 \
  --set controller.service.nodePorts.stat=30002 \
  --set controller.service.nodePorts.prometheus=30003
nix
helm install haproxy-kubernetes-ingress oci://ghcr.io/haproxytech/helm-charts/kubernetes-ingress \
  --create-namespace \
  --namespace haproxy-controller \
  --set controller.service.nodePorts.http=30000 \
  --set controller.service.nodePorts.https=30001 \
  --set controller.service.nodePorts.stat=30002 \
  --set controller.service.nodePorts.prometheus=30003
nix
helm install haproxy-kubernetes-ingress oci://ghcr.io/haproxytech/helm-charts/kubernetes-ingress \
  --create-namespace \
  --namespace haproxy-controller \
  --set controller.service.nodePorts.http=30000 \
  --set controller.service.nodePorts.https=30001 \
  --set controller.service.nodePorts.stat=30002 \
  --set controller.service.nodePorts.prometheus=30003

Run the ingress controller as a DaemonSet Jump to heading

By default, the ingress controller is installed using a Deployment resource. To use a DaemonSet instead, set the controller.kind field to DaemonSet and controller.daemonset.useHostPort to true.

nix
helm install haproxy-kubernetes-ingress haproxytech/kubernetes-ingress \
  --create-namespace \
  --namespace haproxy-controller \
  --set controller.kind=DaemonSet \
  --set controller.daemonset.useHostPort=true
nix
helm install haproxy-kubernetes-ingress haproxytech/kubernetes-ingress \
  --create-namespace \
  --namespace haproxy-controller \
  --set controller.kind=DaemonSet \
  --set controller.daemonset.useHostPort=true
nix
helm install haproxy-kubernetes-ingress oci://ghcr.io/haproxytech/helm-charts/kubernetes-ingress \
  --create-namespace \
  --namespace haproxy-controller \
  --set controller.kind=DaemonSet \
  --set controller.daemonset.useHostPort=true
nix
helm install haproxy-kubernetes-ingress oci://ghcr.io/haproxytech/helm-charts/kubernetes-ingress \
  --create-namespace \
  --namespace haproxy-controller \
  --set controller.kind=DaemonSet \
  --set controller.daemonset.useHostPort=true

Install with kubectl Jump to heading

If you prefer to install without Helm, then you can install the Deployment YAML file directly.

  1. Download the latest source code from the HAProxy Kubernetes Ingress Controller GitHub page.

  2. Use the kubectl apply command to deploy the controller:

    nix
    kubectl apply -f deploy/haproxy-ingress.yaml
    nix
    kubectl apply -f deploy/haproxy-ingress.yaml

    You can also download the YAML file and modify it for your needs before you apply it (such as changing the namespace in which the controller runs and/or its exposed ports).

Check your installation Jump to heading

Verify that the controller is installed into your Kubernetes cluster by using the command kubectl get pods:

nix
kubectl get pods --namespace haproxy-controller
nix
kubectl get pods --namespace haproxy-controller
output
text
NAME                                       READY   STATUS    RESTARTS   AGE
haproxy-kubernetes-ingress-7dd4cc4b-x5fkv  1/1     Running   0          1m
output
text
NAME                                       READY   STATUS    RESTARTS   AGE
haproxy-kubernetes-ingress-7dd4cc4b-x5fkv  1/1     Running   0          1m

Call kubectl get svc to see which ports were mapped. In this example, port 32063 forwards to port 80 on the ingress controller.

nix
kubectl get svc --namespace haproxy-controller
nix
kubectl get svc --namespace haproxy-controller
output
text
NAME                         TYPE       CLUSTER-IP       EXTERNAL-IP   PORT(S)                                     AGE
haproxy-kubernetes-ingress   NodePort   10.104.173.167   <none>        80:30264/TCP,443:31575/TCP,1024:31785/TCP   155m
output
text
NAME                         TYPE       CLUSTER-IP       EXTERNAL-IP   PORT(S)                                     AGE
haproxy-kubernetes-ingress   NodePort   10.104.173.167   <none>        80:30264/TCP,443:31575/TCP,1024:31785/TCP   155m

Do you have any suggestions on how we can improve the content of this page?

Previous page Install on Google GKE Next page Install on Rancher
© 2025 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences