Security¶

This document covers the security policy and best practices for the Cloudflare Tunnel Gateway Controller.

Supported Versions¶

Fixes land on the latest 3.x minor; older minors are not backported.

Reporting Vulnerabilities¶

Report vulnerabilities via email:

• Email: f@lex.la
• GPG Key: F57F 85FC 7975 F22B BC3F 2504 9C17 3EB1 B531 AA1F

What to Include¶

• Type of vulnerability
• Full paths of affected source files
• Location of affected source code (tag/branch/commit)
• Step-by-step reproduction instructions
• Proof-of-concept or exploit code (if possible)
• Impact assessment

Response Timeline¶

Security Best Practices¶

API Token Management¶

The Cloudflare API token is sensitive and should be:

1. Stored in Kubernetes Secret

   kubectl create secret generic cloudflare-credentials \
     --from-literal=api-token="${CF_API_TOKEN}"
   

2. Scoped with minimum permissions

3. Account: Cloudflare Tunnel (Edit, Read)

4. Rotated regularly

5. Create new token in Cloudflare dashboard
6. Update Kubernetes secret

7. Controller picks up new token on restart

8. Never committed to git

9. Use external secret management (Vault, AWS Secrets Manager)

RBAC Configuration¶

The controller requires specific Kubernetes permissions:

# Minimum required permissions (v3) -- matches charts/.../templates/clusterrole.yaml
rules:
  # Gateway API - read specs
  - apiGroups: ["gateway.networking.k8s.io"]
    resources: ["httproutes", "grpcroutes", "referencegrants", "backendtlspolicies", "listenersets"]
    verbs: ["get", "list", "watch"]
  # GatewayClasses - the controller manages the spec-defined gateway-exists
  # finalizer (metadata write outside the status subresource)
  - apiGroups: ["gateway.networking.k8s.io"]
    resources: ["gatewayclasses"]
    verbs: ["get", "list", "watch", "update", "patch"]
  # Gateways - status patches require update/patch on the parent resource
  - apiGroups: ["gateway.networking.k8s.io"]
    resources: ["gateways"]
    verbs: ["get", "list", "watch", "update", "patch"]
  # Gateway API status subresources - write status
  - apiGroups: ["gateway.networking.k8s.io"]
    resources: ["gatewayclasses/status", "gateways/status", "httproutes/status", "grpcroutes/status", "backendtlspolicies/status", "listenersets/status"]
    verbs: ["get", "update", "patch"]
  # ServiceImport - a backendRef may target an imported multicluster Service
  - apiGroups: ["multicluster.x-k8s.io"]
    resources: ["serviceimports"]
    verbs: ["get", "list", "watch"]
  # CustomResourceDefinitions - single Get of the gatewayclasses CRD to read
  # the bundle-version annotation for the SupportedVersion condition
  - apiGroups: ["apiextensions.k8s.io"]
    resources: ["customresourcedefinitions"]
    verbs: ["get"]

  # Core API
  - apiGroups: [""]
    resources: ["namespaces"]
    verbs: ["get", "list", "watch"]
  # Services - read everywhere (backend resolution) plus full write for the
  # per-Gateway data planes: the controller renders a headless config Service
  # per opted-in Gateway. Rendered objects are controller-owned via
  # ownerReferences and deleted only when owned.
  - apiGroups: [""]
    resources: ["services"]
    verbs: ["get", "list", "watch", "create", "update", "delete"]
  # Secrets - read for credentials; create for the generated config-API auth Secret, both the per-Gateway one and the shared plane's (no update/delete: token never rotated).
  - apiGroups: [""]
    resources: ["secrets"]
    verbs: ["get", "list", "watch", "create"]
  - apiGroups: [""]
    resources: ["configmaps"]
    verbs: ["get", "list", "watch"]
  # EndpointSlice - the proxy endpoint reconciler discovers proxy pods so a
  # newly-joined replica gets the cached config pushed immediately
  - apiGroups: ["discovery.k8s.io"]
    resources: ["endpointslices"]
    verbs: ["get", "list", "watch"]
  # Events - route reconcilers emit Events via both the core (v1) and the new
  # (events.k8s.io/v1) recorders; grant both so neither path is denied
  - apiGroups: [""]
    resources: ["events"]
    verbs: ["create", "patch"]
  - apiGroups: ["events.k8s.io"]
    resources: ["events"]
    verbs: ["create", "patch"]

  # Deployments - the proxy Secret reconciler patches the proxy Deployment's
  # pod-template annotation to roll pods when the tunnel-token Secret rotates,
  # and the per-Gateway data planes render a dedicated proxy Deployment per
  # opted-in Gateway (full write, cluster-wide, because Gateways live in
  # arbitrary namespaces)
  - apiGroups: ["apps"]
    resources: ["deployments"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
  # HorizontalPodAutoscalers - rendered per opted-in Gateway when its
  # GatewayConfig requests autoscaling
  - apiGroups: ["autoscaling"]
    resources: ["horizontalpodautoscalers"]
    verbs: ["get", "list", "watch", "create", "update", "delete"]
  # NetworkPolicies - rendered per opted-in Gateway to lock the proxy's
  # config-API port to the controller (+ monitoring) namespaces
  - apiGroups: ["networking.k8s.io"]
    resources: ["networkpolicies"]
    verbs: ["get", "list", "watch", "create", "update", "delete"]

  # GatewayConfig CRD - per-Gateway data-plane parameters referenced from
  # Gateway.spec.infrastructure.parametersRef
  - apiGroups: ["cf.k8s.lex.la"]
    resources: ["gatewayconfigs"]
    verbs: ["get", "list", "watch"]

  # GatewayClassConfig CRD
  - apiGroups: ["cf.k8s.lex.la"]
    resources: ["gatewayclassconfigs"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["cf.k8s.lex.la"]
    resources: ["gatewayclassconfigs/status"]
    verbs: ["get", "update", "patch"]
  # ExternalBackend CRD - a backendRef may target an out-of-cluster endpoint
  - apiGroups: ["cf.k8s.lex.la"]
    resources: ["externalbackends"]
    verbs: ["get", "list", "watch"]

  # Leader election
  - apiGroups: ["coordination.k8s.io"]
    resources: ["leases"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]

Multi-Tenancy¶

Tenant isolation is layered: admission-level scoping (per-tenant listeners, allowedListeners/allowedRoutes, the opt-in hostname-ownership ValidatingAdmissionPolicy), an independent controller-side enforcement of the same hostname-ownership rule (a route that bypasses admission is still never programmed), and optional hard data-plane isolation with a dedicated proxy and tunnel per Gateway. An operator can cap how many dedicated data planes one namespace may hold with maxDataPlanesPerNamespace on the GatewayClassConfig; past the cap the newest Gateways are refused and no plane is rendered for them. The boundaries and trade-offs are documented in the Multi-Tenancy guide and the Per-Gateway Isolation guide.

Container Security¶

The controller container follows security best practices:

Network Security¶

Config API Authentication¶

The shared proxy's config API (where the controller pushes the routing table) is authenticated and network-restricted by default, matching the per-Gateway data planes described above. When proxy.authTokenSecretRef.name is left empty, the controller itself generates a random bearer token into a Secret (<fullname>-proxy-auth-token, where <fullname> is the Helm release fullname, typically <release>-cloudflare-tunnel-gateway-controller) on startup and uses it directly for its own push auth, and the proxy reads the same Secret via a pod-level secretKeyRef; the token is created once and reused on every restart, never rotated. Generating it via a live API call rather than at Helm template time means this is correct under GitOps controllers that render client-side with no cluster access (e.g. ArgoCD's default helm template), where a template-time lookup would silently mint a fresh value on every sync. proxy.networkPolicy.enabled (default true) additionally locks the config-API port to the controller pod: the ingress peer names it with a podSelector AND'd with the controller namespace, so a pod that merely shares that namespace is not admitted. Use proxy.networkPolicy.ingress.from to admit anything else, a monitoring stack scraping /metrics on the same port being the usual case. Set proxy.authTokenSecretRef.name to bring your own Secret instead — the controller resolves it through the same direct-API mechanism, never a secretKeyRef on its own pod, and never creates or modifies it: a missing bring-your-own Secret fails the controller closed rather than silently generating one at the operator's chosen name. Set proxy.networkPolicy.enabled: false to drop the NetworkPolicy on a cluster where it would be inert or unwanted — see the Helm values reference.

The binary enforces this on its own side too, which matters for a hand-written proxy Deployment where no chart is wiring anything. In tunnel mode it refuses to start unless PROXY_AUTH_TOKEN is set, because its config API listens on every interface and one successful push replaces the entire routing table. A present-but-empty value is refused in either mode, since that is what a broken Secret produces rather than a decision to run open. PROXY_ALLOW_UNAUTHENTICATED_CONFIG_API=1 opts out deliberately; it is a separate variable so a misconfiguration cannot spell the same thing as consent. Standalone mode, selected by omitting TUNNEL_TOKEN, keeps the unauthenticated default and binds the same interfaces, so the network boundary there is the operator's to provide.

The token and the NetworkPolicy are both reach controls, and neither encrypts anything. The push is plain HTTP — the endpoint the chart wires for the shared plane and the ones the controller renders for per-Gateway planes are both http:// URLs — and it carries the bearer token in an Authorization header, plus the private key of the backend client certificate for any route whose parent Gateway sets spec.tls.backend.clientCertificateRef and whose backend is covered by a BackendTLSPolicy. So the token answers who may replace the routing table and the NetworkPolicy answers who may reach the port at all; neither says anything about who can read the bytes in flight, and on a CNI without pod-to-pod encryption an on-path party inside the cluster reads the token and that key. Wire confidentiality is the cluster's to provide: an encrypting CNI mode (WireGuard or IPsec), or a mesh that wraps pod-to-pod traffic in mTLS. TLS on the config API itself is tracked in #719.

Egress Requirements¶

The controller only needs egress to:

Writing that as a policy runs into one thing worth knowing before you narrow anything. A rule with ports and no to permits those ports to every destination, and rules are OR'd, so one unrestricted rule makes every narrower rule beside it inert. The obvious fix — replacing it with a catch-all ipBlock — is not equivalent: Cilium does not match in-cluster identities through CIDR peers unless the agent runs with --policy-cidr-match-mode, which Cilium ships disabled and still marks beta, so a 0.0.0.0/0 peer denies a host-network API server on the self-managed clusters where that is exactly how the API server is reached. Narrow with a destination you have checked against your own CNI, and remember that most of them evaluate egress after DNAT, so a Service ClusterIP never matches.

The chart's networkPolicy.kubernetesApiIpBlocks is where that narrowing goes; it ships empty, meaning unrestricted.

The Cloudflare rule beside it is narrowed by networkPolicy.cloudflareIpRanges, which ships populated. Emptying both its address families is refused rather than rendered: the rule would lose its to: and become the unrestricted shape above, which is the opposite of what emptying an allowlist looks like it does. The refusal is armed by networkPolicy.enabled for the controller policy and by proxy.networkPolicy.egressRestricted for the proxy one, neither of which is on by default; turn off whichever of those two you have enabled to drop the restriction.

The chart's policy carries no rule for the collector, so turning tracing on under it drops the exporter's traffic. Add the rule yourself.

NetworkPolicy Example¶

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: cloudflare-tunnel-gateway-controller
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: cloudflare-tunnel-gateway-controller
  policyTypes:
    - Ingress
    - Egress
  ingress:
    # Prometheus scraping
    - from:
        - namespaceSelector:
            matchLabels:
              name: monitoring
      ports:
        - port: 8080
  egress:
    # Kubernetes API. No `to` at all, which permits these ports everywhere —
    # the same thing the chart renders by default, for the reasons above. Until
    # you narrow it the Cloudflare rule below has no effect.
    - ports:
        - port: 443
        - port: 6443
    # Cloudflare API. Abbreviated — the full list is at
    # https://www.cloudflare.com/ips/ and both families belong here. Narrowing
    # the rule above without completing this one breaks Cloudflare API calls.
    - to:
        - ipBlock:
            cidr: 173.245.48.0/20
      ports:
        - port: 443
    # The proxies' config API. Without this no data plane receives a routing
    # table, and Gateway status stays clean while that is true. The first peer
    # is the shared plane in this namespace; the second is per-Gateway planes,
    # which live in their Gateway's namespace.
    - to:
        - podSelector:
            matchLabels:
              app.kubernetes.io/name: cloudflare-tunnel-gateway-controller-proxy
              app.kubernetes.io/component: proxy
        - namespaceSelector: {}
          podSelector:
            matchLabels:
              app.kubernetes.io/name: cloudflare-tunnel-gateway-proxy
      ports:
        - port: 8081
    # DNS
    - ports:
        - port: 53
          protocol: UDP
        - port: 53
          protocol: TCP

This is a starting point for operators applying manifests by hand, not a transcript of what the chart renders: the chart's version is generated from values and carries knobs this example flattens. Read templates/networkpolicy.yaml if you need the exact shape.

Supply Chain Security¶

Container Image Verification¶

Container images are signed with cosign (keyless):

cosign verify ghcr.io/lexfrei/cloudflare-tunnel-gateway-controller:latest \
  --certificate-identity-regexp="https://github.com/lexfrei/cloudflare-tunnel-gateway-controller" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com"

Helm Chart Verification¶

helm verify cloudflare-tunnel-gateway-controller-<version>.tgz

Secrets in Logs¶

The controller is designed to never log sensitive information:

• API tokens are not logged
• Tunnel tokens are not logged
• Secret contents are not logged

Security Scanning¶

The project uses automated security scanning:

Incident Response¶

If you believe the controller has been compromised:

1. Revoke Cloudflare API token immediately
2. Delete the controller deployment
3. Review Cloudflare audit logs for unauthorized changes
4. Rotate tunnel credentials if needed
5. Report the incident via security email

Secure Deployment Checklist¶

• API token stored in Kubernetes Secret (not in values.yaml)
• API token has minimal required permissions
• Controller running as non-root
• Read-only root filesystem enabled
• NetworkPolicy restricting egress
• ServiceAccount with minimal RBAC
• proxy.allowXOriginalHost left off (the default) — it exists for the conformance suite, and trusting that header lets a client be served by a different hostname's backend
• Container image verified with cosign
• Prometheus monitoring enabled
• Alerts configured for anomalous behavior