windows_ad_domain
A new domain in an Active Directory forest that exists, a child or a new tree, with this Windows host as its first domain controller and DNS server. It never reboots: reboot_required says Windows wants one, and windows_reboot does it. Removing the step leaves the domain; nothing is demoted.
Use windows_ad_domain to add a domain to a forest that exists, with this host as the new domain’s first domain controller and DNS server. Shops that split by region or business unit add a child, such as emea.lab.example.com under lab.example.com. After a merger, a company with its own name often gets a new tree instead, such as apac.example.net beside lab.example.com, in the same forest. It never reboots the host. Promotion always needs a reboot, so follow it with a windows_reboot step, then wait for AD to answer.
Example usage
Section titled “Example usage”The host needs the AD DS role, and DNS that finds the parent domain. Point it at a domain controller of the parent with windows_dns_client, with loopback second, which promotion adds anyway.
step "ad_ds" { windows_feature { name = "AD-Domain-Services" include_management_tools = true }}step "dns" { windows_dns_client { servers = ["10.46.0.4", "127.0.0.1"] }}step "domain" { windows_ad_domain { domain_name = "emea.lab.example.com" netbios_name = "EMEA" username = "azadmin@lab.example.com" password_wo = "use an ephemeral variable here" safe_mode_password_wo = "use an ephemeral variable here" }}step "promoted" { windows_reboot { only_if_pending = true timeout = "15m" }}step "adws" { windows_wait_for { port = 9389 timeout = "10m" }}A new tree names the forest domain it joins:
step "domain" { windows_ad_domain { domain_name = "apac.example.net" domain_type = "tree" parent_domain_name = "lab.example.com" netbios_name = "APAC" username = "azadmin@lab.example.com" password_wo = "use an ephemeral variable here" safe_mode_password_wo = "use an ephemeral variable here" }}Arguments
Section titled “Arguments”| Name | Type | Required | Description |
|---|---|---|---|
database_path |
string | No | Folder for the AD database. Windows’ default is C:\Windows\NTDS. Used only when the domain is made. |
domain_name |
string | Yes | Full DNS name of the new domain, such as emea.lab.example.com. For a child, everything after the first label is the parent domain, which must exist. For a tree, a name outside the forest’s other domains, such as apac.example.net. |
domain_type |
string | No | “child” (default), a domain under the one its name says, or “tree”, a new tree in the forest beside its other domains. Used only when the domain is made. |
log_path |
string | No | Folder for the AD logs. Used only when the domain is made. |
netbios_name |
string | No | NetBIOS name of the new domain, up to 15 characters, such as EMEA. Unset lets Windows take it from the first label. Used only when the domain is made. |
parent_domain_name |
string | No | For a tree: a domain in the forest it joins, usually the forest root, such as lab.example.com. Not set for a child. Used only when the domain is made. |
password_wo |
string | No | Password for username, kept out of plan and state. Needed to make the domain, and used only then. |
safe_mode_password_wo |
string | No | Directory Services Restore Mode password for this domain controller, kept out of plan and state. Needed to make the domain, and used only then: changing it later changes nothing on the host. |
sysvol_path |
string | No | Folder for SYSVOL. Used only when the domain is made. |
timeout |
string | No | How long promotion may take. Defaults to “30m”. |
username |
string | Yes | Account in the forest that may add a domain, a member of Enterprise Admins, named by its domain’s DNS name: admin@lab.example.com or lab.example.com\admin, not LAB\admin. Its domain is the new domain’s parent or another domain above it. Used only when the domain is made. |
Read-only attributes
Section titled “Read-only attributes”Conn3x sets these; reference them as conn3x_windows_ad_domain.<circuit>__<step>["<host>"].<name>.
| Name | Type | Description |
|---|---|---|
in_sync |
bool | Whether the host was a domain controller in this domain, or promoted into it and waiting for its reboot, at the last refresh. |
reboot_required |
bool | Whether Windows reported wanting a reboot after the last change. Promotion always does. |
revision |
string | Changes each time Conn3x changes this on the host. Handlers watch it. |
A step lowers to the conn3x_windows_ad_domain resource, one instance per host, and connects with its circuit’s ssh block.
How it works
Section titled “How it works”Promotion. Conn3x runs Install-ADDSDomain with -DomainType ChildDomain, -InstallDns, -CreateDnsDelegation and -NoRebootOnCompletion. domain_name is the new domain’s full name, and everything after its first label is the parent, so emea.lab.example.com goes under lab.example.com. The parent’s DNS gets a delegation to this server, so names in the new domain resolve from the rest of the forest. The new domain controller is a global catalog, as Windows makes one by default, and the new domain trusts its parent both ways, as every child domain does.
A new tree. With domain_type = "tree", Conn3x runs Install-ADDSDomain with -DomainType TreeDomain, the full domain_name, and parent_domain_name as the domain it joins. A tree has no parent zone, so there’s no delegation: the rest of the forest finds the new domain’s names once you give their DNS servers a forwarder or a stub zone for it. The new tree and the forest root trust each other both ways. Its name has to be outside the namespace of parent_domain_name, or it’s a child, and Conn3x says so before anything reaches the host. On Azure, with two 2-vCPU Windows Server 2025 VMs, promotion took under 3 minutes, the reboot after it about 6, and the second plan made no change to either domain.
Why it needs a password. A key login has no password to show the forest, so promotion uses the account in username and password_wo. Adding a domain to a forest takes a member of Enterprise Admins, such as the forest root’s first administrator. It belongs to the parent domain or one above it. For a tree, that’s parent_domain_name or a domain above it. Name it by that domain’s DNS name, as azadmin@lab.example.com or lab.example.com\azadmin: the host isn’t in the forest yet, so it finds the domain through DNS, and Install-ADDSDomain refuses LAB\azadmin. Conn3x checks this before anything reaches the host.
The passwords. password_wo and safe_mode_password_wo go to the host on stdin and become SecureString values through .NET before the cmdlet sees them, so a logging policy that records cmdlet parameters records only the type name. They’re never in plan or state, and they’re blanked from errors. Both are used once, at promotion. To change the Directory Services Restore Mode password later, use ntdsutil on the host.
Reboots. reboot_required is true after promotion, and promotion leaves the marker windows_reboot with only_if_pending looks for. sshd answers before AD does, which is why the example waits for Active Directory Web Services on port 9389. The AD steps that come after wait for the global catalog themselves.
Reads change nothing. A refresh reads the host’s domain role, its domain and NTDS’s root domain from the registry, and loads no AD tools. Until the reboot, Windows still says the host is in a workgroup, so promotion records the new domain’s name in the reboot marker, which goes with the reboot. While it’s there, a promoted host counts as a domain controller in that domain.
Folders. database_path, log_path and sysvol_path are checked as windows_ad_forest checks them: a folder that exists must be empty, owned by an administrator, not a link, and writable by nobody else. A missing one is made with SYSTEM and Administrators only.
Settings used once. netbios_name, username and the folders apply only at promotion. Changing domain_name plans a new promotion, which fails: Conn3x won’t demote the host.
Logging in afterwards. A domain controller has no local accounts. Seen on Azure, the bare name, such as azadmin, logs in as the new domain’s account of that name after promotion, EMEA\azadmin, with the same key. A local login, such as dc2\azadmin or .\azadmin, stops working, so Conn3x refuses to promote with one. To use the domain form, set netbios_name so Conn3x can check it’s the new domain’s.
What it refuses. A host that’s a domain controller already, and a host that’s a member of a domain: promoting it would take it out, and Conn3x never does that. A child’s domain_name with fewer than three labels, since a child needs a parent with two. A tree without parent_domain_name, a child with one, and a tree named inside its parent’s namespace.
Removal
Section titled “Removal”Deleting a windows_ad_domain step leaves the domain and its domain controller as they are. Conn3x never demotes one. Delete the VM, or run Uninstall-ADDSDomainController yourself, which for the last domain controller of a domain also removes the domain from the forest.