Skip to main content

​
Overview

Datum Cloud uses the Kubernetes Gateway API to expose services and manage ingress traffic. The Gateway API provides a modern, extensible way to configure load balancing, routing, and traffic management.
Gateway API resources are part of the standard Kubernetes Gateway API (gateway.networking.k8s.io/v1).

​
Gateway API Resources

The Gateway API consists of three main resources:
  1. GatewayClass - Defines the gateway implementation (e.g., GCP Load Balancer, Nginx)
  2. Gateway - Deploys a load balancer instance
  3. HTTPRoute - Routes HTTP traffic to services

​
GatewayClass

Defines the class of gateway implementation to use. 
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: datum-gateway
spec:
  controllerName: datum.net/gateway-controller
  description: "Datum Cloud gateway implementation"

​
GatewayClass Fields

​
spec.controllerName
string
required
The name of the controller that implements this gateway class.Example: datum.net/gateway-controller
​
spec.description
string
Human-readable description of the gateway class.
​
spec.parametersRef
object
Reference to provider-specific configuration parameters.

​
Gateway

Deploys an instance of a load balancer. 
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
  namespace: project-myproject
spec:
  gatewayClassName: datum-gateway
  listeners:
  - name: http
    protocol: HTTP
    port: 80
  - name: https
    protocol: HTTPS
    port: 443
    tls:
      mode: Terminate
      certificateRefs:
      - name: tls-cert

​
Gateway Metadata

​
metadata.name
string
required
The name of the gateway. Must be unique within the namespace.
​
metadata.namespace
string
required
The project namespace. Format: project-<project-name>

​
Gateway Spec

​
spec.gatewayClassName
string
required
Reference to the GatewayClass to use.
​
spec.listeners
array
required
List of listeners that define how to accept traffic.
​
spec.addresses
array
Requested addresses for the gateway (e.g., static IPs).

​
Gateway Status

​
status.conditions
array
Conditions describing the gateway state.Common conditions:
  • Accepted: Gateway configuration is valid
  • Programmed: Gateway is configured in the data plane
  • Ready: Gateway is ready to accept traffic
​
status.addresses
array
Assigned addresses for the gateway.Each address includes:
  • type: Address type (IPAddress, Hostname)
  • value: The actual address value
​
status.listeners
array
Status for each listener.Each listener status includes:
  • name: Listener name
  • supportedKinds: Route kinds this listener supports
  • attachedRoutes: Number of routes attached
  • conditions: Listener-specific conditions

​
HTTPRoute

Routes HTTP traffic from a Gateway to backend services. 
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: web-route
  namespace: project-myproject
spec:
  parentRefs:
  - name: my-gateway
  hostnames:
  - www.example.com
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api
    backendRefs:
    - name: api-service
      port: 8080
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - name: web-service
      port: 80

​
HTTPRoute Metadata

​
metadata.name
string
required
The name of the route. Must be unique within the namespace.
​
metadata.namespace
string
required
The project namespace. Format: project-<project-name>

​
HTTPRoute Spec

​
spec.parentRefs
array
required
References to Gateways this route should attach to.
​
spec.hostnames
array
Hostnames this route should match.Examples: www.example.com, *.example.com
​
spec.rules
array
List of routing rules.

​
HTTPRoute Status

​
status.parents
array
Status for each parent Gateway.Each parent status includes:
  • parentRef: Reference to the parent Gateway
  • conditions: Route attachment conditions
  • controllerName: Controller managing this route

​
Examples

​
Simple HTTP Gateway

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: http-gateway
  namespace: project-myproject
spec:
  gatewayClassName: datum-gateway
  listeners:
  - name: http
    protocol: HTTP
    port: 80
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-app
  namespace: project-myproject
spec:
  parentRefs:
  - name: http-gateway
  rules:
  - backendRefs:
    - name: my-service
      port: 8080

​
HTTPS Gateway with TLS

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: https-gateway
  namespace: project-myproject
spec:
  gatewayClassName: datum-gateway
  listeners:
  - name: https
    protocol: HTTPS
    port: 443
    hostname: www.example.com
    tls:
      mode: Terminate
      certificateRefs:
      - name: example-com-tls
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: secure-app
  namespace: project-myproject
spec:
  parentRefs:
  - name: https-gateway
  hostnames:
  - www.example.com
  rules:
  - backendRefs:
    - name: web-service
      port: 80

​
Advanced Routing with Path-Based Rules

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: multi-service-route
  namespace: project-myproject
spec:
  parentRefs:
  - name: my-gateway
  hostnames:
  - app.example.com
  rules:
  # API traffic
  - matches:
    - path:
        type: PathPrefix
        value: /api/v1
    backendRefs:
    - name: api-v1-service
      port: 8080
  
  # Admin traffic
  - matches:
    - path:
        type: PathPrefix
        value: /admin
    filters:
    - type: RequestHeaderModifier
      requestHeaderModifier:
        add:
        - name: X-Admin-Request
          value: "true"
    backendRefs:
    - name: admin-service
      port: 9000
  
  # Default traffic
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - name: frontend-service
      port: 80

​
Traffic Splitting (Canary Deployment)

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: canary-route
  namespace: project-myproject
spec:
  parentRefs:
  - name: my-gateway
  rules:
  - backendRefs:
    - name: stable-service
      port: 8080
      weight: 90
    - name: canary-service
      port: 8080
      weight: 10

​
kubectl Commands

​
Gateway Commands

# List gateways
kubectl get gateways -n project-myproject

# Get gateway details
kubectl describe gateway my-gateway -n project-myproject

# Get gateway IP address
kubectl get gateway my-gateway -n project-myproject \
  -o jsonpath='{.status.addresses[0].value}'

# Create gateway
kubectl apply -f gateway.yaml

# Delete gateway
kubectl delete gateway my-gateway -n project-myproject

​
HTTPRoute Commands

# List routes
kubectl get httproutes -n project-myproject

# Get route details
kubectl describe httproute web-route -n project-myproject

# Check route status
kubectl get httproute web-route -n project-myproject -o yaml

# Create route
kubectl apply -f httproute.yaml

# Delete route
kubectl delete httproute web-route -n project-myproject

​
GatewayClass Commands

# List gateway classes
kubectl get gatewayclasses

# Get gateway class details
kubectl describe gatewayclass datum-gateway
  • Workload - Deploy applications to expose via gateways
  • Network - Network infrastructure for gateway connectivity
  • Project - Gateways are scoped to projects

​
Troubleshooting

Check:
  1. View gateway status: kubectl describe gateway <name> -n <namespace>
  2. Check gateway conditions for errors
  3. Verify GatewayClass controller is running
  4. Check cloud provider quota for load balancers
Check:
  1. Verify route is attached: kubectl get httproute <name> -n <namespace> -o yaml
  2. Check status.parents for attachment status
  3. Verify backend service exists and has endpoints
  4. Test with curl using the gateway IP address
Check:
  1. Verify the certificate secret exists: kubectl get secret <cert-name> -n <namespace>
  2. Check secret has tls.crt and tls.key data
  3. Verify hostname matches certificate CN/SAN
  4. Check gateway listener conditions for TLS errors

Build docs developers (and LLMs) love

Get started for freeTalk to us