Targeting Minions: Globs, Lists, Grains, Compound Matchers, Nodegroups and Batch

SaltStack 24 min min read Updated: Nov 17, 2026 Beginner
Targeting Minions: Globs, Lists, Grains, Compound Matchers, Nodegroups and Batch
Beginner Topic 3 of 3

Why Targeting Matters

A Salt command always has the form: salt 'WHO' WHAT ARGUMENTS. The target (WHO) decides which minions run the job. Good targeting is the safety belt of Salt: a wrong target on a destructive command is expensive.

bash salt 'web*' pkg.upgrade # WHO = web* WHAT = pkg.upgrade salt -G 'os:Ubuntu' test.ping # WHO = grain match

Match by Minion ID

bash salt '*' test.ping # all minions salt 'web1' test.ping # exact id salt 'web*' test.ping # glob: web1, web2, webserver9 salt 'web[1-3]' test.ping # character range salt 'web?' test.ping # one character salt '*.example.com' test.ping # by domain part of the id salt -E 'web(1|2|3)$' test.ping # regular expression (-E / --pcre) salt -L 'web1,db1,cache2' test.ping # explicit list (-L / --list)

Match by Grains

Grains are facts about the machine (see the Grains lesson). Matching on grains lets you target by OS, role, virtualisation, kernel and more.

bash salt -G 'os:Ubuntu' test.ping salt -G 'os_family:RedHat' pkg.upgrade salt -G 'kernel:Linux' cmd.run 'uname -r' salt -G 'osmajorrelease:9' test.ping salt -G 'roles:webserver' test.ping # a custom grain you set yourself salt -P 'os:(RedHat|CentOS|Rocky)' test.ping # grain with a regex (-P) salt -G 'ip4_interfaces:eth0:*' test.ping # nested grain keys with colons

Match by Pillar, Network and Others

bash salt -I 'env:production' test.ping # pillar value (-I) salt -J 'role:web.*' test.ping # pillar with regex (-J) salt -S '192.168.56.0/24' test.ping # IP or subnet (-S / --ipcidr) salt -N webservers test.ping # nodegroup (-N) salt -R ... # range matcher (needs range server) salt -T ... # data from a cache of minion info
FlagMatcherExample
(none)Glob on idsalt 'web*' ...
-ERegex on idsalt -E 'web[0-9]+' ...
-LList of idssalt -L 'a,b' ...
-GGrainsalt -G 'os:Ubuntu' ...
-PGrain regexsalt -P 'os:(Ubuntu|Debian)' ...
-IPillarsalt -I 'env:prod' ...
-JPillar regexsalt -J 'env:pr.*' ...
-SSubnet or IPsalt -S '10.0.0.0/8' ...
-NNodegroupsalt -N db ...
-CCompound (mix of the above)salt -C 'G@os:Ubuntu and web*' ...

Compound Matchers: Combine Conditions

With -C you combine matchers with and, or, not, and parentheses. Each part has a letter prefix.

PrefixMatches
(none)Glob on minion id
G@Grain
P@Grain regex
I@Pillar
J@Pillar regex
E@Regex on id
L@List of ids
S@Subnet/IP
N@Nodegroup
bash salt -C 'G@os:Ubuntu and web*' test.ping salt -C 'G@kernel:Linux and not G@virtual:physical' test.ping salt -C '( web* or app* ) and G@os_family:RedHat' pkg.upgrade salt -C 'I@env:prod and G@roles:web and not L@web9' cmd.run 'systemctl is-active nginx' salt -C 'E@^db[0-9]+$ and not N@legacy' test.ping

Nodegroups: Name a Set of Minions

yaml # /etc/salt/master.d/nodegroups.conf nodegroups: webservers: 'G@roles:web and not G@virtual:physical' databases: 'L@db1,db2,db3' prod: 'I@env:prod' linux: 'G@kernel:Linux'
bash sudo systemctl restart salt-master salt -N webservers test.ping salt -N prod state.apply nginx test=True

Nodegroups give meaningful names to groups, so your team types -N webservers instead of a long compound expression. Keep them in Git.

Batch: Run on a Few Machines at a Time

With --batch-size (or -b) Salt runs the job on a limited number of minions at once and waits before the next group. This is the simplest way to do a rolling restart or update.

bash salt 'web*' --batch-size 2 service.restart nginx # 2 at a time salt 'web*' -b 25% service.restart nginx # 25% of the matched minions at a time salt 'web*' -b 1 --batch-wait 30 state.apply nginx # one at a time, wait 30 seconds between each

Dry Runs and Safety Checks

bash salt 'web*' test.ping # first: does my target match what I think? salt-run manage.up # which minions are connected salt-run manage.down # which are not salt 'web*' --preview-target # shows which minions match without running (3000 and newer) salt -C 'G@os:Ubuntu and web*' --preview-target salt 'web*' state.apply nginx test=True # dry-run a state: shows changes only
Always preview first: Before a risky command, run --preview-target (or a harmless test.ping) with the same target and check the list of machines.

Other Useful Options

OptionMeaning
-t 30, --timeout=30Seconds to wait for returns (default 5)
--out=json, --out=yaml, --out=tableOutput format
--staticPrint all results together after everyone returns
-v, --verboseShow the job id and targeted minions
--asyncStart the job and return the job id immediately
--subset=NRun on any N of the matched minions
--no-color, --hide-timeoutCleaner output for scripts

Targeting in Top Files

The same matchers work in top.sls (states) and the pillar top file. Without -C, add match: grain or match: compound.

yaml # /srv/salt/top.sls base: '*': - common 'web*': - nginx 'G@os_family:RedHat and G@roles:db': - match: compound - postgresql 'os:Ubuntu': - match: grain - ubuntu_tweaks

Practice Tasks

  1. Set a custom grain roles: web on two minions, then target them with -G
  2. Create a nodegroup called webservers and use -N webservers test.ping
  3. Write a compound target that selects all RedHat family minions that are not named db*
  4. Run service.restart with --batch-size 1 --batch-wait 10 on three minions
  5. Use --preview-target to check a target before running a package upgrade

Conclusion

Targeting decides who runs a job. Use globs for ids, -G and -I for grains and pillar, -C for combinations and nodegroups for names. Preview targets and run risky jobs in batches.

Quick Summary: -G grain, -I pillar, -L list, -E regex, -C compound with and/or/not; nodegroups; --batch-size; --preview-target.

Get Newsletter

Subscibe to our newsletter and we will notify you about the newest updates on Edugators