Skip to content

windows_dns_record

Experimental. One name’s DNS records of one type, in a zone on a Windows DNS server such as a domain controller, owned as a set.

Experimental. New, and tested on GitHub’s Windows Server 2022 and 2025 runners with the DNS Server role added, not yet on a domain controller. See Windows readiness.

Use windows_dns_record to keep a name’s records in a zone on a Windows DNS server, usually a domain controller: the A records for a web farm, a CNAME for an app, a TXT record for a mail check. A circuit that builds a domain can then publish its own names, instead of someone adding them in the DNS console.

Two web servers behind one name:

step "www" {
windows_dns_record {
zone = "corp.example.com"
name = "www"
type = "A"
values = ["10.0.1.11", "10.0.1.12"]
ttl = 300
}
}

An alias for an app:

step "intranet" {
windows_dns_record {
zone = "corp.example.com"
name = "intranet"
type = "CNAME"
values = ["web1.corp.example.com"]
}
}

Run the step on the DNS server that holds the zone, such as a domain controller in the circuit’s hosts.

Name Type Required Description
name string Yes The name in the zone, such as www, or @ for the zone itself.
on_remove string No What happens on the server when this resource is removed: “forget” (default) leaves the records, “delete” removes them.
ttl number No Time to live, in seconds. Defaults to 3600.
type string Yes “A”, “AAAA”, “CNAME”, “PTR” or “TXT”.
values list of string Yes Every value the name has of this type: addresses for A and AAAA, so several make round robin, one host name for a CNAME, host names for PTR, text for TXT. Values not listed are removed.
zone string Yes The zone, such as corp.example.com. It must be on the server the step runs on.

Conn3x sets these; reference them as conn3x_windows_dns_record.<circuit>__<step>["<host>"].<name>.

Name Type Description
in_sync bool Whether the name had exactly these values, at this TTL, at the last refresh.
revision string Changes each time Conn3x changes this on the host. Handlers watch it.

A step lowers to the conn3x_windows_dns_record resource, one instance per host, and connects with its circuit’s ssh block.

The set. A step owns every record of its type that name has in zone. Values not listed are removed, and missing ones are added, so a step with two addresses makes a round robin, and changing one address leaves the other record alone.

Reading. On every plan, Conn3x reads the records with Get-DnsServerResourceRecord. Values compare the way DNS reads them: IPv6 addresses in any form, and host names without case or the trailing dot the server adds. in_sync is true when the values match and they have ttl.

Applying. Conn3x removes what isn’t listed, adds what’s missing, and sets a new ttl in place on the records that stay, so none of them disappears while it changes. A zone that isn’t on the server is an error that says so.

Changes. Changing values or ttl updates the records in place. Changing zone, name or type replaces the step.

on_remove = "forget", the default, leaves the records. on_remove = "delete" removes every record of the step’s type that the name has.