Getting started with Saltstack part 2 (Minion selection & running salt commands)

This article explores selecting minion ids while running commands from the salt master, some command execution examples & also how we can modify the command output format to suit our needs.

Anatomy of a salt command:

salt <option> <target> <function> <arguments>

Salt command output formatting options:

We can use the cmd module to run an arbitrary unix command via a shell in case salt does not have a separate module suitable for our needs.

The following command will echo out the string hello on all minions controlled by our salt master.

 salt '*' cmd.run_all 'echo HELLO'

secondminion:
    ----------
    pid:
        14127
    retcode:
        0
    stderr:
    stdout:
        HELLO
firstminion:
    ----------
    pid:
        130049
    retcode:
        0
    stderr:
    stdout:
        HELLO

There are ways we can modify the output format. Here are some examples:

 salt --out=raw '*' cmd.run_all 'echo HELLO'
 salt --out=json '*' cmd.run_all 'echo HELLO'
 salt --out=yaml '*' cmd.run_all 'echo HELLO'

In case we don't want to see the output printed to screen, there is also a quiet options.

salt --out=quiet "*' cmd.run_all 'echo hello'


Executing commands on one or more minions:

We can execute a command on a single minion or more than one minions in one go. Salt allows doing glob/regex matches while typing out minion ids with the salt command.
So, it'll be a good standard to have a defined nomenclature for the minion ids like myminion1 myminion2.


Glob matching:

# salt 'my*' test.ping

# salt 'my*mini*' test.ping

# salt '??minion' test.ping

# salt '[a-m]yminion' test.ping


Regex matching:

Salt uses Python re library while doing regex matches for minion ids:

# salt -E 'myminion' test.ping

# sudo salt -E 'my' test.ping


List matching:

This is to execute the salt commands on a named list of minion ids. No pattern matching is involved here.

salt -L 'myminion,yourminion,theirminion' test.ping


Grain matching:

Grains store some attributes & values related to the minions in the form of key-value pairs.

salt '*' grains.item os_family

salt '*' grains.item os

To view all grain items for the minions, type:

salt '*' grains.items

So, while running our salt commands we can do a grain match for all minions running the cent0S OS.
To do this run the salt command with --grain or -G followed by the key-value pair you'd like to match on & specify the execution module function in the end.

salt --grain 'os_family:RedHat' test.ping


Create a grain key value pair:

salt '*' grains.setval foo bar


Delete a custom grain key value pair:

salt '*' grains.delval foo destructive=True


Minions store grain data in a file /etc/salt/grains


Compound matching:

This happens when we mix different types of minion id matching techniques in a single salt command.

salt -C '*minion and G@os:Ubuntu and not L@yourminion,theirminion' test.ping


To list available modules, type:

salt '*' sys.list_modules

To list available functions corresponding to a module type:

salt '*' sys.list_functions user

To view documentation on an execution function type:

salt '*' sys.doc user.add


Execution module usage modules:


Example 1: Add a user:

To create users on minions the salt master uses the user module.

[root@cserver ~]# salt 'secondminion' user.add test_user
secondminion:
    True

[root@cserver ~]# salt 'secondminion' user.info test_user

secondminion:

    ----------

    fullname:

    gid:

        1002

    groups:

        - test_user

    home:

        /home/test_user

    homephone:

    name:

        test_user

    passwd:

        x

    roomnumber:

    shell:

        /bin/bash

    uid:

        1002

    workphone:

You can get more information on the user module usage options by querying this via the sys module like sys.doc & sys.list_functions.

Example 2: Install a package

[root@cserver ~]# salt --verbose 'secondminion' pkg.install screen
Executing job with jid 20161112002227262556
-------------------------------------------

secondminion:
    ----------
[root@cserver ~]#
[root@cserver ~]# salt --verbose 'secondminion' pkg.info_installed screen
Executing job with jid 20161112002411144850
-------------------------------------------

secondminion:
    ----------
    screen:
        ----------
        arch:
            x86_64
        build_date:
            2016-02-16T12:07:17Z
        build_date_time_t:
            1455642437
        build_host:
            worker1.bsys.centos.org
        description:
            The screen utility allows you to have multiple logins on just one
            terminal. Screen is useful for users who telnet into a machine or are
            connected via a dumb terminal, but want to use more than just one
            login.

            Install the screen package if you need a screen manager that can
            support multiple logins on one terminal.

--------------------------------------------------------------------------------------------

Example 3: Examine an OS service

[root@cserver ~]# salt --verbose 'secondminion'  service.show sshd

Executing job with jid 20161112002624580891

-------------------------------------------

secondminion:

    ----------

    ActiveEnterTimestamp:

        Tue 2016-11-08 11:53:23 EST

    ActiveEnterTimestampMonotonic:

        68185435

    ActiveExitTimestampMonotonic:

        0

    ActiveState:

        active

    After:

        - syslog.target

        - network.target

        - auditd.service

        - systemd-journald.socket

        - basic.target

        - system.slice

------------------------------------------------------------------------

I shortened the outputs of the commands for brevity. The verbose output showed a lot of information. We can find nice documentation on use cases of different modules using the sys.doc module.