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.5.1/standard-install.yaml

v1.5.0 is the minimum supported version

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. Installing the controller against an older Gateway API bundle (v1.4.x or earlier) leaves the manager unable to start because the watch target is missing. The controller is built and tested against v1.5.1, which is the recommended bundle.

If you are on an older Gateway API bundle, apply the v1.5.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.