community.general.cloudflare_dns – Manage Cloudflare DNS records

Note

This plugin is part of the community.general collection (version 3.8.1).

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

Requirements

The below requirements are needed on the host that executes this module.

  • python >= 2.6

Parameters

Parameter Choices/Defaults Comments
account_api_key
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/.

aliases: account_api_token
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 0.2.0 of community.general
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
    Choices:
  • 0
  • 1
  • 2
  • 3
Certificate usage number.
Required for type=TLSA when state=present.
hash_type
integer
    Choices:
  • 1
  • 2
Hash type number.
Required for type=DS, type=SSHFP and type=TLSA when state=present.
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
Default:
1
Record priority.
Required for type=MX and type=SRV
proto
string
Service protocol. Required for type=SRV and type=TLSA.
Common values are TCP and UDP.
Before Ansible 2.6 only TCP and UDP were available.
proxied
boolean
    Choices:
  • no
  • yes
Proxy through Cloudflare network or just use DNS.
record
string
Default:
"@"
Record to add.
Required if state=present.
Default is @ (e.g. the zone name).

aliases: name
selector
integer
    Choices:
  • 0
  • 1
Selector number.
Required for type=TLSA when state=present.
service
string
Record service.
Required for type=SRV.
solo
boolean
    Choices:
  • no
  • yes
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.
state
string
    Choices:
  • absent
  • present
Whether the record(s) should exist or not.
timeout
integer
Default:
30
Timeout for Cloudflare API calls.
ttl
integer
Default:
1
The TTL to give the new record.
Must be between 120 and 2,147,483,647 seconds, or 1 for automatic.
type
string
    Choices:
  • A
  • AAAA
  • CNAME
  • DS
  • MX
  • NS
  • SPF
  • SRV
  • SSHFP
  • TLSA
  • TXT
The type of DNS record to create. Required if state=present.
type=DS, type=SSHFP and type=TLSA added in Ansible 2.7.
value
string
The record value.
Required for state=present.

aliases: content
weight
integer
Default:
1
Service weight.
Required for type=SRV.
zone
string / required
The name of the Zone to work with (e.g. "example.com").
The Zone must already exist.

aliases: domain

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 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: yes
    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 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 Returned Description
record
complex
success, except on record deletion
A dictionary containing the record data.

content
string
success
The record content (details depend on record type).

Sample:
192.0.2.91
created_on
string
success
The record creation date.

Sample:
2016-03-25T19:09:42.516553Z
data
dictionary
success, if type is SRV, DS, SSHFP or TLSA
Additional record data.

Sample:
{'name': 'jabber', 'port': 8080, 'priority': 10, 'proto': '_tcp', 'service': '_xmpp', 'target': 'jabberhost.sample.com', 'weight': 5}
id
string
success
The record ID.

Sample:
f9efb0549e96abcb750de63b38c9576e
locked
boolean
success
No documentation available.

meta
dictionary
success
No documentation available.

Sample:
{'auto_added': False}
modified_on
string
success
Record modification date.

Sample:
2016-03-25T19:09:42.516553Z
name
string
success
The record name as FQDN (including _service and _proto for SRV).

Sample:
www.sample.com
priority
integer
success, if type is MX
Priority of the MX record.

Sample:
10
proxiable
boolean
success
Whether this record can be proxied through Cloudflare.

proxied
boolean
success
Whether the record is proxied through Cloudflare.

ttl
integer
success
The time-to-live for the record.

Sample:
300
type
string
success
The record type.

Sample:
A
zone_id
string
success
The ID of the zone containing the record.

Sample:
abcede0bf9f0066f94029d2e6b73856a
zone_name
string
success
The name of the zone containing the record.

Sample:
sample.com


Authors

  • Michael Gruener (@mgruener)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/general/cloudflare_dns_module.html