Skip to content

Network: Gateway API (Traefik)

What is the Kubernetes Gateway API?

The Kubernetes Gateway API is the next-generation standard for service networking in Kubernetes, superseding the Ingress resource. It introduces role-oriented resources (GatewayClass, Gateway, HTTPRoute, GRPCRoute, etc.) that cleanly separate infrastructure operations (defining listening ports and TLS certificates) from application routing (defining paths, headers, and target services).

kubara supports Gateway API alongside traditional Ingress. When configured with Traefik, Traefik functions as both the Gateway controller and Ingress controller simultaneously.

Architecture & Dual-Provider Operation

When Gateway API is enabled:

  1. Traefik runs both providers in parallel:
  2. providers.kubernetesGateway: Watches and reconciles Gateway and HTTPRoute resources.

  3. providers.kubernetesIngress & providers.kubernetesCRD: Remain active so non-migrated endpoints (such as cert-manager HTTP-01 challenge ingresses, OpenBao ingress, and Traefik dashboard IngressRoute at /traefik) continue to function without interruption.

  4. Automated TLS provisioning:

  5. Traefik provisions a cert-manager Certificate (traefik-gateway-tls) for the Gateway's HTTPS listener.

  6. The listener references traefik-gateway-tls in certificateRefs, which is also set as Traefik's tlsStore.default.defaultCertificate.

  7. Cross-Namespace Route Attachment:

  8. The HTTPS listener is configured with allowedRoutes.namespaces.from: All, enabling HTTPRoute resources across any namespace (argocd, traefik, monitoring, or application workloads) to attach to the central Gateway.

  9. Namespace-Local ForwardAuth Middlewares:

  10. In Gateway API, HTTPRoute filter references (ExtensionRef) are restricted to local object references (LocalObjectReference) and cannot span across namespaces.

  11. To support OAuth2 Proxy authentication, kubara renders a namespace-local <release>-gateway-auth Middleware into each service's namespace (and argocd-gateway-auth in argocd), referencing the central OAuth2 Proxy service.

  12. Automatic DNS Synchronization:

  13. ExternalDNS is automatically configured with --source=gateway-httproute, inspecting hostnames defined on HTTPRoute resources and syncing DNS records with your cloud provider.

Configuration in config.yaml

To enable Gateway API on your cluster, configure the .cluster.networking block in config.yaml:

clusters:
  - name: my-cluster
    stage: dev
    dnsName: my-cluster.example.com

    networking:
      type: gateway # selects Gateway API ("ingress" or "gateway")
      gateway:
        name: traefik # name of the Gateway resource
        namespace: traefik # namespace where Traefik is deployed
        sectionName: websecure # listener section (defaults to websecure)

    services:
      traefik:
        status: enabled
      cert-manager:
        status: enabled
      oauth2-proxy:
        status: enabled

Configuration Options

Field Type Description
networking.type string ingress (default) or gateway. Sets the active routing API for catalog templates.
networking.ingress.className string Ingress class name (defaults to traefik). Used when type: ingress.
networking.gateway.name string Name of the parent Gateway resource. Required when type: gateway.
networking.gateway.namespace string Namespace of the parent Gateway resource (must be traefik for the bundled Traefik setup).
networking.gateway.sectionName string Optional listener name on the Gateway (defaults to websecure).

Service-Level Overrides

Individual services can override the cluster Gateway reference or add custom routing annotations under services.<service>.networking:

services:
  custom-service:
    status: enabled
    networking:
      gateway:
        name: custom-gateway
        namespace: custom-namespace
        sectionName: https
      annotations:
        custom.annotation/key: "value"

A service-level gateway override completely replaces the cluster Gateway reference for that service and requires networking.type: gateway.

Workflow & Deployment

  1. Update config.yaml: Set networking.type: gateway with the corresponding gateway block.

  2. Generate platform manifests: Run kubara generate to re-render Helm values and manifests: 

    kubara generate

  3. Review generated artifacts:

  4. In platform-configs/<cluster>/helm/traefik/values.generated.yaml, verify that providers.kubernetesGateway.enabled: true and the gateway block are rendered.

  5. In platform services (argo-cd, homer-dashboard, kube-prometheus-stack, longhorn, kyverno-policy-reporter, oauth2-proxy), verify that ingress.enabled: false and gatewayRoutes / httproute are generated.

  6. Deploy via GitOps: Commit and push your changes. Argo CD will synchronize:

  7. Gateway API Standard CRDs (installed via bootstrap-crds).
  8. Traefik Gateway, listeners, and certificates.
  9. HTTPRoute resources attaching to the Gateway.