Skip to content

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.25 or later
  • kubectl configured to access the cluster
  • Helm 3.x installed

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.1/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.

Two version thresholds: v1.5.0 to start, v1.6.x to be supported

The controller watches ListenerSet resources as part of its core reconcile loop. The listenersets.gateway.networking.k8s.io CRD entered the Standard channel in Gateway API v1.5.0, so with any older bundle (v1.4.x or earlier) the manager cannot start at all because the watch target is missing.

Being able to start is not the same as being supported: the controller is built and tested against v1.6.1, and its GatewayClass SupportedVersion condition compares the installed bundle's major.minor against that version — any other minor, including v1.5.x, is reported as SupportedVersion=False with reason UnsupportedVersion while the controller keeps running.

If you are on an older Gateway API bundle, apply the v1.6.1 standard bundle before installing this controller.

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

Controller and proxy

The controller manages Cloudflare-side tunnel ingress configuration via API; tunnel traffic itself is terminated by the in-process L7 proxy that the Helm chart deploys alongside the controller. Supply the tunnel token via proxy.tunnelTokenSecretRef — see the Helm values reference for the full set of proxy knobs.

Cloudflare API Token

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

Scope Permission Access
Account Cloudflare Tunnel Edit

Account ID

Account ID is auto-detected from the API token when not explicitly provided (works if the token has access to a single account).

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.