Prerequisites¶

Before installing the Cloudflare Tunnel Gateway Controller, ensure you have the following prerequisites in place.

Kubernetes Cluster¶

You need a Kubernetes cluster with:

• Kubernetes version 1.31 or later (see Compatibility)
• kubectl configured to access the cluster
• Helm 3.x installed

Compatibility¶

• Kubernetes 1.31 is the kubeVersion constraint in the chart's Chart.yaml, and Helm refuses to install on an older cluster. The floor comes from the Gateway API standard bundle the controller is built against, which an older API server rejects in part. The bundle ships a ValidatingAdmissionPolicy under admissionregistration.k8s.io/v1, which the API server serves from 1.30. Its TLSRoute CRD has a validation rule that calls the CEL isIP function, and a newly created CRD's rules can use that function from 1.31: the library was added in 1.30, but a 1.30 API server compiles new rules against the 1.29 function set. Upstream Gateway API states the same 1.31 requirement for TLSRoute.
• The chart's own optional ValidatingAdmissionPolicies use the same admissionregistration.k8s.io/v1 API, so the 1.31 floor covers them. They are rendered by ruleNameUniquenessPolicy.enabled and by hostnameOwnershipPolicy.enabled while hostnameOwnershipPolicy.admissionPolicy keeps its default of true.
• Upstream Gateway API supports at least the five most recent Kubernetes minor versions at the time of each release. The bundle's own version thresholds for this controller are described below.

Gateway API CRDs¶

The controller requires Gateway API Custom Resource Definitions (CRDs) to be installed in your cluster:

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

As of Gateway API v1.6 the standard bundle also installs the TCPRoute and UDPRoute CRDs (GA); this controller does not implement them — Cloudflare Tunnel exposes HTTP(S) only — so they are inert.

Cloudflare Account¶

You need a Cloudflare account with:

• A domain managed by Cloudflare (for DNS)
• Access to Cloudflare Zero Trust dashboard

Create Cloudflare Tunnel¶

Before deploying the controller, create a Cloudflare Tunnel:

1. Go to Cloudflare Zero Trust Dashboard
2. Navigate to Networks > Tunnels
3. Click Create a tunnel
4. Choose Cloudflared connector type
5. Name your tunnel and save:
   • Tunnel ID - UUID identifying the tunnel
   • Tunnel Token - Used by cloudflared to authenticate

Cloudflare API Token¶

Create an API token at Cloudflare Account API Tokens with the following permissions:

The same permission covers checking a dedicated Gateway's tunnel claim, which reads that tunnel's connector token from the Cloudflare API — see Proving a tunnel claim.

Creating the API Token¶

1. Go to Cloudflare Account API Tokens
2. Click Create Token
3. Click Get Started (on the right-hand side of Create Custom Token)
4. Configure the token:
   • Token name: cloudflare-tunnel-gateway-controller
   • Permissions: Account > Cloudflare Tunnel > Edit
5. Click Continue to summary and Create Token
6. Copy the token value (you won't be able to see it again)

Secrets Preparation¶

Prepare the following secrets for the controller:

API Token Secret¶

apiVersion: v1
kind: Secret
metadata:
  name: cloudflare-credentials
  namespace: cloudflare-tunnel-system
type: Opaque
stringData:
  api-token: "YOUR_API_TOKEN"

Tunnel Token Secret¶

The L7 proxy pod consumes this Secret via the chart's proxy.tunnelTokenSecretRef value. The Secret must exist before helm install (the chart references it but does not create it).

apiVersion: v1
kind: Secret
metadata:
  name: cloudflare-tunnel-token
  namespace: cloudflare-tunnel-system
type: Opaque
stringData:
  tunnel-token: "YOUR_TUNNEL_TOKEN"

Next Steps¶

Once you have all prerequisites in place, proceed to Installation.