effectivelywild.technitium_dns.technitium_dns_init_cluster module – Initialize a new DNS cluster

Note

This module is part of the effectivelywild.technitium_dns collection (version 1.1.2).

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 effectivelywild.technitium_dns. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: effectivelywild.technitium_dns.technitium_dns_init_cluster.

New in effectivelywild.technitium_dns 1.0.0

Synopsis

  • Initialize a new Technitium DNS cluster making this server the Primary node.

  • You can add other DNS servers to this cluster later which will be added as Secondary nodes.

  • No data will be lost on this DNS server in this process.

  • If HTTPS is not enabled, it will be enabled automatically with a self-signed certificate.

  • Creates two zones if they don’t exist - the Cluster Primary zone and the Cluster Catalog zone.

  • The Cluster domain name cannot be changed later.

Requirements

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

  • Technitium DNS Server v14.0 or later

Parameters

Parameter

Comments

api_port

integer

Port for the Technitium DNS API. Defaults to 5380

Default: 5380

api_token

string / required

API token for authenticating with the Technitium DNS API

api_url

string / required

Base URL for the Technitium DNS API

cluster_domain

string / required

The fully qualified domain name to be used to identify the new cluster.

This cannot be changed later.

primary_node_ip_addresses

list / elements=string / required

The static IP address(es) of this DNS server.

Must be accessible by all other DNS servers to be added later as Secondary nodes.

Accepts a list of IP addresses for nodes with multiple network interfaces.

When multiple IPs are provided, they will be used for cluster communication.

validate_certs

boolean

Whether to validate SSL certificates when making API requests.

Choices:

  • false

  • true ← (default)

Notes

Note

  • The initialization process will enable HTTPS with a self-signed certificate if not already enabled.

  • It’s recommended to manually configure HTTPS with a valid certificate before initializing the cluster.

  • The Cluster Primary zone is named as the cluster domain name.

See Also

See also

effectivelywild.technitium_dns.technitium_dns_get_cluster_state

Get cluster state information

effectivelywild.technitium_dns.technitium_dns_delete_cluster

Delete cluster configuration

Examples

- name: Initialize a new DNS cluster with single IP
  effectivelywild.technitium_dns.technitium_dns_init_cluster:
    api_url: "http://localhost"
    api_token: "myapitoken"
    cluster_domain: "example.com"
    primary_node_ip_addresses:
      - "192.168.10.5"
  register: result

- name: Initialize cluster with multiple IP addresses
  effectivelywild.technitium_dns.technitium_dns_init_cluster:
    api_url: "http://localhost"
    api_token: "myapitoken"
    cluster_domain: "example.com"
    primary_node_ip_addresses:
      - "192.168.10.5"
      - "10.0.1.5"
  register: result

- name: Display cluster state after initialization
  debug:
    var: result.cluster_state

- name: Initialize cluster with custom API port
  effectivelywild.technitium_dns.technitium_dns_init_cluster:
    api_url: "http://server1.example.com"
    api_token: "myapitoken"
    api_port: 5381
    cluster_domain: "dns-cluster.example.com"
    primary_node_ip_addresses:
      - "10.0.1.5"

Return Values

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

Key

Description

changed

boolean

Whether the module made changes

Returned: always

Sample: true

cluster_state

dictionary

Complete cluster state after initialization

Returned: always

clusterDomain

string

The cluster domain name

Returned: always

Sample: "example.com"

clusterInitialized

boolean

Whether the cluster is initialized

Returned: always

Sample: true

clusterNodes

list / elements=dictionary

List of nodes in the cluster

Returned: always

id

integer

Node ID

Returned: success

Sample: 1081800048

ipAddress

string

Node IP address

Returned: success

Sample: "192.168.10.5"

name

string

Node domain name

Returned: success

Sample: "server1.example.com"

state

string

Node state (Self, Connected, Unreachable)

Returned: success

Sample: "Self"

type

string

Node type (Primary or Secondary)

Returned: success

Sample: "Primary"

upSince

string

Node up since timestamp

Returned: success

Sample: "2025-11-08T19:11:05.591447Z"

url

string

Node API URL

Returned: success

Sample: "https://server1.example.com:53443/"

configRefreshIntervalSeconds

integer

Interval in seconds for config refresh

Returned: always

Sample: 900

configRetryIntervalSeconds

integer

Interval in seconds for config retry

Returned: always

Sample: 60

dnsServerDomain

string

The DNS server domain name

Returned: always

Sample: "server1.example.com"

heartbeatRefreshIntervalSeconds

integer

Interval in seconds for heartbeat refresh

Returned: always

Sample: 30

heartbeatRetryIntervalSeconds

integer

Interval in seconds for heartbeat retry

Returned: always

Sample: 10

version

string

Technitium DNS Server version

Returned: always

Sample: "14.0"

failed

boolean

Whether the module failed

Returned: always

Sample: false

msg

string

Status message

Returned: on error

Sample: "Failed to initialize cluster"

Authors

  • Frank Muise (@effectivelywild)