Targeting

Targeting devices is largely based on the Roster interface. This is the starting point, where salt-sproxy know what devices you want to manage. The Roster interface can be a Pillar file, an Ansible inventory file, a NetBox instance and so on. See Using the Roster Interface for more details, usage examples and documentation for each of the available Roster options.

To put it in other words, the Roster provides the totality (or the universe) of devices you have. When you’re executing a command, you may want to execute a command against all these devices, or only a subset of them. There are several targeting selection mechanisms, as presented below.

Targeting in salt-sproxy, from an user perspective, is very similar to the native Salt targeting - however, the implementation is fundamentally different (again, please see Using the Roster Interface for more details on this); that’s why the targeting in salt-sproxy comes with some caveats you should be aware of.

Tip

Before executing any command, it may be a good idea to check that your target matches the devices you want to run against, by using the --preview-target CLI option, e.g.,

salt-sproxy -G netbox:role:router --preview-target

See also

When targeting making use of Grains or Pillar data that depend on the device characteristics (such as interfaces, IP addresses, OS version, platform details, and so on), or other properties retrieved from other systems, such as APIs, databases, etc., salt-sproxy needs cached data which is obtained _only_ after the (first) execution is complete. To do so, you have a number of options: once salt-sproxy is installed and configured, you can run salt-sproxy '*' test.ping or similar to execute across all the devices and cache their data.

Alternatively, you may want to look at –invasive-targeting or –preload-targeting options. These two options would allow you to work around this caveat, however bear in mind they’ll eveluate - and eventually connect to - every device salt-sproxy is aware of, in order to determine which devices match your target.

Glob

Shell-style globbing on the device name / Minion ID.

See https://docs.saltstack.com/en/latest/topics/targeting/globbing.html#globbing

Examples:

• Match all the devices salt-sproxy knows about:

salt-sproxy '*' test.ping

• Match edge1 and edge3 devices:

salt-sproxy 'edge[1,3]' test.ping

PCRE

PCRE stands for Perl Compatible Regular Expression, so you can target against devices with the name matching the regular expression.

See also: https://docs.saltstack.com/en/latest/topics/targeting/globbing.html#regular-expressions

Example: match top of rack switches with the name ending in a digit:

salt-sproxy -E '.*-tor\d' napalm.junos_rpc get-route-summary-information table=mpls.0

List

A list of device names.

Example: execute a command on three devices edge1, edge2, and edge3:

salt-sproxy -L 'edge1,edge2,edge3' net.arp

Grain

Targeting using Grain data.

This is a tricky subject. Unlike the native Salt, salt-sproxy doesn’t have access to device data before connecting to it (i.e., it can’t possibly know device details before even connecting to it). You can however target using Grain data, but there are some caveats, and it’s up to you to decide whether you want performance or limit the resource consumption. Generally, Grain targeting won’t work at the first execution, as salt-sproxy needs cached data. An alternative would be using the --invasive-targeting or --preload-targeting options, but that has a price (see https://salt-sproxy.readthedocs.io/en/latest/opts.html#cmdoption-invasive-targeting for more details).

See also

See also: Managing Static Grains. Static Grains are always available, and can be anytime used in your targeting, without any restrictions.

An exception is the NetBox Roster module which provides an additional set of Grains you can use, under the netbox key. See the Enhanced Grain targeting section for more details.

Examples: match devices on their role:

salt-sproxy -G role:router test.ping

Grain PCRE

As the grain targeting, but instead of exact matching, can match on a regular expression on the Grain value.

Note

This targeting mechanism has the same caveats as the Grain.

Example: match the devices from multiple sites (e.g., lon1, lon2, etc.)

salt-sproxy -P site:lon\d test.ping

Pillar

Targeting using Pillar data.

Similarly to the Grain targeting, this is possible but with one caveats when you’re not running active Minions: salt-sproxy needs this data cached in order to evaluate the target and determine which devices match, however using the CLI (and configuration file) options --invasive-targeting or --preload-targeting, you can work around this limitation. Once you’ve executed once, the data will be cached, and you can use it for future targets.

Hint

If you want to target against statically defined Pillar, whenever possible, static Grains may be a better fit for your use case. Have a look at Managing Static Grains.

Example:

salt-sproxy -I proxy:user:salt --preview-target

Pillar PCRE

As the pillar targeting, but instead of exact matching, can match on a regular expression on the Pillar value.

Note

This targeting mechanism has the same caveats as the Pillar.

Hint

If you want to target against statically defined Pillar, whenever possible, static Grains may be a better fit for your use case. Have a look at Managing Static Grains.

Example: match the devices from multiple sites, based on the hostname pattern (e.g., lon1, lon2, etc.)

salt-sproxy -J proxy:host:.*lon\d --preview-target

Compound

You can mix all the matchers above. See https://docs.saltstack.com/en/latest/topics/targeting/compound.html for more details and notes.

Example: match edge routers 1 and 3 from multiple sites

salt-sproxy -C 'edge[1,3] and G@role:router and P@site:lon\d' net.lldp