# inventory

hosts and groups

An inventory lists the hosts that winch manages, puts them in groups, and gives them values.

## Files

An inventory is a file in inventories/, such as inventories/production.yaml, or a key in inventories of winch.yaml. It holds data and secrets, but no templates or expressions.

## Choosing the inventory

--inventory \<name\> names the inventory of a run. inventory in winch.yaml names a default. A project with one inventory uses it. A project with more inventories and no default makes each run name its inventory, so a run against production is always deliberate.

## Groups and values

The group all contains every host. A host value beats a group value, and a group value beats a value of all. Two groups of one host that set different values for one variable, or for user, are an error, unless the host sets that value too.

## SSH settings

Every other SSH setting, such as the port or the key, comes from your SSH config. Its Host blocks match the host name, also when the host has an address.

## Host patterns

Host patterns select hosts in the hosts of a stage, in --hosts, and in winch run and winch exec:

|  |  |
| --- | --- |
| web | the hosts in the group web, or the host named web |
| web,db | the hosts in web or in db |
| web \& prod | the hosts in web and in prod |
| web \& !web3 | the hosts in web, without web3 |

\& and ! bind tighter than ",". Hosts keep inventory order. A name that is neither a group nor a host is an error. A pattern with only ! names is an error: write all \& !web, not !web.

## Keys

| Key | Type | Default | Meaning |
| --- | --- | --- | --- |
| [`hosts`](#inventory.hosts) | map | - | keyed by host name |
| [`hosts.address`](#inventory.hosts.address) | string | - | host name or IP for SSH |
| [`hosts.user`](#inventory.hosts.user) | string | - | SSH login user |
| [`hosts.vars`](#inventory.hosts.vars) | map | - | variable values of the host |
| [`groups`](#inventory.groups) | map | - | keyed by group name |
| [`groups.user`](#inventory.groups.user) | string | - | SSH login user of the members |
| [`groups.hosts`](#inventory.groups.hosts) | list of strings | - | member host names |
| [`groups.vars`](#inventory.groups.vars) | map | - | variable values of the members |

### `inventory.hosts` {#inventory.hosts}

map

Keyed by host name. Without address, the name is the SSH host name. A host name that YAML reads as a number, such as 1234, needs quotes. A host and a group cannot have the same name.

### `inventory.hosts.address` {#inventory.hosts.address}

string

Host name or IP for SSH. Without it, the SSH config decides the host name, and host.address is the name of the host. The Host blocks of the SSH config match the host name, also with address. A port goes in the SSH config. Two hosts cannot have the same SSH host name, port, and jump host.

### `inventory.hosts.user` {#inventory.hosts.user}

string

SSH login user. Without it, the host takes the user of its groups, then of all, then of the SSH config. --user beats it. Every other SSH setting comes from your SSH config.

### `inventory.hosts.vars` {#inventory.hosts.vars}

map

Variable values of the host. They beat the values of its groups.

### `inventory.groups` {#inventory.groups}

map

Keyed by group name. The group all contains every host. A host value beats a group value, and a group value beats a value of all.

### `inventory.groups.user` {#inventory.groups.user}

string

SSH login user of the members. Two groups of one host with different users are an error, unless the host sets user.

### `inventory.groups.hosts` {#inventory.groups.hosts}

list of strings

Member host names. The group all cannot have hosts. A group can be empty: hosts: \[\].

### `inventory.groups.vars` {#inventory.groups.vars}

map

Variable values of the members. Two groups of one host that set different values for one variable are an error, unless the host sets that value too.

## Example

```
# inventories/production.yaml
hosts:
  mail.acme.com:
    address: 192.0.2.10
  monitor.acme.com:
    address: 192.0.2.20
groups:
  all:
    user: admin
    vars:
      domain: acme.com
  mail:
    hosts: [mail.acme.com]
    vars:
      mail_server: true

# winch.yaml
name: acme
vars:
  domain: example.com
  mail_server: false
steps:
  - name: Install postfix on the mail servers
    pkg:
      name: postfix
    when: !expr vars.mail_server
```