cfgate.iocfgate v0.2.0-alpha.11 · Release documentation

CloudflareDNS schema

These fields come from the released CRD. Required means required when its parent object is present. Schema defaults do not describe every runtime fallback.

v1alpha1

Field	Type	Required in parent	Schema default	Description

Field	Type	Required in parent	Schema default	Description
“	object	no	none	CloudflareDNS is the Schema for the cloudflarednses API. CloudflareDNS manages DNS record synchronization independently from CloudflareTunnel resources. It supports two target modes: tunnel references (for tunnel-based CNAME records) and external targets (for non-tunnel DNS management). DNS records can be sourced from Gateway API routes or explicitly defined. CloudflareDNS implements ownership tracking via TXT records (aligned with external-dns patterns) to enable safe multi-cluster deployments and prevent accidental deletion of records created by other installations. Status conditions: - Ready: DNS sync is fully operational - CredentialsValid: Cloudflare credentials have been validated - ZonesResolved: All configured zones have been resolved via API - RecordsSynced: DNS records have been synchronized to Cloudflare - OwnershipVerified: TXT ownership records have been verified, when enabled

Field	Type	Required in parent	Schema default	Description
`apiVersion`	string	no	none	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources

Field	Type	Required in parent	Schema default	Description
`kind`	string	no	none	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds

Field	Type	Required in parent	Schema default	Description
`metadata`	object	no	none

Field	Type	Required in parent	Schema default	Description
`spec`	object	no	none	CloudflareDNSSpec defines the desired state of a CloudflareDNS resource. CloudflareDNSSpec configures DNS record synchronization, including the target (tunnel or external), zones to manage, hostname sources, and ownership tracking. Either tunnelRef or externalTarget must be specified (mutually exclusive).

Validation for spec:

x-kubernetes-validations:
  - message: either tunnelRef or externalTarget must be specified
    rule: has(self.tunnelRef) || has(self.externalTarget)
  - message: tunnelRef and externalTarget are mutually exclusive
    rule: "!(has(self.tunnelRef) && has(self.externalTarget))"
  - message: cloudflare credentials required when using externalTarget
    rule: has(self.tunnelRef) || has(self.cloudflare)
  - message: TXT ownership prefix is immutable
    rule: "(has(self.ownership) && has(self.ownership.txtRecord) &&
      has(self.ownership.txtRecord.prefix) ? self.ownership.txtRecord.prefix :
      '_cfgate') == (has(oldSelf.ownership) && has(oldSelf.ownership.txtRecord)
      && has(oldSelf.ownership.txtRecord.prefix) ?
      oldSelf.ownership.txtRecord.prefix : '_cfgate')"

Field	Type	Required in parent	Schema default	Description
`spec.cleanupPolicy`	object	no	none	CleanupPolicy defines cleanup behavior for records.

Field	Type	Required in parent	Schema default	Description
`spec.cleanupPolicy.deleteOnResourceRemoval`	boolean	no	none	DeleteOnResourceRemoval deletes records when CloudflareDNS resource is deleted. nil defaults to true.

Field	Type	Required in parent	Schema default	Description
`spec.cleanupPolicy.deleteOnRouteRemoval`	boolean	no	none	DeleteOnRouteRemoval deletes obsolete hostname, type, or selected-zone records. This applies to discovered routes and explicit hostnames. nil defaults to true.

Field	Type	Required in parent	Schema default	Description
`spec.cleanupPolicy.onlyManaged`	boolean	no	none	OnlyManaged is retained for compatibility. Ownership verification is always required; setting false cannot authorize deletion of foreign or unmarked records.

Field	Type	Required in parent	Schema default	Description
`spec.cloudflare`	object	no	none	Cloudflare API credentials (required when using externalTarget). When using tunnelRef, credentials are inherited from the tunnel.

Validation for spec.cloudflare:

x-kubernetes-validations:
  - message: either accountId or accountName must be specified
    rule: has(self.accountId) || has(self.accountName)
  - message: accountId must be a 32-character hex string
    rule: "!has(self.accountId) || self.accountId.matches('^[a-f0-9]{32}$')"

Field	Type	Required in parent	Schema default	Description
`spec.cloudflare.accountId`	string	no	none	AccountID is the Cloudflare Account ID.

Validation for spec.cloudflare.accountId:

maxLength: 32

Field	Type	Required in parent	Schema default	Description
`spec.cloudflare.accountName`	string	no	none	AccountName is the Cloudflare Account name. Will be looked up via API.

Validation for spec.cloudflare.accountName:

maxLength: 255

Field	Type	Required in parent	Schema default	Description
`spec.cloudflare.secretKeys`	object	no	none	SecretKeys defines the key mappings within the secret.

Field	Type	Required in parent	Schema default	Description
`spec.cloudflare.secretKeys.apiToken`	string	no	`"CLOUDFLARE_API_TOKEN"`	APIToken is the key name for the Cloudflare API token.

Validation for spec.cloudflare.secretKeys.apiToken:

maxLength: 253

Field	Type	Required in parent	Schema default	Description
`spec.cloudflare.secretRef`	object	yes	none	SecretRef references the Secret containing Cloudflare API credentials. The secret must contain an API token (not tunnel token).

Field	Type	Required in parent	Schema default	Description
`spec.cloudflare.secretRef.name`	string	yes	none	Name of the secret.

Validation for spec.cloudflare.secretRef.name:

maxLength: 253
minLength: 1

Field	Type	Required in parent	Schema default	Description
`spec.cloudflare.secretRef.namespace`	string	no	none	Namespace of the secret. Defaults to the tunnel’s namespace.

Validation for spec.cloudflare.secretRef.namespace:

maxLength: 63

Field	Type	Required in parent	Schema default	Description
`spec.defaults`	object	no	none	Defaults defines default settings for DNS records.

Validation for spec.defaults:

x-kubernetes-validations:
  - message: TTL must be 1 (auto) or between 60 and 86400 seconds
    rule: "!has(self.ttl) || self.ttl == 1 || (self.ttl >= 60 && self.ttl <= 86400)"

Field	Type	Required in parent	Schema default	Description
`spec.defaults.proxied`	boolean	no	`true`	Proxied enables Cloudflare proxy by default.

Field	Type	Required in parent	Schema default	Description
`spec.defaults.ttl`	integer	no	`1`	TTL is the default DNS record TTL in seconds. Valid values: 1 (auto) or 60-86400 (explicit).

Validation for spec.defaults.ttl:

format: int32
maximum: 86400
minimum: 1

Field	Type	Required in parent	Schema default	Description
`spec.externalTarget`	object	no	none	ExternalTarget specifies a non-tunnel DNS target.

Field	Type	Required in parent	Schema default	Description
`spec.externalTarget.type`	string	yes	none	Type is the DNS record type.

Allowed values for spec.externalTarget.type: ["CNAME","A","AAAA"].

Field	Type	Required in parent	Schema default	Description
`spec.externalTarget.value`	string	yes	none	Value is the target value (domain for CNAME, IP for A/AAAA). Max 253: RFC 1035 section 2.3.4 FQDN presentation-format limit.

Validation for spec.externalTarget.value:

maxLength: 253
minLength: 1

Field	Type	Required in parent	Schema default	Description
`spec.fallbackCredentialsRef`	object	no	none	FallbackCredentialsRef references fallback Cloudflare API credentials. Used during deletion when primary credentials are unavailable.

Field	Type	Required in parent	Schema default	Description
`spec.fallbackCredentialsRef.name`	string	yes	none	Name of the secret.

Validation for spec.fallbackCredentialsRef.name:

maxLength: 253
minLength: 1

Field	Type	Required in parent	Schema default	Description
`spec.fallbackCredentialsRef.namespace`	string	no	none	Namespace of the secret. Defaults to the resource’s namespace if empty.

Validation for spec.fallbackCredentialsRef.namespace:

maxLength: 63

Field	Type	Required in parent	Schema default	Description
`spec.ownership`	object	no	none	Ownership defines how to track record ownership.

Field	Type	Required in parent	Schema default	Description
`spec.ownership.comment`	object	no	none	Comment configures comment-based ownership. Deprecated: since v0.1.0-alpha.13. All fields are ignored. Will be removed in a future cleanup release.

Field	Type	Required in parent	Schema default	Description
`spec.ownership.comment.enabled`	boolean	no	`false`	Enabled enables comment-based ownership tracking. Deprecated: since v0.1.0-alpha.13. This field is ignored. The controller always writes an exact resource owner marker. Will be removed in a future cleanup release.

Field	Type	Required in parent	Schema default	Description
`spec.ownership.comment.template`	string	no	`"managed by cfgate"`	Template is the comment template. Deprecated: since v0.1.0-alpha.13. This field is ignored. The controller always uses an exact resource owner marker. Will be removed in a future cleanup release.

Validation for spec.ownership.comment.template:

maxLength: 255

Field	Type	Required in parent	Schema default	Description
`spec.ownership.ownerId`	string	no	none	OwnerID is a deprecated legacy migration hint, not an ownership authority. Since v0.2.0-alpha.6 the controller persists installation/resource UIDs in status.ownerId. Setting this field cannot adopt another resource’s records.

Validation for spec.ownership.ownerId:

maxLength: 253
pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(/[a-z0-9]([-a-z0-9]*[a-z0-9])?)?$

Field	Type	Required in parent	Schema default	Description
`spec.ownership.txtRecord`	object	no	none	TXTRecord configures TXT record-based ownership.

Field	Type	Required in parent	Schema default	Description
`spec.ownership.txtRecord.enabled`	boolean	no	none	Enabled enables TXT record ownership tracking. nil defaults to true.

Field	Type	Required in parent	Schema default	Description
`spec.ownership.txtRecord.prefix`	string	no	`"_cfgate"`	Prefix is the immutable prefix for TXT record names.

Validation for spec.ownership.txtRecord.prefix:

maxLength: 63

Field	Type	Required in parent	Schema default	Description
`spec.policy`	string	no	`"sync"`	Policy controls DNS record lifecycle.

Allowed values for spec.policy: ["sync","upsert-only","create-only"].

Field	Type	Required in parent	Schema default	Description
`spec.source`	object	no	none	Source defines where to get hostnames to sync.

Field	Type	Required in parent	Schema default	Description
`spec.source.explicit`	array	no	none	Explicit defines explicit hostnames to sync.

Validation for spec.source.explicit:

maxItems: 100

Field	Type	Required in parent	Schema default	Description
`spec.source.explicit[]`	object	no	none	DNSExplicitHostname defines an explicit hostname to sync with optional per-hostname configuration. DNSExplicitHostname provides direct specification of DNS hostnames without depending on Gateway API route discovery. The Target field supports the {{ .TunnelDomain }} template variable for dynamic resolution when using tunnelRef.

Validation for spec.source.explicit[]:

x-kubernetes-validations:
  - message: TTL must be 1 (auto) or between 60 and 86400 seconds
    rule: "!has(self.ttl) || self.ttl == 1 || (self.ttl >= 60 && self.ttl <= 86400)"

Field	Type	Required in parent	Schema default	Description
`spec.source.explicit[].hostname`	string	yes	none	Hostname is the DNS hostname to create. Max 253: RFC 1035 section 2.3.4 FQDN presentation-format limit.

Validation for spec.source.explicit[].hostname:

maxLength: 253
minLength: 1
x-kubernetes-validations:
  - message: each DNS label must not exceed 63 octets (RFC 1035 section 2.3.4)
    rule: self.split('.').all(s, size(s) <= 63)

Field	Type	Required in parent	Schema default	Description
`spec.source.explicit[].proxied`	boolean	no	none	Proxied enables Cloudflare proxy for this record. nil inherits from zone or defaults.

Field	Type	Required in parent	Schema default	Description
`spec.source.explicit[].target`	string	no	none	Target overrides the resolved record target for this hostname. Supports template variable {{ .TunnelDomain }} when tunnelRef is used. Defaults to the resource-level resolved target when omitted. Max 253: RFC 1035 section 2.3.4 FQDN presentation-format limit.

Validation for spec.source.explicit[].target:

maxLength: 253

Field	Type	Required in parent	Schema default	Description
`spec.source.explicit[].ttl`	integer	no	none	TTL is the DNS record TTL in seconds. 1 means auto (Cloudflare managed). Omitted values inherit spec.defaults.ttl. Valid values: 1 (auto) or 60-86400.

Validation for spec.source.explicit[].ttl:

format: int32
maximum: 86400
minimum: 1

Field	Type	Required in parent	Schema default	Description
`spec.source.gatewayRoutes`	object	no	none	GatewayRoutes configures watching Gateway API routes.

Field	Type	Required in parent	Schema default	Description
`spec.source.gatewayRoutes.annotationFilter`	string	no	none	AnnotationFilter only syncs routes with this annotation.

Validation for spec.source.gatewayRoutes.annotationFilter:

maxLength: 255

Field	Type	Required in parent	Schema default	Description
`spec.source.gatewayRoutes.enabled`	boolean	no	`true`	Enabled enables watching Gateway API routes.

Field	Type	Required in parent	Schema default	Description
`spec.source.gatewayRoutes.namespaceSelector`	object	no	none	NamespaceSelector limits route discovery to specific namespaces.

Validation for spec.source.gatewayRoutes.namespaceSelector:

x-kubernetes-validations:
  - message: at least one selector must be specified
    rule: has(self.matchLabels) || has(self.matchNames)

Field	Type	Required in parent	Schema default	Description
`spec.source.gatewayRoutes.namespaceSelector.matchLabels`	object	no	none	MatchLabels selects namespaces with matching labels.

Field	Type	Required in parent	Schema default	Description
`spec.source.gatewayRoutes.namespaceSelector.matchLabels[key]`	string	no	none

Field	Type	Required in parent	Schema default	Description
`spec.source.gatewayRoutes.namespaceSelector.matchNames`	array	no	none	MatchNames selects namespaces by name.

Validation for spec.source.gatewayRoutes.namespaceSelector.matchNames:

maxItems: 50

Field	Type	Required in parent	Schema default	Description
`spec.source.gatewayRoutes.namespaceSelector.matchNames[]`	string	no	none

Field	Type	Required in parent	Schema default	Description
`spec.tunnelRef`	object	no	none	TunnelRef references a CloudflareTunnel for CNAME target resolution.

Field	Type	Required in parent	Schema default	Description
`spec.tunnelRef.name`	string	yes	none	Name is the name of the CloudflareTunnel.

Validation for spec.tunnelRef.name:

maxLength: 63
minLength: 1

Field	Type	Required in parent	Schema default	Description
`spec.tunnelRef.namespace`	string	no	none	Namespace is the namespace of the CloudflareTunnel. Defaults to the CloudflareDNS’s namespace.

Validation for spec.tunnelRef.namespace:

maxLength: 63

Field	Type	Required in parent	Schema default	Description
`spec.zones`	array	yes	none	Zones defines the DNS zones to manage.

Validation for spec.zones:

maxItems: 10
minItems: 1

Field	Type	Required in parent	Schema default	Description
`spec.zones[]`	object	no	none	DNSZoneConfig defines a DNS zone where records will be managed. DNSZoneConfig identifies a Cloudflare DNS zone either by name (requiring API lookup) or by explicit zone ID. The optional Proxied field sets the default proxy behavior for all records in this zone.

Field	Type	Required in parent	Schema default	Description
`spec.zones[].id`	string	no	none	ID is the optional explicit zone ID (skips API lookup).

Validation for spec.zones[].id:

maxLength: 32
pattern: ^[a-f0-9]{32}$

Field	Type	Required in parent	Schema default	Description
`spec.zones[].name`	string	yes	none	Name is the zone domain name (e.g., example.com). Max 253: RFC 1035 section 2.3.4 FQDN presentation-format limit.

Validation for spec.zones[].name:

maxLength: 253
minLength: 1
x-kubernetes-validations:
  - message: each DNS label must not exceed 63 octets (RFC 1035 section 2.3.4)
    rule: self.split('.').all(s, size(s) <= 63)

Field	Type	Required in parent	Schema default	Description
`spec.zones[].proxied`	boolean	no	none	Proxied sets the default proxied setting for this zone. nil inherits from spec.defaults.proxied.

Field	Type	Required in parent	Schema default	Description
`status`	object	no	none	CloudflareDNSStatus defines the observed state of a CloudflareDNS resource. CloudflareDNSStatus captures the synchronization state of all DNS records, including counts of synced, pending, and failed records. The ResolvedTarget field shows the actual CNAME target being used (either from tunnel or external target).

Field	Type	Required in parent	Schema default	Description
`status.conditions`	array	no	none	Conditions represent the latest available observations.

Validation for status.conditions:

x-kubernetes-list-map-keys:
  - type
x-kubernetes-list-type: map

Field	Type	Required in parent	Schema default	Description
`status.conditions[]`	object	no	none	Condition contains details for one aspect of the current state of this API Resource.

Field	Type	Required in parent	Schema default	Description
`status.conditions[].lastTransitionTime`	string	yes	none	lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.

Validation for status.conditions[].lastTransitionTime:

format: date-time

Field	Type	Required in parent	Schema default	Description
`status.conditions[].message`	string	yes	none	message is a human readable message indicating details about the transition. This may be an empty string.

Validation for status.conditions[].message:

maxLength: 32768

Field	Type	Required in parent	Schema default	Description
`status.conditions[].observedGeneration`	integer	no	none	observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.

Validation for status.conditions[].observedGeneration:

format: int64
minimum: 0

Field	Type	Required in parent	Schema default	Description
`status.conditions[].reason`	string	yes	none	reason contains a programmatic identifier indicating the reason for the condition’s last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.

Validation for status.conditions[].reason:

maxLength: 1024
minLength: 1
pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$

Field	Type	Required in parent	Schema default	Description
`status.conditions[].status`	string	yes	none	status of the condition, one of True, False, Unknown.

Allowed values for status.conditions[].status: ["True","False","Unknown"].

Field	Type	Required in parent	Schema default	Description
`status.conditions[].type`	string	yes	none	type of condition in CamelCase or in foo.example.com/CamelCase.

Validation for status.conditions[].type:

maxLength: 316
pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$

Field	Type	Required in parent	Schema default	Description
`status.failedRecords`	integer	no	none	FailedRecords is the number of records that failed to sync.

Validation for status.failedRecords:

format: int32

Field	Type	Required in parent	Schema default	Description
`status.lastSyncTime`	string	no	none	LastSyncTime is the last time records were synced.

Validation for status.lastSyncTime:

format: date-time

Field	Type	Required in parent	Schema default	Description
`status.observedGeneration`	integer	no	none	ObservedGeneration is the generation observed by the controller.

Validation for status.observedGeneration:

format: int64

Field	Type	Required in parent	Schema default	Description
`status.ownerId`	string	no	none	OwnerID persists the installation namespace UID and resource UID for cleanup.

Field	Type	Required in parent	Schema default	Description
`status.ownershipPrefix`	string	no	none	OwnershipPrefix pins the claim namespace used for publication and cleanup.

Field	Type	Required in parent	Schema default	Description
`status.pendingRecords`	integer	no	none	PendingRecords is the number of records pending sync.

Validation for status.pendingRecords:

format: int32

Field	Type	Required in parent	Schema default	Description
`status.pendingWrites`	array	no	none	PendingWrites retains destinations until their results are durably recorded.

Validation for status.pendingWrites:

maxItems: 1000

Field	Type	Required in parent	Schema default	Description
`status.pendingWrites[]`	object	no	none	DNSPendingWrite records a destination before an external write. It survives failed status writes and later edits to the desired zones or hostnames.

Field	Type	Required in parent	Schema default	Description
`status.pendingWrites[].hostname`	string	yes	none	Hostname and Type identify the intended record.

Field	Type	Required in parent	Schema default	Description
`status.pendingWrites[].operationId`	string	yes	none	OperationID distinguishes a creation from another record incarnation.

Validation for status.pendingWrites[].operationId:

pattern: ^[A-Za-z0-9_-]{10}$

Field	Type	Required in parent	Schema default	Description
`status.pendingWrites[].previousOwned`	boolean	no	none	PreviousOwned distinguishes an unowned baseline from a foreign replacement.

Field	Type	Required in parent	Schema default	Description
`status.pendingWrites[].previousRecordId`	string	no	none	PreviousRecordID identifies an existing owned record before an update.

Field	Type	Required in parent	Schema default	Description
`status.pendingWrites[].type`	string	yes	none

Field	Type	Required in parent	Schema default	Description
`status.pendingWrites[].zoneId`	string	yes	none	ZoneID is the resolved destination, independent of current spec.zones.

Field	Type	Required in parent	Schema default	Description
`status.records`	array	no	none	Records contains the status of individual DNS records.

Validation for status.records:

maxItems: 1000

Field	Type	Required in parent	Schema default	Description
`status.records[]`	object	no	none	DNSRecordSyncStatus represents the synchronization status of a single DNS record. DNSRecordSyncStatus tracks individual DNS record state including the Cloudflare record ID, current configuration, and sync status. The Status field indicates: Synced (successfully synchronized), Pending (awaiting sync), Skipped (policy prevented synchronization), or Failed (sync failed, see Error field).

Field	Type	Required in parent	Schema default	Description
`status.records[].error`	string	no	none	Error contains the error message if status is Failed.

Field	Type	Required in parent	Schema default	Description
`status.records[].hostname`	string	yes	none	Hostname is the DNS hostname.

Field	Type	Required in parent	Schema default	Description
`status.records[].proxied`	boolean	yes	none	Proxied indicates if Cloudflare proxy is enabled.

Field	Type	Required in parent	Schema default	Description
`status.records[].recordId`	string	no	none	RecordID is the Cloudflare record ID.

Field	Type	Required in parent	Schema default	Description
`status.records[].status`	string	yes	none	Status is the sync status: Synced, Pending, Skipped, Failed.

Field	Type	Required in parent	Schema default	Description
`status.records[].target`	string	yes	none	Target is the record target/content.

Field	Type	Required in parent	Schema default	Description
`status.records[].ttl`	integer	no	none	TTL is the record TTL.

Validation for status.records[].ttl:

format: int32

Field	Type	Required in parent	Schema default	Description
`status.records[].type`	string	yes	none	Type is the DNS record type (CNAME, A, AAAA).

Field	Type	Required in parent	Schema default	Description
`status.records[].zoneId`	string	no	none	ZoneID is the Cloudflare zone ID where the record was created.

Field	Type	Required in parent	Schema default	Description
`status.resolvedTarget`	string	no	none	ResolvedTarget is the resolved CNAME target (tunnel domain or external value).

Field	Type	Required in parent	Schema default	Description
`status.syncedRecords`	integer	no	none	SyncedRecords is the number of successfully synced records.

Validation for status.syncedRecords:

format: int32