Configuration

The Pigsty-compatible Inventory fields Farrow reads, their defaults, and node-level drift behavior.

Discovery

Configuration lookup order is explicit -f, then farrow.yml, farrow.yaml, pigsty.yml, and pigsty.yaml in the current directory. Every name uses the same Pigsty-compatible YAML Inventory format.

The retired top-level version:/nodes: format is rejected with migration guidance.

For plan, up, reload, and recreate, absence of a file falls back to the applied spec when a deployment exists. validate has no fallback. A configuration must be a regular non-symlink file no larger than 4 MiB.

What Farrow reads

Farrow reads host IPs, nodename, admin_ip, pg_cluster, pg_seq, node_admin_username, node_admin_uid, and the documented vm_* variables. admin_ip is read from all.vars; it selects the control node, or the first managed host is used. All nodes must resolve the same login username. For the default dba user, an explicit node_admin_uid must be 88.

Everything else is opaque and cannot create drift. This means unconsumed fields such as pg_role, pg_version, repo_*, and node_packages, not all possible pg_* or node_* names.

Inside this namespace validation is strict: unknown vm_* names, wrong types, Jinja expressions, invalid addresses, and conflicting sibling-group values are errors.

VM variables

Variable	Default	Meaning
`vm_skip`	`false`	do not virtualize this real/external host
`vm_image`	`u24`	image alias
`vm_arch`	`native`	deployment-wide Guest architecture: `native`, `amd64`, or `arm64`
`vm_cpu`	`2`	vCPU count
`vm_mem`	`4096`	MiB integer, or a size such as `8GiB`
`vm_disk`	`64`	root disk GiB
`vm_disks`	`[{path: /data}]`	extra disks
`vm_alias`	`[]`	guest `/etc/hosts`, SSH-config, and optional host aliases
`vm_shares`	`[]`	QEMU 9p host-directory shares

An empty host entry is a complete VM. A deployment contains 1–20 managed hosts; vm_cpu accepts 1–256 and memory must be at least 512 MiB.

vm_arch is stricter than ordinary per-host VM fields: when present it must resolve to one value on every managed host, so define it once in all.vars. Changing it is a deployment-envelope change and requires whole-deployment recreation. Linux setup installs only the native emulator; a foreign architecture also needs its matching qemu-system-* binary and firmware.

Data disks

vm_disks:
  - path: /data
    size: 128
    fs: xfs
    persistent: false

path is the disk identity and mount point. fs is xfs or ext4. persistent: true survives normal destroy. Use vm_disks: [] for no extra disk.

vm_shares:
  - host: /absolute/owned/source
    guest: /src
    readonly: true

Shares must be real, caller-owned, non-overlapping directories. They are for trusted development files, not PostgreSQL data.

Names and addresses

Node name order: nodename, then <pg_cluster>-<pg_seq>, then node-<last-octet>. Names must be unique.

All managed hosts must be in one RFC1918 /24: .1 is the host, .2–.8 are reserved, and nodes use .9–.254.

Drift

Farrow hashes each resolved node. Added hosts are created by up; selected existing stopped nodes are started; running peers stay untouched. Changed VM definitions require per-node recreate; removed hosts are reported but never destroyed. Deployment architecture, user, or subnet changes require whole-deployment recreation. Changing a field used to derive a node name appears as a missing old node plus a new node, so prefer stable explicit nodename values.