Skip to content

README.md

Latest commit

 

History

History
295 lines (228 loc) · 11.3 KB

README.md

File metadata and controls

295 lines (228 loc) · 11.3 KB

Cloudflare Operator Documentation

Welcome to the Cloudflare Zero Trust Operator documentation. This operator enables Kubernetes-native management of Cloudflare Zero Trust resources.

Quick Navigation

Topic Description
Getting Started Installation and first tunnel
Configuration API tokens and credentials
Namespace Restrictions CRD scope and Secret management
API Reference Complete CRD documentation
Guides How-to guides for common tasks
Troubleshooting Common issues and solutions
Migration Upgrading from v1alpha1

Overview

The Cloudflare Operator provides Kubernetes-native management of:

  • Tunnels - Secure connections from your cluster to Cloudflare's edge
  • Private Network Access - Enable WARP clients to access internal services
  • Access Control - Zero Trust authentication for applications
  • Gateway - DNS/HTTP/L4 security policies
  • Device Management - WARP client configuration and posture rules
  • Kubernetes Integration - Native Ingress and Gateway API support

Architecture

The operator uses a Three-Layer Architecture:

L1: K8s CRD → L2: Controller → L3: Cloudflare API

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 CRDs"]
            CRDs["Custom Resources"]
            K8sNative["Ingress / Gateway API"]
        end

        subgraph Layer2["Layer 2: Controllers"]
            RC["1:1 Controllers"]
            TC["TunnelConfig Controller"]
            CM["ConfigMap (aggregation)"]
        end

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

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

    CRDs -.->|watch| RC
    K8sNative -.->|watch| RC
    RC -->|direct API calls| API
    CRDs -.->|watch| TC
    K8sNative -->|write config| CM
    CM -.->|watch| TC
    TC -->|aggregated API calls| API
    TC -->|creates| Managed
    Managed -->|proxy| Service
    Service --> Pod
    Users -->|HTTPS/WARP| Edge
    Edge <-->|tunnel| Deployment
Loading

Key Benefits

Feature Description
Simple Data Flow Controllers directly call Cloudflare API
Direct Status Updates Status written back to CRD immediately
Independent Informers Each CRD has isolated controller, no interference
ConfigMap Aggregation Tunnel config aggregated via ConfigMap

See Three-Layer Architecture for details.

CRD Summary (34 Total)

Credentials & Configuration

CRD Scope Description
CloudflareCredentials Cluster Shared API credential configuration
CloudflareDomain Cluster Zone settings (SSL/TLS, Cache, Security, WAF)

Tunnel Management

CRD Scope Description
Tunnel Namespaced Cloudflare Tunnel with managed cloudflared
ClusterTunnel Cluster Cluster-wide Cloudflare Tunnel
TunnelBinding Namespaced Bind Services to Tunnels with DNS

Private Network

CRD Scope Description
VirtualNetwork Cluster Traffic isolation network
NetworkRoute Cluster Route CIDR through tunnel
PrivateService Namespaced Expose Service via private IP
WARPConnector Namespaced WARP connector for site-to-site

Access Control

CRD Scope Description
AccessApplication Namespaced Zero Trust application
AccessGroup Cluster Reusable access policy group
AccessPolicy Cluster Reusable access policy template
AccessIdentityProvider Cluster Identity provider configuration
AccessServiceToken Namespaced M2M authentication token
AccessTunnel Namespaced Access-protected tunnel endpoint

Gateway & Security

CRD Scope Description
GatewayRule Cluster DNS/HTTP/L4 policy rule
GatewayList Cluster List for gateway rules
GatewayConfiguration Cluster Global gateway settings

Device Management

CRD Scope Description
DeviceSettingsPolicy Cluster WARP client configuration
DevicePostureRule Cluster Device health check rule

DNS & Connectivity

CRD Scope Description
DNSRecord Namespaced DNS record management

SSL/TLS & Certificates

CRD Scope Description
OriginCACertificate Namespaced Cloudflare Origin CA certificate with auto K8s Secret

R2 Storage

CRD Scope Description
R2Bucket Namespaced R2 storage bucket with lifecycle rules
R2BucketDomain Namespaced Custom domain for R2 bucket
R2BucketNotification Namespaced Event notifications for R2 bucket

Rules Engine

CRD Scope Description
ZoneRuleset Namespaced Zone ruleset (WAF, rate limiting, etc.)
TransformRule Namespaced URL rewrite & header modification
RedirectRule Namespaced URL redirect rules

Cloudflare Pages

CRD Scope Description
PagesProject Namespaced Pages project with build config and resource bindings
PagesDomain Namespaced Custom domain for Pages project
PagesDeployment Namespaced Pages deployment (create, retry, rollback)

Registrar (Enterprise)

CRD Scope Description
DomainRegistration Cluster Domain registration settings

Kubernetes Integration

CRD Scope Description
TunnelIngressClassConfig Cluster Configuration for Ingress integration
TunnelGatewayClassConfig Cluster Configuration 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.

Namespace and Secret Rules

The operator uses different Secret lookup rules based on CRD scope:

Resource Scope Secret Location
Namespaced Same namespace as the resource
Cluster Operator namespace (cloudflare-operator-system)

See Namespace Restrictions for detailed information.

Getting Help

Version Information

  • Current Version: v0.34.x (Alpha)
  • API Version: networking.cloudflare-operator.io/v1alpha2
  • Kubernetes: v1.28+
  • Go: 1.25
  • controller-runtime: v0.22
  • cloudflare-go SDK: v0.116.0
  • gateway-api: v1.4.1

Recent Changes

v0.34.x - Three-Layer Architecture

  • Architecture Simplification: Migrated from six-layer SyncState architecture to three-layer ConfigMap architecture
  • Direct API Calls: 1:1 resource controllers now call Cloudflare API directly
  • ConfigMap Aggregation: Tunnel configuration aggregated via ConfigMap instead of SyncState
  • Eliminated Service Layer: Removed intermediate service and sync layers for most resources
  • Improved Polling: Each CRD has independent controller with isolated Informer

v0.27.x - AccessApplication Inline Policies & NetworkRoute Improvements

  • AccessApplication Inline Policies: Define include/exclude/require rules directly in AccessApplication spec without creating separate AccessPolicy resources
  • NetworkRoute Cross-VNet Adoption: Fixed VirtualNetworkID handling to properly search and adopt routes across all Virtual Networks
  • New API methods: ListTunnelRoutesByNetwork, GetDefaultVirtualNetwork, ListVirtualNetworks

v0.26.0 - Cloudflare Pages Support

  • PagesProject CRD: Full Pages project management with build config, environment variables, and resource bindings (KV, R2, D1, Durable Objects, Queues, AI, Vectorize, Hyperdrive)
  • PagesDomain CRD: Custom domain management for Pages projects with validation status tracking
  • PagesDeployment CRD: Deployment operations (create, retry, rollback) with stage history tracking
  • Complete six-layer architecture implementation for Pages CRDs
  • Unit tests and E2E tests for all Pages controllers

v0.25.0 - Unified Aggregation Pattern

  • L5 Sync Controllers: Unified aggregation pattern for consistent state management
  • Improved config hash computation for change detection
  • Enhanced debouncing for reduced API calls

v0.24.0 - AccessPolicy CRD

  • AccessPolicy CRD: Reusable access policy templates for Zero Trust applications
  • Supports all policy rule types: include, exclude, require
  • Can be referenced by multiple AccessApplication resources

v0.23.x - Unified Sync Architecture & Comprehensive Testing

  • Unified Sync Architecture: Six-layer architecture with CloudflareSyncState CRD (100% CRD coverage)
  • E2E Test Framework: Comprehensive mock server and test infrastructure
    • WARP Connector lifecycle tests
    • State consistency tests for deletion handling
    • Tunnel lifecycle E2E tests
  • Unit Test Expansion: New test coverage for L5 Sync Controllers and L3 Services
    • lifecycle_controller_test.go - Tunnel lifecycle sync tests
    • connector_controller_test.go - WARP Connector sync tests
    • lifecycle_service_test.go - Tunnel service tests
    • connector_service_test.go - WARP service tests
    • origincacertificate_controller_test.go - Certificate sync tests
    • domainregistration_controller_test.go - Domain registration sync tests
  • Race Condition Fix: Single sync point eliminates concurrent API conflicts
  • Debouncing: 500ms aggregation reduces API calls

v0.22.x - Performance Improvements

  • Read-merge-write pattern for Tunnel config updates
  • WARP routing configuration sync to Cloudflare Remote Config
  • Improved error handling and retry logic

v0.21.0 - Type Safety Improvements

  • Replaced all interface{}/any types with precise typed structs
  • 30+ typed structs for Access rules, Gateway settings, DNS record data
  • 200+ new unit tests for type conversion functions

v0.20.0 - New CRDs

  • R2 Storage: R2Bucket, R2BucketDomain, R2BucketNotification
  • Rules Engine: ZoneRuleset, TransformRule, RedirectRule
  • SSL/TLS: OriginCACertificate (with auto K8s Secret)
  • Registrar: DomainRegistration (Enterprise)
  • OpenSSF Scorecard security compliance improvements

v0.19.0 - Multi-Zone Support

  • CloudflareDomain CRD for zone settings (SSL/TLS, Cache, Security, WAF)
  • Multi-zone DNS support for DNSRecord resources

v0.18.0 - Kubernetes Integration

  • Native Kubernetes Ingress controller support
  • Gateway API support (Gateway, HTTPRoute, TCPRoute, UDPRoute)
  • TunnelIngressClassConfig and TunnelGatewayClassConfig CRDs