Cloudflare Zero Trust Operator

A Kubernetes Operator for Cloudflare Zero Trust: Tunnels, Access, Gateway, Device, DNS, R2, and Rules Management

Documentation (English) » | 文档 (中文) »

Examples · Report Bug · Request Feature

Note: This project is currently in Alpha (v0.34.x). This is NOT an official Cloudflare product. It uses the Cloudflare API and cloudflared to automate Zero Trust configuration on Kubernetes.

This project is a fork of adyanth/cloudflare-operator with extended Zero Trust features and improvements.

Overview

The Cloudflare Zero Trust Operator provides Kubernetes-native management of Cloudflare Zero Trust resources. Built with kubebuilder and controller-runtime, it enables declarative configuration of tunnels, access policies, gateway rules, device settings, R2 storage, and zone rules through Custom Resource Definitions (CRDs).

Features

Category	Features
Tunnel Management	Create/manage Cloudflare Tunnels, automatic cloudflared deployments, Service binding with DNS
Private Network	Virtual Networks, Network Routes, Private Service exposure via WARP
Access Control	Zero Trust Applications, Access Groups, Reusable Access Policies, Inline Policy Rules, Identity Providers, Service Tokens
Gateway & Security	Gateway Rules (DNS/HTTP/L4), Gateway Lists, Browser Isolation
Device Management	Split Tunnel configuration, Fallback Domains, Device Posture Rules
DNS & Connectivity	DNS Record management, WARP Connectors for site-to-site
Domain Management	Zone settings (SSL/TLS, Cache, Security), Origin CA Certificates
R2 Storage	R2 Buckets, Custom Domains, Event Notifications
Rules Engine	Zone Rulesets, Transform Rules (URL/Header), Redirect Rules
Cloudflare Pages	Pages Projects (build config, resource bindings), Custom Domains, Deployment management (create, retry, rollback)
Registrar	Domain Registration management (Enterprise)
Kubernetes Integration	Native Ingress support, Gateway API support (Gateway, HTTPRoute, TCPRoute, UDPRoute)

Architecture

This operator uses a Three-Layer Architecture for simplicity and reliability:

flowchart TB
    subgraph Internet["Internet"]
        Users["Users / WARP Clients"]
    end

    subgraph Cloudflare["Cloudflare Edge"]
        Edge["Cloudflare Edge Network"]
        API["Cloudflare API"]
    end

    subgraph K8s["Kubernetes Cluster"]
        subgraph Layer1["Layer 1: K8s CRD"]
            OneToOne["1:1 Resources<br/>(DNSRecord, AccessApp, R2Bucket, PagesDeployment, etc.)"]
            Aggregate["Aggregate Resources<br/>(Tunnel, ClusterTunnel, Ingress, HTTPRoute)"]
        end

        subgraph Layer2["Layer 2: Controllers"]
            Direct["Direct Controllers<br/>(Call CF API directly, write status to CRD)"]
            ConfigAgg["Config Aggregation<br/>(Write to ConfigMap, TunnelConfig Controller syncs)"]
        end

        subgraph Layer3["Layer 3: Cloudflare API Client"]
            CFClient["Connection Pool, Rate Limiting<br/>Auto Retry, Error Handling"]
        end

        subgraph Managed["Managed Resources"]
            Deployment["cloudflared Deployment"]
            ConfigMap["Tunnel ConfigMap"]
        end

        subgraph App["Applications"]
            Service["Services"]
            Pod["Pods"]
        end
    end

    OneToOne -.->|watch| Direct
    Aggregate -.->|watch| ConfigAgg
    Direct -->|"API calls"| API
    Direct -->|"status"| OneToOne
    ConfigAgg -->|write| ConfigMap
    ConfigMap -.->|watch| Direct
    Direct -->|"tunnel config"| API
    Direct -->|creates| Deployment
    Deployment -->|proxy| Service
    Service --> Pod
    Users -->|HTTPS/WARP| Edge
    Edge <-->|tunnel| Deployment

    style Layer2 fill:#9f9,stroke:#333,stroke-width:2px
    style CFClient fill:#f9f,stroke:#333,stroke-width:2px

Architecture Benefits

Feature	Benefit
Direct Status Writes	Controllers write directly to CRD.Status, no intermediate layers
Independent Informers	Each CRD has its own Controller + Informer, no event interference
ConfigMap Aggregation	Tunnel config uses ConfigMap for multi-source aggregation (Ingress, legacy TunnelBinding, etc.)
Hash Detection	Skip sync when config unchanged, reducing API usage
Simple Data Flow	L1 CRD → L2 Controller → L3 CF API, easy to trace and debug

Note: See Three-Layer Architecture Design for detailed documentation.

Quick Start

Prerequisites

Kubernetes cluster v1.28+
Cloudflare account with Zero Trust enabled
Cloudflare API Token (Create Token)

Installation

Option 1: Full Installation (Recommended for new users)

# All-in-one: CRDs + Namespace + RBAC + Operator (without webhook)
kubectl apply -f https://github.com/0ekk/cloudflare-operator/releases/latest/download/cloudflare-operator-full-no-webhook.yaml

# Verify installation
kubectl get pods -n cloudflare-operator-system

Option 2: Modular Installation (Recommended for production)

# Step 1: Install CRDs (cluster-admin required)
kubectl apply -f https://github.com/0ekk/cloudflare-operator/releases/latest/download/cloudflare-operator-crds.yaml

# Step 2: Create namespace
kubectl apply -f https://github.com/0ekk/cloudflare-operator/releases/latest/download/cloudflare-operator-namespace.yaml

# Step 3: Install operator (RBAC + Deployment)
kubectl apply -f https://github.com/0ekk/cloudflare-operator/releases/latest/download/cloudflare-operator-no-webhook.yaml

# Verify installation
kubectl get pods -n cloudflare-operator-system

Option 3: Helm Chart (Recommended for GitOps/values-driven deployment)

helm repo add cloudflare-operator https://0ekk.github.io/cloudflare-operator
helm repo update

helm upgrade --install cloudflare-operator cloudflare-operator/cloudflare-operator \
  --namespace cloudflare-operator-system \
  --create-namespace

# Verify installation
kubectl get pods -n cloudflare-operator-system

Chart defaults to cloudflare-operator-no-webhook.yaml, and can enable webhook/cert-manager via values (webhook.enabled=true, certManager.enabled=true).

Available Installation Files

File	Contents	Use Case
`cloudflare-operator-full.yaml`	CRDs + Namespace + RBAC + Operator + Webhook	Full installation with cert-manager
`cloudflare-operator-full-no-webhook.yaml`	CRDs + Namespace + RBAC + Operator	Full installation without webhook
`cloudflare-operator-crds.yaml`	CRDs only	Modular: install CRDs separately
`cloudflare-operator-namespace.yaml`	Namespace only	Modular: create namespace
`cloudflare-operator.yaml`	RBAC + Operator + Webhook	Modular: operator with webhook
`cloudflare-operator-no-webhook.yaml`	RBAC + Operator	Modular: operator without webhook

Create a Tunnel

# 1. Create API credentials secret
apiVersion: v1
kind: Secret
metadata:
  name: cloudflare-credentials
  namespace: cloudflare-operator-system
type: Opaque
stringData:
  CLOUDFLARE_API_TOKEN: "<your-api-token>"
---
# 2. Create CloudflareCredentials
apiVersion: networking.cloudflare-operator.io/v1alpha2
kind: CloudflareCredentials
metadata:
  name: default
spec:
  accountId: "<your-account-id>"
  authType: apiToken
  secretRef:
    name: cloudflare-credentials
    namespace: cloudflare-operator-system
  isDefault: true
---
# 3. Create tunnel
apiVersion: networking.cloudflare-operator.io/v1alpha2
kind: Tunnel
metadata:
  name: my-tunnel
  namespace: default
spec:
  newTunnel:
    name: k8s-tunnel
  cloudflare:
    domain: example.com
    credentialsRef:
      name: default

Expose a Service

apiVersion: networking.cloudflare-operator.io/v1alpha2
kind: TunnelIngressClassConfig
metadata:
  name: cf-tunnel
  namespace: default
spec:
  tunnelRef:
    kind: Tunnel
    name: my-tunnel
  dnsManagement: Automatic
  dnsProxied: true
---
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: cf-tunnel
spec:
  controller: cloudflare-operator.io/ingress-controller
  parameters:
    apiGroup: networking.cloudflare-operator.io
    kind: TunnelIngressClassConfig
    name: cf-tunnel
    scope: Namespace
    namespace: default
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web
  namespace: default
spec:
  ingressClassName: cf-tunnel
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: web-app
                port:
                  number: 80

TunnelBinding is legacy/deprecated. For migration steps, see TunnelBinding Migration Guide.

CRD Reference

Credentials & Configuration

CRD	API Version	Scope	Description
CloudflareCredentials	`networking.cloudflare-operator.io/v1alpha2`	Cluster	Cloudflare API credentials management
CloudflareDomain	`networking.cloudflare-operator.io/v1alpha2`	Cluster	Zone settings (SSL/TLS, Cache, Security, WAF)

Tunnel Management

CRD	API Version	Scope	Description
Tunnel	`networking.cloudflare-operator.io/v1alpha2`	Namespaced	Cloudflare Tunnel with managed cloudflared
ClusterTunnel	`networking.cloudflare-operator.io/v1alpha2`	Cluster	Cluster-wide Cloudflare Tunnel
TunnelBinding (Deprecated)	`networking.cfargotunnel.com/v1alpha1`	Namespaced	Legacy Service-to-Tunnel binding

Private Network Access

CRD	API Version	Scope	Description
VirtualNetwork	`networking.cloudflare-operator.io/v1alpha2`	Cluster	Cloudflare virtual network for isolation
NetworkRoute	`networking.cloudflare-operator.io/v1alpha2`	Cluster	Route CIDR through tunnel
PrivateService	`networking.cloudflare-operator.io/v1alpha2`	Namespaced	Expose Service via private IP

Access Control

CRD	API Version	Scope	Description
AccessApplication	`networking.cloudflare-operator.io/v1alpha2`	Namespaced	Zero Trust application with inline policy rules
AccessGroup	`networking.cloudflare-operator.io/v1alpha2`	Cluster	Access policy group
AccessPolicy	`networking.cloudflare-operator.io/v1alpha2`	Cluster	Reusable access policy (referenced by applications)
AccessIdentityProvider	`networking.cloudflare-operator.io/v1alpha2`	Cluster	Identity provider config
AccessServiceToken	`networking.cloudflare-operator.io/v1alpha2`	Namespaced	Service token for M2M

Gateway & Security

CRD	API Version	Scope	Description
GatewayRule	`networking.cloudflare-operator.io/v1alpha2`	Cluster	Gateway policy rule
GatewayList	`networking.cloudflare-operator.io/v1alpha2`	Cluster	List for gateway rules
GatewayConfiguration	`networking.cloudflare-operator.io/v1alpha2`	Cluster	Global gateway settings

Device Management

CRD	API Version	Scope	Description
DeviceSettingsPolicy	`networking.cloudflare-operator.io/v1alpha2`	Cluster	WARP client settings
DevicePostureRule	`networking.cloudflare-operator.io/v1alpha2`	Cluster	Device posture check

DNS & Connectivity

CRD	API Version	Scope	Description
DNSRecord	`networking.cloudflare-operator.io/v1alpha2`	Namespaced	DNS record management
WARPConnector	`networking.cloudflare-operator.io/v1alpha2`	Namespaced	WARP connector deployment
AccessTunnel	`networking.cloudflare-operator.io/v1alpha2`	Namespaced	Access tunnel configuration

SSL/TLS & Certificates

CRD	API Version	Scope	Description
OriginCACertificate	`networking.cloudflare-operator.io/v1alpha2`	Namespaced	Cloudflare Origin CA certificate with K8s Secret

R2 Storage

CRD	API Version	Scope	Description
R2Bucket	`networking.cloudflare-operator.io/v1alpha2`	Namespaced	R2 storage bucket with lifecycle rules
R2BucketDomain	`networking.cloudflare-operator.io/v1alpha2`	Namespaced	Custom domain for R2 bucket
R2BucketNotification	`networking.cloudflare-operator.io/v1alpha2`	Namespaced	Event notifications for R2 bucket

Rules Engine

CRD	API Version	Scope	Description
ZoneRuleset	`networking.cloudflare-operator.io/v1alpha2`	Namespaced	Zone ruleset (WAF, rate limiting, etc.)
TransformRule	`networking.cloudflare-operator.io/v1alpha2`	Namespaced	URL rewrite & header modification
RedirectRule	`networking.cloudflare-operator.io/v1alpha2`	Namespaced	URL redirect rules

Cloudflare Pages

CRD	API Version	Scope	Description
PagesProject	`networking.cloudflare-operator.io/v1alpha2`	Namespaced	Pages project with build config and bindings
PagesDomain	`networking.cloudflare-operator.io/v1alpha2`	Namespaced	Custom domain for Pages project
PagesDeployment	`networking.cloudflare-operator.io/v1alpha2`	Namespaced	Pages deployment (create, retry, rollback)

Registrar (Enterprise)

CRD	API Version	Scope	Description
DomainRegistration	`networking.cloudflare-operator.io/v1alpha2`	Cluster	Domain registration settings

Kubernetes Integration

CRD	API Version	Scope	Description
TunnelIngressClassConfig	`networking.cloudflare-operator.io/v1alpha2`	Namespaced	Config for Ingress integration
TunnelGatewayClassConfig	`networking.cloudflare-operator.io/v1alpha2`	Namespaced	Config for Gateway API integration

Note: The operator also supports native Kubernetes Ingress and Gateway API (Gateway, HTTPRoute, TCPRoute, UDPRoute) resources when configured with the appropriate IngressClass or GatewayClass.

Examples

See the examples directory for comprehensive usage examples:

Basic - Credentials, Tunnels, DNS, Service Binding
Private Network - Virtual Networks, Routes, Private Services
Zero Trust - Access Apps, Groups, Policies, Identity Providers
Gateway - Gateway Rules, Lists
Device - Device Policies, Posture Rules
Pages - Pages Projects, Domains, Deployments
Scenarios - Complete real-world scenarios

Documentation

Language	Link
English	docs/en/README.md
中文	docs/zh/README.md

Documentation includes:

Installation Guide
API Token Permissions
Complete CRD Reference
Troubleshooting Guide
Migration Guide (v1alpha1 → v1alpha2)

API Token Permissions

Feature	Permission	Scope
Tunnels	`Account:Cloudflare Tunnel:Edit`	Account
DNS	`Zone:DNS:Edit`	Zone
Access	`Account:Access: Apps and Policies:Edit`	Account
Access Groups & IdP	`Account:Access: Organizations, Identity Providers, and Groups:Edit`	Account
Service Tokens	`Account:Access: Service Tokens:Edit`	Account
Device Posture	`Account:Access: Device Posture:Edit`	Account
Gateway	`Account:Zero Trust:Edit`	Account
Zone Settings	`Zone:Zone Settings:Edit`	Zone
SSL/TLS	`Zone:SSL and Certificates:Edit`	Zone
R2	`Account:Workers R2 Storage:Edit`	Account
Pages	`Account:Cloudflare Pages:Edit`	Account
Rules	`Zone:Zone Rulesets:Edit`	Zone
Registrar	`Account:Registrar:Edit`	Account

For detailed per-CRD permission requirements, see Configuration Guide.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Acknowledgements

This project is forked from adyanth/cloudflare-operator. We extend our gratitude to @adyanth and all original contributors for their excellent work on the initial implementation.

What's Different

This fork extends the original project with:

Complete Zero Trust resource support (Access, Gateway, Device management)
v1alpha2 API with improved resource management
Native Kubernetes Ingress and Gateway API integration
R2 Storage management (buckets, custom domains, notifications)
Cloudflare Pages support (projects, custom domains, advanced deployments with retry/rollback)
Zone settings and rules engine (SSL/TLS, Cache, WAF, Transform/Redirect rules)
Origin CA certificate integration
Domain registration management (Enterprise)
Three-layer architecture for simplicity and reliability (simplified from six-layer)
Reusable Access Policies and inline include/exclude/require rules
NetworkRoute adoption with cross-VNet search support
Enhanced error handling and status reporting
Comprehensive documentation and examples

License

Apache License 2.0 - See LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 488 Commits
.claude/skills		.claude/skills
.github		.github
api		api
bundle		bundle
charts/cloudflare-operator		charts/cloudflare-operator
cmd		cmd
config		config
docs		docs
examples		examples
hack		hack
internal		internal
scripts		scripts
test		test
.dockerignore		.dockerignore
.gitignore		.gitignore
.golangci.yml		.golangci.yml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
NOTICE		NOTICE
PROJECT		PROJECT
README.md		README.md
README_zh.md		README_zh.md
SECURITY.md		SECURITY.md
bundle.Dockerfile		bundle.Dockerfile
go.mod		go.mod
go.sum		go.sum

Folders and files

Latest commit

History

Repository files navigation

Cloudflare Zero Trust Operator

Overview

Features

Architecture

Architecture Benefits

Quick Start

Prerequisites

Installation

Create a Tunnel

Expose a Service

CRD Reference

Credentials & Configuration

Tunnel Management

Private Network Access

Access Control

Gateway & Security

Device Management

DNS & Connectivity

SSL/TLS & Certificates

R2 Storage

Rules Engine

Cloudflare Pages

Registrar (Enterprise)

Kubernetes Integration

Examples

Documentation

API Token Permissions

Contributing

Acknowledgements

What's Different

License

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages