README.md

HAProxy Ingress controller

Ingress controller implementation for HAProxy loadbalancer.

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

Documentation:

• Getting started guide: /docs/getting-started/
• Global and per ingress/service configuration keys: /docs/configuration/keys/
• Command-line options: /docs/configuration/command-line/

Supported versions:

HAProxy Ingress	Embedded HAProxy	Supported Kubernetes	External 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

Community:

• Slack: We're in the #haproxy-ingress channel on Kubernetes Slack. Take an invite here if not subscribed yet
• Users mailing list: Announcements and discussion on a mailing list
• Stack Overflow: Practical questions and curated answers

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/github.com/jcmoraisjr
cd $GOPATH/src/github.com/jcmoraisjr
git clone https://github.com/jcmoraisjr/haproxy-ingress.git
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 https://haproxy-ingress.github.io/charts
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, needs golangci-lint in the path.
• test: Runs unit tests.
• test-integration: Runs integration tests, needs haproxy 2.2+ in the path.
• 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.