Skip to content

Gateway API

This section documents the Gateway API implementation in the Cloudflare Tunnel Gateway Controller.

Overview

The controller implements the Kubernetes Gateway API to manage an in-process L7 reverse proxy data plane. It watches Gateway and Route resources, pushes routing configuration to the in-cluster proxy, and registers tunnel endpoints with the Cloudflare API for DNS/edge connectivity. All L7 routing, matching, and filter logic executes in the in-cluster proxy; the Cloudflare API is used only for edge configuration.

Supported Resources

Resource API Version Status
GatewayClass gateway.networking.k8s.io/v1 Supported
Gateway gateway.networking.k8s.io/v1 Supported
HTTPRoute gateway.networking.k8s.io/v1 Supported
GRPCRoute gateway.networking.k8s.io/v1 Supported — see GRPCRoute
TCPRoute gateway.networking.k8s.io/v1alpha2 Not supported
TLSRoute gateway.networking.k8s.io/v1alpha2 Not supported
UDPRoute gateway.networking.k8s.io/v1alpha2 Not supported

Sections

  • Supported Resources

    Detailed feature support matrix for each Gateway API resource.

    Supported Resources

  • HTTPRoute

    HTTP routing examples and configuration patterns.

    HTTPRoute

  • ReferenceGrant

    Cross-namespace backend references and security.

    ReferenceGrant

  • Limitations

    Known limitations and workarounds.

    Limitations

How It Works

flowchart TB
    subgraph Kubernetes["Kubernetes Cluster"]
        GW[Gateway]
        HR[HTTPRoute]
        SVC[Services]
        CTRL[Controller]
        PROXY[Proxy Pod<br/>embedded cloudflared transport]
    end

    subgraph Cloudflare["Cloudflare Edge"]
        API[Cloudflare API]
        EDGE[Edge Network]
    end

    GW -->|watch| CTRL
    HR -->|watch| CTRL
    SVC -->|resolve| CTRL
    CTRL -->|configure| API
    CTRL -->|sync routes| PROXY
    API -->|tunnel config| PROXY
    PROXY -->|tunnel| EDGE
    EDGE -->|traffic| PROXY
    PROXY -->|route| SVC

Key Concepts

TLS Termination

Cloudflare Tunnel terminates TLS at Cloudflare's edge network; in-cluster TLS termination settings on Gateway listeners have no effect. Listener port and protocol still govern route binding per the Gateway API spec.

Full Sync

Any change to an HTTPRoute or GRPCRoute triggers a full desired-state rebuild. The merged config is pushed to the proxy replicas (via PUT /config) only when its content or the replica set changed, and the Cloudflare edge registration is rewritten only when the resulting ingress document differs from the deployed one — steady-state reconciles skip both writes. See Full Sync Behavior.