Enable the Gateway API

In this section, you will learn how to enable Gateway API.

The Gateway API is a new way to define network routing in Kubernetes. HAProxy Kubernetes Ingress Controller implements this API alongside its support for the older and established Ingress API.

With objects meant to promote a separation of concerns between platform engineers, cluster operators, and application developers, Gateway API can improve workflows and access control, whereas those lines are more blurred in Ingress API.

For example, in Ingress API, the same person will often choose which ingress controllers to use and then deploy them into the cluster. In Gateway API, one person in the organization can handle choosing which Gateway API implementations to make available, and then someone else can pick which ones to use from that list.

After enabling Gateway API, you will make it available for use in the cluster by defining a GatewayClass. A GatewayClass is similar to an IngressClass in that while an IngressClass specifies which controller will handle a particular Ingress resource, a GatewayClass defines what type of Gateway to use for routing traffic, or in other words, which controller’s Gateway API implementation. Another resource called a Gateway then configures which GatewayClass to use for a particular Route. Similarly to Ingress resources, Routes define the mechanism and rules for directing external traffic to Services deployed in the cluster.

Deploy Gateway API resources Jump to heading #

Install the resources that enable Gateway API functionality in your cluster:

1. Deploy the Gateway API custom resource definitions:

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

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

2. Deploy the HAProxy Kubernetes Ingress Controller RBAC resources, which give the haproxy-kubernetes-ingress ServiceAccount permissions to use the Gateway API resource types:

   nix
   kubectl apply -f https://raw.githubusercontent.com/haproxytech/kubernetes-ingress/master/deploy/tests/config/experimental/gwapi-rbac.yaml

   nix
   kubectl apply -f https://raw.githubusercontent.com/haproxytech/kubernetes-ingress/master/deploy/tests/config/experimental/gwapi-rbac.yaml

Update your ingress controller Jump to heading #

To enable Gateway API, you must update your HAProxy Kubernetes Ingress Controller Deployment. Whether you installed the ingress controller via Helm or via kubectl will determine how you perform these updates.

Update with Helm Jump to heading #

If using Helm, create a values file to set the startup argument for gateway controller name.

1. Create a file named values.yaml that enables Gateway API and sets TCP ports where the controller should listen. The following values file creates the necessary ClusterRoleBinding object and enables support for Gateway API. If you created a values file for your initial installation, or for altering other settings, you can reuse this file, updating it with the following:

   values.yaml
   yaml
   controller:
     kubernetesGateway:
       enabled: true
       gatewayControllerName: haproxy.org/gateway-controller

   values.yaml
   yaml
   controller:
     kubernetesGateway:
       enabled: true
       gatewayControllerName: haproxy.org/gateway-controller

   • Set controller.kubernetesGateway.enabled to true.
   • Specify the name of the gateway controller in controller.kubernetesGateway.gatewayControllerName. You will reference this later when you define a GatewayClass.

2. Execute the helm upgrade command, providing the name of the YAML values file with -f.

   community enterprise

   nix
   helm upgrade haproxy-kubernetes-ingress haproxytech/kubernetes-ingress \
     --namespace haproxy-controller \
     -f values.yaml

   nix
   helm upgrade haproxy-kubernetes-ingress haproxytech/kubernetes-ingress \
     --namespace haproxy-controller \
     -f values.yaml

   nix
   helm upgrade haproxy-kubernetes-ingress haproxytech/kubernetes-ingress \
     --create-namespace \
     --namespace haproxy-controller \
     --set controller.imageCredentials.registry=kubernetes-registry.haproxy.com \
     --set controller.imageCredentials.username=<KEY> \
     --set controller.imageCredentials.password=<KEY> \
     --set controller.image.repository=kubernetes-registry.haproxy.com/hapee-ingress \
     --set controller.image.tag=v3.0 \
     -f values.yaml

   nix
   helm upgrade haproxy-kubernetes-ingress haproxytech/kubernetes-ingress \
     --create-namespace \
     --namespace haproxy-controller \
     --set controller.imageCredentials.registry=kubernetes-registry.haproxy.com \
     --set controller.imageCredentials.username=<KEY> \
     --set controller.imageCredentials.password=<KEY> \
     --set controller.image.repository=kubernetes-registry.haproxy.com/hapee-ingress \
     --set controller.image.tag=v3.0 \
     -f values.yaml

   About Helm upgrade

   Performing a helm upgrade in this way uses the values file to automatically update the kubernetes-ingress-controller Deployment. You can view the changes using kubectl get as follows:

   nix
   kubectl get deployment haproxy-kubernetes-ingress -n haproxy-controller -o yaml

   nix
   kubectl get deployment haproxy-kubernetes-ingress -n haproxy-controller -o yaml

   You will see the --gateway-controller-name startup argument was added to the Deployment:

   deployment/haproxy-kubernetes-ingress
   yaml
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     [...]
     name: haproxy-kubernetes-ingress
     namespace: haproxy-controller
   spec:
   [...]
     template:
     [...]
       spec:
         containers:
         - args:
           - --gateway-controller-name=haproxy.org/gateway-controller

   deployment/haproxy-kubernetes-ingress
   yaml
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     [...]
     name: haproxy-kubernetes-ingress
     namespace: haproxy-controller
   spec:
   [...]
     template:
     [...]
       spec:
         containers:
         - args:
           - --gateway-controller-name=haproxy.org/gateway-controller

   The Deployment name for the community version is kubernetes-ingress-controller and is haproxy-ingress for the enterprise version.

Update with kubectl Jump to heading #

To enable Gateway API features using kubectl and YAML files, we will create patch files to patch the ingress controller Deployment to add the gateway controller name startup argument.

1. Examine your current Deployment using the following command. This will show your Deployment in YAML. Make note of any additional arguments present in args for the haproxy-ingress container. You will need these arguments in the next step.

   community enterprise

   nix
   kubectl get deployment haproxy-kubernetes-ingress -n haproxy-controller -o yaml

   nix
   kubectl get deployment haproxy-kubernetes-ingress -n haproxy-controller -o yaml

   nix
   kubectl get deployment haproxy-ingress -n ingress-controller -o yaml

   nix
   kubectl get deployment haproxy-ingress -n ingress-controller -o yaml

2. Create a new file named deployment-enable-gateway-api-patch.yaml and add the following to it. Be sure to include in this file, the Deployment patch, any additional startup arguments that exist or that you have added to your Deployment. The entire args list is replaced upon the patch being applied:

   deployment-enable-gateway-api-patch.yaml
   yaml
   spec:
   template:
     spec:
       containers:
       - name: haproxy-ingress
         args:
           - --configmap=haproxy-controller/haproxy-kubernetes-ingress
           - --gateway-controller-name=haproxy.org/gateway-controller

   deployment-enable-gateway-api-patch.yaml
   yaml
   spec:
   template:
     spec:
       containers:
       - name: haproxy-ingress
         args:
           - --configmap=haproxy-controller/haproxy-kubernetes-ingress
           - --gateway-controller-name=haproxy.org/gateway-controller

3. Apply the Deployment Patch:

   community enterprise

   nix
   kubectl patch deployment haproxy-kubernetes-ingress --patch-file=deployment-enable-gateway-api-patch.yaml -n haproxy-controller

   nix
   kubectl patch deployment haproxy-kubernetes-ingress --patch-file=deployment-enable-gateway-api-patch.yaml -n haproxy-controller

   output
   text
   deployment.apps/haproxy-kubernetes-ingress patched

   output
   text
   deployment.apps/haproxy-kubernetes-ingress patched

   nix
   kubectl patch deployment haproxy-ingress --patch-file=deployment-enable-gateway-api-patch.yaml -n haproxy-controller

   nix
   kubectl patch deployment haproxy-ingress --patch-file=deployment-enable-gateway-api-patch.yaml -n haproxy-controller

   output
   text
   deployment.apps/haproxy-ingress patched

   output
   text
   deployment.apps/haproxy-ingress patched

4. (Optional): Add an annotation to the Deployment to track the change within the resource. This will make it so that when you review the rollout history of the deployment, this change has a record associated with it, which may assist in tracking changes and performing rollbacks. Note that this is an overwrite of the original entry, which was blank.

   community enterprise

   nix
   kubectl annotate deployment haproxy-kubernetes-ingress kubernetes.io/change-cause="Updated haproxy-kubernetes-ingress Deployment to enable Gateway API support" --overwrite=true -n haproxy-controller

   nix
   kubectl annotate deployment haproxy-kubernetes-ingress kubernetes.io/change-cause="Updated haproxy-kubernetes-ingress Deployment to enable Gateway API support" --overwrite=true -n haproxy-controller

   output
   text
   deployment.apps/haproxy-kubernetes-ingress annotated

   output
   text
   deployment.apps/haproxy-kubernetes-ingress annotated

   Check the rollout history:

   nix
   kubectl rollout history deployment/haproxy-kubernetes-ingress -n haproxy-controller

   nix
   kubectl rollout history deployment/haproxy-kubernetes-ingress -n haproxy-controller

   output
   text
   REVISION  CHANGE-CAUSE
   1         <none>
   2         Updated haproxy-kubernetes-ingress deployment to enable Gateway API support

   output
   text
   REVISION  CHANGE-CAUSE
   1         <none>
   2         Updated haproxy-kubernetes-ingress deployment to enable Gateway API support

   nix
   kubectl annotate deployment haproxy-ingress kubernetes.io/change-cause="Updated haproxy-ingress Deployment to enable Gateway API support" --overwrite=true -n haproxy-controller

   nix
   kubectl annotate deployment haproxy-ingress kubernetes.io/change-cause="Updated haproxy-ingress Deployment to enable Gateway API support" --overwrite=true -n haproxy-controller

   output
   text
   deployment.apps/haproxy-kubernetes-ingress annotated

   output
   text
   deployment.apps/haproxy-kubernetes-ingress annotated

   Check the rollout history:

   nix
   kubectl rollout history deployment/haproxy-ingress --revision=2 -n haproxy-controller

   nix
   kubectl rollout history deployment/haproxy-ingress --revision=2 -n haproxy-controller

   output
   text
   REVISION  CHANGE-CAUSE
   1         <none>
   2         Updated haproxy-ingress deployment to enable Gateway API 

   output
   text
   REVISION  CHANGE-CAUSE
   1         <none>
   2         Updated haproxy-ingress deployment to enable Gateway API 

Define a GatewayClass Jump to heading #

A GatewayClass makes a Gateway API implementation available so that cluster operators can use it. Platform engineers can be responsible for this, defining GatewayClass objects that are available in the cluster.

To deploy a GatewayClass for HAProxy Kubernetes Ingress Controller:

• Create a file named haproxy-ingress-gatewayclass.yaml and add the following to it to define a GatewayClass:

  haproxy-ingress-gatewayclass.yaml
  yaml
  apiVersion: gateway.networking.k8s.io/v1alpha2
  kind: GatewayClass
  metadata:
    namespace: default
    name: haproxy-ingress-gatewayclass
  spec:
    controllerName: haproxy.org/gateway-controller

  haproxy-ingress-gatewayclass.yaml
  yaml
  apiVersion: gateway.networking.k8s.io/v1alpha2
  kind: GatewayClass
  metadata:
    namespace: default
    name: haproxy-ingress-gatewayclass
  spec:
    controllerName: haproxy.org/gateway-controller

  In this definition:

  • The name attribute will uniquely identify this GatewayClass in the cluster.
  • The controllerName attribute refers to the name you set with the --gateway-controller-name startup argument.

  Apply the changes with kubectl:

  nix
  kubectl apply -f haproxy-ingress-gatewayclass.yaml

  nix
  kubectl apply -f haproxy-ingress-gatewayclass.yaml

Next steps Jump to heading #

After platform engineers have deployed the Gateway API resources, HAProxy Kubernetes Ingress Controller, and a GatewayClass, cluster operators should then define a Gateway that uses that GatewayClass. Following that, application developers can then define Routes that make use of the Gateway.

To see Routes in action with a Gateway and a Service that communicates over TCP, see Use TCPRoute. In this tutorial, we show how to define a Gateway that uses the GatewayClass you deployed, and we show how to define a TCPRoute, a Route that enables TCP traffic to reach your service.

See also Jump to heading #

• Values files
• Startup arguments - community
• Startup arguments - enterprise
• Kubernetes official documentation - Update API Objects in Place Using kubectl patch