Hetzner DNS 指南

community.dns 集合提供了多个模块来处理 Hetzner DNS 服务。这些模块使用基于 JSON 的 REST API。

该集合提供了六个用于处理 Hetzner DNS 的模块

community.dns.hetzner_dns_record：创建/更新/删除单个 DNS 记录
community.dns.hetzner_dns_record_info：检索 DNS 记录信息
community.dns.hetzner_dns_record_set：创建/更新/删除 DNS 记录集
community.dns.hetzner_dns_record_set_info：检索 DNS 记录集信息
community.dns.hetzner_dns_record_sets：批量同步 DNS 记录集
community.dns.hetzner_dns_zone_info：检索区域信息

如果您有兴趣从 markuman.hetzner_dns 集合迁移，请参见从 markuman.hetzner_dns 迁移。

它还提供了一个清单插件

community.dns.hetzner_dns_records：从 DNS 记录创建清单

使用 DNS 区域 

community.dns.hetzner_dns_zone_info 模块允许查询区域信息。区域既可以用其名称标识，也可以用其 ID（整数）标识

- name: Query zone information by name
  community.dns.hetzner_dns_zone_info:
    zone_name: example.com
  register: result

- name: Query zone information by ID
  community.dns.hetzner_dns_zone_info:
    zone_id: aBcDeFgHiJlMnOpQrStUvW
  register: result

该模块返回区域名称和区域 ID，因此该模块可用于在区域 ID 和区域名称之间进行转换

- ansible.builtin.debug:
    msg: |
        The zone ID: {{ result.zone_id }}
        The zone name: {{ result.zone_name }}

使用 DNS 记录 

注意

默认情况下，此集合中的模块和插件返回和接受的 TXT 记录值是不带引号的。这意味着您无需添加双引号（"），以及转义双引号（如 \"）和反斜杠（如 \\）。所有与 DNS 记录一起使用的模块和插件都支持 txt_transformation 选项，该选项允许配置此行为。

查询 DNS 记录和记录集 

community.dns.hetzner_dns_record_set_info 模块允许从 API 查询 DNS 记录集。它可用于查询单个记录集。

- 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

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

在本节的所有示例中，您可以将 zone_name=example.com 替换为 zone_id=aBcDeFgHiJlMnOpQrStUvW，其中包含区域的 ID 字符串。

您还可以查询记录名称或前缀的所有记录集列表。

- 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 记录集 

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 存在其当前值为 ::1 且 TTL 为 300 的 AAAA 记录时才删除当前值。如果设置了其他值，则模块不会进行任何更改，但会失败。这对于避免意外删除您不想更改的值很有用。要发出警告而不是失败，请使用 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，这允许我们跳过该值。它告诉模块它不应该触及 example.com 的 NS 记录。

- 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` 迁移 

本节描述如何将 playbook 和角色从使用 markuman.hetzner_dns 集合迁移到 community.dns 集合中的 Hetzner 模块和插件。

迁移有三个步骤。其中两个步骤必须在迁移时完成，第三个步骤也可以稍后完成。

用新的模块和插件替换使用的模块和插件。
如有必要，调整模块和插件选项。
避免使用简化过渡的已弃用别名。

markuman.hetzner_dns 集合提供三个模块和一个清单插件。

注意

在使用 TXT 记录时，请查看 txt_transformation 选项。默认情况下，此集合中的模块和插件使用 **无引号** 值（您无需添加双引号并转义双引号和反斜杠），而 markuman.hetzner_dns 中的模块和插件使用部分带引号的值。您可以通过传递 txt_transformation=api 或 txt_transformation=quoted 来切换 community.dns 模块的行为。

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

最后一步是用 prefix 替换已删除的 name 别名 ( 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 模块替换。主要区别在于：

name 参数必须更改为 zone_name 或 zone。
返回值 zone_info 不再包含 name 和 id 条目。请改用返回值 zone_name 和 zone_id。

markuman.hetzner_dns.inventory 库存插件 

markuman.hetzner_dns.inventory 库存插件可以用 community.dns.hetzner_dns_records 库存插件替换。除了插件名称外，无需其他更改。

Hetzner DNS 指南

身份验证 

使用 `community.dns.hetzner` 模块默认组 