The HAProxy Kubernetes Ingress Controller is available on Rancher, an open-source multi-cluster orchestration platform. This section shows you how to install the HAProxy Kubernetes Ingress Controller on Rancher.

Add a TLS certificate

You'll need to configure a TLS certificate in Rancher if you plan to use HTTPS. You can add TLS certificates to your Kubernetes cluster by storing them in a special type of resource called a TLS Secret. Rancher provides a convenient way to add these using its Certificates management window.

  1. Locate your PEM-formatted certificate and private key files to import them into Rancher.

  2. Choose a project within one of your clusters, such as the Default project.

  3. Go to Resources > Secrets > Certificates.

  4. Click Add Certificate.

  5. In this this window, give the certificate a name.

  6. Paste the values for the public certificate and private key into the corresponding boxes.

  7. Click Save.

    [Adding a certificate]

Launch the ingress controller

The HAProxy Kubernetes Ingress Controller is available as a Rancher Catalog app.

  1. From either the 'Global' or 'Project' scope, go to Apps and click Launch.

  2. Select the haproxy listing:

    [Rancher HAProxy app]
  3. On the app's Configuration Options screen, configure HAProxy using the options described in the table below.


    Some options appear only when you launch the application in either the 'Global' or 'Project' scope.

  4. After you configure your options, click Launch, and wait for the application to finish installing.

Configuration options





The name that appears under Apps, e.g. haproxy-ingress

Template Version

The version of the HAProxy Helm chart to deploy

Namespace (Project scope only)

The namespace where to deploy the application


Target Projects (Global scope only)

The projects within your cluster(s) where you intend to use the Ingress, e.g. Default

Helm Wait

Whether to wait for resources to become ready before marking the application as active


Helm Timeout

Seconds to wait for the Kubernetes commands to complete


Upgrade Strategy (Global Scope only)

When a new version of the HAProxy Ingress Controller becomes available, whether to update all instances at once or to use a rolling update.

Upgrade all apps simultaneously

Available Roles

Select either Project or Cluster scope, depending on whether you want the Ingress Controller to manage resources in the target projects only or across the entire cluster. You must choose 'Cluster'


Use Default Image

Whether to use the latest tag for the HAProxy Ingress Controller Docker image or to specify a different tag


Deployment Type

How you want the Ingress Controller to deploy, either Deployment or DaemonSet


Service Type

How to expose ports on the Ingress Controller, either L4 Balancer or NodePort. Use L4 Balancer when your cluster is hosted on a compatible cloud provider


Ingress Class

A name that uniquely identifies this ingress controller, so that Ingress objects may target it by its class name. If you plan to keep the default Ingress Controller enabled in Rancher, we recommended that you set a value here so that you can target either the default controller or the HAProxy Ingress controller on a case-by-case basis.

TLS Certificate Secret

The name of a TLS secret that contains a private key and public certificate to use for TLS encryption. If not set, a self-signed certificate generates automatically. You must add the certificate to Rancher first, and then specify the name you used here. You must prefix the name with the namespace, such as default/my-cert


Whether to use the HAProxy Enterprise Ingress Controller



The registry for HAProxy Enterprise Docker images



The Docker repository for the HAProxy Enterprise Ingress Controller



Your HAProxy Enterprise username. This is your HAProxy Enterprise license key


Your HAProxy Enterprise password. This is your HAProxy Enterprise license key

Optional: Disable the default NGINX ingress controller

When you launch the HAProxy Kubernetes Ingress Controller into your Rancher cluster, it watches for Ingress objects and creates routes for ingress traffic.

However, the default NGINX Ingress Controller is also running and doing the same job. You can disable this default ingress controller as follows:

  1. Select your cluster to display the cluster dashboard.

  2. Click the options icon () in the upper right corner, then choose Edit.

  3. Under Advanced Options, set Nginx Ingress to Disabled. Click Save.

Add an Ingress to publish a workload

After you deploy a container workload, you add an Ingress as follows:

  1. Under your project, go to Resources > Workloads, and select the Load Balancing tab.

  2. Click Add Ingress.

  3. Set a name for your Ingress and its target namespace.

  4. Under Rules, specify the following:

    • the workload you want to target

    • the port it listens on

    • optionally, a path for the client to use to access your application

    [Set the path]
  5. If you set an Ingress Class on the HAProxy Kubernetes Ingress Controller, you can specify it here. This is the case if you are running multiple ingress controllers, such as the default NGINX ingress controller and the HAProxy Ingress Controller, and you want to target one by name.

    • Under Labels & Annotations, click Add Annotation.

    • Set Key to haproxy.org/ingress.class.

    • Set Value to the value you set for Ingress Class when launching the HAProxy app.

      [Set the class]
  6. Click Save.

  7. By default, the controller listens on a NodePort. From the Apps window, you can see the assigned NodePort.