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.27.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

Architecture

This operator uses a Unified Sync Architecture with six layers to ensure concurrent safety and eliminate race conditions:

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 Resources"]
            CRDs["Custom Resources<br/>(Tunnel, DNSRecord, AccessApp, etc.)"]
            K8sNative["Kubernetes Native<br/>(Ingress, Gateway API)"]
        end

        subgraph Layer2["Layer 2: Resource Controllers"]
            RC["Resource Controllers<br/>(Lightweight, 100-150 lines each)"]
        end

        subgraph Layer3["Layer 3: Core Services"]
            SVC["Core Services<br/>(TunnelConfigService, DNSService, etc.)"]
        end

        subgraph Layer4["Layer 4: SyncState CRD"]
            SyncState["CloudflareSyncState<br/>(Shared state with optimistic locking)"]
        end

        subgraph Layer5["Layer 5: Sync Controllers"]
            SC["Sync Controllers<br/>(Debouncing, Aggregation, Hash detection)"]
        end

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

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

    CRDs -.->|watch| RC
    K8sNative -.->|watch| RC
    RC -->|register config| SVC
    SVC -->|update| SyncState
    SyncState -.->|watch| SC
    SC -->|"API calls<br/>(single sync point)"| API
    SC -->|creates| Managed
    Managed -->|proxy| Service
    Service --> Pod
    Users -->|HTTPS/WARP| Edge
    Edge <-->|tunnel| Deployment

    style Layer4 fill:#f9f,stroke:#333,stroke-width:2px
    style SC fill:#9f9,stroke:#333,stroke-width:2px

Architecture Benefits

Note: See Unified Sync 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/StringKe/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/StringKe/cloudflare-operator/releases/latest/download/cloudflare-operator-crds.yaml

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

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

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

Available Installation Files

Create a Tunnel

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

Expose a Service

apiVersion: networking.cfargotunnel.com/v1alpha1
kind: TunnelBinding
metadata:
  name: web-binding
subjects:
  - kind: Service
    name: web-app
    spec:
      fqdn: app.example.com
      protocol: http
tunnelRef:
  kind: Tunnel
  name: my-tunnel

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

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

Documentation includes:

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

API Token Permissions

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)
• Six-layer unified sync architecture for race condition elimination
• 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.