Helm Chart Reference¶

The Cloudflare Tunnel Gateway Controller is distributed as a Helm chart.

Installation¶

helm install cloudflare-tunnel-gateway-controller \
  oci://ghcr.io/lexfrei/charts/cloudflare-tunnel-gateway-controller \
  --namespace cloudflare-tunnel-system \
  --create-namespace \
  --values values.yaml

Chart Information¶

Field	Value
Chart Name	`cloudflare-tunnel-gateway-controller`
Repository	`oci://ghcr.io/lexfrei/charts/cloudflare-tunnel-gateway-controller`
Source	GitHub

Values Reference¶

For the complete and up-to-date list of all configuration values, see the Helm Chart README.

The README is auto-generated by helm-docs from the chart's values.yaml and Chart.yaml files.

Quick Reference¶

Essential Values¶

The chart requires both a credentials Secret (for the controller's Cloudflare API calls) and a tunnel-token Secret (consumed by the proxy pod). Create those out-of-band, then point the chart at them:

gatewayClassConfig:
  create: true
  tunnelID: "550e8400-e29b-41d4-a716-446655440000"   # Required
  cloudflareCredentialsSecretRef:
    name: cloudflare-credentials                       # Secret with key "api-token"

proxy:
  tunnelTokenSecretRef:
    name: cloudflare-tunnel-token                      # Secret with key "tunnel-token"

proxy.tunnelTokenSecretRef.name is mandatory in v3 — the chart's required check fails install otherwise.

High Availability¶

replicaCount: 2

leaderElection:
  enabled: true

proxy:
  replicas: 2
  tunnelTokenSecretRef:
    name: cloudflare-tunnel-token

podDisruptionBudget:
  enabled: true
  minAvailable: 1

Monitoring¶

serviceMonitor:
  enabled: true
  interval: 30s
  labels:
    release: prometheus

Example Values Files¶

The chart includes example values files in the examples/ directory:

File	Description
`basic-values.yaml`	Minimal configuration
`production-values.yaml`	Production HA setup
`external-secrets-values.yaml`	External Secrets Operator integration

Upgrading¶

helm upgrade cloudflare-tunnel-gateway-controller \
  oci://ghcr.io/lexfrei/charts/cloudflare-tunnel-gateway-controller \
  --namespace cloudflare-tunnel-system \
  --values values.yaml

Version Pinning¶

Pin to specific versions in production:

helm upgrade cloudflare-tunnel-gateway-controller \
  oci://ghcr.io/lexfrei/charts/cloudflare-tunnel-gateway-controller \
  --version 1.0.0 \
  --namespace cloudflare-tunnel-system \
  --values values.yaml

Uninstalling¶

helm uninstall cloudflare-tunnel-gateway-controller \
  --namespace cloudflare-tunnel-system

Cleanup

Uninstalling the Helm release removes the controller and proxy pods. The tunnel configuration in Cloudflare will remain. To fully clean up, delete the tunnel from the Cloudflare dashboard.

CRDs¶

The chart installs two CRDs: GatewayClassConfig and ExternalBackend. Gateway API CRDs must be installed separately:

kubectl apply --filename https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.1/standard-install.yaml

Components¶

The chart renders two deployments:

Controller (<release>-cloudflare-tunnel-gateway-controller) — watches Gateway / HTTPRoute / GRPCRoute / ListenerSet resources and pushes config to both Cloudflare's tunnel-ingress API and the in-cluster L7 proxy. HTTPRoute and GRPCRoute both route through the proxy at runtime.
Proxy (<release>-cloudflare-tunnel-gateway-controller-proxy) — embeds cloudflared transport in-process (via the vendored fork's OverrideProxy hook) and terminates tunnel traffic. Requires proxy.tunnelTokenSecretRef.name to be set; the chart fails install otherwise.

Helm Chart Testing¶

Test the chart locally:

# Lint
helm lint charts/cloudflare-tunnel-gateway-controller

# Template
helm template test charts/cloudflare-tunnel-gateway-controller \
  --values charts/cloudflare-tunnel-gateway-controller/examples/basic-values.yaml

# Unit tests
helm unittest charts/cloudflare-tunnel-gateway-controller