Agent groups
Group agents so one certificate job can target all of them, and so a certificate policy has something to apply to - membership, effects, and when to use one.
An agent group is a named set of agents. Each agent belongs to at most one.
A group is useful on its own - a certificate job can target the whole group instead of one server - but its main purpose is to give a certificate policy something to apply to. The group decides who gets a certificate; the policy decides what they get.
Agent groups require the Standard plan or higher.
Creating a group and filling it
Create one under Manage > Agent Groups. Each group has its own page with four tabs:
| Tab | What is on it |
|---|---|
| Overview | How far the group's policies have rolled out across its members. |
| Policies | Every certificate policy attached to this group, each with a rollout meter. |
| Members | Tick agents in or out and save once. Every affected agent's policies are applied or unapplied in a single request. |
| Settings | Rename or delete the group. |
There are two other ways to put an agent in a group: from the agent's own page (Manage > Agents > Edit > Group), or by picking the group in the installer step under Manage > Agents, so the host joins the moment it enrolls.
What happens when membership changes
Membership is not a label. Changing it triggers real work.
| Change | Effect |
|---|---|
| An agent joins | Every enabled policy on the group is applied to it: its certificate is created and its issue job queued straight away. |
| An agent leaves | Those policies are unapplied. Queued work is cancelled. Each policy's own setting decides whether its certificate is kept (the default) or retired. |
| An agent is revoked | Same as leaving - it can no longer authenticate, so nothing further is applied to it. |
| The group is deleted | The policies attached to it are deleted, each unapplied first so its keep-or-retire setting is honoured. Members stay enrolled, just ungrouped. |
Deleting a group is blocked while a certificate job targets it directly - reassign or delete those jobs first. Policies are not a blocker, because deleting them is part of deleting the group.
Targeting a group from a certificate job
A certificate job can target a group directly, without a policy. That is a one-off fan-out: one certificate, one job per member, resolved at the moment you create it.
Renewals re-resolve the group's current membership, so a renewal does cover agents that joined since. But between renewals, an agent that joins gets nothing.
If you want the answer to keep holding as the fleet changes, that is what a certificate policy is for.
Group or single agent?
| Situation | Use |
|---|---|
| A standalone server | A single agent |
| Identical web servers behind a load balancer | A group, with a shared-mode policy |
| A cluster where each node needs its own hostname | A group, with a per-agent policy |
| Anything that scales up and down | A group, always - adding capacity should need no certificate work at all |
The test is whether you would have to remember to do something when a server is added. If the answer is yes, it belongs in a group with a policy on it.