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

Note

This module is part of the hetzner.hcloud collection (version 5.4.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

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 API Endpoint for the Hetzner Cloud.

You can also set this option by using the HCLOUD_ENDPOINT environment variable.

Default: "https://api.hetzner.cloud/v1"

api_token

string / required

The API Token for the Hetzner Cloud.

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.

See Also

See also

Documentation for Hetzner Cloud API

Complete reference for the Hetzner Cloud API.

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)