Functions and Arguments

Salt is structured as a very simple and pluggable core with many features able to interact between them. A very important functionlity is represented by the execution modules. They are the main entry point into the Salt world. The execution modules are Python modules, and are very easy to read (and eventually write) by anyone with basic Python programming knowledge. Everything is linear, which makes them flexible and easy to understand; in general, they consist only of simple functions.

In Example 3-1 we executed test.ping: test is the name of the execution module, while ping is the execution function inside this module.

This function only returns the logical value True when the minion is up. test.ping is an excellent way to test that the minion has been configured correctly and its key is accepted by the master. It doesn’t mean, however, that the connection to the network device succeeded. For this particular usage we can execute the net.connected module. Repeating the exercise: the Python function connected is defined under the Salt execution module net. While the test execution module corresponds to a Python module called test.py, net corresponds to napalm_network.py. This is because some modules have a virtual name associated and they are loaded under a cross-platform consistent name.

An execution function must return JSON-serializable data structures. Thanks to this approach the output can be manipulated, ported, and reused in different modules, displayed in the shape we require or transform it and load in a certain service. A good example is on the CLI: the output is transformed into a more human-readable and colorful format. There are many possibilities to adjust the output and this can be pluggable: you even have the option of customizing the way the output is processed and presented.

In Example 3-2, after test.ping was executed Salt provides the response from device1 as True.

$ sudo salt device1 test.ping
device1:
    True

Another useful function is grains.items, which provides the complete list of grains, and grains.get, which returns the value of a given grain identified by name, as shown in Example 3-3.

$ sudo salt device1 grains.get serial
device1:
    VM58737E84CF

In a similar way, pillar.items provides the pillar data available on the minion, while pillar.get returns a specific value (see Example 3-4).

$ sudo salt device1 pillar.get ntp.servers
device1:
    - 172.17.17.1
    - 172.17.17.2

Here, the pillar key ntp.servers has the value of a list of NTP servers. This also introduces the arguments to Example 3-4. ntp.servers is an argument passed to the get execution function from the pillar execution module.

To check what modules are loaded, identified by their virtual name, we can run sys.list_modules. Similarly, to display the complete list of available functions we can run sys.list_functions.

For network automation needs there are many execution functions natively embedded in Salt. For example, net.arp retrieves the ARP tables (see Example 3-5).

$ sudo salt device1 net.arp
device1:
    ----------
    out:
        |_
          ----------
          age:
              129.0
          interface:
              ae2.100
          ip:
              10.0.0.1
          mac:
              00:0f:53:36:e4:50
        |_
          ----------
          age:
              1101.0
          interface:
              xe-0/0/3.0
          ip:
              10.0.0.2
          mac:
              00:1d:70:83:40:c0

In Example 3-5 we executed the net.arp function, which retrieves the ARP table from device1. One can easily notice that the output is not a Python object, though. The reasoning is that although the arp execution function returned JSON-serializable data, Salt transformed it in a more human-readable and colorful format when displaying on the CLI. This format comes from an outputter module called nested. The user can choose to display the data formatted by a different outputter if they prefer.

The output is a list of ARP entries, each having the following details: age, interface, ip, and mac. It is vendor-agnostic, thanks to NAPALM capabilities, so executing net.arp against a device running a different supported platform will return exactly the same structure!

Several other samples are provided in Examples 3-6 through 3-8.

$ sudo salt device3 net.arp interface=TenGigE0/0/0/0
# output omitted

Note that although net.arp does not require an argument in Example 3-5, it can be passed. However, in Example 3-6, we retrieve the ARP table from device3 but only on the interface TenGigE0/0/0/0.

$ sudo salt device2 ntp.stats 172.17.17.1
# output omitted

Example 3-7 returns the NTP synchronization statistics with the server 172.17.17.1 from device2. The ntp.stats execution function can be equally executed without an explicit argument, in that case it returns the synchronization details with all the NTP peers.

$ sudo salt device1 net.ping 8.8.8.8 vrf=CUSTOMER1
# output omitted

In Example 3-8 we execute a ping to 8.8.8.8 from the CUSTOMER1 VRF.

You can learn more about these functions in the documentation, but sometimes it’s easier to check it directly from the CLI by executing sys.doc followed by the function or module name (e.g., salt device1 sys.doc net.arp). To check which arguments are mandatory and which ones are the default values, you can run sys.argspec in a similar way (e.g., salt device1 sys.argspec net.arp).

Targeting Devices

Targeting is used on the CLI but also in scheduled actions or when reacting to events. It is used to select a group of minions that need to execute a function. Targeting is a task sent by the master in a payload to all minions and the minions decide independently if the target matched their characteristics. This is yet another optimization that makes Salt extremely scalable. In the next sections, we will be executing the test.ping function.

$ sudo salt device1 test.ping
# output omitted

$ sudo salt -L device1,device2 grains.get vendor
device2:
    Juniper
device1:
    Arista

$ sudo salt 'device*' grains.get model
device1:
    VMX
device2:
    vEOS
device3:
    ASR9001

$ sudo salt -E '(device|edge)d' test.ping
# output omitted

$ sudo salt -G 'os:junos' test.ping
# output omitted

$ sudo salt -C 'G@os:junos and G@version:15.1F7.3' test.ping
# output omitted

$ sudo salt -C 'G@vendor:cisco
and G@model:ASR*
and G@interfaces:TenGigE0/0/0/30' test.ping
# output omitted

$ sudo salt -I 'proxy:host:*as1234.net' test.ping
# output omitted

$ sudo salt -C 'device* and G@os:iosxr and G@version:6.*' test.ping
# output omitted

$ sudo salt -C '
P@model:(MX960|MX480)
and J@proxy:host:^(.*bbone.asd+.net)$ ' test.ping
# output omitted

nodegroups:
  bbone-mxs: |
    P@model:(MX960|MX480)
    and J@proxy:host:^(.*bbone.asd+.net)$
  iosxr6: |
    device*
    and G@os:iosxr and G@version:6.*

$ salt -N bbone-mxs test.ping
# output omitted
$ salt -N iosxr6 test.ping
# output omitted

base:
  'device* and G@os:iosxr and G@version:6.*':
    - pillar_for_iosxr6
  'N@bbone-mxs':
    - mx_routers_bbone

Options

The salt command has a very long list of options, which you can retrieve by executing salt --help. In “Targeting Devices” we have listing some of the most usual, the target options. We highly encourage you to explore the full list of options, as they prove very handy in many situations. Due to size limitations in this book, we will present only a few of the most common.

$ sudo salt --out=json device1 net.arp
[
  {
    "interface": "ae2.100",
    "ip": "10.0.0.1",
    "mac": "00:0f:53:36:e4:50",
    "age": 129.0
  },
  {
    "interface": "xe-0/0/3.0",
    "ip": "10.0.0.2",
    "mac": "00:1d:70:83:40:c0",
    "age": 1101.0
  }
]