Skip to content
Cloudflared icon
v1.5.21App: v2026.10.1Pinned DigestS3 Backup Ready

Production Helm chart • Apache-2.0 • Zero-Root • Verified on Kubernetes v1.33-v1.36+

Cloudflare Tunnel (cloudflared) Helm Chart

Deploy Cloudflare Tunnel on Kubernetes using the official cloudflare/cloudflared Docker image. Secure, outbound-only connections between your cluster and Cloudflare's network require no open ports or public IP.

Features

  • Zero-trust networking — no inbound firewall rules needed
  • Remotely-managed — configure routes in the Cloudflare dashboard
  • Quick tunnel default — installable demo and smoke-test mode without a token
  • High availability ready — production values can enable 2+ replicas with PodDisruptionBudget
  • Prometheus metrics — /ready and /metrics on port 2000
  • ServiceMonitor — optional Prometheus Operator integration
  • Existing secrets — bring your own Secret for the tunnel token
  • External Secrets — optional External Secrets Operator integration for tunnel tokens
  • Quick tunnel mode — optional ephemeral mode for demos and smoke tests

Architecture

Cloudflared initiates outbound connections from the Deployment to Cloudflare's edge. Managed tunnels and URL-mode quick tunnels proxy requests to the configured origin URL, which can be a cluster-internal Service. The default quick tunnel uses cloudflared's built-in hello-world origin and does not use a tunnel token or cluster origin Service. The chart does not render Kubernetes Ingress or configure Cloudflare hostnames and routes. See DESIGN.md for the topology and responsibility boundaries.

Installation

HTTPS repository:

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install cloudflared helmforge/cloudflared -f values.yaml

OCI registry:

helm install cloudflared oci://ghcr.io/helmforgedev/helm/cloudflared -f values.yaml

Quick Start

Default installs run an ephemeral quick tunnel for demos and smoke tests. For a managed Cloudflare Tunnel, create a tunnel in the Cloudflare dashboard under Networks → Tunnels, copy the tunnel token, and deploy:

# values.yaml
tunnel:
  quickTunnel:
    enabled: false
  token: "eyJhIjoiY2Y..."

Then configure public hostnames in the dashboard to route traffic to your Kubernetes services (for example, http://my-service.default.svc:80).

Using an Existing Secret

tunnel:
  quickTunnel:
    enabled: false
  existingSecret: my-tunnel-secret
  existingSecretKey: token

Create the secret beforehand:

kubectl create secret generic my-tunnel-secret \
  --from-literal=token=eyJhIjoiY2Y...

External Secrets

When your cluster already runs External Secrets Operator, render an ExternalSecret for the tunnel token and point the Deployment at the generated Kubernetes Secret:

tunnel:
  quickTunnel:
    enabled: false
  existingSecret: cloudflared-tunnel-token

externalSecrets:
  enabled: true
  secretStoreRef:
    name: platform-secrets
    kind: ClusterSecretStore
  data:
    - secretKey: token
      remoteRef:
        key: cloudflared/tunnel
        property: token

Quick Tunnel Mode

Quick tunnel mode runs an ephemeral tunnel without a Cloudflare-managed tunnel token. It is enabled by default for tokenless installs. Use it for demos and smoke tests only; production deployments should set tunnel.quickTunnel.enabled=false and use tunnel.token or tunnel.existingSecret.

tunnel:
  quickTunnel:
    enabled: true

Production Example

tunnel:
  quickTunnel:
    enabled: false
  existingSecret: cloudflare-tunnel

replicaCount: 2

pdb:
  enabled: true
  minAvailable: 1

resources:
  requests:
    cpu: 50m
    memory: 64Mi
  limits:
    memory: 128Mi

serviceMonitor:
  enabled: true
  labels:
    release: prometheus

topologySpreadConstraints:
  - maxSkew: 1
    topologyKey: kubernetes.io/hostname
    whenUnsatisfiable: DoNotSchedule
    labelSelector:
      matchLabels:
        app.kubernetes.io/name: cloudflared
Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

|-----|---------|-------------| | tunnel.token | "" | Tunnel token from Cloudflare dashboard | | tunnel.existingSecret | "" | Existing secret with tunnel token | | tunnel.existingSecretKey | token | Key in the existing secret | | tunnel.quickTunnel.enabled | true | Enable ephemeral quick tunnel mode for demos and smoke tests | | tunnel.quickTunnel.helloWorld | true | Use cloudflared's built-in hello-world origin | | tunnel.quickTunnel.url | http://localhost:8080 | Origin URL for quick tunnel URL mode | | externalSecrets.enabled | false | Render an ExternalSecret for the tunnel token | | externalSecrets.secretStoreRef.name | "" | SecretStore or ClusterSecretStore name | | externalSecrets.secretStoreRef.kind | SecretStore | Secret store kind | | externalSecrets.data | [] | ExternalSecret data mappings | | replicaCount | 1 | Number of replicas | | cloudflared.logLevel | info | Log level | | cloudflared.noAutoupdate | true | Disable auto-update | | cloudflared.metricsPort | 2000 | Metrics listen port | | cloudflared.extraArgs | [] | Extra cloudflared arguments | | pdb.enabled | false | Create PodDisruptionBudget | | pdb.minAvailable | 1 | Min available during disruption | | metrics.enabled | true | Expose metrics service | | serviceMonitor.enabled | false | Create Prometheus ServiceMonitor | | service.port | 2000 | Metrics service port | | service.ipFamilyPolicy | "" | Service IP family policy | | service.ipFamilies | [] | Ordered list of Service IP families | | resources.requests.cpu | 50m | Default CPU request | | resources.requests.memory | 64Mi | Default memory request | | resources.limits.cpu | 250m | Default CPU limit | | resources.limits.memory | 128Mi | Default memory limit | | securityContext.runAsUser | 65532 | Non-root container user |

Important Notes

  • Do not use HPA — downscaling terminates active tunnel connections
  • Routing is dashboard-managed — this chart does not configure ingress rules; use the Cloudflare dashboard to map public hostnames to internal services
  • No ingress template — cloudflared replaces traditional ingress controllers

Upgrade Notes

Cloudflared 2026.10.1 retains the existing quick-tunnel and managed-token contracts. It improves QUIC request cancellation and DNS resolution retries. The new normalized-path access-rule behavior is present but disabled by default, so the forwarded request path and existing ingress selection remain unchanged.

Review the official 2026.10.1 release before production rollout.

For chart upgrades, pin the target version and preserve tunnel mode, Secret name and key, replica count, disruption budget, metrics port, and transport options. Use --reuse-values only after auditing existing overrides. With --reset-values, restate every non-default tunnel, Secret, availability, transport, and monitoring setting. A chart upgrade must not rotate or replace a managed tunnel token.

Troubleshooting

Inspect Pod events and cloudflared logs first. A failing readiness probe means no active edge connection; verify DNS and outbound access for the selected HTTP/2 or QUIC transport. If the tunnel connects but traffic fails, validate the Public Hostname route and cluster origin Service independently. Authentication errors usually indicate a changed Secret name, key, or token. Metrics availability on port 2000 does not prove that a public hostname reaches its origin.

Security Scan

Security Scan: cloudflared

Framework Score
MITRE + NSA + SOC2 87.88%

Security posture acceptable. Verified with Kubescape 4.0.14 against rendered default manifests.

Local details:

Framework Score
MITRE 100.00%
NSA 85.00%
SOC2 80.00%

The rendered-manifest scan reports non-root, service-account token mapping, and network-isolation findings. The container explicitly runs as UID 65532; the chart does not create a NetworkPolicy. Review the service account and platform network policies for the deployment environment.

More Information

The startup probe allows 180 seconds of failed readiness checks, plus its initial delay, so edge registration retries and protocol fallback can complete without a premature container restart. Readiness still requires a live tunnel.

Quick tunnels use HTTP/2 by default so the demo does not require outbound UDP. Set tunnel.quickTunnel.protocol to auto or quic when appropriate. This setting applies only to ephemeral quick tunnels; managed tunnels retain the upstream transport default and can use cloudflared.extraArgs for overrides.

System Architecture

DESIGN.md Synced

Verified architecture contract rendered dynamically from GitHub DESIGN.md

flowchart LR
  User[User traffic] --> Edge[Cloudflare edge]
  Pod[cloudflared Deployment] -->|outbound tunnel| Edge
  Edge -->|tunnel route| Pod
  Pod --> Origin[Cluster origin Service<br/>managed or URL-mode quick tunnel]
  Pod --> HelloWorld[Built-in hello-world origin<br/>default quick tunnel]
  Prometheus[Prometheus] -. optional scrape .-> Metrics[Metrics Service]
  Metrics --> Pod
  Secret[Tunnel token Secret<br/>managed tunnel only] --> Pod
Official Contractvalues.schema.json

Cloudflared Values Schema Reference

Official schema parameters, default values, and types extracted directly from the chart repository.

88 parametersValues Studio

Global(1)

ParameterTypeDefaultDescription
globalobject-Global settings shared by the chart.

Name Override(1)

ParameterTypeDefaultDescription
nameOverridestring""Override the chart name used in resource names

Fullname Override(1)

ParameterTypeDefaultDescription
fullnameOverridestring""Override the full release name used in resource names

Common Labels(1)

ParameterTypeDefaultDescription
commonLabelsobject-Labels added to every resource created by this chart

Image(3)

ParameterTypeDefaultDescription
image.repositorystringcloudflare/cloudflaredcloudflared container image
image.tagstring""Image tag (defaults to appVersion)
image.pullPolicystringIfNotPresentImage pull policy
Allowed:AlwaysIfNotPresentNever

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Image pull secrets for private registries

Tunnel(7)

ParameterTypeDefaultDescription
tunnel.tokenstring""Tunnel token obtained from the Cloudflare dashboard
tunnel.existingSecretstring""Use an existing secret containing the tunnel token
tunnel.existingSecretKeystringtokenKey inside the existing secret
tunnel.quickTunnel.enabledbooleantrueRun an ephemeral quick tunnel for demos and smoke tests. Set false when using a managed tunnel token or existing Secret
tunnel.quickTunnel.protocolstringhttp2Chart configuration parameter
Allowed:autohttp2quic
tunnel.quickTunnel.helloWorldbooleantrueRun cloudflared's built-in hello-world origin
tunnel.quickTunnel.urlstringhttp://localhost:8080Origin URL used when helloWorld=false

External Secrets(7)

ParameterTypeDefaultDescription
externalSecrets.enabledbooleanfalseRender an ExternalSecret for the tunnel token
externalSecrets.apiVersionstringexternal-secrets.io/v1ExternalSecret API version
Allowed:external-secrets.io/v1
externalSecrets.refreshIntervalstring0ExternalSecret refresh interval
externalSecrets.secretStoreRef.namestring""SecretStore or ClusterSecretStore name
externalSecrets.secretStoreRef.kindstringSecretStoreSecret store kind
Allowed:SecretStoreClusterSecretStore
externalSecrets.target.creationPolicystringOwnerExternalSecret target creation policy
Allowed:OwnerMergeOrphanNone
externalSecrets.dataarray[]ExternalSecret data mappings

Cloudflared(5)

ParameterTypeDefaultDescription
cloudflared.logLevelstringinfoLog level
Allowed:infodebugwarnerrorfatal
cloudflared.noAutoupdatebooleantrueDisable auto-update (recommended in containers)
cloudflared.metricsPortinteger2000Metrics listen port (serves /ready and /metrics)
cloudflared.extraArgsarray-Extra arguments appended to the cloudflared command
cloudflared.extraEnvarray-Extra environment variables for the container

Replica Count(1)

ParameterTypeDefaultDescription
replicaCountinteger1Number of replicas. Use 2+ for production managed tunnels

Pdb(2)

ParameterTypeDefaultDescription
pdb.enabledbooleanfalseCreate a PodDisruptionBudget
pdb.minAvailableinteger1Minimum available replicas during disruption

Service Account(3)

ParameterTypeDefaultDescription
serviceAccount.createbooleanfalseCreate a ServiceAccount
serviceAccount.namestring""ServiceAccount name
serviceAccount.annotationsobject-Annotations for the ServiceAccount

Service & Networking(5)

ParameterTypeDefaultDescription
service.typestringClusterIPService type
Allowed:ClusterIPNodePortLoadBalancer
service.portinteger2000Metrics service port
service.annotationsobject-Annotations for the Service
service.ipFamilyPolicystring""Service IP family policy
Allowed:SingleStackPreferDualStackRequireDualStack
service.ipFamiliesarray[]Ordered list of Service IP families

Metrics & Observability(1)

ParameterTypeDefaultDescription
metrics.enabledbooleantrueExpose metrics service

Service Monitor(3)

ParameterTypeDefaultDescription
serviceMonitor.enabledbooleanfalseCreate a Prometheus ServiceMonitor
serviceMonitor.intervalstring30sScrape interval
serviceMonitor.labelsobject-Extra labels for the ServiceMonitor

Health Probes(18)

ParameterTypeDefaultDescription
probes.startup.enabledbooleantrueChart configuration parameter
probes.startup.pathstring/readyChart configuration parameter
probes.startup.initialDelaySecondsinteger-Chart configuration parameter
probes.startup.periodSecondsinteger-Chart configuration parameter
probes.startup.timeoutSecondsinteger-Chart configuration parameter
probes.startup.failureThresholdinteger-Chart configuration parameter
probes.liveness.enabledbooleantrueChart configuration parameter
probes.liveness.pathstring/readyChart configuration parameter
probes.liveness.initialDelaySecondsinteger-Chart configuration parameter
probes.liveness.periodSecondsinteger-Chart configuration parameter
probes.liveness.timeoutSecondsinteger-Chart configuration parameter
probes.liveness.failureThresholdinteger-Chart configuration parameter
probes.readiness.enabledbooleantrueChart configuration parameter
probes.readiness.pathstring/readyChart configuration parameter
probes.readiness.initialDelaySecondsinteger-Chart configuration parameter
probes.readiness.periodSecondsinteger-Chart configuration parameter
probes.readiness.timeoutSecondsinteger-Chart configuration parameter
probes.readiness.failureThresholdinteger-Chart configuration parameter

Resources(4)

ParameterTypeDefaultDescription
resources.requests.cpustringnumbernull-Chart configuration parameter
resources.requests.memorystringnumbernull-Chart configuration parameter
resources.limits.cpustringnumbernull-Chart configuration parameter
resources.limits.memorystringnumbernull-Chart configuration parameter

Pod Security(6)

ParameterTypeDefaultDescription
podSecurityContext.runAsNonRootbooleannull-Chart configuration parameter
podSecurityContext.runAsUserintegernull-Chart configuration parameter
podSecurityContext.runAsGroupintegernull-Chart configuration parameter
podSecurityContext.fsGroupintegernull-Chart configuration parameter
podSecurityContext.seccompProfile.typestringnull-Chart configuration parameter
podSecurityContext.seccompProfile.localhostProfilestringnull-Chart configuration parameter

Container Security(7)

ParameterTypeDefaultDescription
securityContext.allowPrivilegeEscalationbooleannull-Chart configuration parameter
securityContext.readOnlyRootFilesystembooleannull-Chart configuration parameter
securityContext.runAsNonRootbooleannull-Chart configuration parameter
securityContext.runAsUserintegernull-Chart configuration parameter
securityContext.runAsGroupintegernull-Chart configuration parameter
securityContext.capabilities.addarraynull-Chart configuration parameter
securityContext.capabilities.droparraynull-Chart configuration parameter

Node Selector(1)

ParameterTypeDefaultDescription
nodeSelectorobject-Node selector for pod scheduling

Tolerations(1)

ParameterTypeDefaultDescription
tolerationsarray-Tolerations for pod scheduling

Affinity(1)

ParameterTypeDefaultDescription
affinityobject-Affinity rules for pod scheduling

Topology Spread Constraints(1)

ParameterTypeDefaultDescription
topologySpreadConstraintsarray-Topology spread constraints

Priority Class Name(1)

ParameterTypeDefaultDescription
priorityClassNamestring""Priority class name

Termination Grace Period Seconds(1)

ParameterTypeDefaultDescription
terminationGracePeriodSecondsinteger30Grace period for shutdown (seconds)

Pod Labels(1)

ParameterTypeDefaultDescription
podLabelsobject-Additional labels for the pod

Pod Annotations(1)

ParameterTypeDefaultDescription
podAnnotationsobject-Additional annotations for the pod

Extra Volumes(1)

ParameterTypeDefaultDescription
extraVolumesarray-Additional volumes for the pod

Extra Volume Mounts(1)

ParameterTypeDefaultDescription
extraVolumeMountsarray-Additional volume mounts for the container

Extra Manifests(1)

ParameterTypeDefaultDescription
extraManifestsarray-Extra Kubernetes manifests to deploy alongside the chart