Manages DNS record synchronization independently from CloudflareTunnel resources.

API Version: cfgate.io/v1alpha1 Kind: CloudflareDNS Short Names: cfdns, dns Scope: Namespaced

CloudflareDNS manages DNS record synchronization for Cloudflare zones. It supports two target modes: tunnel references (for tunnel-based CNAME records) and external targets (for non-tunnel DNS records such as A, AAAA, or external CNAMEs). DNS records can be sourced automatically from Gateway API HTTPRoute resources or explicitly defined in the spec.

CloudflareDNS implements ownership tracking via TXT records, aligned with the external-dns pattern, to enable safe multi-cluster deployments and prevent accidental deletion of records created by other installations. Lifecycle behavior is controlled via spec.policy (sync, upsert-only, create-only) and spec.cleanupPolicy.

When using tunnelRef, credentials are inherited from the referenced CloudflareTunnel. When using externalTarget, the cloudflare field must be provided explicitly.

These are mutually exclusive. Exactly one must be specified.

tunnelRef: References a CloudflareTunnel resource. DNS CNAME records are created pointing to the tunnel's domain ({tunnelId}.cfargotunnel.com). The controller waits for the tunnel to become ready before creating DNS records. When using tunnelRef, Cloudflare API credentials are inherited from the tunnel, so no separate spec.cloudflare is needed.

externalTarget: Points DNS records to an external resource. Supports CNAME (external domain), A (IPv4 address), and AAAA (IPv6 address) record types. When using externalTarget, spec.cloudflare must be provided since there is no tunnel to inherit credentials from.

# Tunnel-backed DNS
spec:
  tunnelRef:
    name: prod-tunnel

# External CNAME
spec:
  externalTarget:
    type: CNAME
    value: external-lb.example.com
  cloudflare:
    accountId: "a1b2c3d4..."
    secretRef:
      name: cloudflare-api-token

# External A record
spec:
  externalTarget:
    type: A
    value: "203.0.113.10"
  cloudflare:
    accountId: "a1b2c3d4..."
    secretRef:
      name: cloudflare-api-token

Defines the Cloudflare DNS zones where records will be managed. At least one zone is required (max 10). The controller extracts the zone from each hostname using the public suffix list, matches it against configured zones, and syncs records to the correct zone. Your API token's zone-level permissions determine which zones are accessible.

id (optional): When provided, the controller uses this zone ID directly and skips the API zone lookup. This avoids the extra API call and is useful when the token does not have zone-list permissions or when you want to pin a specific zone ID.

proxied (optional): Per-zone override for the Cloudflare proxy setting. When nil, inherits from spec.defaults.proxied. Set to true for orange-cloud (Cloudflare proxy), false for DNS-only (grey-cloud).

spec:
  zones:
    - name: example.com
      id: "zone123abc"        # skip API lookup
      proxied: true           # force proxy on
    - name: internal.dev
      proxied: false          # DNS-only for this zone

Controls the DNS record lifecycle policy. Aligned with external-dns patterns.

spec:
  policy: upsert-only

Configures automatic hostname discovery from Gateway API HTTPRoute resources. Route discovery is enabled by the presence of this block. If source.gatewayRoutes is absent, the resource is explicit-only and does not watch routes. If the block is present and enabled is omitted, it defaults to true.

annotationFilter: An opt-in filter that restricts which routes trigger DNS sync. The controller checks this annotation on HTTPRoute resources, never on Gateways. You can use any annotation key=value pair of your choosing. The format is key=value. See Annotations Reference for details on how annotation filtering works.

A common convention is cfgate.io/dns-sync=enabled, but this is not a controller-defined annotation; it is a user-chosen convention. The controller simply checks whether the route has the specified annotation with the specified value.

namespaceSelector: Limits route discovery to specific namespaces. Supports matchLabels (label selectors) and matchNames (explicit namespace names). At least one must be specified when namespaceSelector is set. This enables multi-tenant setups where different CloudflareDNS resources manage routes from different namespaces.

spec:
  source:
    gatewayRoutes:
      enabled: true
      annotationFilter: "cfgate.io/dns-sync=enabled"
      namespaceSelector:
        matchLabels:
          environment: production
        matchNames:
          - app-team-a
          - app-team-b

Defines explicit hostnames to sync without depending on Gateway API route discovery. Route discovery can add hostnames, but when the same hostname appears in both sources, the explicit entry wins for target, proxied, and ttl.

The target field overrides the resource-level resolved target for that hostname. It supports the {{ .TunnelDomain }} template variable, which resolves to the tunnel's CNAME target domain when tunnelRef is set. When target is omitted, the resource-level resolved target is used.

spec:
  source:
    explicit:
      - hostname: app.example.com
        target: "{{ .TunnelDomain }}"
        proxied: true
        ttl: 1
      - hostname: api.example.com
        proxied: false
        ttl: 300

Mixed sources remain additive. In the example below, route discovery can still add other hostnames, but the explicit app.example.com entry wins if a route also advertises that hostname:

spec:
  source:
    gatewayRoutes:
      enabled: true
    explicit:
      - hostname: app.example.com
        target: app-origin.example.net
        proxied: false
        ttl: 300

Fallback values for records that do not have explicit settings. Per-hostname and per-zone settings take precedence.

A TTL of 1 means "auto": Cloudflare manages the TTL (typically 300 seconds). Explicit TTL values must be between 60 and 86400 seconds.

spec:
  defaults:
    proxied: true
    ttl: 1

Configures ownership tracking to identify which cfgate installation created each DNS record. This is critical for safe multi-cluster deployments.

TXT record ownership (recommended): Creates companion TXT records with the format:

heritage=cfgate,cfgate/owner=<owner-id>,cfgate/resource=cloudflaredns/<namespace>/<name>

This pattern is compatible with external-dns. The TXT record name is {prefix}.{hostname} (e.g., _cfgate.app.example.com).

Comment ownership (compatibility only): The controller writes a fixed "managed by cfgate" comment on all managed DNS records. This is informational only and is not used for ownership verification or conflict detection. TXT record ownership is the sole mechanism for multi-cluster safety.

Deprecation notice (v0.1.0-alpha.13): The spec.ownership.comment.enabled and spec.ownership.comment.template fields are deprecated and ignored. The controller always writes "managed by cfgate" regardless of these values. The fields remain in the schema for compatibility, and schema removal is deferred to a future cleanup pass. Removing the comment section from spec.ownership produces no behavioral change.

ownerId: Identifies this installation. Defaults to {namespace}/{name} of the CloudflareDNS resource. Override this when you need explicit control over the identity (e.g., migrating between CloudflareDNS resources).

spec:
  ownership:
    ownerId: "production/main-dns"
    txtRecord:
      enabled: true
      prefix: "_cfgate"

Controls what happens to DNS records when they are no longer needed. All fields are pointer booleans (*bool); nil defaults to true.

spec:
  cleanupPolicy:
    deleteOnRouteRemoval: true
    deleteOnResourceRemoval: true
    onlyManaged: true

Cloudflare API credentials. Required when using externalTarget. When using tunnelRef, credentials are inherited from the referenced CloudflareTunnel and this field can be omitted.

See CloudflareTunnel spec.cloudflare for full credential configuration details.

References a Secret containing fallback Cloudflare API credentials. Used during deletion when the primary credentials (either explicit or inherited from tunnel) are unavailable. This enables cleanup of DNS records even if the credentials Secret has been deleted.

spec:
  fallbackCredentialsRef:
    name: cloudflare-admin-credentials
    namespace: cfgate-system

apiVersion: cfgate.io/v1alpha1
kind: CloudflareDNS
metadata:
  name: prod-dns
  namespace: cfgate-system
spec:
  tunnelRef:
    name: prod-tunnel
  zones:
    - name: example.com
    - name: example.org
  source:
    gatewayRoutes:
      enabled: true
      annotationFilter: "cfgate.io/dns-sync=enabled"
  defaults:
    proxied: true
    ttl: 1
  policy: sync
  ownership:
    txtRecord:
      enabled: true
      prefix: "_cfgate"

apiVersion: cfgate.io/v1alpha1
kind: CloudflareDNS
metadata:
  name: external-dns
  namespace: cfgate-system
spec:
  externalTarget:
    type: A
    value: "203.0.113.10"
  cloudflare:
    accountId: "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
    secretRef:
      name: cloudflare-api-token
  zones:
    - name: example.com
      id: "zone123abc"
  source:
    explicit:
      - hostname: api.example.com
        proxied: false
        ttl: 300
      - hostname: www.example.com
        proxied: true
        ttl: 1
  policy: upsert-only
  cleanupPolicy:
    deleteOnRouteRemoval: false
    deleteOnResourceRemoval: false
    onlyManaged: true

apiVersion: cfgate.io/v1alpha1
kind: CloudflareDNS
metadata:
  name: team-a-dns
  namespace: cfgate-system
spec:
  tunnelRef:
    name: prod-tunnel
  zones:
    - name: example.com
      proxied: true
  source:
    gatewayRoutes:
      enabled: true
      annotationFilter: "cfgate.io/dns-sync=enabled"
      namespaceSelector:
        matchLabels:
          team: team-a
        matchNames:
          - team-a-apps
          - team-a-staging
  defaults:
    proxied: true
    ttl: 1
  policy: sync
  ownership:
    ownerId: "cluster-west/team-a-dns"
    txtRecord:
      enabled: true
  cleanupPolicy:
    deleteOnRouteRemoval: true
    deleteOnResourceRemoval: true
    onlyManaged: true
  fallbackCredentialsRef:
    name: cloudflare-admin-credentials
    namespace: cfgate-system

The controller adds the finalizer cfgate.io/dns-cleanup to every CloudflareDNS resource. When the resource is deleted, the controller attempts to delete all owned DNS records and their TXT ownership records before removing the finalizer.

If cleanup fails, the controller blocks indefinitely and requeues every 15 seconds. It never removes the finalizer automatically. Within a 1-minute retry budget, the controller emits Warning events with reason CleanupFailed. After the retry budget is exhausted, subsequent events escalate to reason CleanupBlocked.

To skip Cloudflare cleanup and remove the finalizer immediately, set the cfgate.io/deletion-policy=orphan annotation on the CloudflareDNS resource. The controller will leave DNS records in Cloudflare and remove the finalizer without attempting cleanup.

kubectl annotate cloudflarednses my-dns -n cfgate-system \
  cfgate.io/deletion-policy=orphan

When using tunnelRef, all DNS records are CNAME records pointing to {tunnelId}.cfargotunnel.com. The record type is not configurable in tunnel-ref mode.

When using externalTarget, the type field determines the DNS record type. Valid values are CNAME, A, and AAAA. The value field contains the record target: a domain name for CNAME, an IPv4 address for A, or an IPv6 address for AAAA. The controller does not validate that A or AAAA target values are valid IP addresses; values are passed through to the Cloudflare API.

Only A, AAAA, and CNAME records can be proxied by Cloudflare. Setting proxied: true on other record types will cause the Cloudflare API to reject the request.

Cloudflare Universal SSL certificates cover *.example.com but not deeper wildcards such as *.sub.example.com. Hostnames with more than one subdomain level relative to the zone (for example, api.staging.example.com in zone example.com) require Cloudflare Advanced Certificate Manager or a custom certificate uploaded to Cloudflare.

The controller emits a DeepSubdomain warning event when it encounters a hostname with depth greater than 1 relative to the zone. This warning is informational only; record creation proceeds regardless.

To suppress the warning, set the annotation cfgate.io/allow-deep-subdomains: "true" on the CloudflareDNS resource.

kubectl annotate cloudflarednses my-dns -n cfgate-system \
  cfgate.io/allow-deep-subdomains=true

When spec.source.gatewayRoutes.namespaceSelector is set, only routes from matching namespaces are considered for DNS record creation. The selector supports two filters: matchLabels and matchNames.

matchLabels uses AND semantics: all specified labels must be present on the namespace. matchNames matches namespaces by name. If both filters are specified, the result is a union (a namespace matching either filter is included).

An empty selector (namespaceSelector: {}) matches all namespaces, following the Kubernetes convention used by NetworkPolicy and other resources.