Gateway API tutorials

Enable the Gateway API

Available since

version 1.10

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.

    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.

    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:

    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.

    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

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