Gateways

Datum Cloud leverages the standard Kubernetes Gateway API to provide powerful, flexible traffic routing for your workloads. The Gateway API is the successor to Ingress and provides a more expressive, extensible way to manage ingress and egress traffic.

Overview

The Gateway API uses three main resources:

GatewayClass: Defines the type of gateway (provided by Datum)
Gateway: The actual load balancer instance
Routes: Routing rules (HTTPRoute, TCPRoute, TLSRoute, etc.)

Datum Cloud fully implements the Kubernetes Gateway API v1 specification, ensuring compatibility with standard tooling and practices.

GatewayClass

GatewayClass resources are provided by Datum and define the gateway implementation. Available GatewayClasses:

kubectl get gatewayclasses

NAME              CONTROLLER                      AGE
datum-gateway     datum.net/gateway-controller    30d

You reference the GatewayClass when creating a Gateway:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
spec:
  gatewayClassName: datum-gateway  # Use Datum's gateway implementation
  listeners:
    - name: http
      protocol: HTTP
      port: 80

Gateway

A Gateway resource represents an instance of a load balancer.

HTTP Gateway

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: web-gateway
  annotations:
    kubernetes.io/description: "Public HTTP gateway for web applications"
spec:
  gatewayClassName: datum-gateway
  
  listeners:
    # HTTP listener
    - name: http
      protocol: HTTP
      port: 80
      
      # Allow routes from same namespace
      allowedRoutes:
        namespaces:
          from: Same

HTTPS Gateway with TLS

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: secure-gateway
spec:
  gatewayClassName: datum-gateway
  
  listeners:
    # HTTPS listener
    - name: https
      protocol: HTTPS
      port: 443
      
      # TLS configuration
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: tls-cert
      
      # Hostname
      hostname: "*.example.com"
      
      allowedRoutes:
        namespaces:
          from: Same
    
    # HTTP redirect to HTTPS
    - name: http
      protocol: HTTP
      port: 80

Create TLS certificate secret:

kubectl create secret tls tls-cert \
  --cert=path/to/cert.pem \
  --key=path/to/key.pem

Multi-Protocol Gateway

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: multi-protocol-gateway
spec:
  gatewayClassName: datum-gateway
  
  listeners:
    # HTTP
    - name: http
      protocol: HTTP
      port: 80
    
    # HTTPS
    - name: https
      protocol: HTTPS
      port: 443
      tls:
        mode: Terminate
        certificateRefs:
          - name: tls-cert
    
    # TCP (for databases, etc.)
    - name: tcp
      protocol: TCP
      port: 5432

HTTPRoute

HTTPRoute defines how HTTP traffic is routed to backend services.

Basic HTTPRoute

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: web-app-route
spec:
  # Attach to gateway
  parentRefs:
    - name: web-gateway
      sectionName: http
  
  # Routing rules
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      
      backendRefs:
        - name: web-app
          port: 80

Advanced HTTPRoute

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-route
spec:
  parentRefs:
    - name: secure-gateway
      sectionName: https
  
  # Hostname matching
  hostnames:
    - api.example.com
  
  rules:
    # API v2 - /api/v2/*
    - matches:
        - path:
            type: PathPrefix
            value: /api/v2
      
      backendRefs:
        - name: api-v2
          port: 8080
    
    # API v1 - /api/v1/*
    - matches:
        - path:
            type: PathPrefix
            value: /api/v1
      
      backendRefs:
        - name: api-v1
          port: 8080
    
    # Default - redirect to v2
    - matches:
        - path:
            type: PathPrefix
            value: /api
      
      filters:
        - type: RequestRedirect
          requestRedirect:
            path:
              type: ReplacePrefixMatch
              replacePrefixMatch: /api/v2

Traffic Splitting (Canary Deployments)

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: canary-route
spec:
  parentRefs:
    - name: web-gateway
  
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      
      # Split traffic between versions
      backendRefs:
        # 90% to stable version
        - name: web-app-stable
          port: 80
          weight: 90
        
        # 10% to canary version
        - name: web-app-canary
          port: 80
          weight: 10

Header-Based Routing

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: header-route
spec:
  parentRefs:
    - name: web-gateway
  
  rules:
    # Route based on custom header
    - matches:
        - headers:
            - type: Exact
              name: X-Version
              value: beta
      
      backendRefs:
        - name: web-app-beta
          port: 80
    
    # Default route
    - matches:
        - path:
            type: PathPrefix
            value: /
      
      backendRefs:
        - name: web-app-stable
          port: 80

Request Manipulation

Request Header Modification

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: header-manipulation
spec:
  parentRefs:
    - name: web-gateway
  
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      
      filters:
        # Add headers
        - type: RequestHeaderModifier
          requestHeaderModifier:
            add:
              - name: X-Custom-Header
                value: datum-cloud
            set:
              - name: X-Environment
                value: production
            remove:
              - X-Debug
      
      backendRefs:
        - name: web-app
          port: 80

URL Rewriting

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: url-rewrite
spec:
  parentRefs:
    - name: web-gateway
  
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /old-api
      
      filters:
        # Rewrite /old-api/* to /api/*
        - type: URLRewrite
          urlRewrite:
            path:
              type: ReplacePrefixMatch
              replacePrefixMatch: /api
      
      backendRefs:
        - name: api-service
          port: 8080

TLS Configuration

TLS Termination

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: tls-gateway
spec:
  gatewayClassName: datum-gateway
  
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      
      # Terminate TLS at gateway
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: tls-cert
      
      hostname: "app.example.com"

TLS Passthrough

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: tls-passthrough-gateway
spec:
  gatewayClassName: datum-gateway
  
  listeners:
    - name: tls
      protocol: TLS
      port: 443
      
      # Pass TLS through to backend
      tls:
        mode: Passthrough
      
      hostname: "secure.example.com"

Multiple Certificates (SNI)

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: multi-cert-gateway
spec:
  gatewayClassName: datum-gateway
  
  listeners:
    # app.example.com
    - name: app-https
      protocol: HTTPS
      port: 443
      hostname: "app.example.com"
      tls:
        mode: Terminate
        certificateRefs:
          - name: app-tls-cert
    
    # api.example.com
    - name: api-https
      protocol: HTTPS
      port: 443
      hostname: "api.example.com"
      tls:
        mode: Terminate
        certificateRefs:
          - name: api-tls-cert

Managing Gateways

Create a Gateway

kubectl apply -f gateway.yaml

List Gateways

kubectl get gateways

View Gateway Status

kubectl describe gateway web-gateway

Get Gateway address:

kubectl get gateway web-gateway -o jsonpath='{.status.addresses[0].value}'

Update a Gateway

kubectl edit gateway web-gateway
# Or
kubectl apply -f gateway.yaml

Delete a Gateway

kubectl delete gateway web-gateway

Deleting a gateway will remove the load balancer and make all associated routes unavailable.

Managing Routes

Create an HTTPRoute

kubectl apply -f httproute.yaml

List HTTPRoutes

kubectl get httproutes

View HTTPRoute Details

kubectl describe httproute web-app-route

Update an HTTPRoute

kubectl edit httproute web-app-route
# Or
kubectl apply -f httproute.yaml

Delete an HTTPRoute

kubectl delete httproute web-app-route

Troubleshooting

Gateway not getting an address

# Check gateway status
kubectl describe gateway <gateway-name>

# Look for events
kubectl get events --field-selector involvedObject.name=<gateway-name>

# Check gateway controller logs
kubectl logs -n datum-system -l app=gateway-controller

Routes not working

# Verify HTTPRoute is attached to Gateway
kubectl describe httproute <route-name>

# Check backend service exists
kubectl get service <backend-service>

# Check allowedRoutes in Gateway
kubectl get gateway <gateway-name> -o yaml | grep -A 5 allowedRoutes

TLS certificate issues

# Verify secret exists
kubectl get secret tls-cert

# Check certificate contents
kubectl get secret tls-cert -o jsonpath='{.data.tls\.crt}' | base64 -d | openssl x509 -text -noout

# Verify secret is referenced correctly
kubectl get gateway <gateway-name> -o yaml | grep -A 5 certificateRefs

Best Practices

Use HTTPS

Always use TLS for production traffic. Terminate at the gateway for easier certificate management.

Hostname-based routing

Use distinct hostnames for different services (api.example.com, app.example.com).

Rate limiting

Implement rate limiting at the gateway level to protect backends.

Health checks

Configure backend health checks to automatically remove unhealthy instances.

Monitoring

Monitor gateway metrics (requests, latency, errors) with Prometheus.

Canary deployments

Use traffic splitting for gradual rollouts.

Common Patterns

Blue-Green Deployment

# Switch traffic instantly by changing backend
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: blue-green-route
spec:
  parentRefs:
    - name: web-gateway
  rules:
    - backendRefs:
        # Switch between blue and green
        - name: app-green  # Change to app-blue for rollback
          port: 80

API Gateway Pattern

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-gateway
spec:
  parentRefs:
    - name: api-gateway
  hostnames:
    - api.example.com
  rules:
    # Users service
    - matches:
        - path:
            type: PathPrefix
            value: /users
      backendRefs:
        - name: users-service
          port: 8080
    
    # Orders service
    - matches:
        - path:
            type: PathPrefix
            value: /orders
      backendRefs:
        - name: orders-service
          port: 8080
    
    # Products service
    - matches:
        - path:
            type: PathPrefix
            value: /products
      backendRefs:
        - name: products-service
          port: 8080

Next Steps

Workloads

Deploy backend services for your gateways

Networks

Configure network connectivity

Security

TLS and security best practices

Gateway API Docs

Official Kubernetes Gateway API documentation

Get Started

Core Concepts

Deployment

Operations

​Gateways

​Overview

​GatewayClass

​Gateway

​HTTP Gateway

​HTTPS Gateway with TLS

​Multi-Protocol Gateway

​HTTPRoute

​Basic HTTPRoute

​Advanced HTTPRoute

​Traffic Splitting (Canary Deployments)

​Header-Based Routing

​Request Manipulation

​Request Header Modification

​URL Rewriting

​TLS Configuration

​TLS Termination

​TLS Passthrough

​Multiple Certificates (SNI)

​Managing Gateways

​Create a Gateway

​List Gateways

​View Gateway Status

​Update a Gateway

​Delete a Gateway

​Managing Routes

​Create an HTTPRoute

​List HTTPRoutes

​View HTTPRoute Details

​Update an HTTPRoute

​Delete an HTTPRoute

​Troubleshooting

​Gateway not getting an address

​Routes not working

​TLS certificate issues

​Best Practices

Use HTTPS

Hostname-based routing

Rate limiting

Health checks

Monitoring

Canary deployments

​Common Patterns

​Blue-Green Deployment

​API Gateway Pattern

​Next Steps

Workloads

Networks

Security

Gateway API Docs

Build docs developers (and LLMs) love

Gateways

Overview

GatewayClass

Gateway

HTTP Gateway

HTTPS Gateway with TLS

Multi-Protocol Gateway

HTTPRoute

Basic HTTPRoute

Advanced HTTPRoute

Traffic Splitting (Canary Deployments)

Header-Based Routing

Request Manipulation

Request Header Modification

URL Rewriting

TLS Configuration

TLS Termination

TLS Passthrough

Multiple Certificates (SNI)

Managing Gateways

Create a Gateway

List Gateways

View Gateway Status

Update a Gateway

Delete a Gateway

Managing Routes

Create an HTTPRoute

List HTTPRoutes

View HTTPRoute Details

Update an HTTPRoute

Delete an HTTPRoute

Troubleshooting

Gateway not getting an address

Routes not working

TLS certificate issues

Best Practices

Common Patterns

Blue-Green Deployment

API Gateway Pattern

Next Steps