The following sections walk through steps to have HAProxy Ingress working, watching ingress resources and exposing services.
HAProxy Ingress needs a running Kubernetes cluster. Controller version v0.14 needs Kubernetes 1.19 or newer, see other supported versions in the README file. HAProxy Ingress also works fine on local k8s deployments like minikube, kind or k3d.
An ingress controller works exposing internal services to the external world, so another pre-requisite is that at least one cluster node is accessible externally. On cloud environments, a cloud load balancer can be configured to reach the ingress controller nodes.
HAProxy Ingress uses TLS SNI extension and the Host header to associate requests and ingress’
hosts. The easiest way to accomplish this on local environment is using nip.io. A production environment should consider a dynamic DNS solution or a wildcard DNS record.
HAProxy Ingress uses Helm chart to install and configure the controller. See below some deployment instructions:
helm, HAProxy Ingress requires version 3. See the installation instructions here.
2) Add the HAProxy Ingress’ Helm repository. This will instruct Helm to find all available packages:
$ helm repo add haproxy-ingress https://haproxy-ingress.github.io/charts
3) Check if kubeconfig points to the right cluster:
$ kubectl cluster-info
The default cluster can be changed either via
kubectl config set-context <cluster-context> or adding
--kube-context <cluster-context> in the helm command-line options.
Note that the user needs administrative privileges in the cluster to properly installs the controller.
4) Create a
haproxy-ingress-values.yaml file with custom parameters:
controller: hostNetwork: true ingressClassResource: enabled: true
5) Install HAProxy Ingress using
haproxy-ingress as the release name and
haproxy-ingress-values.yaml file as the custom parameters:
$ helm install haproxy-ingress haproxy-ingress/haproxy-ingress\ --create-namespace --namespace ingress-controller\ --version 0.14.5\ -f haproxy-ingress-values.yaml
installabove can be changed to
upgradeto start a rolling update of HAProxy Ingress version or configuration.
templatecan be used instead to generate the manifests without installing them - add either a redirect
... >haproxy-ingress-install.yamlto save the output, or
--output-dir output/command line option to save one file per manifest.
The controller should be running in a few seconds. There are four important customizations made in the example above:
- version: a good practice, this will ensure that you’ll have the same version installed even if a new release issued.
- namespace: we’re instructing helm to install HAProxy Ingress in the
ingress-controllernamespace. This namespace will be created if it does not exist yet. The default behavior, if namespace is not provided, is to deploy the controller in the kubectl’s current namespace.
- hostNetwork: we’re configuring the deployment to expose haproxy in the host network, which means bind all haproxy ports, including but not limited to 80 and 443, in the node’s IPs. Maybe this isn’t a proper configuration for your production - it depends on the options you have to expose a Kubernetes’ service, but doing so we’ll be able to send http/s requests on local development environments, or even baremetal and on premise deployments that doesn’t have a fronting router or load balancer to expose the controller. In any case a service is also configured in the
ingress-controllernamespace which tries to expose haproxy.
- ingressClassResource.enabled: This causes the helm chart to apply an IngressClass to your cluster. IngressClasses are how HAProxy Ingress knows which of your Ingresses that it should control. IngressClasses replace the kubernetes.io/ingress.class annotation used in Kubernetes versions before v1.18.
Deploy and expose
The following steps deploy an echoserver image and exposes it in the current namespace using an Ingress resource. See here how to expose using Gateway API.
1) Create the echoserver’s deployment and service:
$ kubectl --namespace default create deployment echoserver --image k8s.gcr.io/echoserver:1.3 $ kubectl --namespace default expose deployment echoserver --port=8080
2) Check if echoserver is up and running:
$ kubectl -n default get pod -w NAME READY STATUS RESTARTS AGE echoserver-5b6fb6dd96-68jwp 1/1 Running 0 27s
3) Make HAProxy Ingress exposes the echoserver service. Change
echoserver.local value in the
--rule option below to a hostname that resolves to an ingress controller node.
nip.io is a convenient service which converts a valid domain name to any IP, either public or local. See here how it works.
$ kubectl --namespace default create ingress echoserver \ --class=haproxy \ --rule="echoserver.local/*=echoserver:8080,tls"
4) Send a request to our echoserver.
$ curl -k https://echoserver.local $ wget -qO- --no-check-certificate https://echoserver.local
See what differs to expose services using Gateway API:
- Gateway API introduction from Kubernetes’ SIG-Network documentation
- Getting started with Gateway API and HAProxy Ingress
Learn more about Ingress and IngressClass resources:
- Ingress and IngressClass resources from Kubernetes docs
HAProxy Ingress has lots of configuration options. See the following tips to get started faster:
- Follow some configuration instruction from the examples page
- See how HAProxy Ingress uses ingress objects: configuration keys
- Get started with all the configuration options: configuration