Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Failed to load latest commit information.

HAProxy Ingress controller

Ingress controller implementation for HAProxy loadbalancer.

build helm

HAProxy Ingress is a Kubernetes ingress controller: it configures a HAProxy instance to route incoming requests from an external network to the in-cluster applications. The routing configurations are built reading specs from the Kubernetes cluster. Updates made to the cluster are applied on the fly to the HAProxy instance.

Use HAProxy Ingress


Supported versions:

HAProxy Ingress Embedded
HAProxy (*)
v0.15 (snapshot) 2.6 1.19+ 2.2+
v0.14 (latest) 2.4 1.19+ 2.2+
v0.13 2.3 up to v0.13.10
2.4 on v0.13.11+
1.19+ 2.2+
v0.12 2.2 1.18 - 1.21 2.0+
v0.10 2.0 1.8 - 1.21 -
  • Beta quality versions (beta / canary tags) has some new, but battle tested features, usually running on some of our production clusters
  • Development versions (alpha / snapshot tags) has major changes with few tests, usually not recommended for production
  • (*) Minimum supported HAProxy version if using an external HAProxy instance


Develop HAProxy Ingress

The instructions below are valid for v0.14 and newer. See v0.13 branch for older versions.

Building and running locally:

mkdir -p $GOPATH/src/
cd $GOPATH/src/
git clone
cd haproxy-ingress
make run

Dependencies to run locally:

  • Golang
  • HAProxy compiled with USE_OPENSSL=1 and USE_LUA=1
  • golangci-lint is used when running make lint or make test targets
  • Lua with lua-json (luarocks install lua-json) if using Auth External or OAuth
  • Kubernetes network should be reachable from the local machine for a proper e2e test

Building container image:

Fast build - cross compile for linux/amd64 (locally) and generate localhost/haproxy-ingress:latest:

make image

Official image - build in a multi-stage Dockerfile and generate localhost/haproxy-ingress:latest:

make docker-build

Deploy local image using Helm:

helm repo add haproxy-ingress
helm install haproxy-ingress haproxy-ingress/haproxy-ingress\
  --create-namespace --namespace=ingress-controller\
  --set controller.image.repository=localhost/haproxy-ingress\
  --set controller.image.tag=latest\
  --set controller.image.pullPolicy=Never

make options:

The following make variables are supported:

  • CONTROLLER_TAG (defaults to localhost/haproxy-ingress:latest): tag name for make image and make docker-build.
  • LOCAL_FS_PREFIX (defaults to /tmp/haproxy-ingress): temporary directory for make run.
  • KUBECONFIG (defaults to $KUBECONFIG, or $(HOME)/.kube/config if the former is empty): Kubernetes from where to read Ingress configurations.
  • CONTROLLER_CONFIGMAP: <namespace>/<name> of the ConfigMap with global configurations.
  • CONTROLLER_ARGS: space separated list of additional command-line arguments.

The following make targets are supported:

  • build (default): Compiles HAProxy Ingress using the default OS and arch, and generates an executable at bin/controller.
  • run: Runs HAProxy Ingress locally.
  • lint: Runs golangci-lint.
  • test: Runs unit tests.
  • linux-build: Compiles HAProxy Ingress and generates an ELF (Linux) executable despite the source platform at rootfs/haproxy-ingress-controller. Used by image step.
  • image: Compiles HAProxy Ingress locally and generates a Docker image.
  • docker-build: Compiles HAProxy Ingress and generates a Docker image using a multi-stage Dockerfile.