hetzner.hcloud.zone module – Create and manage DNS Zone on the Hetzner Cloud.

Note

This module is part of the hetzner.hcloud collection (version 6.9.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 hetzner.hcloud. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: hetzner.hcloud.zone.

Synopsis
Requirements
Parameters
See Also
Examples
Return Values

Synopsis

Create, update and delete DNS Zone on the Hetzner Cloud.
See the Zones API documentation for more details.

Aliases: hcloud_zone

Requirements

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

python-dateutil >= 2.7.5
requests >=2.20

Parameters

Parameter	Comments
api_endpoint aliases: endpoint string	The endpoint for the Hetzner Cloud API. You can also set this option by using the `HCLOUD_ENDPOINT` environment variable. Default: `"https://api.hetzner.cloud/v1"`
api_endpoint_hetzner string	The endpoint for the Hetzner API. You can also set this option by using the `HETZNER_ENDPOINT` environment variable. Default: `"https://api.hetzner.com/v1"`
api_token string / required	The token for the Hetzner Cloud API. You can also set this option by using the `HCLOUD_TOKEN` environment variable.
delete_protection boolean	Protect the Zone from deletion. Choices: `false` `true`
id integer	ID of the Zone to manage. Only required if no Zone `name` is given.
labels dictionary	User-defined key-value pairs.
mode string	Mode of the Zone. Required if the Zone does not exist. Choices: `"primary"` `"secondary"`
name string	Name of the Zone to manage. Only required if no Zone `id` is given or the Zone does not exist. All names with well-known public suffixes (e.g. .de, .com, .co.uk) are supported. Subdomains are not supported. The name must be in lower case and must not end with a dot. Internationalized domain names must be transcribed to Punycode representation with ACE prefix, e.g. xn--mnchen-3ya.de (münchen.de).
primary_nameservers list / elements=dictionary	Primary nameservers of the Zone. Only applicable for Zones with `mode=secondary`.
address string	Public IPv4 or IPv6 address of the primary nameserver.
port integer	Port of the primary nameserver.
tsig_algorithm string	Transaction signature (TSIG) algorithm used to generate the TSIG key.
tsig_key string	Transaction signature (TSIG) key.
state string	State of the Zone. `import` is not idempotent. Choices: `"absent"` `"present"` ← (default) `"import"`
ttl integer	TTL of the Zone.
zonefile string	Zone file to import. Optional if `state=present` and the Zone does not exist, ignored otherwise. Required if `state=import`.

Examples

- name: Create a primary Zone
  hetzner.hcloud.zone:
    name: example.com
    mode: primary
    ttl: 10800
    labels:
      key: value
    state: present

- name: Create a primary Zone using a zonefile
  hetzner.hcloud.zone:
    name: example.com
    mode: primary
    zonefile: |
      $ORIGIN       example.com.
      $TTL  3600

      @ 300 IN CAA 0 issue "letsencrypt.org"

      @     600     IN      A       192.168.254.2
      @     600     IN      A       192.168.254.3

      @     IN      AAAA    fdd0:367a:0cb7::2
      @     IN      AAAA    fdd0:367a:0cb7::3

      www   IN      CNAME   example.com.
      blog  IN      CNAME   example.com.

      anything      IN      TXT     "some value"
    state: present

- name: Create a primary Zone with Internationalized Domain Name (IDN)
  hetzner.hcloud.zone:
    # Leverage Python's encoding.idna module https://docs.python.org/3/library/codecs.html#module-encodings.idna
    name: "{{ 'këks-🍪-example.com'.encode('idna') }}"
    mode: primary
    state: present

- name: Create a secondary Zone
  hetzner.hcloud.zone:
    name: example.com
    mode: secondary
    primary_nameservers:
      - address: 203.0.113.1
        port: 53
    labels:
      key: value
    state: present

- name: Delete a Zone
  hetzner.hcloud.zone:
    name: example.com
    state: absent

Return Values

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

Key	Description
hcloud_zone dictionary	Zone instance. Returned: always
authoritative_nameservers dictionary	Authoritative nameservers of the Zone. Returned: always
assigned list / elements=string	Authoritative Hetzner nameservers assigned to the Zone. Returned: always Sample: `["hydrogen.ns.hetzner.com.", "oxygen.ns.hetzner.com.", "helium.ns.hetzner.de."]`
delegated list / elements=string	Authoritative nameservers delegated to the parent DNS zone. Returned: always Sample: `["hydrogen.ns.hetzner.com.", "oxygen.ns.hetzner.com.", "helium.ns.hetzner.de."]`
delegation_last_check string	Point in time when the DNS zone delegation was last checked (in ISO-8601 format). Returned: always Sample: `"2023-11-06T13:36:56+00:00"`
delegation_status string	Status of the delegation. Returned: always Sample: `"valid"`
delete_protection boolean	Protect the Zone from deletion. Returned: always Sample: `false`
id integer	ID of the Zone. Returned: always Sample: `12345`
labels dictionary	User-defined labels (key-value pairs) Returned: always Sample: `{"key": "value"}`
mode string	Mode of the Zone. Returned: always Sample: `"primary"`
name string	Name of the Zone. Returned: always Sample: `"example.com"`
primary_nameservers list / elements=dictionary	Primary nameservers of the Zone. Returned: always
address string	Public IPv4 or IPv6 address of the primary nameserver. Returned: always Sample: `"203.0.113.1"`
port integer	Port of the primary nameserver. Returned: always Sample: `53`
tsig_algorithm string	Transaction signature (TSIG) algorithm used to generate the TSIG key. Returned: always Sample: `"hmac-sha256"`
tsig_key string	Transaction signature (TSIG) key. Returned: always
record_count integer	Number of Resource Records (RR) within the Zone. Returned: always Sample: `4`
registrar string	Registrar of the Zone. Returned: always Sample: `"hetzner"`
status string	Status of the Zone. Returned: always Sample: `"ok"`
ttl integer	TTL of the Zone. Returned: always Sample: `10800`

Authors

Jonas Lammler (@jooola)

Collection links

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/hetzner/hcloud/zone_module.html