salt/doc/topics/targeting/nodegroups.rst

Node groups

Nodegroups are declared using a compound target specification. The compound target documentation can be found here <targeting-compound>.

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

nodegroups:
  group1: 'L@foo.domain.com,bar.domain.com,baz.domain.com or bl*.domain.com'
  group2: 'G@os:Debian and foo.domain.com'
  group3: 'G@os:Debian and N@group1'
  group4:
    - 'G@foo:bar'
    - 'or'
    - 'G@foo:baz'

Note

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

As of the 2017.7.0 release of Salt, group names can also be prepended with a dash. This brings the usage in line with many other areas of Salt. For example:

nodegroups:
  - group1: 'L@foo.domain.com,bar.domain.com,baz.domain.com or bl*.domain.com'

2015.8.0

Note

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.

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 test.ping

2019.2.0

Note

The N@ classifier historically could not be used in compound matches within the CLI or top file, it was only recognized in the nodegroups master config file parameter. As of the 2019.2.0 release, this limitation no longer exists.

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

base:
  group1:
    - match: nodegroup
    - webserver

Note

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:

nodegroups:
  group1: L@host1,host2,host3

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

nodegroups:
  group1:
    - host1
    - host2
    - host3

2016.11.0