Node groups

Nodegroups are declared using a compound target specification. The compound target documentation can be found here.

The nodegroups master config file parameter is used to define nodegroups. Here's an example nodegroup configuration within /etc/salt/master:

  group1: ',, or bl*'
  group2: 'G@os:Debian and'
  group3: 'G@os:Debian and N@group1'
    - 'G@foo:bar'
    - 'or'
    - 'G@foo:baz'


The L within group1 is matching a list of minions, while the G in group2 is matching specific grains. See the compound matchers documentation for more details.

New in version 2015.8.0.


Nodegroups can reference other nodegroups as seen in group3. Ensure that you do not have circular references. Circular references will be detected and cause partial expansion with a logged error message.

New in version 2015.8.0.

Compound nodegroups can be either string values or lists of string values. When the nodegroup is A string value will be tokenized by splitting on whitespace. This may be a problem if whitespace is necessary as part of a pattern. When a nodegroup is a list of strings then tokenization will happen for each list element as a whole.

To match a nodegroup on the CLI, use the -N command-line option:

salt -N group1


The N@ classifier cannot be used in compound matches within the CLI or top file, it is only recognized in the nodegroups master config file parameter.

To match a nodegroup in your top file, make sure to put - match: nodegroup on the line directly following the nodegroup name.

    - match: nodegroup
    - webserver


When adding or modifying nodegroups to a master configuration file, the master must be restarted for those changes to be fully recognized.

A limited amount of functionality, such as targeting with -N from the command-line may be available without a restart.

Defining Nodegroups as Lists of Minion IDs

A simple list of minion IDs would traditionally be defined like this:

  - group1: L@host1,host2,host3

They can now also be defined as a YAML list, like this:

  - group1:
    - host1
    - host2
    - host3

New in version 2016.11.0.

Using Nodegroups in SLS files

To use Nodegroups in Jinja logic for SLS files, the pillar_opts option in /etc/salt/master must be set to True. This will pass the master's configuration as Pillar data to each minion.


If the master's configuration contains any sensitive data, this will be passed to each minion. Do not enable this option if you have any configuration data that you do not want to get on your minions.

Also, if you make changes to your nodegroups, you might need to run salt '*' saltutil.refresh_pillar after restarting the master.

Once pillar_opts is set to True, you can find the nodegroups under the "master" pillar. To make sure that only the correct minions are targeted, you should use each matcher for the nodegroup definition. For example, to check if a minion is in the 'webserver' nodegroup:

  webserver: 'G@os:Debian and L@minion1,minion2'
{% if in salt['pillar.get']('master:nodegroups:webserver', [])
and grains.os in salt['pillar.get']('master:nodegroups:webserver', []) %}
{% endif %}


If you do not include all of the matchers used to define a nodegroup, Salt might incorrectly target minions that meet some of the nodegroup requirements, but not all of them.