Policy examples

A policy decides, for the hosts it selects, what happens to each update: propose it for a person to approve, merge it automatically, or ignore it — and when and how an approved change may run. Every field is in the reference; every example here is checked against it on each build of this site.

Everything by hand

The smallest policy: every update on every host becomes a proposal that one person approves.

name: everything-by-hand
rules:
  - action: propose

No selector means every host; a rule with no match matches every update.

Security fixes merge themselves, the rest wait

Rules are tried in order and the first that matches decides, so the specific rule goes first.

name: security-first
rules:
  - match: { kind: security }
    action: auto_merge
  - action: propose

auto_merge opens the proposal already approved. It still names exact package versions, still only runs where the host’s agent.toml allows it, and still goes through the rollout and health checks like any other change.

A production web fleet

This is the example from Updawg’s own design, and it is also a test fixture the server’s policy engine is checked against.

name: web-production
priority: 100
selector:
  groups: [web-prod]
  labels: { env: production }

maintenance_window:
  days: [tue, wed, thu]
  start: "02:00"
  duration: 3h
  timezone: Europe/London

rules:
  - match: { kind: security, severity: [critical, high] }
    action: auto_merge
    rollout: canary
    apply: asap_in_window

  - match: { kind: security }
    action: auto_merge
    rollout: canary

  - match: { kind: patch }
    action: propose
    batch: weekly
    approval: { required: true }

  - match: { kind: kernel }
    action: propose
    approval: { required: true }
    reboot: in_window

  - match: { kind: dist_upgrade }
    action: propose
    preflight: required
    snapshot: required
    approval: { required: true, min_approvers: 2 }

  - match: { packages: ["postgresql-*"] }
    action: ignore

rollouts:
  canary:
    stages:
      - name: canary
        hosts: { labels: { canary: "true" } }
        soak: 24h
      - name: wave-1
        percent: 25
        soak: 2h
      - name: remainder
        percent: 100
    halt_on:
      failed_jobs: 1
      failed_health_checks: 1

What it does, rule by rule:

1. Critical and high security fixes merge themselves and roll out through the canary rollout, starting as soon as the maintenance window opens.
2. Other security fixes merge themselves and roll out the same way.
3. Ordinary patches are gathered into one proposal a week, which one person approves.
4. Kernel updates need an approval, and the host reboots inside the window.
5. Release upgrades need a passing preflight, a snapshot and two approvers.
6. PostgreSQL is left alone: it is upgraded some other way.

The canary rollout goes to hosts labelled canary: "true" first and waits a day; then a quarter of the rest, waiting two hours; then everything else. One failed job or one failed health check halts it before it reaches more hosts.