Policy reference

Note

Generated from the policy schema the server validates against. What is here is exactly what the server accepts; there is nothing to keep in step by hand.

A policy deciding which updates become proposals, whether they merge themselves, and when they may be applied.

A policy

Field	Type	Default	Meaning
enabled	boolean	true
maintenance_window	MaintenanceWindow (or omitted)
name (required)	string		Unique within the organization.
priority	integer	100	Higher wins when two policies both select a host. 100 is the default and ties are broken by name, so two policies at the same priority are fine.
rollouts	map of name to Rollout
rules (required)	list of Rule		Tried in order. The first rule that matches an update decides it.
selector	Selector		Which hosts this applies to. Omitted means every host.

Types

Action

What a rule decided should happen.

One of:

• propose — Open a proposal and wait for a human.
• auto_merge — Open a proposal already approved, and let the rollout carry it.
• ignore — Decide it, and decide to do nothing. Distinct from no rule matching: this one is a choice somebody wrote down.

Apply

When an approved proposal may start.

One of:

• asap — As soon as it is approved, window or no window. The default, because a policy with no maintenance_window has nothing to wait for.
• asap_in_window — As soon as it is approved and the maintenance window is open.

Approval

Field	Type	Default	Meaning
min_approvers	integer	1
required	boolean	true

Batch

How often a batching rule opens a new proposal.

A daily, weekly, monthly.

Duration

A length of time: a number and one of s, m, h, d.

A string.

HaltOn

Field	Type	Default	Meaning
failed_health_checks	integer	0
failed_jobs	integer	0

MaintenanceWindow

Field	Type	Default	Meaning
days	list of Weekday	[]	Empty or omitted means every day.
duration (required)	Duration		How long the window stays open: 3h, 90m, 2d.
start (required)	string		Local wall-clock time in timezone, HH:MM or HH:MM:SS.
timezone (required)	string		An IANA zone name, so the window stays at the time it was written across a clock change.

Match

Field	Type	Default	Meaning
kind	OneOrMany (or omitted)		One kind or a list of them. Omitted matches every kind.
packages	list of Pattern	[]	Package name globs: * and ?, not regular expressions.
severity	SeverityList (or omitted)		Severities to catch, optionally including the word unrated.

OneOrMany

One value, or a list of them.

One of:

• UpdateKind
• list of UpdateKind

Pattern

A package-name glob: * and ?, not a regular expression.

A string.

Reboot

What to do about a host that needs a reboot afterwards.

One of:

• never — Apply the update and leave the reboot to a human. The default. domain::classify makes the case for why requires_reboot travels on its own axis: a fleet that reports itself patched while still running the old kernel is exactly the quiet wrongness this product exists to prevent. That argues for rebooting, and this default does the opposite — because rebooting a server nobody asked us to reboot is the one action that cannot be taken back, and the pending reboot stays visible on the host either way. Visible inaction, not invisible action.
• immediate — Reboot as part of the same job.
• in_window — Reboot, but only once the maintenance window is open.

Requirement

A step that may be required before a proposal applies.

A optional, required.

Rollout

Field	Type	Default	Meaning
halt_on	HaltOn
stages (required)	list of Stage

Rule

One rule. Rules are tried in the order they are written, and the first one that matches an update decides it.

Field	Type	Default	Meaning
action (required)	Action
apply	Apply	asap
approval	Approval (or omitted)		Omitted follows the action: propose asks one person, auto_merge asks nobody.
batch	Batch (or omitted)		Fold everything this rule catches into one proposal per period.
match	Match		Every field is a filter, and they are ANDed. Omitted matches everything.
preflight	Requirement	optional
reboot	Reboot	never
rollout	string (or omitted)		The name of one of this policy’s rollouts.
snapshot	Requirement	optional

Selector

Host groups (any of) and labels (all of). Empty matches everything.

Field	Type	Default	Meaning
groups	list of string	[]
labels	map of name to string	{}

Severity

How bad an update is. unrated is not a level: it is how you ask for updates nobody has assessed, which on a Debian fleet is most of them.

One of:

• none, low, medium, high, critical
• unrated — Not a Severity: it is how you ask for updates nobody has rated.

SeverityList

Which severities this rule catches. Omit it to catch every severity, including unrated.

A list of Severity.

Stage

Field	Type	Default	Meaning
count	integer (or omitted)		Exactly this many more hosts.
hosts	Selector (or omitted)		Which hosts this stage covers, when chosen by label rather than by proportion.
name (required)	string
percent	integer (or omitted)		Bring the rollout up to this share of its hosts, counted from the start.
soak	Duration (or omitted)		How long to wait before the next stage: 24h, 2h.

UpdateKind

What an update is. A kernel update published to the security pocket is security, not kernel; whether a reboot is needed travels separately.

A security, patch, kernel, dist_upgrade.

Weekday

A day of the week.

A mon, tue, wed, thu, fri, sat, sun.