windows_domain_membership

Experimental. This Windows host joined to an Active Directory domain as a member. It never reboots: reboot_required says Windows wants one, and windows_reboot does it. Removing the step leaves the host in the domain; nothing is unjoined.

Experimental. Windows support is new, and this module may change between releases.

Use windows_domain_membership to join a Windows server to an Active Directory domain. It never reboots the host. A join only takes effect after a reboot, so follow it with a windows_reboot step.

Example usage

The server has to find the domain first, so point its DNS at a domain controller.

step "dns" {
  windows_dns_client {
    servers = ["10.44.0.4"]
  }
}

step "join" {
  windows_domain_membership {
    domain      = "lab.example.com"
    username    = "LAB\\joiner"
    password_wo = "use an ephemeral variable here"
  }
}

step "joined" {
  windows_reboot {
    only_if_pending = true
  }
}

Arguments

Name	Type	Required	Description
domain	string	Yes	DNS name of the domain to join, such as lab.example.com.
ou	string	No	Distinguished name of the OU for the computer’s account, such as OU=Servers,DC=lab,DC=example,DC=com. Unset uses the domain’s default. Used only when joining.
password_wo	string	No	Password for username, kept out of plan and state. Needed to join, and used only then.
timeout	string	No	How long joining may take. Defaults to “10m”.
username	string	Yes	Domain account that may join computers, such as LAB\joiner or joiner@lab.example.com. Used only when joining.

Read-only attributes

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

Name	Type	Description
in_sync	bool	Whether the host was in this domain at the last refresh.
reboot_required	bool	Whether Windows reported wanting a reboot after the last change. Joining always does.
revision	string	Changes each time Conn3x changes this on the host. Handlers watch it.

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

How it works

Why it needs a password. Conn3x logs in with an SSH key, and a key login has no password of its own to show the domain. So the join runs Add-Computer with the account you give in username and password_wo. The account needs the right to join computers: a member of Domain Admins has it, or delegate it on an OU.

The password. password_wo goes to the host on stdin and becomes a SecureString through .NET before Add-Computer sees it, so a logging policy that records cmdlet parameters records only the type name. It’s never in plan or state, and it’s blanked from errors. It’s used once, when the host joins. Changing it later does nothing, and Conn3x can’t tell if it’s still right.

Reboots. reboot_required is true after a join. The join also leaves the marker windows_reboot with only_if_pending looks for, so a run that stopped before its reboot plans the reboot next time.

Reads change nothing. A refresh reads whether the computer is in a domain, and which, from Win32_ComputerSystem. A host that joined but hasn’t rebooted yet already reads as joined. A domain controller of the same domain counts as joined, so promoting a member later with windows_ad_domain_controller doesn’t make this step plan again.

Settings used once. ou and username apply only when the host joins. Changing domain plans a new join, which fails: Conn3x won’t take the host out of the domain it’s in.

Logging in afterwards. Nothing changes for the SSH login. On a member server, the bare name, such as azadmin, is still the local account, and so is win2\azadmin. A domain account can log in too, once it’s in the server’s Administrators group and has the key.

What it refuses. A host already in another domain.

Removal

Deleting a windows_domain_membership step leaves the host in the domain. Conn3x never takes a host out of one. Delete the VM, or run Remove-Computer yourself and then delete its computer account in the domain.