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.
On-demand webinar
Deploy Gateway API resources Jump to heading
Install the resources that enable Gateway API functionality in your cluster:
-
Deploy the Gateway API custom resource definitions:
nixkubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v0.5.1/experimental-install.yamlnixkubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v0.5.1/experimental-install.yaml -
Deploy the HAProxy Kubernetes Ingress Controller RBAC resources, which give the
haproxy-kubernetes-ingress
ServiceAccount permissions to use the Gateway API resource types:nixkubectl apply -f https://raw.githubusercontent.com/haproxytech/kubernetes-ingress/master/deploy/tests/config/experimental/gwapi-rbac.yamlnixkubectl 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.
-
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.yamlyamlcontroller:kubernetesGateway:enabled: truegatewayControllerName: haproxy.org/gateway-controllervalues.yamlyamlcontroller:kubernetesGateway:enabled: truegatewayControllerName: haproxy.org/gateway-controller- Set
controller.kubernetesGateway.enabled
totrue
. - Specify the name of the gateway controller in
controller.kubernetesGateway.gatewayControllerName
. You will reference this later when you define aGatewayClass
.
- Set
-
Execute the
helm upgrade
command, providing the name of the YAML values file with-f
.nixhelm upgrade haproxy-kubernetes-ingress haproxytech/kubernetes-ingress \--namespace haproxy-controller \-f values.yamlnixhelm upgrade haproxy-kubernetes-ingress haproxytech/kubernetes-ingress \--namespace haproxy-controller \-f values.yamlnixhelm 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.yamlnixhelm 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.yamlAbout Helm upgrade
Performing a
helm upgrade
in this way uses the values file to automatically update thekubernetes-ingress-controller
Deployment. You can view the changes usingkubectl get
as follows:nixkubectl get deployment haproxy-kubernetes-ingress -n haproxy-controller -o yamlnixkubectl get deployment haproxy-kubernetes-ingress -n haproxy-controller -o yamlYou will see the
--gateway-controller-name
startup argument was added to the Deployment:deployment/haproxy-kubernetes-ingressyamlapiVersion: apps/v1kind: Deploymentmetadata:[...]name: haproxy-kubernetes-ingressnamespace: haproxy-controllerspec:[...]template:[...]spec:containers:- args:- --gateway-controller-name=haproxy.org/gateway-controllerdeployment/haproxy-kubernetes-ingressyamlapiVersion: apps/v1kind: Deploymentmetadata:[...]name: haproxy-kubernetes-ingressnamespace: haproxy-controllerspec:[...]template:[...]spec:containers:- args:- --gateway-controller-name=haproxy.org/gateway-controllerThe Deployment name for the community version is
kubernetes-ingress-controller
and ishaproxy-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.
-
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 thehaproxy-ingress
container. You will need these arguments in the next step.nixkubectl get deployment haproxy-kubernetes-ingress -n haproxy-controller -o yamlnixkubectl get deployment haproxy-kubernetes-ingress -n haproxy-controller -o yamlnixkubectl get deployment haproxy-ingress -n ingress-controller -o yamlnixkubectl get deployment haproxy-ingress -n ingress-controller -o yaml -
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 entireargs
list is replaced upon the patch being applied:deployment-enable-gateway-api-patch.yamlyamlspec:template:spec:containers:- name: haproxy-ingressargs:- --configmap=haproxy-controller/haproxy-kubernetes-ingress- --gateway-controller-name=haproxy.org/gateway-controllerdeployment-enable-gateway-api-patch.yamlyamlspec:template:spec:containers:- name: haproxy-ingressargs:- --configmap=haproxy-controller/haproxy-kubernetes-ingress- --gateway-controller-name=haproxy.org/gateway-controller -
Apply the Deployment Patch:
nixkubectl patch deployment haproxy-kubernetes-ingress --patch-file=deployment-enable-gateway-api-patch.yaml -n haproxy-controllernixkubectl patch deployment haproxy-kubernetes-ingress --patch-file=deployment-enable-gateway-api-patch.yaml -n haproxy-controlleroutputtextdeployment.apps/haproxy-kubernetes-ingress patchedoutputtextdeployment.apps/haproxy-kubernetes-ingress patchednixkubectl patch deployment haproxy-ingress --patch-file=deployment-enable-gateway-api-patch.yaml -n haproxy-controllernixkubectl patch deployment haproxy-ingress --patch-file=deployment-enable-gateway-api-patch.yaml -n haproxy-controlleroutputtextdeployment.apps/haproxy-ingress patchedoutputtextdeployment.apps/haproxy-ingress patched -
(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.
nixkubectl annotate deployment haproxy-kubernetes-ingress kubernetes.io/change-cause="Updated haproxy-kubernetes-ingress Deployment to enable Gateway API support" --overwrite=true -n haproxy-controllernixkubectl annotate deployment haproxy-kubernetes-ingress kubernetes.io/change-cause="Updated haproxy-kubernetes-ingress Deployment to enable Gateway API support" --overwrite=true -n haproxy-controlleroutputtextdeployment.apps/haproxy-kubernetes-ingress annotatedoutputtextdeployment.apps/haproxy-kubernetes-ingress annotatedCheck the rollout history:
nixkubectl rollout history deployment/haproxy-kubernetes-ingress -n haproxy-controllernixkubectl rollout history deployment/haproxy-kubernetes-ingress -n haproxy-controlleroutputtextREVISION CHANGE-CAUSE1 <none>2 Updated haproxy-kubernetes-ingress deployment to enable Gateway API supportoutputtextREVISION CHANGE-CAUSE1 <none>2 Updated haproxy-kubernetes-ingress deployment to enable Gateway API supportnixkubectl annotate deployment haproxy-ingress kubernetes.io/change-cause="Updated haproxy-ingress Deployment to enable Gateway API support" --overwrite=true -n haproxy-controllernixkubectl annotate deployment haproxy-ingress kubernetes.io/change-cause="Updated haproxy-ingress Deployment to enable Gateway API support" --overwrite=true -n haproxy-controlleroutputtextdeployment.apps/haproxy-kubernetes-ingress annotatedoutputtextdeployment.apps/haproxy-kubernetes-ingress annotatedCheck the rollout history:
nixkubectl rollout history deployment/haproxy-ingress --revision=2 -n haproxy-controllernixkubectl rollout history deployment/haproxy-ingress --revision=2 -n haproxy-controlleroutputtextREVISION CHANGE-CAUSE1 <none>2 Updated haproxy-ingress deployment to enable Gateway APIoutputtextREVISION CHANGE-CAUSE1 <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.yamlyamlapiVersion: gateway.networking.k8s.io/v1alpha2kind: GatewayClassmetadata:namespace: defaultname: haproxy-ingress-gatewayclassspec:controllerName: haproxy.org/gateway-controllerhaproxy-ingress-gatewayclass.yamlyamlapiVersion: gateway.networking.k8s.io/v1alpha2kind: GatewayClassmetadata:namespace: defaultname: haproxy-ingress-gatewayclassspec:controllerName: haproxy.org/gateway-controllerIn 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
:nixkubectl apply -f haproxy-ingress-gatewayclass.yamlnixkubectl apply -f haproxy-ingress-gatewayclass.yaml - The
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?