Installation

Install HAProxy Unified Gateway on premises

On this page

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.

Supported version

HAProxy Unified Gateway supports Gateway API version experimental 1.3.0 and newer.

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.

Install HAProxy Unified Gateway Jump to heading

Install the HAProxy Unified Gateway controller, which 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 Helm Jump to heading

To install HAProxy Unified Gateway using Helm:

  1. Add the HAProxy Technologies Helm repository:

    nix
    helm repo add haproxytech https://haproxytech.github.io/helm-charts
    nix
    helm repo add haproxytech https://haproxytech.github.io/helm-charts

  2. Update your list of Helm charts:

    nix
    helm repo update
    nix
    helm repo update

  3. Install HAProxy Unified Gateway. This will install the Gateway API resources and the HAProxy Unified Gateway custom resources. By default it creates a service of type NodePort, but you can change it to LoadBalancer if running in a cloud environment.

    • If you’ve already installed the Gateway API into your cluster, you can disable Helm from installing it by adding the flag --set gwapijob.enabled=false.
    • You can also change the version of Gateway API by adding --set gwapijob.version=<VERSION>, for example --set gwapijob.version=1.5.0.
    • To disable adding the HAProxy Unified Gateway custom resources, add --set crdjob.enabled=false.
    nix
    helm install haproxy-unified-gateway haproxytech/haproxy-unified-gateway \
      --create-namespace \
      --namespace haproxy-unified-gateway \
      --set controller.service.type=NodePort \
      --set controller.service.stat.nodePort=31024 \
      --set controller.service.metrics.nodePort=31060
    nix
    helm install haproxy-unified-gateway haproxytech/haproxy-unified-gateway \
      --create-namespace \
      --namespace haproxy-unified-gateway \
      --set controller.service.type=NodePort \
      --set controller.service.stat.nodePort=31024 \
      --set controller.service.metrics.nodePort=31060
    nix
    helm install haproxy-unified-gateway haproxytech/haproxy-unified-gateway \
      --create-namespace \
      --namespace haproxy-unified-gateway \
      --set controller.service.type=LoadBalancer
    nix
    helm install haproxy-unified-gateway haproxytech/haproxy-unified-gateway \
      --create-namespace \
      --namespace haproxy-unified-gateway \
      --set controller.service.type=LoadBalancer

  4. 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 uniquely identifies this GatewayClass in the cluster. Gateways will reference this name.
    • controllerName associates this GatewayClass with a controller.

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

  6. Verify that HAProxy Unified Gateway is installed into your Kubernetes cluster:

    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-f9f554dd6-gx84h   1/1     Running   0          25m
    output
    text
    NAME                                       READY   STATUS    RESTARTS   AGE
    haproxy-unified-gateway-f9f554dd6-gx84h   1/1     Running   0          25m

Install with kubectl Jump to heading

To install HAProxy Unified Gateway using kubectl:

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

    nix
    kubectl apply --server-side -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.0/experimental-install.yaml
    nix
    kubectl apply --server-side -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

  2. Install the HAProxy Unified Gateway custom 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 custom resource definitions.
    • The namespace haproxy-unified-gateway to contain controller-related resources.
    • The ServiceAccount haproxy-unified-gateway that the controller will run as, giving it access to the Kubernetes API.
    • A ClusterRole that defines the necessary permissions to manage resources in the cluster.
    • A ClusterRoleBinding to assign the ClusterRole to the ServiceAccount.
    • A Deployment named haproxy-unified-gateway that runs the HAProxy Unified Gateway controller.
    • The Service haproxy-unified-gateway that publishes the gateway’s HTTP, HTTPS, and stats ports.
    • A HugConf custom resource that configures logging.

  3. Optional: HAProxy Unified Gateway uses a Service of type LoadBalancer. To change it to NodePort:

    • Download the v1.0 controller.yaml file.

    • Edit it so that the Service has a Type of NodePort and set a nodePort field for the stat and metrics ports:

      controller.yaml
      yaml
      apiVersion: v1
      kind: Service
      metadata:
        name: haproxy-unified-gateway
        namespace: haproxy-unified-gateway
        labels:
          app.kubernetes.io/name: haproxy-unified-gateway
      spec:
        selector:
          run: haproxy-unified-gateway
        type: NodePort
        ports:
          - name: stat
            port: 31024
            targetPort: 31024
            nodePort: 31024
          - name: metrics
            port: 31060
            targetPort: 31060
            nodePort: 31060
      controller.yaml
      yaml
      apiVersion: v1
      kind: Service
      metadata:
        name: haproxy-unified-gateway
        namespace: haproxy-unified-gateway
        labels:
          app.kubernetes.io/name: haproxy-unified-gateway
      spec:
        selector:
          run: haproxy-unified-gateway
        type: NodePort
        ports:
          - name: stat
            port: 31024
            targetPort: 31024
            nodePort: 31024
          - name: metrics
            port: 31060
            targetPort: 31060
            nodePort: 31060

    • Apply the changes with kubectl:

      nix
      kubectl apply -f controller.yaml
      nix
      kubectl apply -f controller.yaml
      output
      text
      deployment.apps/haproxy-unified-gateway configured
      service/haproxy-unified-gateway configured
      output
      text
      deployment.apps/haproxy-unified-gateway configured
      service/haproxy-unified-gateway configured

  4. 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 use a different value here if you also override it on the controller by setting the --controller-name argument when deploying the controller.

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

  6. Verify that HAProxy Unified Gateway is installed into your Kubernetes cluster:

    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

Do you have any suggestions on how we can improve the content of this page?

Previous page Installation Next page Administration
© 2026 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences