community.general.cloudflare_dns module – Manage Cloudflare DNS records

Note

This module is part of the community.general collection (version 10.1.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.cloudflare_dns.

Synopsis

• Manages dns records via the Cloudflare API, see the docs: https://api.cloudflare.com/.

Parameters

Parameter	Comments
account_api_key aliases: account_api_token string	Account API key. Required for api keys authentication. You can obtain your API key from the bottom of the Cloudflare ‘My Account’ page, found here: https://dash.cloudflare.com/.
account_email string	Account email. Required for API keys authentication.
algorithm integer	Algorithm number. Required for type=DS and type=SSHFP when state=present.
api_token string added in community.general 0.2.0	API token. Required for api token authentication. You can obtain your API token from the bottom of the Cloudflare ‘My Account’ page, found here: https://dash.cloudflare.com/. Can be specified in CLOUDFLARE_TOKEN environment variable since community.general 2.0.0.
cert_usage integer	Certificate usage number. Required for type=TLSA when state=present. Choices: 0 1 2 3
comment string added in community.general 10.1.0	Comments or notes about the DNS record.
flag integer added in community.general 8.0.0	Issuer Critical Flag. Required for type=CAA when state=present. Choices: 0 1
hash_type integer	Hash type number. Required for type=DS, type=SSHFP and type=TLSA when state=present. Choices: 1 2
key_tag integer	DNSSEC key tag. Needed for type=DS when state=present.
port integer	Service port. Required for type=SRV and type=TLSA.
priority integer	Record priority. Required for type=MX and type=SRV Default: 1
proto string	Service protocol. Required for type=SRV and type=TLSA. Common values are TCP and UDP.
proxied boolean	Proxy through Cloudflare network or just use DNS. Choices: false ← (default) true
record aliases: name string	Record to add. Required if state=present. Default is @ (that is, the zone name). Default: "@"
selector integer	Selector number. Required for type=TLSA when state=present. Choices: 0 1
service string	Record service. Required for type=SRV.
solo boolean	Whether the record should be the only one for that record type and record name. Only use with state=present. This will delete all other records with the same record name and type. Choices: false true
state string	Whether the record(s) should exist or not. Choices: "absent" "present" ← (default)
tag string added in community.general 8.0.0	CAA issue restriction. Required for type=CAA when state=present. Choices: "issue" "issuewild" "iodef"
tags list / elements=string added in community.general 10.1.0	Custom tags for the DNS record.
timeout integer	Timeout for Cloudflare API calls. Default: 30
ttl integer	The TTL to give the new record. Must be between 120 and 2,147,483,647 seconds, or 1 for automatic. Default: 1
type string	The type of DNS record to create. Required if state=present. Support for SPF has been removed from community.general 9.0.0 since that record type is no longer supported by CloudFlare. Choices: "A" "AAAA" "CNAME" "DS" "MX" "NS" "SRV" "SSHFP" "TLSA" "CAA" "TXT"
value aliases: content string	The record value. Required for state=present.
weight integer	Service weight. Required for type=SRV. Default: 1
zone aliases: domain string / required	The name of the Zone to work with (e.g. “example.com”). The Zone must already exist.

Attributes

Attribute	Support	Description
check_mode	Support: full	Can run in check_mode and return changed status prediction without modifying target.
diff_mode	Support: none	Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Examples

- name: Create a test.example.net A record to point to 127.0.0.1
  community.general.cloudflare_dns:
    zone: example.net
    record: test
    type: A
    value: 127.0.0.1
    account_email: [email protected]
    account_api_key: dummyapitoken
  register: record

- name: Create a record using api token
  community.general.cloudflare_dns:
    zone: example.net
    record: test
    type: A
    value: 127.0.0.1
    api_token: dummyapitoken

- name: Create a record with comment and tags
  community.general.cloudflare_dns:
    zone: example.net
    record: test
    type: A
    value: 127.0.0.1
    comment: Local test website
    tags:
    - test
    - local
    api_token: dummyapitoken

- name: Create a example.net CNAME record to example.com
  community.general.cloudflare_dns:
    zone: example.net
    type: CNAME
    value: example.com
    account_email: [email protected]
    account_api_key: dummyapitoken
    state: present

- name: Change its TTL
  community.general.cloudflare_dns:
    zone: example.net
    type: CNAME
    value: example.com
    ttl: 600
    account_email: [email protected]
    account_api_key: dummyapitoken
    state: present

- name: Delete the record
  community.general.cloudflare_dns:
    zone: example.net
    type: CNAME
    value: example.com
    account_email: [email protected]
    account_api_key: dummyapitoken
    state: absent

- name: Create a example.net CNAME record to example.com and proxy through Cloudflare's network
  community.general.cloudflare_dns:
    zone: example.net
    type: CNAME
    value: example.com
    proxied: true
    account_email: [email protected]
    account_api_key: dummyapitoken
    state: present

# This deletes all other TXT records named "test.example.net"
- name: Create TXT record "test.example.net" with value "unique value"
  community.general.cloudflare_dns:
    domain: example.net
    record: test
    type: TXT
    value: unique value
    solo: true
    account_email: [email protected]
    account_api_key: dummyapitoken
    state: present

- name: Create an SRV record _foo._tcp.example.net
  community.general.cloudflare_dns:
    domain: example.net
    service: foo
    proto: tcp
    port: 3500
    priority: 10
    weight: 20
    type: SRV
    value: fooserver.example.net

- name: Create a SSHFP record login.example.com
  community.general.cloudflare_dns:
    zone: example.com
    record: login
    type: SSHFP
    algorithm: 4
    hash_type: 2
    value: 9dc1d6742696d2f51ca1f1a78b3d16a840f7d111eb9454239e70db31363f33e1

- name: Create a TLSA record _25._tcp.mail.example.com
  community.general.cloudflare_dns:
    zone: example.com
    record: mail
    port: 25
    proto: tcp
    type: TLSA
    cert_usage: 3
    selector: 1
    hash_type: 1
    value: 6b76d034492b493e15a7376fccd08e63befdad0edab8e442562f532338364bf3

- name: Create a CAA record subdomain.example.com
  community.general.cloudflare_dns:
    zone: example.com
    record: subdomain
    type: CAA
    flag: 0
    tag: issue
    value: ca.example.com

- name: Create a DS record for subdomain.example.com
  community.general.cloudflare_dns:
    zone: example.com
    record: subdomain
    type: DS
    key_tag: 5464
    algorithm: 8
    hash_type: 2
    value: B4EB5AC4467D2DFB3BAF9FB9961DC1B6FED54A58CDFAA3E465081EC86F89BFAB

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
record complex	A dictionary containing the record data. Returned: success, except on record deletion
comment string added in community.general 10.1.0	Comments or notes about the DNS record. Returned: success Sample: "Domain verification record"
comment_modified_on string added in community.general 10.1.0	When the record comment was last modified. Omitted if there is no comment. Returned: success Sample: "2024-01-01T05:20:00.12345Z"
content string	The record content (details depend on record type). Returned: success Sample: "192.0.2.91"
created_on string	The record creation date. Returned: success Sample: "2016-03-25T19:09:42.516553Z"
data dictionary	Additional record data. Returned: success, if type is SRV, DS, SSHFP TLSA or CAA Sample: {"name": "jabber", "port": 8080, "priority": 10, "proto": "_tcp", "service": "_xmpp", "target": "jabberhost.sample.com", "weight": 5}
id string	The record ID. Returned: success Sample: "f9efb0549e96abcb750de63b38c9576e"
locked boolean	No documentation available. Returned: success Sample: false
meta dictionary	Extra Cloudflare-specific information about the record. Returned: success Sample: {"auto_added": false}
modified_on string	Record modification date. Returned: success Sample: "2016-03-25T19:09:42.516553Z"
name string	The record name as FQDN (including _service and _proto for SRV). Returned: success Sample: "www.sample.com"
priority integer	Priority of the MX record. Returned: success, if type is MX Sample: 10
proxiable boolean	Whether this record can be proxied through Cloudflare. Returned: success Sample: false
proxied boolean	Whether the record is proxied through Cloudflare. Returned: success Sample: false
tags list / elements=string added in community.general 10.1.0	Custom tags for the DNS record. Returned: success Sample: ["production", "app"]
tags_modified_on string added in community.general 10.1.0	When the record tags were last modified. Omitted if there are no tags. Returned: success Sample: "2025-01-01T05:20:00.12345Z"
ttl integer	The time-to-live for the record. Returned: success Sample: 300
type string	The record type. Returned: success Sample: "A"
zone_id string	The ID of the zone containing the record. Returned: success Sample: "abcede0bf9f0066f94029d2e6b73856a"
zone_name string	The name of the zone containing the record. Returned: success Sample: "sample.com"

Authors

• Michael Gruener (@mgruener)

Collection links

• Issue Tracker
• Repository (Sources)
• Ask for help
• Submit a bug report
• Request a feature
• Communication