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, GRPCRoute).

Features¶

• Standard Gateway API implementation (GatewayClass, Gateway, HTTPRoute, GRPCRoute)
• Hot reload of tunnel configuration (no cloudflared restart required)
• Optional cloudflared lifecycle management via Helm SDK
• 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.0/standard-install.yaml

# 2. Install the controller
helm install cloudflare-tunnel-gateway-controller \
  oci://ghcr.io/lexfrei/charts/cloudflare-tunnel-gateway-controller \
  --namespace cloudflare-tunnel-system \
  --create-namespace \
  --set config.tunnelID=YOUR_TUNNEL_ID \
  --set config.apiToken=YOUR_API_TOKEN

# 3. 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.

Documentation Sections¶

Project Links¶

• GitHub Repository
• Issues
• Releases

License¶

BSD 3-Clause License - see LICENSE for details.