Working with Gateway API

1. Installing Gateway API CRDs

Example: Install Gateway API CRDs using kubectl

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/latest/download/crds.yaml

Resource	Description	Version
GatewayClass	Defines a class of Gateways	`v1beta1`
Gateway	Represents a network gateway	`v1beta1`
HTTPRoute	Routes HTTP traffic to services	`v1beta1`
TLSRoute	Routes TLS traffic to services	`v1beta1`
ReferenceGrant	Allows cross-namespace references	`v1beta1`

Note: Ensure your Kubernetes cluster has version 1.20 or higher to support Gateway API resources.

2. Creating GatewayClass Resource

Field	Description	Required	Example Value
apiVersion	API version of the GatewayClass resource	Yes	`gateway.networking.k8s.io/v1beta1`
kind	Kind of the Kubernetes resource	Yes	`GatewayClass`
metadata.name	Name of the GatewayClass resource	Yes	`my-gateway-class`
spec.controller	Identifier for the controller that manages this GatewayClass	Yes	`example.com/gateway-controller`
spec.description	Human-readable description of the GatewayClass	No	`Production gateway class for external traffic`
spec.parametersRef	Reference to a ConfigMap or Secret containing parameters for the controller	No	`{ name: "gateway-config", namespace: "default" }`

Example: Creating a GatewayClass Resource

apiVersion: gateway.networking.k8s.io/v1beta1
kind: GatewayClass
metadata:
  name: my-gateway-class
spec:
  controller: example.com/gateway-controller
  description: Production gateway class for external traffic

Note: The controller field must match the value set by the Gateway controller to manage this GatewayClass.

3. Creating Gateway Resource

Field	Description	Example Value	Required
apiVersion	API version of the Gateway resource	`gateway.networking.k8s.io/v1`	Yes
kind	Type of the Kubernetes resource	`Gateway`	Yes
metadata.name	Name of the Gateway resource	`my-gateway`	Yes
metadata.namespace	Namespace where the Gateway is created	`default`	No
spec.listeners	List of listeners that define how traffic is handled	`[{name: "http", port: 80, protocol: "HTTP"}]`	Yes
spec.gatewayClassName	Name of the GatewayClass that this Gateway belongs to	`my-gateway-class`	Yes

Example: Basic Gateway Resource

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

Note: The Gateway resource must be managed by a controller that supports the Gateway API. Ensure that the appropriate GatewayClass is configured and available in your cluster.

4. Configuring HTTPRoute

Field	Description	Example	Notes
hostnames	List of hostnames to match	`["example.com"]`	Optional. If omitted, matches all hostnames
rules	Rules to match and route traffic	`[{matches: [{path: {value: "/api"}}], backendRefs: [{name: "service1", port: 80}]}]`	Required. Defines routing logic
parentRefs	References to Gateway resources	`[{name: "my-gateway"}]`	Required. Points to the Gateway that this route belongs to

Example: Basic HTTPRoute Configuration

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: example-route
spec:
  parentRefs:
    - name: my-gateway
  hostnames:
    - example.com
  rules:
    - matches:
        - path:
            value: /api
      backendRefs:
        - name: api-service
          port: 80

Example: Route with Multiple Rules

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: multi-rule-route
spec:
  parentRefs:
    - name: my-gateway
  rules:
    - matches:
        - path:
            value: /api/v1/users
      backendRefs:
        - name: user-service
          port: 80
    - matches:
        - path:
            value: /api/v1/orders
      backendRefs:
        - name: order-service
          port: 80

Note: The HTTPRoute must be in the same namespace as the Gateway or a namespace that is allowed by the Gateway's allowedRoutes configuration.

Warning: If hostnames is not specified, the route will match all hostnames. This can lead to unintended traffic routing if multiple services are exposed on the same Gateway.

5. Using TCPRoute

Field	Description	Example
apiVersion	API version of the TCPRoute resource	`gateway.networking.k8s.io/v1beta1`
kind	Kind of the resource	`TCPRoute`
metadata.name	Name of the TCPRoute	`tcp-route-example`
spec.parentRefs	References to Gateway resources that this route belongs to	`[ { "name": "my-gateway" } ]`
spec.rules	List of rules to match and forward TCP traffic	`[ { "backendRefs": [ { "name": "tcp-service", "port": 8080 } ] } ]`

Example: Basic TCPRoute Configuration

apiVersion: gateway.networking.k8s.io/v1beta1
kind: TCPRoute
metadata:
  name: tcp-route-example
spec:
  parentRefs:
  - name: my-gateway
  rules:
  - backendRefs:
    - name: tcp-service
      port: 8080

Note: The TCPRoute is part of the Gateway API, which provides a standardized way to configure traffic routing in Kubernetes.

6. Using TLSRoute

Field	Description	Example
apiVersion	API version of the TLSRoute resource	`gateway.networking.k8s.io/v1beta1`
kind	Kind of the resource	`TLSRoute`
metadata.name	Name of the TLSRoute	`tls-example`
spec.hostnames	List of hostnames to match for TLS termination	`["example.com", "api.example.com"]`
spec.parentRefs	References to Gateway resources that this route belongs to	`[{name: "my-gateway"}]`
spec.tls	Configuration for TLS settings	`{ "mode": "Terminate", "certificateRef": { "name": "tls-cert" } }`

Example: TLSRoute with Certificate Reference

apiVersion: gateway.networking.k8s.io/v1beta1
kind: TLSRoute
metadata:
  name: tls-example
spec:
  hostnames:
    - example.com
    - api.example.com
  parentRefs:
    - name: my-gateway
  tls:
    mode: Terminate
    certificateRef:
      name: tls-cert

Note: The TLSRoute resource is part of the Gateway API and allows you to define TLS termination for specific hostnames.

7. Setting Gateway Listeners

Field	Description	Values	Notes
name	Name of the listener	`string`	Must be unique within the Gateway
port	Port number to listen on	`int`	Valid range: 1-65535
protocol	Protocol to use for the listener	`TCP`, `UDP`, `HTTP`, `HTTPS`	Must match the Gateway's supported protocols
hostname	Hostname to match for the listener	`string`	Optional; can be used for host-based routing
tls	Transport Layer Security configuration	`struct`	Optional; used for HTTPS listeners

Example: Basic HTTP Listener

listeners:
- name: http-listener
  port: 80
  protocol: HTTP

Example: HTTPS Listener with TLS

listeners:
- name: https-listener
  port: 443
  protocol: HTTPS
  tls:
    mode: Terminate
    certificateRef:
      name: my-tls-cert

8. Configuring Backend References

Field	Description	Values	Notes
backendRef	Reference to a backend service	`core/v1.Service` or `networking/v1.Ingress`	Required field for routing rules
backendRef.name	Name of the referenced backend	`string`	Must match a valid resource name
backendRef.namespace	Namespace of the referenced backend	`string`	Defaults to current namespace if not specified
backendRef.port	Port number to route traffic to	`int`	Must be a valid port in the backend service
backendRef.weight	Weight for traffic distribution	`int`	Used in weighted routing; default is 1

Example: Basic Backend Reference

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: example-route
spec:
  parentRefs:
    - name: example-gateway
  rules:
    - backendRefs:
        - backendRef:
            name: my-service
            port: 80

Example: Weighted Backend Routing

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: weighted-route
spec:
  parentRefs:
    - name: example-gateway
  rules:
    - backendRefs:
        - backendRef:
            name: service-v1
            port: 80
            weight: 70
        - backendRef:
            name: service-v2
            port: 80
            weight: 30

Note: Backend references must point to valid Kubernetes services or ingresses. Ensure that the referenced backend is accessible and properly configured.

9. Using Request Matching

Field	Description	Example
method	HTTP method to match	`GET`
path	Path to match in the request	`/api/v1/users`
headers	Headers to match in the request	`{"Authorization": "Bearer.*"}`
queryParams	Query parameters to match	`{"format": "json"}`

Example: Matching a GET request with specific headers

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: example-route
spec:
  parentRefs:
  - name: example-gateway
  rules:
  - matches:
    - method: GET
      path: /api/v1/users
      headers:
        Authorization:
          regex: "Bearer .*"

10. Implementing Traffic Splitting

Field	Description	Example
kind	Resource type, must be `HTTPRoute`	`HTTPRoute`
spec.parentRefs	Reference to Gateway that this route attaches to	`[ { "name": "my-gateway", "namespace": "default" } ]`
spec.hostnames	Hostnames to match for routing (optional)	`[ "api.example.com" ]`
spec.rules	List of routing rules to apply	`[ { "matches": [ ... ], "backendRefs": [ ... ] } ]`

Example: Basic Traffic Splitting Rule

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: traffic-splitting-route
spec:
  parentRefs:
  - name: my-gateway
  rules:
  - matches:
    - path:
        type: Prefix
        value: /api/v1/
    backendRefs:
    - name: service-v1
      port: 80
      weight: 70
    - name: service-v2
      port: 80
      weight: 30

Note: The weight field determines how much traffic is routed to each backend. Values are relative, so 70 and 30 means 70% to v1, 30% to v2.

Key Concepts

Weighted routing allows distributing traffic between multiple services based on percentages.
backendRefs can reference different versions of the same service for A/B testing or gradual rollouts.
Each backendRef can have a weight value between 0 and 100.

11. Understanding Gateway API vs Ingress

Gateway API vs Ingress

Gateway API is a newer, more flexible Kubernetes networking API designed to be extensible and support a wide range of use cases including HTTP, TCP, UDP, and TLS.
Ingress is the older, more limited API for routing external traffic to services in Kubernetes.
Gateway API supports multiple protocols (HTTP, HTTPS, TCP, UDP) and provides better support for TLS termination and routing rules.
Ingress is primarily focused on HTTP/HTTPS traffic and has limited support for other protocols.
Gateway API introduces concepts like GatewayClass, Gateway, and Route to provide more granular control over traffic routing.
Ingress uses Ingress and IngressClass resources to define routing rules.
Gateway API is designed to be a superset of Ingress, aiming to eventually replace it with more features and extensibility.
Ingress is widely adopted and supported by many Ingress controllers, while Gateway API is still in beta and requires a compatible controller.

Feature	Gateway API	Ingress
Protocol Support	`HTTP, HTTPS, TCP, UDP`	`HTTP, HTTPS`
Resource Types	`GatewayClass, Gateway, HTTPRoute, TCPRoute`	`Ingress, IngressClass`
Extensibility	Highly extensible with CRDs	Limited extensibility
TLS Handling	Advanced TLS support including SNI	Basic TLS support
Adoption Status	BETA	Stable and widely adopted

Note: The Gateway API is designed to evolve and eventually supersede the Ingress API, offering more flexibility and features for modern networking needs.