N42 Gateway

September 12, 2026 · View on GitHub

Ingress and Gateway API controller implementation for HAProxy loadbalancer.

N42 Gateway is a Kubernetes Ingress and Gateway API 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 N42 Gateway

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:

N42 Gateway	Embedded HAProxy	Supported Kubernetes	External HAProxy (*)
`v0.17` (alpha)	`3.0`	`1.21+`	`2.6+`
`v0.16` (latest)	`2.8`	`1.21+`	`2.4+`
`v0.15`	`2.6`	`1.21+`	`2.2+`
`v0.14`	`2.4`	`1.19+`	`2.2+`
`v0.13` (critical fixes)	`2.3` up to `v0.13.10` `2.4` on `v0.13.11`+	`1.19+`	`2.2+`

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 #n42-gateway channel on Kubernetes Slack. Take an invite if not subscribed yet
Discussions: Follow announcements and ask questions on GitHub Discussions.

Develop N42 Gateway

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/n42-gateway
cd $GOPATH/src/github.com/n42-gateway
git clone https://github.com/n42-gateway/n42-gateway.git
cd n42-gateway
make run

Dependencies to run locally:

Golang
HAProxy compiled with USE_OPENSSL=1 and USE_LUA=1
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 (locally) and generate localhost/n42-gateway:latest:

make image

Official image - build in a multi-stage Dockerfile and generate localhost/n42-gateway:latest:

make docker-build

Deploy local image using Helm:

helm repo add n42 https://n42-gateway.github.io/charts
helm install n42 n42/n42-gateway\
  --create-namespace --namespace=n42-gateway-system\
  --set controller.image.repository=localhost/n42-gateway\
  --set controller.image.tag=latest\
  --set controller.image.pullPolicy=Never

make options:

The following make variables are supported:

CONTROLLER_TAG (defaults to localhost/n42-gateway:latest): tag name for make image and make docker-build.
LOCAL_FS_PREFIX (defaults to /tmp/n42-gateway): 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 N42 Gateway using the default OS and arch, and generates an executable at bin/controller.
run: Runs N42 Gateway locally.
lint: Runs golangci-lint
test: Runs unit tests.
test-integration: Runs integration tests, needs haproxy 2.6+ in the path.
linux-build: Compiles N42 Gateway and generates an ELF (Linux) executable despite the source platform at rootfs/n42-gateway-controller. Used by image step.
image: Compiles N42 Gateway locally and generates a Docker image.
docker-build: Compiles N42 Gateway and generates a Docker image using a multi-stage Dockerfile.

HAProxy is a registered trademark of HAProxy Technologies SAS.