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

JSON REST API

Чтобы использовать JSON REST API, необходимо создать токен API. Токенами API можно управлять в разделе «API» редактора DNS («DNS Editor»). Токен необходимо указать в параметре hosttech_token модулей:

- community.dns.hosttech_dns_record:
    hosttech_token: '{{ token }}'
    # ...

В примерах этого руководства мы не будем указывать параметры аутентификации. Обратите внимание, что их можно задать глобально с помощью module_defaults (см. раздел Значения модулей по умолчанию).

WSDL API

Чтобы использовать WSDL API, необходимо указать учетные данные API. Их можно найти и изменить в разделе «Solutions» центра «Servercenter», в настройках инструмента «DNS Tool». Имя пользователя фиксировано, но пароль можно изменить. Учетные данные необходимо указать в параметрах hosttech_username и hosttech_password модулей.

Для работы с WSDL API также необходимо установить модуль Python lxml. Это можно сделать перед использованием модулей:

- name: Make sure lxml is installed
  pip:
    name: lxml

- community.dns.hosttech_dns_record:
    hosttech_username: '{{ username }}'
    hosttech_password: '{{ password }}'
    # ...

В примерах этого руководства мы не будем указывать параметры аутентификации. Обратите внимание, что их можно задать глобально с помощью module_defaults (см. раздел Значения модулей по умолчанию).

Использование группы значений по умолчанию модулей community.dns.hosttech

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

---
- name: Hosttech DNS
  hosts: localhost
  gather_facts: false
  module_defaults:
    group/community.dns.hosttech:
      hosttech_username: '{{ username }}'
      hosttech_password: '{{ password }}'
  tasks:
    - name: Query zone information
      community.dns.hosttech_dns_zone_info:
        zone_name: example.com
      register: result

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

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

Получение DNS-записей и наборов записей

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

- name: Query single record
  community.dns.hosttech_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=42 с целочисленным идентификатором зоны.

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

- name: Query all records for www.example.com
  community.dns.hosttech_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.hosttech_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.hosttech_dns_record_info. Он поддерживает те же параметры фильтрации, что и модуль community.dns.hosttech_dns_record_set_info.

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

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

Модуль community.dns.hosttech_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.hosttech_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.hosttech_dns_record:
    state: absent
    zone_name: example.com
    type: A  # IPv4 addresses
    record: www.example.com
    value: 1.1.1.1

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

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

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

- name: Make sure record is set to the given value
  community.dns.hosttech_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.hosttech_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.hosttech_dns_record_set:
    zone_name: example.com
    type: TXT
    prefix: www
    state: absent

- name: Remove specific AAAA values for www.example.com
  community.dns.hosttech_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. Это заставит модуль удалить текущее значение, только если существует запись AAAA для www.example.com, текущее значение которой — ::1, а TTL равен 300. Если задано другое значение, модуль не внесет изменений и завершится с ошибкой. Это может быть полезно, чтобы случайно не удалить значения, которые вы не хотите изменять. Чтобы вместо ошибки выдать предупреждение, используйте on_existing=keep_and_warn, а чтобы просто не вносить изменения без каких-либо сообщений об этой ситуации — on_existing=keep.

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

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

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

- name: Make sure that multiple records are present
  community.dns.hosttech_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.hosttech_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