# cloudflare_dns – Manage Cloudflare DNS records

- Synopsis

- Requirements

- Parameters

- Examples

- Return Values

- Status

## Synopsis

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

## Requirements

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

- python >= 2.6

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
account_api_token string / required |  | Account API token. You can obtain your API key from the bottom of the Cloudflare 'My Account' page, found here: https://dash.cloudflare.com/
account_email string / required |  | Account email.
algorithm integer added in 2.7 |  | Algorithm number. Required for `type=DS` and `type=SSHFP` when `state=present`.

cert_usage
integer
added in 2.7

Choices:
- 0
- 1
- 2
- 3

Certificate usage number.
Required for `type=TLSA` when `state=present`.

hash_type
integer
added in 2.7

Choices:
- 1
- 2

Hash type number.
Required for `type=DS`, `type=SSHFP` and `type=TLSA` when `state=present`.

key_tag integer added in 2.7 |  | DNSSEC key tag. Needed for `type=DS` when `state=present`.
port integer |  | Service port. Required for `type=SRV` and `type=TLSA`.
priority - | 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
added in 2.7

Choices:
- 0
- 1

Selector number.
Required for `type=TLSA` when `state=present`.

service - |  | 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.my.com A record to point to 127.0.0.1
      cloudflare_dns:
        zone: my.com
        record: test
        type: A
        value: 127.0.0.1
        account_email: test@example.com
        account_api_token: dummyapitoken
      register: record

    - name: Create a my.com CNAME record to example.com
      cloudflare_dns:
        zone: my.com
        type: CNAME
        value: example.com
        account_email: test@example.com
        account_api_token: dummyapitoken
        state: present

    - name: Change its TTL
      cloudflare_dns:
        zone: my.com
        type: CNAME
        value: example.com
        ttl: 600
        account_email: test@example.com
        account_api_token: dummyapitoken
        state: present

    - name: Delete the record
      cloudflare_dns:
        zone: my.com
        type: CNAME
        value: example.com
        account_email: test@example.com
        account_api_token: dummyapitoken
        state: absent

    - name: create a my.com CNAME record to example.com and proxy through Cloudflare's network
      cloudflare_dns:
        zone: my.com
        type: CNAME
        value: example.com
        proxied: yes
        account_email: test@example.com
        account_api_token: dummyapitoken
        state: present

    # This deletes all other TXT records named "test.my.com"
    - name: Create TXT record "test.my.com" with value "unique value"
      cloudflare_dns:
        domain: my.com
        record: test
        type: TXT
        value: unique value
        solo: true
        account_email: test@example.com
        account_api_token: dummyapitoken
        state: present

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

    - name: Create a SSHFP record login.example.com
      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
      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
      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

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]

- This module is maintained by the Ansible Community. [community]

### Authors

- Michael Gruener (@mgruener)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.