Cloudflare Tunnel Gateway Controller¶

Kubernetes controller implementing Gateway API for Cloudflare Tunnel.

Enables routing traffic through Cloudflare Tunnel using standard Gateway API resources (Gateway, HTTPRoute).

Features¶

• Standard Gateway API implementation (GatewayClass, Gateway, HTTPRoute, GRPCRoute, ListenerSet)
• Hot reload of tunnel configuration (no cloudflared restart required)
• In-process L7 proxy embeds cloudflared transport (single data plane, no separate cloudflared deployment)
• Leader election for high availability deployments
• Multi-arch container images (amd64, arm64)
• Signed container images with cosign

L7 Proxy¶

An in-process L7 reverse proxy embedded inside cloudflared (via the OverrideProxy hook) provides full Gateway API HTTPRoute feature support:

• Header-based routing -- match requests by HTTP header values
• Query parameter matching -- route based on URL query parameters
• HTTP method matching -- differentiate GET, POST, PUT, and other methods
• Regex path matching -- match paths using regular expressions
• Request/response header modification -- add, set, or remove headers via filters
• Request redirects -- configure HTTP redirects declaratively
• URL rewriting -- rewrite hostname and/or path before forwarding
• Request mirroring -- mirror traffic to a secondary backend
• Weighted traffic splitting -- distribute traffic across backends by percentage
• Per-route timeouts -- configure request timeouts per routing rule

See the L7 Proxy Guide for setup and examples.

Quick Start¶

# 1. Install Gateway API CRDs
kubectl apply --filename https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.1/standard-install.yaml

# 2. Create the credentials and tunnel-token Secrets
kubectl create namespace cloudflare-tunnel-system
kubectl create secret generic cloudflare-credentials \
  --namespace cloudflare-tunnel-system \
  --from-literal=api-token="YOUR_API_TOKEN"
kubectl create secret generic cloudflare-tunnel-token \
  --namespace cloudflare-tunnel-system \
  --from-literal=tunnel-token="YOUR_TUNNEL_TOKEN"

# 3. Install the controller
helm install cloudflare-tunnel-gateway-controller \
  oci://ghcr.io/lexfrei/charts/cloudflare-tunnel-gateway-controller \
  --namespace cloudflare-tunnel-system \
  --set gatewayClassConfig.create=true \
  --set gatewayClassConfig.tunnelID=YOUR_TUNNEL_ID \
  --set gatewayClassConfig.cloudflareCredentialsSecretRef.name=cloudflare-credentials \
  --set proxy.tunnelTokenSecretRef.name=cloudflare-tunnel-token

# 4. Create HTTPRoute to expose your service
kubectl apply --filename - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-app
spec:
  parentRefs:
    - name: cloudflare-tunnel
      namespace: cloudflare-tunnel-system
  hostnames:
    - app.example.com
  rules:
    - backendRefs:
        - name: my-service
          port: 80
EOF

See Getting Started for detailed setup instructions, including full Secret creation and gatewayClassConfig reference.

Documentation Sections¶

Project Links¶

• GitHub Repository
• Issues
• Releases

License¶

BSD 3-Clause License - see LICENSE for details.