N42 Gateway

Ingress and Gateway API controller implementation for HAProxy loadbalancer.

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

| 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

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

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: / of the ConfigMap with global configurations.
• CONTROLLER_ARGS: space separated list of additional command-line arguments.

• 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.