Skip to main content

​
Overview

Datum integrates with the Kubernetes Gateway API to provide advanced traffic management, routing, and ingress capabilities. This allows you to define how external and internal traffic connects to your services using standard, portable Kubernetes resources.
The Gateway API is a Kubernetes SIG project that provides a more expressive, extensible, and role-oriented API for traffic management compared to the traditional Ingress resource.

​
Key Features

Standard API

Use the official Kubernetes Gateway API resources (GatewayClass, Gateway, HTTPRoute)

TLS Management

Configure TLS certificates and termination for secure connections

Advanced Routing

Path-based, header-based, and weighted routing logic

Multi-Network Support

Integrate with Datum’s network services for cross-VPC routing

​
Gateway API Resources

The Gateway API defines several key resources:

​
GatewayClass

Defines a class of gateways managed by a specific controller: 
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: datum-gateway
spec:
  controllerName: datum.net/gateway-controller
  description: "Datum-managed gateway class"

​
Gateway

Defines load balancer configuration and listeners: 
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: production-gateway
  namespace: my-project
spec:
  gatewayClassName: datum-gateway
  
  listeners:
    # HTTPS listener
    - name: https
      protocol: HTTPS
      port: 443
      hostname: "*.example.com"
      tls:
        mode: Terminate
        certificateRefs:
          - name: example-com-tls
            kind: Secret
    
    # HTTP listener (redirect to HTTPS)
    - name: http
      protocol: HTTP
      port: 80
      hostname: "*.example.com"

​
HTTPRoute

Defines routing rules for HTTP(S) traffic: 
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-route
  namespace: my-project
spec:
  parentRefs:
    - name: production-gateway
  
  hostnames:
    - "api.example.com"
  
  rules:
    # Route /v1/* to v1 service
    - matches:
        - path:
            type: PathPrefix
            value: /v1/
      backendRefs:
        - name: api-v1
          port: 8080
    
    # Route /v2/* to v2 service
    - matches:
        - path:
            type: PathPrefix
            value: /v2/
      backendRefs:
        - name: api-v2
          port: 8080

​
Getting Started

1

Install Gateway API CRDs

The Gateway API custom resources need to be installed in your cluster:
# Install standard Gateway API CRDs
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/standard-install.yaml
If you’re using Datum Cloud, the Gateway API CRDs are pre-installed.
2

Create a Gateway

Define a gateway to handle incoming traffic:
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
  namespace: my-project
spec:
  gatewayClassName: datum-gateway
  listeners:
    - name: http
      protocol: HTTP
      port: 80
Apply the gateway:
kubectl apply -f gateway.yaml
3

Create an HTTPRoute

Define routing rules to direct traffic to your services:
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: web-route
  namespace: my-project
spec:
  parentRefs:
    - name: my-gateway
  rules:
    - backendRefs:
        - name: web-service
          port: 80
Apply the route:
kubectl apply -f httproute.yaml
4

Verify gateway status

Check that the gateway is ready:
kubectl get gateway my-gateway -n my-project
kubectl describe gateway my-gateway -n my-project
Look for the assigned IP address or hostname in the status.

​
TLS Configuration

Configure HTTPS with TLS certificate management:

​
Create TLS Secret

Store your TLS certificate and key: 
kubectl create secret tls example-com-tls \
  --cert=path/to/cert.pem \
  --key=path/to/key.pem \
  -n my-project

​
Configure TLS Termination

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: secure-gateway
  namespace: my-project
spec:
  gatewayClassName: datum-gateway
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      hostname: "example.com"
      tls:
        mode: Terminate
        certificateRefs:
          - name: example-com-tls
            kind: Secret

​
HTTP to HTTPS Redirect

Redirect HTTP traffic to HTTPS: 
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: http-redirect
  namespace: my-project
spec:
  parentRefs:
    - name: secure-gateway
      sectionName: http
  
  rules:
    - filters:
        - type: RequestRedirect
          requestRedirect:
            scheme: https
            statusCode: 301

​
Advanced Routing

​
Path-Based Routing

Route based on URL paths: 
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: app-routes
  namespace: my-project
spec:
  parentRefs:
    - name: my-gateway
  
  hostnames:
    - "app.example.com"
  
  rules:
    # API routes
    - matches:
        - path:
            type: PathPrefix
            value: /api/
      backendRefs:
        - name: api-service
          port: 8080
    
    # Admin routes
    - matches:
        - path:
            type: PathPrefix
            value: /admin/
      backendRefs:
        - name: admin-service
          port: 3000
    
    # Default route (static assets)
    - backendRefs:
        - name: frontend-service
          port: 80

​
Header-Based Routing

Route based on HTTP headers: 
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: header-based-routing
  namespace: my-project
spec:
  parentRefs:
    - name: my-gateway
  
  rules:
    # Route requests with "X-Beta: true" header to beta backend
    - matches:
        - headers:
            - type: Exact
              name: X-Beta
              value: "true"
      backendRefs:
        - name: beta-service
          port: 8080
    
    # Default backend
    - backendRefs:
        - name: stable-service
          port: 8080

​
Weighted Traffic Splitting

Distribute traffic across multiple backends: 
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: canary-deployment
  namespace: my-project
spec:
  parentRefs:
    - name: my-gateway
  
  rules:
    - backendRefs:
        # 90% traffic to stable version
        - name: app-v1
          port: 8080
          weight: 90
        
        # 10% traffic to canary version
        - name: app-v2
          port: 8080
          weight: 10

​
Request Header Manipulation

Add, modify, or remove headers: 
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: header-manipulation
  namespace: my-project
spec:
  parentRefs:
    - name: my-gateway
  
  rules:
    - filters:
        # Add custom headers
        - type: RequestHeaderModifier
          requestHeaderModifier:
            add:
              - name: X-Custom-Header
                value: "added-by-gateway"
            set:
              - name: X-Environment
                value: "production"
            remove:
              - X-Internal-Header
      
      backendRefs:
        - name: api-service
          port: 8080

​
Integration with Datum Workloads

Connect Gateway API to Datum workload instances: 
# Deploy a workload
apiVersion: workload.datum.net/v1alpha1
kind: Workload
metadata:
  name: web-app
  namespace: my-project
spec:
  template:
    spec:
      containers:
        - name: app
          image: gcr.io/my-project/web-app:v1.0
          ports:
            - containerPort: 8080
              name: http
  replicas: 3

---
# Create a Kubernetes Service pointing to workload instances
apiVersion: v1
kind: Service
metadata:
  name: web-app-service
  namespace: my-project
spec:
  selector:
    workload: web-app
  ports:
    - port: 80
      targetPort: 8080

---
# Route traffic to the service via Gateway
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: web-app-route
  namespace: my-project
spec:
  parentRefs:
    - name: production-gateway
  hostnames:
    - "app.example.com"
  rules:
    - backendRefs:
        - name: web-app-service
          port: 80

​
DNS Integration

Combine Gateway API with Datum’s DNS service:
1

Get Gateway IP address

kubectl get gateway my-gateway -n my-project -o jsonpath='{.status.addresses[0].value}'
2

Create DNS record

apiVersion: dns.networking.miloapis.com/v1alpha1
kind: DNSRecordSet
metadata:
  name: app-example-com
  namespace: my-project
spec:
  zoneRef:
    name: example-com
  name: app.example.com.
  type: A
  ttl: 300
  rrdatas:
    - "203.0.113.50"  # Gateway IP
3

Configure HTTPRoute hostname

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: app-route
  namespace: my-project
spec:
  parentRefs:
    - name: my-gateway
  hostnames:
    - "app.example.com"
  rules:
    - backendRefs:
        - name: app-service
          port: 80

​
Monitoring and Observability

Check gateway and route status: 
# View all gateways
kubectl get gateway -A

# Get detailed gateway status
kubectl describe gateway my-gateway -n my-project

# View HTTP routes
kubectl get httproute -n my-project

# Check route status
kubectl describe httproute web-route -n my-project
Gateway status includes:
  • Listener status and readiness
  • Assigned IP addresses or hostnames
  • TLS certificate status
  • Attached route references
HTTPRoute status includes:
  • Parent gateway references
  • Route acceptance status
  • Backend service health

​
Troubleshooting

Check the gateway controller logs:
kubectl logs -n datum-system -l app=gateway-controller
Common issues:
  • GatewayClass controller not installed or not running
  • Invalid listener configuration
  • Infrastructure provider issues (check workload operator logs)
Verify the route is attached to the gateway:
kubectl describe httproute <route-name> -n <namespace>
Check for:
  • Route acceptance status in conditions
  • Backend service exists and has endpoints
  • Hostname matches gateway listener hostname
  • Path matching rules are correct
Verify the TLS secret exists and is valid:
kubectl get secret <tls-secret-name> -n <namespace>
kubectl describe secret <tls-secret-name> -n <namespace>
Ensure:
  • Secret is type kubernetes.io/tls
  • Certificate matches the gateway hostname
  • Certificate is not expired
Check backend service and endpoints:
kubectl get service <backend-service> -n <namespace>
kubectl get endpoints <backend-service> -n <namespace>
Verify:
  • Backend service exists and has selectors matching workload pods
  • Workload instances are running and healthy
  • Service port matches HTTPRoute backendRef port

​
Best Practices

  • Create gateways within project namespaces for isolation
  • Use ReferenceGrant for cross-namespace routing if needed
  • Limit gateway permissions using RBAC
  • Create separate HTTPRoutes for different applications
  • Use meaningful route names that describe their purpose
  • Group related routes using labels
  • Use weighted traffic splitting for canary deployments
  • Gradually shift traffic from old to new versions
  • Monitor metrics before increasing traffic weights
  • Always use HTTPS for production traffic
  • Automate certificate renewal
  • Redirect HTTP to HTTPS
  • Use strong TLS configurations

​
Reference Documentation

Gateway API Docs

Official Kubernetes Gateway API documentation

Gateway API GitHub

Source code and examples

​
Next Steps

DNS Service

Integrate DNS records with your gateways

Workloads

Deploy backend services for your routes

Networks

Configure network connectivity for gateways

Security

Learn about securing your gateway configuration

Build docs developers (and LLMs) love

Get started for freeTalk to us