Install HAProxy Unified Gateway on premises

This guide shows you how to install HAProxy Kubernetes Unified Gateway into an on-premises Kubernetes cluster and enable it as a GatewayClass. Platform engineers can be responsible for this, determining which GatewayClass resources to allow in the cluster.

Pre-installation checklist Jump to heading #

Before continuing, ensure that you’ve met these prerequisites:

• You have a Kubernetes cluster.
• You’ve installed the helm command-line tool if you plan to install using Helm.
• You’ve installed the kubectl command-line tool, which you can use to manage your cluster.

Enable Gateway API in your cluster Jump to heading #

To opt in to using Gateway API in your Kubernetes cluster, you must install a set of custom resource definitions.

1. Use kubectl to install the Gateway API custom resource definitions.

   nix
   kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.0/experimental-install.yaml

   nix
   kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.0/experimental-install.yaml

   output
   text
   customresourcedefinition.apiextensions.k8s.io/gatewayclasses.gateway.networking.k8s.io created
   customresourcedefinition.apiextensions.k8s.io/gateways.gateway.networking.k8s.io created
   customresourcedefinition.apiextensions.k8s.io/grpcroutes.gateway.networking.k8s.io created
   customresourcedefinition.apiextensions.k8s.io/httproutes.gateway.networking.k8s.io created
   customresourcedefinition.apiextensions.k8s.io/referencegrants.gateway.networking.k8s.io created

   output
   text
   customresourcedefinition.apiextensions.k8s.io/gatewayclasses.gateway.networking.k8s.io created
   customresourcedefinition.apiextensions.k8s.io/gateways.gateway.networking.k8s.io created
   customresourcedefinition.apiextensions.k8s.io/grpcroutes.gateway.networking.k8s.io created
   customresourcedefinition.apiextensions.k8s.io/httproutes.gateway.networking.k8s.io created
   customresourcedefinition.apiextensions.k8s.io/referencegrants.gateway.networking.k8s.io created

Install HAProxy Unified Gateway Jump to heading #

After enabling Gateway API, install the HAProxy Unified Gateway controller. The controller runs a control loop that watches the cluster and implements Gateways backed by HAProxy. We’ll also add a GatewayClass so that teams can instantiate Gateways.

Install with kubectl Jump to heading #

To install HAProxy Unified Gateway using kubectl:

1. Run these commands to install the necessary resources into your cluster:

   nix
   kubectl apply -f https://raw.githubusercontent.com/haproxytech/haproxy-unified-gateway/refs/heads/v1.0/api/definition/gate.v3.haproxy.org_backends.yaml
   kubectl apply -f https://raw.githubusercontent.com/haproxytech/haproxy-unified-gateway/refs/heads/v1.0/api/definition/gate.v3.haproxy.org_defaults.yaml
   kubectl apply -f https://raw.githubusercontent.com/haproxytech/haproxy-unified-gateway/refs/heads/v1.0/api/definition/gate.v3.haproxy.org_globals.yaml
   kubectl apply -f https://raw.githubusercontent.com/haproxytech/haproxy-unified-gateway/refs/heads/v1.0/api/definition/gate.v3.haproxy.org_hugconfs.yaml
   kubectl apply -f https://raw.githubusercontent.com/haproxytech/haproxy-unified-gateway/refs/heads/v1.0/api/definition/gate.v3.haproxy.org_huggates.yaml
   kubectl apply -f https://raw.githubusercontent.com/haproxytech/haproxy-unified-gateway/refs/heads/v1.0/example/deploy/hug/namespace.yaml
   kubectl apply -f https://raw.githubusercontent.com/haproxytech/haproxy-unified-gateway/refs/heads/v1.0/example/deploy/hug/rbac.yaml
   kubectl apply -f https://raw.githubusercontent.com/haproxytech/haproxy-unified-gateway/refs/heads/v1.0/example/deploy/hug/controller.yaml
   kubectl apply -f https://raw.githubusercontent.com/haproxytech/haproxy-unified-gateway/refs/heads/v1.0/example/deploy/hug/hugconf.yaml

   nix
   kubectl apply -f https://raw.githubusercontent.com/haproxytech/haproxy-unified-gateway/refs/heads/v1.0/api/definition/gate.v3.haproxy.org_backends.yaml
   kubectl apply -f https://raw.githubusercontent.com/haproxytech/haproxy-unified-gateway/refs/heads/v1.0/api/definition/gate.v3.haproxy.org_defaults.yaml
   kubectl apply -f https://raw.githubusercontent.com/haproxytech/haproxy-unified-gateway/refs/heads/v1.0/api/definition/gate.v3.haproxy.org_globals.yaml
   kubectl apply -f https://raw.githubusercontent.com/haproxytech/haproxy-unified-gateway/refs/heads/v1.0/api/definition/gate.v3.haproxy.org_hugconfs.yaml
   kubectl apply -f https://raw.githubusercontent.com/haproxytech/haproxy-unified-gateway/refs/heads/v1.0/api/definition/gate.v3.haproxy.org_huggates.yaml
   kubectl apply -f https://raw.githubusercontent.com/haproxytech/haproxy-unified-gateway/refs/heads/v1.0/example/deploy/hug/namespace.yaml
   kubectl apply -f https://raw.githubusercontent.com/haproxytech/haproxy-unified-gateway/refs/heads/v1.0/example/deploy/hug/rbac.yaml
   kubectl apply -f https://raw.githubusercontent.com/haproxytech/haproxy-unified-gateway/refs/heads/v1.0/example/deploy/hug/controller.yaml
   kubectl apply -f https://raw.githubusercontent.com/haproxytech/haproxy-unified-gateway/refs/heads/v1.0/example/deploy/hug/hugconf.yaml

   output
   text
   customresourcedefinition.apiextensions.k8s.io/backends.gate.v3.haproxy.org created
   customresourcedefinition.apiextensions.k8s.io/defaults.gate.v3.haproxy.org created
   customresourcedefinition.apiextensions.k8s.io/globals.gate.v3.haproxy.org created
   customresourcedefinition.apiextensions.k8s.io/hugconfs.gate.v3.haproxy.org created
   customresourcedefinition.apiextensions.k8s.io/huggates.gate.v3.haproxy.org created
   namespace/haproxy-unified-gateway created
   serviceaccount/haproxy-unified-gateway created
   clusterrole.rbac.authorization.k8s.io/haproxy-unified-gateway created
   clusterrolebinding.rbac.authorization.k8s.io/haproxy-unified-gateway created
   deployment.apps/haproxy-unified-gateway created
   service/haproxy-unified-gateway created
   hugconf.gate.v3.haproxy.org/hugconf created

   output
   text
   customresourcedefinition.apiextensions.k8s.io/backends.gate.v3.haproxy.org created
   customresourcedefinition.apiextensions.k8s.io/defaults.gate.v3.haproxy.org created
   customresourcedefinition.apiextensions.k8s.io/globals.gate.v3.haproxy.org created
   customresourcedefinition.apiextensions.k8s.io/hugconfs.gate.v3.haproxy.org created
   customresourcedefinition.apiextensions.k8s.io/huggates.gate.v3.haproxy.org created
   namespace/haproxy-unified-gateway created
   serviceaccount/haproxy-unified-gateway created
   clusterrole.rbac.authorization.k8s.io/haproxy-unified-gateway created
   clusterrolebinding.rbac.authorization.k8s.io/haproxy-unified-gateway created
   deployment.apps/haproxy-unified-gateway created
   service/haproxy-unified-gateway created
   hugconf.gate.v3.haproxy.org/hugconf created

   This installs the following:

   • The custom resource definitions.
   • A namespace named haproxy-unified-gateway to contain all of the controller-related resources.
   • A ServiceAccount named haproxy-unified-gateway that the controller will run as, giving it access to the Kubernetes API.
   • A ClusterRole that defines the necessary permissions to watch and manage resources in the cluster and a ClusterRoleBinding to assign that role to the service account.
   • A Deployment named haproxy-unified-gateway that runs the HAProxy Unified Gateway controller.
   • A Service named haproxy-unified-gateway of type NodePort to expose the gateway’s HTTP, HTTPS, and stats ports.
   • A HugConf custom resource that configures logging.

2. Add a GatewayClass. A GatewayClass adds the HAProxy Unified Gateway as a class of Gateways available in your cluster. Teams in your organization can then create Gateways of that type. Create a file named gatewayclass.yaml and add the following to it:

   gatewayclass.yaml
   yaml
   apiVersion: gateway.networking.k8s.io/v1
   kind: GatewayClass
   metadata:
     name: haproxy
   spec:
     controllerName: gate.haproxy.org/hug

   gatewayclass.yaml
   yaml
   apiVersion: gateway.networking.k8s.io/v1
   kind: GatewayClass
   metadata:
     name: haproxy
   spec:
     controllerName: gate.haproxy.org/hug

   In this definition:

   • name will uniquely identify this GatewayClass in the cluster. Gateways will reference this name. We use haproxy.
   • controllerName refers to the controller with which this GatewayClass is associated. The default value is gate.haproxy.org/hug, but you can override it by setting the --controller-name argument when deploying the controller.

   Apply the changes with kubectl:

   nix
   kubectl apply -f gatewayclass.yaml

   nix
   kubectl apply -f gatewayclass.yaml

   output
   text
   gatewayclass.gateway.networking.k8s.io/haproxy created

   output
   text
   gatewayclass.gateway.networking.k8s.io/haproxy created

3. Verify that HAProxy Unified Gateway is installed into your Kubernetes cluster by using the command kubectl get pods:

   nix
   kubectl get pods --namespace haproxy-unified-gateway

   nix
   kubectl get pods --namespace haproxy-unified-gateway

   output
   text
   NAME                                       READY   STATUS    RESTARTS   AGE
   haproxy-unified-gateway-55744dfb75-46ncx   1/1     Running   0          58m

   output
   text
   NAME                                       READY   STATUS    RESTARTS   AGE
   haproxy-unified-gateway-55744dfb75-46ncx   1/1     Running   0          58m

   Call kubectl get svc to see which ports were mapped. In this example, port 31080 forwards to port 8080 on the controller.

   nix
   kubectl get svc --namespace haproxy-unified-gateway

   nix
   kubectl get svc --namespace haproxy-unified-gateway

   output
   text
   NAME                      TYPE       CLUSTER-IP      EXTERNAL-IP   PORT(S)                                         AGE
   haproxy-unified-gateway   NodePort   10.102.118.90   <none>        8080:31080/TCP,8443:31443/TCP,31024:31678/TCP   13h

   output
   text
   NAME                      TYPE       CLUSTER-IP      EXTERNAL-IP   PORT(S)                                         AGE
   haproxy-unified-gateway   NodePort   10.102.118.90   <none>        8080:31080/TCP,8443:31443/TCP,31024:31678/TCP   13h