Getting Started with Kubernetes Gateway API

Introduction

Kubernetes Gateway API is a set of new network APIs designed for Kubernetes users to manage and configure load balancers, gateways, and traffic routing. As a modern alternative to Kubernetes networking resources, Gateway API provides more flexible and powerful features. Compared to the existing Ingress resources, Gateway API supports more complex traffic management and routing needs.

Core Concepts of Gateway API

GatewayClass: Defines different types of gateway implementations that can be provided by various vendors or plugins.
Gateway: Serves as the entry point for traffic into the cluster, defining the behavior and configuration of the load balancer.
HTTPRoute: Defines the routing rules for HTTP and HTTPS traffic.
TLSRoute, TCPRoute, and UDPRoute: Similar to HTTPRoute, these are used to define routing rules for TLS, TCP, and UDP traffic respectively.

Prerequisites

Before using Gateway API, you need to install a load balancer implementation. I recommend using MetalLB to associate addresses with Gateway resources. Additionally, ensure your Kubernetes version is above 1.25.

Installing Envoy Gateway

I prefer installing using a YAML file:

wget https://github.com/envoyproxy/gateway/releases/download/v1.0.1/install.yaml

Modify the image to one accessible from within China:

kubectl apply -f install.yaml

Next, we need to create a GatewayClass:

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: eg
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller
  parametersRef:
    group: gateway.envoyproxy.io
    kind: EnvoyProxy
    name: custom-proxy-config
    namespace: envoy-gateway-system

Usually, creating the following GatewayClass is sufficient:

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: eg
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller

However, due to difficulties accessing Docker Hub images in China, we need to create an EnvoyProxy:

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: custom-proxy-config
  namespace: envoy-gateway-system
spec:
  provider:
    type: Kubernetes
    kubernetes:
      envoyDeployment:
        replicas: 2
        container:
          image: hub.example.com/envoyproxy/envoy:distroless-v1.29.3
        patch:
          type: StrategicMerge
          value:
            spec:
              template:
                spec:
                  containers:
                    - name: shutdown-manager
                      image: hub.example.com/envoyproxy/gateway-dev:62ff3e7

For more details, refer to the official documentation.

Creating a Sample Application

First, create a Gateway:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: eg
  namespace: test
spec:
  gatewayClassName: eg
  listeners:
    - name: http
      protocol: HTTP
      port: 80

Then create an HTTPRoute:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: backend
  namespace: test
spec:
  parentRefs:
    - name: eg
  hostnames:
    - "www.example.com"
  rules:
    - backendRefs:
        - group: ""
          kind: Service
          name: backend
          port: 3000
          weight: 1
      matches:
        - path:
            type: PathPrefix
            value: /

Next, create a Service:

apiVersion: v1
kind: Service
metadata:
  name: backend
  namespace: test
  labels:
    app: backend
    service: backend
spec:
  ports:
    - name: http
      port: 3000
      targetPort: 3000
  selector:
    app: backend

Finally, create a Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: backend
  namespace: test
spec:
  replicas: 1
  selector:
    matchLabels:
      app: backend
      version: v1
  template:
    metadata:
      labels:
        app: backend
        version: v1
    spec:
      containers:
        - image: gcr.io/k8s-staging-gateway-api/echo-basic:v20231214-v1.0.0-140-gf544a46e
          imagePullPolicy: IfNotPresent
          name: backend
          ports:
            - containerPort: 3000
          env:
            - name: POD_NAME
              valueFrom:
                fieldRef:
                  fieldPath: metadata.name
            - name: NAMESPACE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace

Migrating from Ingress to Gateway API

If you are unsure how to configure Gateway API and want a quick migration, you can use the official Ingress2Gateway tool:

Just execute the following command to complete the migration:

ingress2gateway print --input_file=ingress.yaml

Final Words

Although Gateway API has been released to version v1.0.1, I still recommend using Ingress in production environments unless you have a pressing need.

Feel free to follow my blog at www.bboy.app

Have Fun

Bboysoul's Blog