facts

values that winch reads from each host

Facts are values that winch reads from each host before the plan, such as the OS release.

Reading a fact

Expressions read a fact as facts.os.id, and templates as {{ .facts.os.id }}. Facts are a fixed set. A read of an unknown fact is an error.

# winch.yaml
name: demo
hosts:
  web1.example.com: {}
steps:
  - recipe: base
recipes:
  base:
    require:
      - !expr facts.os.id == "debian" and facts.os.version == "13"
    steps:
      - reboot:
          if_required: true
        when: !expr facts.reboot_required

# The plan fails a host that is not Debian 13. A host that needs a
# reboot reboots.

When winch reads them

winch reads the facts once per host per run, before the first step, and again after a reboot. They describe the host before the run.

Keys

facts.os

map

OS release of the host. winch reads id, version, and codename from /etc/os-release, or from /usr/lib/os-release when the first does not exist.

facts.os.id

string

Distribution, such as debian or ubuntu.

facts.os.version

string

Release number, such as 13 or 24.04. It is a string: compare it with a string, such as "13".

facts.os.codename

string

Release code name, such as trixie or noble.

facts.os.arch

string

CPU architecture: amd64 or arm64.

facts.reboot_required

boolean

Pending reboot. It is true when /run/reboot-required exists, or when a kernel in /boot is newer than the running kernel.