variables

named values for hosts, groups, and recipes

Variables are named values that steps, templates, and expressions read.

Sources

Each host has its own value. A value comes from these sources. A later source replaces an earlier one:

1. the default
2. the vars of the groups of the host, then of the host
3. the vars of the recipe step
4. --set vars.<name>=<value>

Maps and lists do not merge.

Defaults

A default is declared once: in vars of winch.yaml, or in vars of the recipe that owns it. A recipe's own defaults start with the recipe name and _. A default can be a !secret, a template, or an expression. It sees vars, host, and facts, but not match(). A cycle between defaults is an error.

Variables without a default

A variable without a default needs no declaration. A read of it is enough, and the variable is required where it is read. A variable that may stay unset needs a default, such as relay_host: "".

Names and reads

A variable name has lowercase letters, digits, and _. A read names the variable: vars.domain, .vars.domain, $.vars.domain, or host.vars.domain. Any other read of the whole map, such as keys(vars) or range .vars, is an error. A map variable holds data that a step reads by key: vars.users[item]. host.vars holds the variables of the host without the vars of a recipe step.

Types

Variables have no types. A value keeps the type that YAML gives it. YAML reads 8.0 as 8 and 3.10 as 3.1. Quote such a value: php_version: "8.0". In the inventory, a default, or the vars of a recipe step, an unquoted one is a warning. --set parses its value as YAML, and there it is an error: --set 'vars.php_version="8.0"'.

Example

# winch.yaml
name: demo
hosts:
  mail.acme.com:
    vars:
      relay_host: smtp.acme.com
  web1.acme.com: {}
groups:
  all:
    vars:
      admin_email: ops@acme.com
vars:
  domain: acme.com
  relay_host: ""
steps:
  - recipe: motd
    vars:
      motd_text: Managed by winch
recipes:
  motd:
    vars:
      motd_text: Welcome
    steps:
      - file:
          path: /etc/motd
          content: !tpl "{{ .vars.motd_text }} on {{ .vars.domain }}\n"
      - file:
          path: /etc/admin_email
          content: !tpl "{{ .vars.admin_email }}\n"
      - file:
          path: /etc/relay_host
          content: !tpl "{{ .vars.relay_host }}\n"
        when: !expr vars.relay_host != ""