Certificate policies
A certificate policy is a standing rule attached to an agent group. It is not a job itself - it hands one out. For as long as an agent is in the policy's group, the policy makes sure that agent has the certificate job the policy describes.
Jobs stay ordinary jobs. Everything a policy creates is a normal certificate and a normal issue job: renewal, revocation, deployment and the PSW Group order poller all behave exactly as they would for a certificate you created by hand.
The rollout it enables
This is the order the feature is built around, and it works even though the policy is written before any agent exists:
- Write the policy on the group. The group can be completely empty - the policy is stored and applies to nobody yet.
- Roll an agent out. Under Build > New agent, pick the group in the installer step. The enrolment token carries it, so the agent joins the group the moment it registers.
- The policy applies itself. The agent's certificate is created and its issue job queued before its first check-in - nothing to click on the policy.
Moving an already-enrolled agent into the group, from the group's Members tab or the agent's own settings, does exactly the same thing.
Two modes
"Every member gets this certificate" means two genuinely different things, so a policy picks one at creation time. The mode can't be changed afterwards - the two produce structurally different certificates, and switching would strand what the policy has already created.
Per agent
Each member gets its own certificate, with its own common name and its own CA order. The common name is a template resolved against the agent:
| Placeholder | Resolves to |
|---|---|
{{hostname_short}} | the agent's reported hostname up to the first dot - web-01 for web-01.corp.local |
{{hostname}} | the full hostname the agent reports, lowercased |
{{agent_name}} | the name the agent carries in the dashboard |
So {{hostname_short}}.example.com gives web-01.example.com on one host and
web-02.example.com on the next. A per-agent policy must contain a placeholder -
without one every member would resolve to the same name, which is what shared mode is
for.
This is the only mode that works with PSW Group. PSW orders (and bills) one certificate at a time, so a single certificate shared across N agents would have them overwrite each other's order state. Giving each agent its own certificate gives each its own order. The flip side is that a per-agent PSW policy places one real, billable order per agent - including for every agent that joins later. The policy form says so explicitly before you save.
Shared
One certificate and one CA order in total, deployed to every member. This is for identical replicas behind a load balancer that all present the same hostname. Its common name is a literal hostname, not a template.
What a policy edit does
Editing a policy changes what future applications produce. It does not rewrite certificates already issued from it - the same way a Group Policy edit doesn't retroactively rewrite what it already applied. Members pick the new spec up at their next issuance; to push it out now, reissue the affected certificates from the certificates list.
The one exception is a shared policy's certificate, which is the thing being issued - spec edits reach it directly.
When a policy stops applying
A policy stops applying to an agent when the agent leaves the group, or the policy is disabled or deleted. Each policy decides what happens to the certificate it created:
- Keep (the default) - the certificate stays exactly where it is and keeps renewing. The host carries on serving it; it simply isn't managed by a policy any more.
- Retire - auto-renew is switched off and a revoke job is queued, the way a Group Policy removes the setting it applied. PSW Group certificates stop renewing but must be revoked at PSW by hand, since PSW revocation is a server-side API call rather than an agent job.
Either way, jobs that were queued but hadn't started are cancelled. Work already in progress, and certificates already deployed, are never retracted.
Rollout state
A policy's page shows how far it has been applied across its group's current members, and what each member's certificate is doing. A member can legitimately show as not applied when:
- its operating system can't run the policy's deploy target (a Linux agent in a group whose policy deploys to the Windows certificate store),
- it hasn't reported a hostname yet, so the template can't resolve, or
- the resolved hostname isn't covered by a verified domain with a DNS provider configured (DNS-01 only).
Fix the cause and press Apply now. Applying is idempotent - members already covered are left alone, so it is always safe to press.
Policies vs. certificate jobs on a group
Both exist, and they answer different questions:
- A certificate job targeting an agent group is a one-off fan-out to whoever is in the group at that moment. Use it for a one-time issuance.
- A certificate policy is the standing rule. Use it whenever the answer should keep holding as the fleet changes.
Certificate policies build on agent groups and require the Standard plan or higher.