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 —
/readyand/metricson 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
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.
|-----|---------|-------------|
| 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 SyncedVerified 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
Cloudflared Values Schema Reference
Official schema parameters, default values, and types extracted directly from the chart repository.
Global(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| global | object | - | Global settings shared by the chart. |
Name Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nameOverride | string | "" | Override the chart name used in resource names |
Fullname Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| fullnameOverride | string | "" | Override the full release name used in resource names |
Common Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| commonLabels | object | - | Labels added to every resource created by this chart |
Image(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| image.repository | string | cloudflare/cloudflared | cloudflared container image |
| image.tag | string | "" | Image tag (defaults to appVersion) |
| image.pullPolicy | string | IfNotPresent | Image pull policy Allowed: AlwaysIfNotPresentNever |
Image Pull Secrets(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| imagePullSecrets | array | - | Image pull secrets for private registries |
Tunnel(7)
| Parameter | Type | Default | Description |
|---|---|---|---|
| tunnel.token | string | "" | Tunnel token obtained from the Cloudflare dashboard |
| tunnel.existingSecret | string | "" | Use an existing secret containing the tunnel token |
| tunnel.existingSecretKey | string | token | Key inside the existing secret |
| tunnel.quickTunnel.enabled | boolean | true | Run an ephemeral quick tunnel for demos and smoke tests. Set false when using a managed tunnel token or existing Secret |
| tunnel.quickTunnel.protocol | string | http2 | Chart configuration parameter Allowed: autohttp2quic |
| tunnel.quickTunnel.helloWorld | boolean | true | Run cloudflared's built-in hello-world origin |
| tunnel.quickTunnel.url | string | http://localhost:8080 | Origin URL used when helloWorld=false |
External Secrets(7)
| Parameter | Type | Default | Description |
|---|---|---|---|
| externalSecrets.enabled | boolean | false | Render an ExternalSecret for the tunnel token |
| externalSecrets.apiVersion | string | external-secrets.io/v1 | ExternalSecret API version Allowed: external-secrets.io/v1 |
| externalSecrets.refreshInterval | string | 0 | ExternalSecret refresh interval |
| externalSecrets.secretStoreRef.name | string | "" | SecretStore or ClusterSecretStore name |
| externalSecrets.secretStoreRef.kind | string | SecretStore | Secret store kind Allowed: SecretStoreClusterSecretStore |
| externalSecrets.target.creationPolicy | string | Owner | ExternalSecret target creation policy Allowed: OwnerMergeOrphanNone |
| externalSecrets.data | array | [] | ExternalSecret data mappings |
Cloudflared(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| cloudflared.logLevel | string | info | Log level Allowed: infodebugwarnerrorfatal |
| cloudflared.noAutoupdate | boolean | true | Disable auto-update (recommended in containers) |
| cloudflared.metricsPort | integer | 2000 | Metrics listen port (serves /ready and /metrics) |
| cloudflared.extraArgs | array | - | Extra arguments appended to the cloudflared command |
| cloudflared.extraEnv | array | - | Extra environment variables for the container |
Replica Count(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| replicaCount | integer | 1 | Number of replicas. Use 2+ for production managed tunnels |
Pdb(2)
| Parameter | Type | Default | Description |
|---|---|---|---|
| pdb.enabled | boolean | false | Create a PodDisruptionBudget |
| pdb.minAvailable | integer | 1 | Minimum available replicas during disruption |
Service Account(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| serviceAccount.create | boolean | false | Create a ServiceAccount |
| serviceAccount.name | string | "" | ServiceAccount name |
| serviceAccount.annotations | object | - | Annotations for the ServiceAccount |
Service & Networking(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| service.type | string | ClusterIP | Service type Allowed: ClusterIPNodePortLoadBalancer |
| service.port | integer | 2000 | Metrics service port |
| service.annotations | object | - | Annotations for the Service |
| service.ipFamilyPolicy | string | "" | Service IP family policy Allowed: SingleStackPreferDualStackRequireDualStack |
| service.ipFamilies | array | [] | Ordered list of Service IP families |
Metrics & Observability(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| metrics.enabled | boolean | true | Expose metrics service |
Service Monitor(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| serviceMonitor.enabled | boolean | false | Create a Prometheus ServiceMonitor |
| serviceMonitor.interval | string | 30s | Scrape interval |
| serviceMonitor.labels | object | - | Extra labels for the ServiceMonitor |
Health Probes(18)
| Parameter | Type | Default | Description |
|---|---|---|---|
| probes.startup.enabled | boolean | true | Chart configuration parameter |
| probes.startup.path | string | /ready | Chart configuration parameter |
| probes.startup.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.startup.periodSeconds | integer | - | Chart configuration parameter |
| probes.startup.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.startup.failureThreshold | integer | - | Chart configuration parameter |
| probes.liveness.enabled | boolean | true | Chart configuration parameter |
| probes.liveness.path | string | /ready | Chart configuration parameter |
| probes.liveness.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.liveness.periodSeconds | integer | - | Chart configuration parameter |
| probes.liveness.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.liveness.failureThreshold | integer | - | Chart configuration parameter |
| probes.readiness.enabled | boolean | true | Chart configuration parameter |
| probes.readiness.path | string | /ready | Chart configuration parameter |
| probes.readiness.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.readiness.periodSeconds | integer | - | Chart configuration parameter |
| probes.readiness.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.readiness.failureThreshold | integer | - | Chart configuration parameter |
Resources(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| resources.requests.cpu | stringnumbernull | - | Chart configuration parameter |
| resources.requests.memory | stringnumbernull | - | Chart configuration parameter |
| resources.limits.cpu | stringnumbernull | - | Chart configuration parameter |
| resources.limits.memory | stringnumbernull | - | Chart configuration parameter |
Pod Security(6)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podSecurityContext.runAsNonRoot | booleannull | - | Chart configuration parameter |
| podSecurityContext.runAsUser | integernull | - | Chart configuration parameter |
| podSecurityContext.runAsGroup | integernull | - | Chart configuration parameter |
| podSecurityContext.fsGroup | integernull | - | Chart configuration parameter |
| podSecurityContext.seccompProfile.type | stringnull | - | Chart configuration parameter |
| podSecurityContext.seccompProfile.localhostProfile | stringnull | - | Chart configuration parameter |
Container Security(7)
| Parameter | Type | Default | Description |
|---|---|---|---|
| securityContext.allowPrivilegeEscalation | booleannull | - | Chart configuration parameter |
| securityContext.readOnlyRootFilesystem | booleannull | - | Chart configuration parameter |
| securityContext.runAsNonRoot | booleannull | - | Chart configuration parameter |
| securityContext.runAsUser | integernull | - | Chart configuration parameter |
| securityContext.runAsGroup | integernull | - | Chart configuration parameter |
| securityContext.capabilities.add | arraynull | - | Chart configuration parameter |
| securityContext.capabilities.drop | arraynull | - | Chart configuration parameter |
Node Selector(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nodeSelector | object | - | Node selector for pod scheduling |
Tolerations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| tolerations | array | - | Tolerations for pod scheduling |
Affinity(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| affinity | object | - | Affinity rules for pod scheduling |
Topology Spread Constraints(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| topologySpreadConstraints | array | - | Topology spread constraints |
Priority Class Name(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| priorityClassName | string | "" | Priority class name |
Termination Grace Period Seconds(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| terminationGracePeriodSeconds | integer | 30 | Grace period for shutdown (seconds) |
Pod Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podLabels | object | - | Additional labels for the pod |
Pod Annotations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podAnnotations | object | - | Additional annotations for the pod |
Extra Volumes(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumes | array | - | Additional volumes for the pod |
Extra Volume Mounts(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumeMounts | array | - | Additional volume mounts for the container |
Extra Manifests(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraManifests | array | - | Extra Kubernetes manifests to deploy alongside the chart |
No schema parameters match your search
Try searching for a different keyword or reset the filter.