Руководство по Hetzner DNS

Использование группы настроек модулей community.dns.hetzner

Чтобы не указывать общие параметры для всех модулей Hetzner DNS в каждой задаче, можно использовать группу настроек модулей community.dns.hetzner:

---
- name: Hetzner DNS
  hosts: localhost
  gather_facts: false
  module_defaults:
    group/community.dns.hetzner:
      hetzner_token: '{{ token }}'
  tasks:
    - name: Query zone information
      community.dns.hetzner_dns_zone_info:
        zone_name: example.com
      register: result

    - name: Set A records for www.example.com
      community.dns.hetzner_dns_record_set:
        state: present
        zone_name: example.com
        type: A
        prefix: www
        value:
          - 192.168.0.1

В этом примере обе задачи используют параметры, заданные для группы настроек модулей.

Запрос DNS-записей и наборов записей

Модуль community.dns.hetzner_dns_record_set_info позволяет запрашивать наборы DNS-записей через API. Его можно использовать для запроса одного набора записей:

- name: Query single record
  community.dns.hetzner_dns_record_set_info:
    zone_name: example.com
    type: A  # IPv4 addresses
    what: single_record  # default value
    # Either specify a record name:
    record: www.example.com
    # Or a record prefix ('' is the zone itself):
    prefix: www
  register: result

- name: Show IPv4 addresses if record exists
  ansible.builtin.debug:
    msg: >
      IPv4s are {{ result.set.value | join(', ') }},
      TTL is {{ result.set.ttl }}
  when: result.set is truthy

- name: Show that record is not set
  ansible.builtin.debug:
    msg: There is no A record for www.example.com
  when: result.set is falsy

Во всех примерах этого раздела вместо zone_name=example.com можно указать zone_id=aBcDeFgHiJlMnOpQrStUvW с текстовым значением идентификатора зоны.

Также можно запросить список всех наборов записей для имени записи или префикса:

- name: Query all records for www.example.com
  community.dns.hetzner_dns_record_set_info:
    zone_name: example.com
    what: all_types_for_record
    # Either specify a record name:
    record: www.example.com
    # Or a record prefix ('' is the zone itself):
    prefix: www
  register: result

- name: Show all records for www.example.com
  ansible.builtin.debug:
    msg: >
      {{ item.type }} record with TTL {{ item.ttl }} has
      values {{ item.value | join(', ') }}
  loop: result.sets

Наконец, можно запросить все наборы записей для зоны:

- name: Query all records for a zone
  community.dns.hetzner_dns_record_set_info:
    zone_name: example.com
    what: all_records
  register: result

- name: Show all records for the example.com zone
  ansible.builtin.debug:
    msg: >
      {{ item.type }} record for {{ item.record }} with
      TTL {{ item.ttl }} has values {{ item.value | join(', ') }}
  loop: result.sets

Если вас интересуют отдельные DNS-записи, а не наборы записей, используйте модуль community.dns.hetzner_dns_record_info. Он поддерживает те же параметры ограничения, что и модуль community.dns.hetzner_dns_record_set_info.

Создание и обновление отдельных DNS-записей

Если вы хотите не добавлять или удалять значения, а заменять их, следует изменить набор записей, а не отдельную запись. Это особенно важно при работе с записями CNAME и SOA.

Модуль community.dns.hetzner_dns_record позволяет задавать, обновлять и удалять отдельные DNS-записи. Задание и обновление выполняются следующим образом. Записи сопоставляются по имени и типу, а значение TTL при необходимости обновляется:

- name: Add an A record with value 1.1.1.1 for www.example.com, resp. make sure the TTL is 300
  community.dns.hetzner_dns_record:
    state: present
    zone_name: example.com
    type: A  # IPv4 addresses
    # Either specify a record name:
    record: www.example.com
    # Or a record prefix ('' is the zone itself):
    prefix: www
    value: 1.1.1.1
    ttl: 300

Чтобы удалить записи, просто используйте state=absent. Записи сопоставляются по имени и типу, а TTL игнорируется:

- name: Remove A values for www.example.com
  community.dns.hetzner_dns_record:
    state: absent
    zone_name: example.com
    type: A  # IPv4 addresses
    record: www.example.com
    value: 1.1.1.1

Записи того же типа с тем же именем, но другими значениями игнорируются.

Создание и обновление наборов DNS-записей

Модуль community.dns.hetzner_dns_record_set позволяет задавать, обновлять и удалять наборы DNS-записей. Задание и обновление выполняются следующим образом:

- name: Make sure record is set to the given value
  community.dns.hetzner_dns_record_set:
    state: present
    zone_name: example.com
    type: A  # IPv4 addresses
    # Either specify a record name:
    record: www.example.com
    # Or a record prefix ('' is the zone itself):
    prefix: www
    value:
      - 1.1.1.1
      - 8.8.8.8

Если необходимо проверить, что запись имеет определенное значение, задайте on_existing=keep. Использование keep_and_warn вместо этого приведет к предупреждению в такой ситуации, а keep_and_fail вызовет сбой модуля.

Чтобы удалить значения, можно либо перезаписать их значением [], либо использовать state=absent:

- name: Remove A values for www.example.com
  community.dns.hetzner_dns_record_set:
    state: present
    zone_name: example.com
    type: A  # IPv4 addresses
    record: www.example.com
    value: []

- name: Remove TXT values for www.example.com
  community.dns.hetzner_dns_record_set:
    zone_name: example.com
    type: TXT
    prefix: www
    state: absent

- name: Remove specific AAAA values for www.example.com
  community.dns.hetzner_dns_record_set:
    zone_name: example.com
    type: AAAA  # IPv6 addresses
    prefix: www
    state: absent
    on_existing: keep_and_fail
    ttl: 300
    value:
      - '::1'

В третьем примере задан on_existing=keep_and_fail, а также явно указаны значение и TTL. Модуль удалит текущее значение, только если для www.example.com существует запись AAAA, текущее значение которой — ::1, а TTL равен 300. Если задано другое значение, модуль ничего не изменит, но завершится с ошибкой. Это может быть полезно, чтобы случайно не удалять значения, которые вы не хотите менять. Чтобы вместо сбоя выдать предупреждение, используйте on_existing=keep_and_warn, а чтобы просто ничего не менять и не сообщать об этом, используйте on_existing=keep.

Массовая синхронизация наборов DNS-записей

Если необходимо задать или обновить сразу несколько записей либо убедиться, что присутствует точный набор указанных вами записей и ничего больше, используйте модуль community.dns.hetzner_dns_record_sets.

В следующем примере показано, как задать или обновить сразу несколько записей:

- name: Make sure that multiple records are present
  community.dns.hetzner_dns_record_sets:
    zone_name: example.com
    record_sets:
      - prefix: www
        type: A
        value:
          - 1.1.1.1
          - 8.8.8.8
      - prefix: www
        type: AAAA
        value:
          - '::1'

В следующем примере показано, как убедиться, что доступны только указанные записи, а все остальные удалены. Обратите внимание: для записи record_sets[].type=NS мы использовали record_sets[].ignore=true, что позволяет не указывать значение. Это указывает модулю не изменять запись NS для example.com.

- name: Make sure that multiple records are present
  community.dns.hetzner_dns_record_sets:
    zone_name: example.com
    prune: true
    record_sets:
      - prefix: www
        type: A
        value:
          - 1.1.1.1
          - 8.8.8.8
      - prefix: www
        type: AAAA
        value:
          - '::1'
      - prefix: ''
        type: NS
        ignore: true

Модуль markuman.hetzner_dns.record

Модуль markuman.hetzner_dns.zone_info можно заменить на модуль community.dns.hetzner_dns_record или модуль community.dns.hetzner_dns_record_set в зависимости от его назначения.

При создании, обновлении или удалении отдельных записей следует использовать модуль community.dns.hetzner_dns_record. Это относится к случаям, когда задан purge=false (значение по умолчанию). Обратите внимание, что replace, overwrite и solo являются псевдонимами purge.

# Creating and updating DNS records

- name: Creating or updating a single DNS record with markuman.hetzner_dns
  markuman.hetzner_dns.record:
    zone_name: example.com
    name: localhost
    type: A
    value: 127.0.0.1
    ttl: 60
    # This means the module operates on single DNS entries. If not specified,
    # this is the default value:
    purge: false

- name: Creating or updating a single DNS record with community.dns
  community.dns.hetzner_dns_record:
    zone_name: example.com
    # 'state' must always be specified:
    state: present
    # 'name' is a deprecated alias of 'prefix', so it can be
    # kept during a first migration step:
    name: localhost
    # 'type', 'value' and 'ttl' do not change:
    type: A
    value: 127.0.0.1
    ttl: 60
    # If type is TXT, you either have to adjust the value you pass,
    # or keep the following option:
    txt_transformation: api

Если модуль markuman.hetzner_dns.record работает в режиме замены, его следует заменить на модуль community.dns.hetzner_dns_record_set, поскольку в этом случае он работает с набором записей, а не с отдельной записью:

# Creating and updating DNS record sets

- name: Creating or updating a record set with markuman.hetzner_dns
  markuman.hetzner_dns.record:
    zone_name: example.com
    name: localhost
    type: A
    value: 127.0.0.1
    ttl: 60
    # This means the module operates on the record set:
    purge: true

- name: Creating or updating a record set with community.dns
  community.dns.hetzner_dns_record_set:
    zone_name: example.com
    # 'state' must always be specified:
    state: present
    # 'name' is a deprecated alias of 'prefix', so it can be
    # kept during a first migration step:
    name: localhost
    # 'type' and 'ttl' do not change:
    type: A
    ttl: 60
    # 'value' is now a list:
    value:
      - 127.0.0.1
    # Ansible allows to specify lists as a comma-separated string.
    # So for records which do not contain a comma, you can also
    # keep the old syntax, in this case:
    #
    #     value: 127.0.0.1
    #
    # If type is TXT, you either have to adjust the value you pass,
    # or keep the following option:
    txt_transformation: api

При удалении записи необходимо учитывать, задан ли value. Если задан value, модуль удаляет отдельную DNS-запись, и следует использовать модуль community.dns.hetzner_dns_record:

# Deleting single DNS records

- name: Deleting a single DNS record with markuman.hetzner_dns
  markuman.hetzner_dns.record:
    zone_name: example.com
    state: absent
    name: localhost
    type: A
    value: 127.0.0.1
    ttl: 60

- name: Deleting a single DNS record with community.dns
  community.dns.hetzner_dns_record:
    zone_name: example.com
    state: absent
    # 'name' is a deprecated alias of 'prefix', so it can be
    # kept during a first migration step:
    name: localhost
    # 'type', 'value' and 'ttl' do not change:
    type: A
    value: 127.0.0.1
    ttl: 60
    # If type is TXT, you either have to adjust the value you pass,
    # or keep the following option:
    txt_transformation: api

Если value не задан, модуль markuman.hetzner_dns.record удалит все записи с этим префиксом и типом. В этом случае он работает с набором записей, поэтому следует использовать модуль community.dns.hetzner_dns_record_set:

# Deleting multiple DNS records

- name: Deleting multiple DNS records with markuman.hetzner_dns
  markuman.hetzner_dns.record:
    zone_name: example.com
    state: absent
    name: localhost
    type: A

- name: Deleting a single DNS record with community.dns
  community.dns.hetzner_dns_record_set:
    zone_name: example.com
    state: absent
    # 'name' is a deprecated alias of 'prefix', so it can be
    # kept during a first migration step:
    name: localhost
    # 'type' does not change:
    type: A

Последний шаг — заменить удаленный псевдоним name для prefix на prefix.

Модуль markuman.hetzner_dns.record_info

Модуль markuman.hetzner_dns.record_info можно заменить на модуль community.dns.hetzner_dns_record_info. Главное отличие состоит в том, что вывод управляется не параметром filters, а параметром what (допустимые значения: single_record, all_types_for_record и all_records), параметром type (необходим, если what=single_record), а также параметрами record и prefix (необходимы, если what не равно all_records).

Модуль markuman.hetzner_dns.zone_info

Модуль markuman.hetzner_dns.zone_info можно заменить на модуль community.dns.hetzner_dns_zone_info. Основные отличия:

1. Параметр name необходимо заменить на zone_name или zone.
2. Возвращаемое значение zone_info больше не содержит элементов name и id. Вместо них используйте возвращаемые значения zone_name и zone_id.

Плагин инвентаризации markuman.hetzner_dns.inventory

Плагин инвентаризации markuman.hetzner_dns.inventory можно заменить на плагин инвентаризации community.dns.hetzner_dns_records. Помимо имени плагина, никаких изменений не требуется.