Simplified Explanation and Tutorial for Kubernetes Gateway API

What is Kubernetes Gateway API

The Kubernetes Gateway API simplifies how you manage external access to your applications by introducing a clear separation of concerns between the infrastructure team and the application development team. Unlike Ingress controller which is limited to Layer 7 HTTP and HTTPS protocol, Gateway API includes Layer 4 e.g. TCP and UDP.

The diagram illustrates the core flow using the four main resources:

How Traffic Flows in Kubernetes Gateway API

1. User Request enters the cluster and hits the Gateway (2).

2. The Gateway (2) looks at the attached HTTPRoute (3) to determine where to send the request.

3. The HTTPRoute (3) directs the traffic to the correct Service / Backend (4), which then delivers the request to your application.

4. This simple model ensures that the infrastructure team maintains control over the network edge (GatewayClass and Gateway), while the application team has the flexibility to manage their own routing rules (HTTPRoute) without needing cluster-wide permissions.

Demonstration of Kubernetes Gateway API

Step 1: Create a Sample Kubernetes Application exposed via Service

First we need to create a sample app we wish to expose via Gateway API. We will use this as an application for this demo. You may follow my previous tutorial on How to Expose a Kubernetes Service. Once you've completed that step, proceed to step 2.

Step 2: Install the Kubernetes Gateway API CRD

Gateway API objects aren't available as native Kubernetes objects. To enable them, we must install the Gateway API Custom Resource Definitions (CRDs) by running the following command.

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.3.0/standard-install.yaml

Step 3: Install a Kubernetes Gateway Controller

I've chosen istio as gateway controller. Run the following command to install istio gateway controller.

install istio command line

# curl -sL https://istio.io/downloadIstioctl | sh -
export PATH=$HOME/.istioctl/bin:$PATH

istioctl install --set profile=default

Step 4: Define a Kubernetes GatewayClass

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: default-gateway-class
spec:
  controllerName: istio.io/gateway-controller

# kubectl apply -f gateway-class.yaml

Step 5: Create a Kubernetes Gateway

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: httpd-gateway
spec:
  gatewayClassName: default-gateway-class
  listeners:
  - name: http
    protocol: HTTP
    port: 8080

# kubectl apply -f gateway.yaml

Step 6: Define HTTP Routes

Notice the code snippet I highlight. Since NGINX is resolving at "/" path, without this portion, the service can not be found because it will look for the path ".home/ui" in the NGINX server which is not currently served.

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: httpd-route
  namespace: non-prod
spec:
  hostnames:
    - home.cloudlet.io
  parentRefs:
    - name: httpd-gateway
      namespace: non-prod
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /home/ui
      filters:
        - type: URLRewrite
          urlRewrite:
            path:
              type: ReplacePrefixMatch
              replacePrefixMatch: /
      backendRefs:
        - name: httpd
          port: 8080

kubectl apply -f routes.yaml

Step 7: Verity and Test the Kubernetes Gateway API is Working

You should see something like the image below to ensure that your HTTPRoute is working and Gateway API is properly setup. Here are the commands that were used:

kubectl get gatewayclass
kubectl get gateway -o wide
kubectl get svc -o wide

check if the HTTPRoute is accessible

curl home.cloudlet.io:8080/home/ui