effectivelywild.technitium_dns.technitium_dns_get_cluster_state module – Get DNS cluster state

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_get_cluster_state.

New in effectivelywild.technitium_dns 1.0.0

Synopsis

  • Returns data on the current state of the DNS cluster.

  • Can be used to check if clustering is initialized and view cluster node information.

  • Optionally includes server IP addresses configured on the server.

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

include_server_ip_addresses

boolean

Set to true to return a list of static IP addresses configured on the server.

Choices:

  • false ← (default)

  • true

node

string

The node domain name for which this API call is intended.

When unspecified, the current node is used.

validate_certs

boolean

Whether to validate SSL certificates when making API requests.

Choices:

  • false

  • true ← (default)

Notes

Note

  • This operation requires Administration View permission.

  • The node parameter can only be used when clustering is initialized.

See Also

See also

effectivelywild.technitium_dns.technitium_dns_init_cluster

Initialize a new cluster

effectivelywild.technitium_dns.technitium_dns_delete_cluster

Delete cluster configuration

Examples

- name: Get cluster state
  effectivelywild.technitium_dns.technitium_dns_get_cluster_state:
    api_url: "http://localhost"
    api_token: "myapitoken"
  register: result

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

- name: Check if cluster is initialized
  effectivelywild.technitium_dns.technitium_dns_get_cluster_state:
    api_url: "http://localhost"
    api_token: "myapitoken"
  register: result

- name: Fail if cluster is not initialized
  fail:
    msg: "Cluster is not initialized"
  when: not result.cluster_state.clusterInitialized

- name: Get cluster state with server IP addresses
  effectivelywild.technitium_dns.technitium_dns_get_cluster_state:
    api_url: "http://localhost"
    api_token: "myapitoken"
    include_server_ip_addresses: true
  register: result

- name: Display server IP addresses
  debug:
    var: result.cluster_state.serverIpAddresses

- name: Get cluster state for specific node
  effectivelywild.technitium_dns.technitium_dns_get_cluster_state:
    api_url: "http://localhost"
    api_token: "myapitoken"
    node: "server2.example.com"
  register: result

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 (always false for get operations)

Returned: always

Sample: false

cluster_state

dictionary

Complete cluster state information

Returned: always

clusterDomain

string

The cluster domain name (only when initialized)

Returned: when cluster is initialized

Sample: "example.com"

clusterInitialized

boolean

Whether the cluster is initialized

Returned: always

Sample: true

clusterNodes

list / elements=dictionary

List of nodes in the cluster (only when initialized)

Returned: when cluster is initialized

id

integer

Node ID

Returned: success

Sample: 1342079372

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

Last seen timestamp

Returned: success

Sample: "2025-09-26T12:30:16Z"

url

string

Node API URL

Returned: success

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

configLastSynced

string

When the configuration was last synced (ISO 8601 format, only when initialized)

Returned: when cluster is initialized

Sample: "2025-09-26T12:30:16Z"

configRefreshIntervalSeconds

integer

Interval in seconds for config refresh (only when initialized)

Returned: when cluster is initialized

Sample: 900

configRetryIntervalSeconds

integer

Interval in seconds for config retry (only when initialized)

Returned: when cluster is initialized

Sample: 60

dnsServerDomain

string

The DNS server domain name

Returned: always

Sample: "server1.example.com"

heartbeatRefreshIntervalSeconds

integer

Interval in seconds for heartbeat refresh (only when initialized)

Returned: when cluster is initialized

Sample: 30

heartbeatRetryIntervalSeconds

integer

Interval in seconds for heartbeat retry (only when initialized)

Returned: when cluster is initialized

Sample: 10

serverIpAddresses

list / elements=string

List of static IP addresses configured on the server (only when include_server_ip_addresses is true)

Returned: when include_server_ip_addresses is true

Sample: ["192.168.10.5", "192.168.120.1"]

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 get cluster state"

Authors

  • Frank Muise (@effectivelywild)