The top file & highstate

Mapping states to minions.

Intermediate12 min · lesson 4 of 12

Individual states are useful, but the real model is the highstate: the complete desired state of a minion, assembled from a top file that maps which states apply to which minions. top.sls lives in the state tree and uses targeting (globs, grains) to assign state files to groups of minions. Run state.highstate and each minion applies everything the top file says it should be.

HIGHSTATE ASSEMBLY

1top.sls

maps states to minions via targeting

2state.highstate

run against a targeted minion

3Compile complete state

assemble every assigned state

4Apply & converge

enforce all, report changes

Editing top.sls changes what minions become on their next highstate, fleet-wide — preview the blast radius with test=True.

top.sls

base:
  '*':
    - base            # every minion gets the base state
  'web*':
    - nginx
    - app
  'G@os_family:Debian':
    - apt_config

Applying the highstate

state.highstate compiles each targeted minion’s complete state from the top file and applies it — the equivalent of a Puppet catalog run or an Ansible playbook covering the whole node. This is what you run routinely (often on a schedule) to keep minions converged. Environments (base, prod, dev) in the top file let you promote changes through stages, and the same test=True dry run applies.

terminal

$ salt 'web1' state.highstate test=True   # preview the FULL desired state
$ salt 'web*' state.highstate             # converge the web tier to everything top.sls assigns
Summary for web1: Succeeded: 14 (changed=3)  Failed: 0

The top file assigns real power — review it like code

Editing top.sls changes what minions become on their next highstate, fleet-wide and automatically — adding a state to ‘*’ applies it everywhere. Keep the top file in reviewed version control, use test=True highstate to preview the blast radius of a change, and stage changes through environments before base/prod so a broad assignment does not converge everywhere unvetted.

States & the SLS formatPillar: secure per-minion data