gibdns-cloudflare

gibdns provider for Cloudflare DNS. Hosts such as gibcert execute this binary to publish ACME DNS-01 TXT records and DANE TLSA records.

Protocol	TXT	TLSA	Zone discovery
gibdns/draft-01	yes	yes	yes
gibdns/draft-02	yes	yes	yes

Install

Download the archive or .deb for your OS from the releases page.

Debian package (installs to /usr/libexec/gibdns):

sudo dpkg -i gibdns-cloudflare_*_linux_amd64.deb

Tarball:

sudo install -D -m 0755 gibdns-cloudflare /usr/local/libexec/gibdns/gibdns-cloudflare

From source:

make install PREFIX=/usr/local

The binary is not an interactive CLI and is intentionally not installed on PATH. Confirm the installation, then let the host invoke it:

# Debian package:
test -x /usr/libexec/gibdns/gibdns-cloudflare
# Source or tarball install:
test -x /usr/local/libexec/gibdns/gibdns-cloudflare

Use /usr/libexec/gibdns/gibdns-cloudflare for a Debian package or /usr/local/libexec/gibdns/gibdns-cloudflare for a source or tarball install in host configuration. See Using gibdns for the host and provider split.

Use with gibcert

Store a scoped API token at /etc/gibcert/cloudflare-token with mode 0600. The token needs Zone.DNS:Write on the zone. Then:

provider cloudflare {
  type dns
  driver exec
  command /usr/libexec/gibdns/gibdns-cloudflare
  zone example.com.

  secret api_token {
    file /etc/gibcert/cloudflare-token
  }
}

certificate wildcard-example.com {
  account letsencrypt
  names example.com *.example.com

  challenge dns-01 {
    provider cloudflare
    propagation-timeout 120s
  }
}

zone is optional because this provider advertises zone discovery. Set it when you want an exact zone selector. If installed from source or a tarball, use /usr/local/libexec/gibdns/gibdns-cloudflare instead.

gibcert binding details are in External DNS Providers.

Secrets

• api_token (required): scoped API token with Zone.DNS:Write
• zone_token (optional): Zone:Read token for the dual-token setup

Config

• api_url (optional)
• account_id (optional): disambiguates zone lookup across Cloudflare accounts
• zone_id (optional): skip zone-name lookup

The token does not need an account ID for ordinary DNS updates. account_id is only useful when the same zone name is visible in more than one account.

Batching

With gibdns/draft-02 the provider advertises rrset.batch with features.batch.atomic: true and constraints.maximum_batch_ops: 200. A batch is sent as one POST /zones/{zone_id}/dns_records/batch request, which Cloudflare executes in a single database transaction: all changes apply or none do, in the order deletes, patches, puts, posts. atomic: false batches use the same single request. Propagation across the Cloudflare network is not atomic.

• The 200 operation limit is conservative: the Cloudflare documentation allows 200 records per batch on the Free plan and 3,500 on Pro, Business and Enterprise. The limit counts RRset operations, not records, so the provider also rejects a batch that would delete, re-TTL or create more than 3,500 records with constraint_violation (maximum_batch_records). Below that, Cloudflare enforces your plan's limit; how it rejects an over-limit batch was not exercised.
• Before the request the provider reads each RRset's records (one zone lookup plus one list request per RRset). Only members an operation names are deleted (by record ID) or created; other records of the same RRset are not touched. A TTL change sets the TTL of every record of that RRset, as the single-RRset patch does. Removing an RRset deletes every record of it.
• Cloudflare returns the first error it hit without naming the failing operation, so a rejected batch is reported without op_index.

Preconditions

In gibdns/draft-02 every advertised precondition (if_revision, if_absent) is check_then_write: it is evaluated against freshly read state and then the write happens. A concurrent writer in between can be overwritten, because Cloudflare has no conditional write for DNS records.

Development

make test
make build
make snapshot

Live tests are off by default. Set GIBDNS_CLOUDFLARE_TOKEN and GIBDNS_CLOUDFLARE_ZONE and run make test-live.

Publish a tagged release with make release. That target runs GoReleaser via go run; a GITEA_TOKEN with package/release access is required.