Groups and patch rings

A group is a named set of nodes you can aim work at. Every group works in runbooks, workflows, schedules, change windows and the secrets vault. When work targets a group, Gardience sends Salt the target expression the group stands for.

Gardience has three kinds of groups, all listed on Machines > Groups:

The All groups list shows each group, where it came from, its target expression and its members that are online right now. Membership is refreshed at most once a minute.

Built-in groups#

The expressions use Salt's compound targeting. G@ matches a grain, a fact the agent reports about its machine. Built-in groups work the same way in attach mode, because Gardience sends the expression itself instead of relying on your master's own group settings.

Custom groups#

To make a group, as an admin:

1. Open Machines > Groups.
2. Under New group, enter a name. Names start with a letter or number, may use letters, numbers, spaces, dots, dashes and underscores, and are up to 60 characters. A name cannot be the same as a built-in group.

3. Under Members, choose how to pick them:

   Choice	What you enter	Resulting target
   Pick nodes	Tick the nodes	A fixed list (L@node1,node2)
   By operating system	Windows, Linux, RHEL family, Debian family or SUSE family	A grain match, for example G@os_family:Suse
   By name pattern	A pattern with * or ? wildcards, for example web-*	Matches node names. Letters, numbers, ., - and _ only, up to 100 characters
   Salt compound expression (advanced)	Any Salt compound expression, for example G@os:Rocky and web*	Used as written. Up to 400 characters

4. Select Save group. Saving with an existing custom group's name replaces it.

To delete a custom group, select Delete next to it. Built-in and Ansible groups cannot be deleted on this page. Saving and deleting groups are written to the audit log.

Act on a group#

Every group, built-in, Ansible or your own, has an Actions menu:

The first four ask first, then run as you, under your role, with the same change windows, locks, approvals and audit log as running the runbook from Automation > Runbooks. Follow the run under Automation > Runbooks, Recent runs. They are greyed out for a group with no machines online.

Ansible groups#

When hosts join through the enrollment playbook, each agent reports its Ansible groups (group_names from your inventory) as the grain gardience_groups. Gardience turns each of those into a group with the same name.

• If an Ansible group has the same name as a built-in group, Gardience names it ansible-<name>.
• Group names that do not fit the naming rules above are ignored.
• Each Ansible group targets an explicit list of nodes (L@...) kept on the server, so a node cannot move itself into a group just by changing what it reports.
• When an Ansible group has no members, it targets nobody. After a day with no members, it is removed.
• When a node's key is removed from the master, Gardience forgets its memberships at the next scan.

To change Ansible groups, change your inventory and run the enrollment playbook again. They cannot be deleted in the console.

Pending approvals#

A grain is something a machine says about itself, so Gardience trusts it only once:

• First report: the groups a node reports when Gardience first sees it become its membership.
• Leaving a group: applies at once.
• Joining a new group later: waits for an admin. Until then the node stays out of that group, and out of any vault secrets scoped to it.

When nodes ask to join new groups, the console shows a notice that says how many, and Machines > Groups shows Ansible group changes waiting for approval with each node and the groups it wants to join. If you changed your inventory and re-ran the playbook, select Approve all. If you did not expect the change, leave it pending and check the machine. If a node stops asking, its pending request is dropped.

Admins can also approve some nodes only, through the API:

curl -s https://gardience.example.com/gardience/api/groups/ansible/approve -H "X-Auth-Token: $TOKEN" \
  -H 'Content-Type: application/json' -d '{"nodes":["web-01","web-02"]}'

Each approval is written to the audit log (group.ansible_membership_approved).

Patch rings#

Patch rings let you patch a small set of machines first, check them, and only then patch the rest:

• Ring0-Pilot holds the nodes that carry the grain gardience_ring set to pilot.
• Ring1-Broad holds every other node.

To move a node between rings, as an admin:

1. Open Machines > Inventory.
2. In the Patch ring column, select Make pilot to put a node in the pilot ring, or Move to broad to take it out.

The node must be online: Gardience sets or removes the grain on the machine and waits up to 60 seconds for it to answer. If it does not, you see an error and can try again when it is back. Each move is written to the audit log (ring.pilot or ring.broad).

Work aimed at an empty pilot ring stops with the message "the pilot ring is empty", so pick pilot machines before you use it.

Rings in workflows and schedules#

Gardience comes with a workflow named Patch Tuesday: pilot ring, then broad ring. It:

1. patches the pilot ring, then checks that its machines are healthy,
2. asks a second person to approve moving on,
3. patches the broad ring, then checks it,
4. re-applies the security baseline to the broad ring if a broad ring step fails.

It also comes with a schedule named Weekly patch window: pilot ring, which patches the pilot ring on Tuesdays at 02:00 (America/Chicago). It is turned off until you turn it on.

Related#

• Enrollment tokens
• Enroll Linux machines
• Enroll Windows machines
• Users and roles