Enroll Windows machines

To manage a Windows machine, Gardience needs the Salt agent on it, pointed at the Salt master and approved. There are two ways to get there:

• The enrollment playbook for many machines at once, run with the Ansible you already use. Machines join without a manual key approval while the enrollment is open.
• The PowerShell installer for one machine at a time. You then approve its key in the console.

Both install the 64-bit Salt 3008.3 agent (Salt-Minion-3008.3-Py3-AMD64.msi from packages.broadcom.com) and check the installer's SHA-256 checksum before running it. After the agent joins, Gardience manages the machine through Salt, so it needs no WinRM access from the Gardience server.

Option 1: enroll with the Ansible playbook#

You need the admin role, and an Ansible control machine with plain ansible-core. No Windows collections are needed: the Windows part of the playbook is one PowerShell script run with ansible.builtin.raw. Gardience never sees your passwords.

To enroll an inventory:

1. In the console, open Machines > Add machines.
2. Under Bring your Ansible inventory, give the enrollment a label and choose how long it stays open (4 hours, 24 hours or 3 days).
3. Select Create enrollment playbook. The browser downloads gardience-enroll.yml.

4. Run it against your inventory:

   Copy

   ansible-playbook -i YOUR_INVENTORY gardience-enroll.yml

The same playbook handles Linux and Windows hosts. It treats a host as Windows when either is true:

• its ansible_connection is winrm or psrp, or
• its ansible_shell_type is powershell (for Windows hosts you reach over SSH).

It uses whatever connection your inventory already defines for those hosts. It runs with gather_facts: false, so it does not depend on Windows facts.

Machines appear under Fleet as they join. Their Ansible groups appear under Machines > Groups after the next scan, which runs every 5 minutes.

The playbook holds an enrollment token that lets machines join without approval. Treat it like a password, and close the enrollment when you are done. See Enrollment tokens.

What the playbook does on a Windows host#

The PowerShell script stops at the first error. It:

1. Installs the agent if C:\Program Files\Salt Project\Salt\salt-minion.exe is missing: downloads the MSI to the temp folder, refuses it if the SHA-256 checksum does not match, and installs it quietly without starting the service.
2. Writes the agent config to C:\ProgramData\Salt Project\Salt\conf\minion.d\gardience.conf, only if it differs. The config is passed base64 encoded, so nothing can change the YAML layout on the way.
3. Sets the line gardience_enroll: <token> in C:\ProgramData\Salt Project\Salt\conf\grains, keeping any other lines in that file.
4. Sets the salt-minion service to start automatically. It restarts the service if anything changed, and otherwise just starts it.

Ansible reports the host as changed only when the script changed something, so the playbook is safe to run again.

Option 2: install on one machine and approve its key#

To add one machine:

1. In the console, open Machines > Add machines and copy the Windows commands. They are filled in with this server's address, the pinned Salt version and the installer checksum.

2. Open PowerShell as Administrator on the machine and run them. They:

   • download the Salt MSI to the temp folder and stop if its checksum does not match,
   • install it quietly with the master address set (MASTER), the agent ID set to the computer name in lower case (MINION_ID), and the service started (START_MINION=1).
3. Back on Machines > Add machines, find the machine under Waiting for approval and select Approve. Select Reject for a machine you do not recognize. The list refreshes every 8 seconds.

Approving and rejecting keys needs a role that can manage keys in Salt (the admin role). Other roles see "Your role cannot manage node keys." Each approval and rejection is written to the audit log.

If the server uses non-default Salt ports (--salt-ports), the PowerShell commands do not set them. Add publish_port and master_port to a file in C:\ProgramData\Salt Project\Salt\conf\minion.d\ and restart the salt-minion service.

Check the key before you approve it#

To compare fingerprints, run this in PowerShell as Administrator on the machine:

& 'C:\Program Files\Salt Project\Salt\salt-call.exe' --local key.finger

On an all-in-one Gardience server, from the install folder:

cd /opt/gardience
sudo docker compose exec salt-master salt-key -f MACHINE_ID

The two fingerprints must match.

What the agent config contains#

The enrollment playbook writes C:\ProgramData\Salt Project\Salt\conf\minion.d\gardience.conf. With default settings it looks like this:

master: gardience.example.com
id: "win-app-01"
autosign_grains:
  - gardience_enroll
grains:
  gardience_groups: ["windows", "app_servers"]

Extra settings appear in some installs:

With the PowerShell installer, the MSI writes the master address and agent ID itself. When the server has a warm standby, the commands also write minion.d\failover.conf with both servers and the failover settings. When --fleet-size is over 1000, they write minion.d\gardience-fleet.conf with the reconnect settings.

The enrollment token grain#

The grains file holds the line gardience_enroll: <token>. Once the node is accepted, Gardience removes this grain from it at the next scan, because anyone who can read grains could otherwise see the token.

After a machine joins#

When a new agent connects, Gardience pushes its Salt modules, grains and pillar to it within seconds. The node then shows on Overview > Dashboard after the next scan. Windows agents answer more slowly than Linux ones, and a first Windows Update scan can take minutes. To see asset facts such as domain, BitLocker and .NET on Machines > Inventory, select Collect now there.

Related#

• Enroll Linux machines
• Enrollment tokens
• Groups and patch rings
• Requirements