Skip to content

crd-reference.md

Latest commit

 

History

History
908 lines (523 loc) · 50 KB

crd-reference.md

File metadata and controls

908 lines (523 loc) · 50 KB

API Reference

Packages

cloudflare.io/v2alpha1

Package v2alpha1 contains API Schema definitions for the cloudflare.io v2alpha1 API group.

Resource Types

CloudflareDNSRecord

CloudflareDNSRecord is the Schema for the cloudflarednsrecords API.

Field Description Default Validation
apiVersion string cloudflare.io/v2alpha1
kind string CloudflareDNSRecord
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec CloudflareDNSRecordSpec
status CloudflareDNSRecordStatus

CloudflareRuleset

CloudflareRuleset is the Schema for the cloudflarerulesets API.

Field Description Default Validation
apiVersion string cloudflare.io/v2alpha1
kind string CloudflareRuleset
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec CloudflareRulesetSpec
status CloudflareRulesetStatus

CloudflareTunnel

CloudflareTunnel is the Schema for the cloudflaretunnels API.

Field Description Default Validation
apiVersion string cloudflare.io/v2alpha1
kind string CloudflareTunnel
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec CloudflareTunnelSpec
status CloudflareTunnelStatus

CloudflareZone

CloudflareZone is the Schema for the cloudflarezones API.

Field Description Default Validation
apiVersion string cloudflare.io/v2alpha1
kind string CloudflareZone
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec CloudflareZoneSpec
status CloudflareZoneStatus

CloudflareZoneConfig

CloudflareZoneConfig is the Schema for the cloudflarezoneconfigs API

Field Description Default Validation
apiVersion string cloudflare.io/v2alpha1
kind string CloudflareZoneConfig
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. Optional: {}
spec CloudflareZoneConfigSpec spec defines the desired state of CloudflareZoneConfig Optional: {}
status CloudflareZoneConfigStatus status defines the observed state of CloudflareZoneConfig Optional: {}

Sub-types

The types below are referenced by one or more of the CRDs above; they are never instantiated directly.

AttachedSource

AttachedSource identifies one source object contributing to this tunnel. Fields are immutable post-create from the source reconciler's perspective.

Appears in:

Field Description Default Validation
kind string Kind is one of Service / Gateway / HTTPRoute / TLSRoute. Required: {}
name string Name of the source object. Required: {}
namespace string Namespace of the source object. Required: {}

BotManagementSettings

BotManagementSettings defines bot management settings for a Cloudflare zone.

Configuring this section requires the Zone:Bot Management:Edit scope on the API token and a Cloudflare plan that supports bot management. On Free plans this section's API call returns 403; the controller will surface that on the BotManagementApplied condition with reason=PlanTierInsufficient without preventing other groups (ssl / security / performance / network) from being applied.

Appears in:

Field Description Default Validation
enableJS boolean EnableJS enables JavaScript detections. Optional: {}
fightMode boolean FightMode enables bot fight mode. Optional: {}

CloudflareCredentialRef

CloudflareCredentialRef bundles the credential Secret and account ID. Per Foundation §5 these are inherited or overridden as a unit.

Appears in:

Field Description Default Validation
tokenSecretRef SecretReference TokenSecretRef points at the Secret carrying the Cloudflare API token.
accountID string AccountID is the Cloudflare account ID this credential scopes to.
Exactly one of accountID or accountIDSecretRef must be set.		 MinLength: 1
Optional: {}
accountIDSecretRef SecretReference AccountIDSecretRef resolves the Cloudflare account ID from a Secret
instead of the inline accountID (exactly one of the two must be set).
NOTE: SecretReference.Key defaults to "token"; set key: accountID
explicitly (the account ID is typically a distinct key in the same
Secret as the API token).		 Optional: {}
txtRegistryKeySecretRef SecretReference TxtRegistryKeySecretRef references a Secret holding an AES-256 key
(exactly 32 bytes, under the SecretReference.Key entry, default "key").
When set, the DNSRecord reconciler encrypts TXT companion-registry
payloads with AES-256-GCM (wire format v1::);
when unset, companions are written as plaintext JSON. The read side
auto-detects either form. See the TXT-registry design for the full
contract (companion naming, ownership verification, observe mode).		 Optional: {}

CloudflareDNSRecordSpec

CloudflareDNSRecordSpec defines the desired state of a Cloudflare DNS record.

Appears in:

Field Description Default Validation
zoneID string ZoneID is the Cloudflare Zone ID. Mutually exclusive with ZoneRef. MinLength: 1
Optional: {}
zoneRef ZoneReference ZoneRef references a CloudflareZone CR. Mutually exclusive with ZoneID. Optional: {}
name string Name is the DNS record name (e.g., "example.com", "sub.example.com"). MinLength: 1
Required: {}
type string Type is the DNS record type. Enum: [A AAAA CNAME SRV MX TXT NS]
Required: {}
content string Content is the record content (IP, hostname, etc.). XOR with DynamicIP. Optional: {}
dynamicIP boolean DynamicIP enables automatic external IP resolution. Only valid for A/AAAA.
XOR with Content.		 Optional: {}
ttl integer TTL in seconds. Use 1 for automatic. 1 Minimum: 1
Optional: {}
proxied boolean Proxied indicates whether the record is proxied through Cloudflare. Optional: {}
srvData SRVData SRVData contains SRV-specific record fields. Required when Type=SRV. Optional: {}
priority integer Priority is the MX record priority (lower = preferred). SRV records use
srvData.priority instead.		 Optional: {}
adopt boolean Adopt, when true, lets the operator take over a pre-existing Cloudflare
record instead of creating a new one. Adoption is TXT-ownership-verified:
the operator only adopts a record whose companion TXT registry entry
identifies THIS CloudflareDNSRecord. A record with no companion, a
foreign companion, or an unparseable one is refused
(AdoptRefusedNoTXT / AdoptRefusedForeign) — there is no silent backfill.
Pre-feature adopted records must be migrated via the documented
TXT-registry migration procedure (design §5.4) before Adopt succeeds.		 Optional: {}
mode RecordMode Mode controls operator write behavior on this record.
Default Managed: operator creates / updates / deletes the underlying
Cloudflare record and TXT companion as needed.
Observe: operator reads but never writes. Useful for verifying state
before claiming a record under Adopt:true (which would otherwise
refuse without a matching TXT companion).		 Managed Enum: [Managed Observe]
Optional: {}
cloudflare CloudflareCredentialRef Cloudflare overrides the operator-level default credential (sourced
from the operator's CLOUDFLARE_API_TOKEN/CLOUDFLARE_ACCOUNT_ID env,
chart-set from a Secret). Per Foundation §5 the token and accountID
are inherited or overridden as a unit; CEL rejects mixing.
Omitted entirely → the operator-level env default applies.		 Optional: {}
interval Duration Interval is the reconciliation interval for drift detection. 5m Optional: {}

CloudflareDNSRecordStatus

CloudflareDNSRecordStatus defines the observed state.

Appears in:

Field Description Default Validation
conditions Condition array Optional: {}
phase Phase Phase is a coarse summary derived from the Ready condition (Foundation §8). Pending Enum: [Ready Reconciling Error Pending]
Optional: {}
recordID string RecordID is the Cloudflare ID of the managed DNS record. Optional: {}
currentContent string CurrentContent is the most-recently-observed record content (post-resolve
for DynamicIP).		 Optional: {}
lastSyncedAt Time LastSyncedAt is the timestamp of the most recent successful reconcile. Optional: {}
txtRecordID string TxtRecordID is the Cloudflare-side ID of the companion TXT record.
Empty when no TXT companion has been written yet. Set on successful
TXT write; cleared on delete.		 Optional: {}
txtAffix string TxtAffix is the prefix used for the companion TXT record name (today
always "cf-txt"). Recorded for forensic clarity if the convention
changes (e.g., v2 affixing scheme). Operator-managed; users should
not edit.		 Optional: {}
observedTXT ObservedTXTPayload ObservedTXT carries the decoded TXT companion payload as last
observed from Cloudflare. Populated by both Managed and Observe modes
when a TXT companion exists. RawContent is set instead when decoding
fails.		 Optional: {}
observedGeneration integer ObservedGeneration is the .metadata.generation observed by the controller
during its last reconcile. When this lags .metadata.generation the
controller has not yet processed the latest spec.		 Optional: {}
lastReconcileToken string LastReconcileToken is the controller-owned ack of the most recent
cloudflare.io/reconcile-at annotation value the controller has
observed. The prelude in internal/reconcile.ForceReconcileRequested
compares this against the live annotation; mismatch forces a full
re-check this reconcile (bypassing the change-detection short-
circuit). The operator NEVER modifies the annotation itself — only
this status field — so admin force-triggers are not auto-cleared.		 Optional: {}
legacyCompanionGCDone boolean LegacyCompanionGCDone marks a record as having completed the one-time
legacy-name companion GC sweep. When true, gcLegacyCompanion is
skipped on subsequent reconciles. Stamped after a successful pass
that either (a) found no legacy candidates, or (b) successfully
deleted a legacy companion. Pre-S1 CRs reconcile once, set the
field, and never pay the GC cost again. Purely additive: existing
CRs without the field behave like field=false on first reconcile.		 Optional: {}

CloudflareRulesetSpec

CloudflareRulesetSpec defines the desired state of CloudflareRuleset.

Appears in:

Field Description Default Validation
zoneID string ZoneID is the Cloudflare Zone ID. Mutually exclusive with ZoneRef. MinLength: 1
Optional: {}
zoneRef ZoneReference ZoneRef references a CloudflareZone CR. Mutually exclusive with ZoneID. Optional: {}
cloudflare CloudflareCredentialRef Cloudflare overrides the top-level credential + account. Optional: {}
name string Name is the human-readable name for the ruleset. MinLength: 1
Required: {}
description string Description is an informative description of the ruleset. Optional: {}
phase string Phase is the Cloudflare ruleset entrypoint phase. This is the
Cloudflare API surface (not the operator's lifecycle Phase).		 Enum: [http_request_firewall_custom http_request_firewall_managed http_request_late_transform http_request_redirect http_request_transform http_response_headers_transform http_response_firewall_managed http_config_settings http_custom_errors http_ratelimit http_request_cache_settings http_request_origin http_request_dynamic_redirect http_response_compression]
Required: {}
rules RulesetRuleSpec array Rules is the list of rules in the ruleset. MinItems: 1
Required: {}
interval Duration Interval is the reconciliation interval. 30m Optional: {}

CloudflareRulesetStatus

CloudflareRulesetStatus defines the observed state of CloudflareRuleset.

Appears in:

Field Description Default Validation
conditions Condition array Conditions represent the latest available observations of the resource's state. Optional: {}
rulesetID string RulesetID is the Cloudflare Ruleset ID. Optional: {}
ruleCount integer RuleCount is the number of rules in the ruleset. Optional: {}
lastSyncedAt Time LastSyncedAt is the last time the ruleset was successfully synced. Optional: {}
observedGeneration integer ObservedGeneration is the most recently observed generation of the CR. Optional: {}
phase Phase Phase is a coarse summary of the reconciliation state. See
Phase for the enum values.		 Pending Enum: [Ready Reconciling Error Pending]
Optional: {}
lastReconcileToken string LastReconcileToken is the controller-owned ack of the most recent
cloudflare.io/reconcile-at annotation value the controller has
observed. The prelude in internal/reconcile.ForceReconcileRequested
compares this against the live annotation; mismatch forces a full
re-check this reconcile (bypassing the change-detection short-
circuit). The operator NEVER modifies the annotation itself — only
this status field — so admin force-triggers are not auto-cleared.		 Optional: {}

CloudflareTunnelSpec

CloudflareTunnelSpec defines the desired state of a Cloudflare Tunnel.

Appears in:

Field Description Default Validation
name string Name is the tunnel name in Cloudflare. Immutable after create — the
Cloudflare API treats config_src as write-once; renames would orphan
the cloudflared credential Secret and DNS targets. Capped at 52
characters so derived resource names (cloudflared-) fit
the 63-character DNS-1123 label limit.		 MaxLength: 52
MinLength: 1
Required: {}
connector ConnectorSpec Connector configures the operator-managed cloudflared Deployment. Required: {}
cloudflare CloudflareCredentialRef Cloudflare overrides the operator-level credential + accountID.
Per Foundation §5: credential and accountID inherited or overridden as
a unit. When unset, the operator-level default applies.		 Optional: {}
interval Duration Interval is the reconciliation interval. Default 30m. 30m Optional: {}
routing TunnelRoutingSpec Routing configures tunnel-wide originRequest defaults + the catch-all
default backend. The catch-all is auto-appended by the reconciler;
users only override it here when http_status:404 is wrong for them.		 Optional: {}

CloudflareTunnelStatus

CloudflareTunnelStatus is the observed state.

Appears in:

Field Description Default Validation
conditions Condition array Conditions: Ready, ConnectorReady, RemoteConfigApplied, plus reason
strings drawn from internal/conventions/conditions.go.		 Optional: {}
phase Phase Phase is a coarse summary derived from the Ready condition (Foundation §8). Pending Enum: [Ready Reconciling Error Pending]
Optional: {}
tunnelID string TunnelID is the Cloudflare-assigned UUID. Optional: {}
tunnelCNAME string TunnelCNAME is .cfargotunnel.com. Populated after create. Optional: {}
connectionsHealthy integer ConnectionsHealthy is the count of active connectors observed via
GET /cfd_tunnel/{id}/connections. Zero is a meaningful value (no
healthy connectors yet) and is always serialized.		 Optional: {}
observedIngress IngressEntrySnapshot array ObservedIngress is the materialized ingress list as last PUT to
/configurations. Used for drift detection — the reconciler skips a
PUT when the computed list matches this slice exactly.		 Optional: {}
observedDataplaneDeploymentHash string ObservedDataplaneDeploymentHash is the sha256 of the last successfully
applied dataplane Deployment's SSA-relevant fields. ensureDataplane
skips the Apply when the computed hash matches.		 Optional: {}
observedDataplaneServiceHash string ObservedDataplaneServiceHash is the analogous hash for the metrics Service. Optional: {}
attachedSources AttachedSource array AttachedSources lists every source object currently contributing to
this tunnel's ingress. Informational; the lexicographically-first entry
is the owner-reference target (or the original owner if still present).		 Optional: {}
observedGeneration integer ObservedGeneration is the .metadata.generation last reconciled. Optional: {}
lastSyncedAt Time LastSyncedAt is the wall-clock time of the most recent successful
reconcile (drift check + remote-config PUT, even if a no-op).		 Optional: {}
lastOrphanedAt Time LastOrphanedAt is the timestamp of the first reconcile that observed this
CR as orphaned (auto-created with no OwnerReferences and an empty
Status.AttachedSources). Self-delete fires only when a subsequent
reconcile observes the same state past the pending-deletion grace window
(60s). Cleared as soon as a source attaches or owner-transfer succeeds.
Operator-managed; user edits will be reverted on the next reconcile.		 Optional: {}
lastReconcileToken string LastReconcileToken is the controller-owned ack of the most recent
cloudflare.io/reconcile-at annotation value the controller has
observed. The prelude in internal/reconcile.ForceReconcileRequested
compares this against the live annotation; mismatch forces a full
re-check this reconcile (bypassing the change-detection short-
circuit). The operator NEVER modifies the annotation itself — only
this status field — so admin force-triggers are not auto-cleared.		 Optional: {}

CloudflareZoneConfigSpec

CloudflareZoneConfigSpec defines the desired state of CloudflareZoneConfig.

Appears in:

Field Description Default Validation
zoneID string ZoneID is the Cloudflare Zone ID.
Mutually exclusive with ZoneRef.		 MinLength: 1
Optional: {}
zoneRef ZoneReference ZoneRef references a CloudflareZone resource in the same namespace.
The controller resolves the zone ID from the referenced resource's status.
Mutually exclusive with ZoneID.		 Optional: {}
cloudflare CloudflareCredentialRef Cloudflare overrides the operator-level default credential (sourced
from the operator's CLOUDFLARE_API_TOKEN/CLOUDFLARE_ACCOUNT_ID env,
chart-set from a Secret). Per Foundation §5 the token and accountID
are inherited or overridden as a unit. Omitted entirely → the
operator-level env default applies.		 Optional: {}
interval Duration Interval is the reconciliation interval. 30m Optional: {}
ssl SSLSettings SSL defines SSL/TLS settings for the zone. Optional: {}
security SecuritySettings Security defines security settings for the zone. Optional: {}
performance PerformanceSettings Performance defines performance settings for the zone. Optional: {}
network NetworkSettings Network defines network settings for the zone. Optional: {}
dns DNSSettings DNS defines DNS-related settings for the zone. Optional: {}
botManagement BotManagementSettings BotManagement defines bot management settings for the zone. Optional: {}

CloudflareZoneConfigStatus

CloudflareZoneConfigStatus defines the observed state of CloudflareZoneConfig.

Appears in:

Field Description Default Validation
conditions Condition array Conditions represent the latest available observations of the resource's state. Optional: {}
phase Phase Phase is a coarse summary of the reconciliation state.
See Phase for the enum values.		 Pending Enum: [Ready Reconciling Error Pending]
Optional: {}
zoneID string ZoneID is the resolved Cloudflare Zone ID, populated regardless of
whether the spec used zoneID or zoneRef.		 Optional: {}
appliedSpecHash string AppliedSpecHash is a hash of the settings-relevant spec fields the last
time reconciliation successfully applied them. When the current hash
matches, the controller skips the per-setting API calls.		 Optional: {}
lastSyncedAt Time LastSyncedAt is the last time the zone config was successfully synced. Optional: {}
observedGeneration integer ObservedGeneration is the most recently observed generation of the CR. Optional: {}
lastReconcileToken string LastReconcileToken is the controller-owned ack of the most recent
cloudflare.io/reconcile-at annotation value the controller has
observed. The prelude in internal/reconcile.ForceReconcileRequested
compares this against the live annotation; mismatch forces a full
re-check this reconcile (bypassing the change-detection short-
circuit). The operator NEVER modifies the annotation itself — only
this status field — so admin force-triggers are not auto-cleared.		 Optional: {}

CloudflareZoneSpec

CloudflareZoneSpec defines the desired state of a Cloudflare Zone.

Appears in:

Field Description Default Validation
name string Name is the domain name to onboard (e.g., "example.com"). MinLength: 1
Required: {}
type string Type is the zone type. "full" means Cloudflare is authoritative DNS;
"partial" is CNAME setup; "secondary" mirrors an upstream master.
Immutable after creation.		 full Enum: [full partial secondary]
paused boolean Paused indicates whether the zone is paused (not serving traffic through Cloudflare). Optional: {}
deletionPolicy string DeletionPolicy controls what happens when the CR is deleted.
"Retain" (default) leaves the zone in Cloudflare; "Delete" removes it.		 Retain Enum: [Retain Delete]
cloudflare CloudflareCredentialRef Cloudflare overrides the operator-level default credential (sourced
from the operator's CLOUDFLARE_API_TOKEN/CLOUDFLARE_ACCOUNT_ID env,
chart-set from a Secret). Per Foundation §5 the token and accountID
are inherited or overridden as a unit; CEL on this CRD must reject
setting only one. Omitted entirely → the operator-level env default
applies.		 Optional: {}
interval Duration Interval is the reconciliation interval. 30m Optional: {}

CloudflareZoneStatus

CloudflareZoneStatus defines the observed state of a CloudflareZone.

Appears in:

Field Description Default Validation
conditions Condition array Optional: {}
zoneID string Optional: {}
status string Status is the zone status in Cloudflare (initializing, pending, active, moved). Optional: {}
nameServers string array Optional: {}
originalNameServers string array Optional: {}
originalRegistrar string Optional: {}
activatedOn Time Optional: {}
lastSyncedAt Time Optional: {}
observedGeneration integer Optional: {}
phase Phase Phase is a coarse summary derived from the Ready condition (Foundation §8). Pending Enum: [Ready Reconciling Error Pending]
Optional: {}
lastReconcileToken string LastReconcileToken is the controller-owned ack of the most recent
cloudflare.io/reconcile-at annotation value the controller has
observed. The prelude in internal/reconcile.ForceReconcileRequested
compares this against the live annotation; mismatch forces a full
re-check this reconcile (bypassing the change-detection short-
circuit). The operator NEVER modifies the annotation itself — only
this status field — so admin force-triggers are not auto-cleared.		 Optional: {}

ConnectorImage

ConnectorImage specifies the cloudflared container image.

Appears in:

Field Description Default Validation
repository string Repository is the container image repository. docker.io/cloudflare/cloudflared Optional: {}
tag string Tag is the image tag. When empty, the operator's compile-time default
applies. Partial overrides (repository-only OR tag-only) preserve the
user's value and combine with the default for the unset half.		 Optional: {}

ConnectorSpec

ConnectorSpec configures the operator-managed cloudflared Deployment.

Appears in:

Field Description Default Validation
replicas integer Replicas is the desired Pod count. Default 2. Range 1-25. No HPA. 2 Maximum: 25
Minimum: 1
image ConnectorImage Image specifies the cloudflared container image. When omitted, the
operator uses a compile-time default (cloudflare/cloudflared:).		 Optional: {}
protocol string Protocol selects cloudflared's transport. auto|http2|quic. auto Enum: [auto http2 quic]
logLevel string LogLevel passes to cloudflared --loglevel. info Enum: [debug info warn error]
gracePeriodSeconds integer GracePeriodSeconds is the cloudflared --grace-period (seconds).
terminationGracePeriodSeconds on the Pod is set to GracePeriodSeconds+15.		 30 Minimum: 0
resources ResourceRequirements Resources are the container resource requests/limits. Defaults observe-
not-prescribe: 50m/64Mi requests, 200m/256Mi limits.		 Optional: {}
nodeSelector object (keys:string, values:string) NodeSelector is a pass-through to the Pod spec. Optional: {}
tolerations Toleration array Tolerations is a pass-through to the Pod spec. Optional: {}
affinity Affinity Affinity is a pass-through to the Pod spec. Optional: {}
topologySpreadConstraints TopologySpreadConstraint array TopologySpreadConstraints is a pass-through to the Pod spec. Optional: {}
originCASecretRef SecretReference OriginCASecretRef, when set, mounts the referenced Secret at
/etc/cloudflared/ca/ in the cloudflared Pod and threads
originRequest.caPool: /etc/cloudflared/ca/ into ingress entries
when noTLSVerify is false. Use for self-signed in-cluster origin TLS.		 Optional: {}

DNSSettings

DNSSettings defines DNS-related zone settings.

Appears in:

Field Description Default Validation
cnameFlattening string CNAMEFlattening controls how the zone resolves CNAME records.
flatten_at_root: only flatten the apex (default Cloudflare behavior).
flatten_all: flatten every CNAME.
flatten_none: never flatten.		 Enum: [flatten_at_root flatten_all flatten_none]
Optional: {}

IngressEntrySnapshot

IngressEntrySnapshot is a status-only snapshot of one materialized ingress entry. NOT the source-of-truth shape — the reconciler computes ingress fresh each loop. Used for drift detection and PUT-skip; the projection rules must match internal/cloudflare/tunnel.go mapConfigurationGetResponse byte-for-byte so live-config and want-config snapshots are byte-comparable.

Appears in:

Field Description Default Validation
hostname string Hostname is the public hostname. Optional: {}
path string Path is the optional path filter. Optional: {}
service string Service is the cloudflared service URL (e.g. http://svc.ns:80). Optional: {}
originRequest IngressSnapshotOriginRequest OriginRequest mirrors the per-entry originRequest block as last PUT. Optional: {}

IngressSnapshotOriginRequest

IngressSnapshotOriginRequest projects the per-entry originRequest block. Conditional projection (mirrors mapConfigurationGetResponse):

  • NoTLSVerify projected only when true (unset-vs-explicit-false ambiguity is unavoidable).
  • OriginServerName projected only when non-empty.

At least one must be set or the parent IngressEntrySnapshot.OriginRequest stays nil.

Appears in:

Field Description Default Validation
originServerName string Optional: {}
noTLSVerify boolean Optional: {}

MinifySettings

MinifySettings defines minification settings for CSS, HTML, and JavaScript.

Appears in:

Field Description Default Validation
css string CSS enables CSS minification. Enum: [on off]
Optional: {}
html string HTML enables HTML minification. Enum: [on off]
Optional: {}
js string JS enables JavaScript minification. Enum: [on off]
Optional: {}

NetworkSettings

NetworkSettings defines network settings for a Cloudflare zone.

Appears in:

Field Description Default Validation
ipv6 string IPv6 enables IPv6 support. Enum: [on off]
Optional: {}
websockets string WebSockets enables WebSocket support. Enum: [on off]
Optional: {}
pseudoIPv4 string PseudoIPv4 controls Pseudo IPv4 behavior. Enum: [off add_header overwrite_header]
Optional: {}
ipGeolocation string IPGeolocation enables IP geolocation. Enum: [on off]
Optional: {}
opportunisticOnion string OpportunisticOnion enables onion routing. Enum: [on off]
Optional: {}

ObservedTXTPayload

ObservedTXTPayload mirrors the decoded RegistryPayload fields in the CR's Status for user-visible diagnostics. The internal payload type lives in internal/cloudflare/; this is the API-stable surface.

Appears in:

Field Description Default Validation
version integer Version is the payload schema version (currently always 1). Optional: {}
kind string Kind is the encoded owner kind ("CloudflareDNSRecord" in v2alpha1). Optional: {}
namespace string Namespace is the encoded owner namespace. Optional: {}
name string Name is the encoded owner name. Optional: {}
contentHash string ContentHash is the SHA256 of the canonicalized spec.content at TXT
write time. Used by drift detection.		 Optional: {}
rawContent string RawContent is the raw TXT content as received from Cloudflare when
decoding failed. Set instead of Version/Kind/Namespace/Name so users
can see what's there even when the operator can't parse it.		 Optional: {}
codec string Codec reports which decoder ("plaintext", "aes-gcm", or
"unrecognized") produced this payload.		 Optional: {}

PerformanceSettings

PerformanceSettings defines performance settings for a Cloudflare zone.

Appears in:

Field Description Default Validation
cacheLevel string CacheLevel controls the cache level. Enum: [aggressive basic simplified]
Optional: {}
browserCacheTTL integer BrowserCacheTTL is the browser cache TTL in seconds. 0 means respect existing headers. Minimum: 0
Optional: {}
minify MinifySettings Minify controls minification settings. Optional: {}
polish string Polish controls image optimization. Enum: [off lossless lossy]
Optional: {}
brotli string Brotli enables brotli compression. Enum: [on off]
Optional: {}
earlyHints string EarlyHints enables early hints. Enum: [on off]
Optional: {}
http2 string HTTP2 enables HTTP/2. Enum: [on off]
Optional: {}
http3 string HTTP3 enables HTTP/3. Enum: [on off]
Optional: {}
alwaysOnline string AlwaysOnline serves cached pages when the origin is unreachable. Enum: [on off]
Optional: {}
rocketLoader string RocketLoader defers JavaScript loading to improve perceived performance.
Cloudflare is sunsetting Rocket Loader; the field will be removed when
the API is retired.		 Enum: [on off]
Optional: {}

Phase

Underlying type: string

Phase is reserved as the schema seat for the coarse-grained status summary derived from the Ready condition. Specs 2/3 add Phase to each CRD's status; Foundation declares the type and constants only.

Validation:

  • Enum: [Ready Reconciling Error Pending]

Appears in:

Field Description
Ready
Reconciling
Error
Pending

RecordMode

Underlying type: string

RecordMode controls operator write behavior on a CloudflareDNSRecord.

Validation:

  • Enum: [Managed Observe]

Appears in:

Field Description
Managed RecordModeManaged is the default. The operator creates / updates /
deletes the underlying Cloudflare record and TXT companion as needed.
Observe RecordModeObserve means the operator reads Cloudflare state and
populates Status, but never writes. Spec.Adopt has no effect. Useful
for verifying state before promoting to Managed (which would
otherwise refuse adoption without a matching TXT companion under
design §2 Q2's no-silent-backfill rule).

RuleLogging

RuleLogging configures per-rule logging. Sibling of ActionParameters in the Cloudflare API. Today exposes only the API's enabled flag; future fields (sampling, destinations) extend this struct without rename.

Reconciliation note: omitting the logging block leaves Cloudflare's per-action default in place. Set logging.enabled only when you want to override the default for that action (e.g. enabled=true on skip, where logging is off by default). Setting enabled=false explicitly will diff against the API on every reconcile because Cloudflare's response shape can't distinguish that case from "no logging configured".

Appears in:

Field Description Default Validation
enabled boolean Enabled enables per-rule logging.
Note: due to Cloudflare API semantics, setting Enabled=false is
indistinguishable from omitting the Logging block entirely. The
operator normalizes both forms to "logging unset" on write to avoid
spurious drift loops. To enable logging, set true.		 Optional: {}

RulesetRuleSpec

RulesetRuleSpec defines a single rule within a Cloudflare Ruleset.

Appears in:

Field Description Default Validation
action string Action is the action to perform when the rule matches. Enum: [block challenge js_challenge managed_challenge log skip execute redirect rewrite route score serve_error set_cache_settings set_config compress_response force_connection_close]
Required: {}
expression string Expression is the filter expression for the rule. MinLength: 1
Required: {}
description string Description is an informative description of the rule. Optional: {}
enabled boolean Enabled indicates whether the rule is active. true Optional: {}
actionParameters JSON ActionParameters contains action-specific parameters as free-form JSON. Type: object
Optional: {}
logging RuleLogging Logging configures per-rule logging behavior. Sibling of ActionParameters
in the Cloudflare API; do not encode logging via ActionParameters.		 Optional: {}

SRVData

SRVData contains SRV-specific record fields.

Appears in:

Field Description Default Validation
service string Service is the symbolic service name (e.g., "_satisfactory", "_minecraft"). Required: {}
proto string Proto is the transport protocol. Enum: [_tcp _udp _tls]
Required: {}
priority integer Priority is the SRV priority (lower = preferred). Maximum: 65535
Minimum: 0
weight integer Weight is the SRV weight for records with the same priority
(higher = more traffic).		 Maximum: 65535
Minimum: 0
port integer Port is the TCP/UDP port the service listens on. Maximum: 65535
Minimum: 0
target string Target is the canonical hostname of the machine providing the service. Required: {}

SSLSettings

SSLSettings defines SSL/TLS settings for a Cloudflare zone.

Appears in:

Field Description Default Validation
mode string Mode is the SSL mode. Enum: [off flexible full strict]
Optional: {}
minTLSVersion string MinTLSVersion is the minimum TLS version. Enum: [1.0 1.1 1.2 1.3]
Optional: {}
tls13 string TLS13 controls TLS 1.3 setting. Enum: [on off zrt]
Optional: {}
alwaysUseHTTPS string AlwaysUseHTTPS redirects all HTTP requests to HTTPS. Enum: [on off]
Optional: {}
automaticHTTPSRewrites string AutomaticHTTPSRewrites rewrites HTTP URLs to HTTPS in page content. Enum: [on off]
Optional: {}
opportunisticEncryption string OpportunisticEncryption enables opportunistic encryption. Enum: [on off]
Optional: {}

SecretReference

SecretReference identifies a Kubernetes Secret carrying credentials.

Appears in:

Field Description Default Validation
name string Name of the Secret. MinLength: 1
Required: {}
namespace string Namespace of the Secret. Defaults to the referencing CR's namespace. Optional: {}
key string Key inside the Secret holding the Cloudflare API token. Defaults to "token". token Optional: {}

SecurityHeaderSettings

SecurityHeaderSettings models the zone-level HSTS / Strict-Transport-Security setting (the strict_transport_security payload of the Cloudflare security_header API). All fields are optional; nil fields are omitted from the API call so individual flags can be toggled without re-asserting the rest.

Appears in:

Field Description Default Validation
enabled boolean Enabled toggles HSTS for the zone. Optional: {}
maxAge integer MaxAge is the HSTS max-age in seconds. Maximum: 3.1536e+07
Minimum: 0
Optional: {}
includeSubdomains boolean IncludeSubdomains extends HSTS to subdomains. Optional: {}
preload boolean Preload requests inclusion in browser HSTS preload lists. Optional: {}
nosniff boolean Nosniff enables the X-Content-Type-Options: nosniff response header. Optional: {}

SecuritySettings

SecuritySettings defines security settings for a Cloudflare zone.

Appears in:

Field Description Default Validation
securityLevel string SecurityLevel controls the security level. Enum: [essentially_off low medium high under_attack]
Optional: {}
challengeTTL integer ChallengeTTL is the challenge TTL in seconds. Enum: [300 900 1800 2700 3600 7200 10800 14400 28800 57600 86400]
Optional: {}
browserCheck string BrowserCheck enables browser integrity check. Enum: [on off]
Optional: {}
emailObfuscation string EmailObfuscation enables email obfuscation. Enum: [on off]
Optional: {}
securityHeader SecurityHeaderSettings SecurityHeader configures the zone's HSTS / Strict-Transport-Security header. Optional: {}
serverSideExclude string ServerSideExclude hides sensitive content from suspicious visitors. Enum: [on off]
Optional: {}
hotlinkProtection string HotlinkProtection blocks hotlinking of images. Enum: [on off]
Optional: {}

TunnelFallback

TunnelFallback is the catch-all backend. Discriminated union: exactly one of URL or HTTPStatus must be set. Enforced via CEL on the parent CRD.

Appears in:

Field Description Default Validation
url string URL is a full URL backend (e.g. "http://default.svc.cluster.local"). Optional: {}
httpStatus integer HTTPStatus is a synthetic status backend (e.g. 404, 503). Optional: {}

TunnelOriginRequest

TunnelOriginRequest mirrors cloudflared's originRequest block at the tunnel level (defaults inherited by every ingress entry that does not supply its own via per-source annotations). Per-ingress overrides come from cloudflare.io/origin-server-name and cloudflare.io/no-tls-verify on the source Gateway / HTTPRoute / TLSRoute / Service.

Appears in:

Field Description Default Validation
noTLSVerify boolean NoTLSVerify disables TLS verification to the origin. Optional: {}
originServerName string OriginServerName is the expected SAN on the origin certificate. Optional: {}

TunnelRoutingSpec

TunnelRoutingSpec configures tunnel-wide routing defaults.

Appears in:

Field Description Default Validation
fallback TunnelFallback Fallback handles traffic that no synthesized ingress entry matches.
Omit to fall through to the auto-appended http_status:404.		 Optional: {}
originRequest TunnelOriginRequest OriginRequest defaults applied to all synthesized rules unless overridden
by per-source annotations (no-tls-verify, origin-server-name, …).		 Optional: {}

ZoneReference

ZoneReference selects a CloudflareZone CR by name (and optional namespace). Used XOR with a literal zoneID per Foundation §7.

Appears in:

Field Description Default Validation
name string Name of the CloudflareZone CR. MinLength: 1
Required: {}
namespace string Namespace of the CloudflareZone CR. Defaults to the referencing CR's namespace. Optional: {}