Tuesday, 26 September 2017

SaltStack - Introduction to Remote Execution

In the last article, we configured Salt master and Salt minion. We also learned how to accept a minion key in order to instruct the master to trust a particular minion. In this article, we will go a step further and learn about remote execution commands in Salt.


In the last article, we came across a command in order to test the master-minion connectivity, which is given as below:

$ salt 'salt_minion1' test.ping

This executes ping function from test module on the minion with ID salt_minion1 from the Salt master. This command is an example of Salt remote execution. To know more about salt command, you can simply run -

$ salt --help | less

This tells us that the basic Salt remote execution command consists of five parts and it's syntax is as below :

Usage: salt [options] '<target>' <function> [arguments]

Consider below example to know about it's usage in further details -

salt --verbose 'salt_minion1' test.fib 5

Let's now see each part individually.


In the example given above, we can categorize various pieces used in salt command as per the syntax as :

  • salt : The Salt remote execution command
  • options (--verbose) : Command line options
  • target (salt_minion1) : Target string
  • function (test.fib) : The salt module function
  • arguments (5) : Arguments to the remote execution function

1. Options

With different output options available, we can display the output returned by salt in various format. The values those can be used for these options may be - nested (the default one), raw, json, yaml, etc. To check this, we introduce a new function here - cmd.run_all. It would return the command output in the form of dictionary that contains process ID or pid of the command, stdout and stderr contents and the return code retcode. Lets check this.

# Output in 'raw' format
$ salt --output=raw 'salt_minion1' cmd.run_all "echo Hello world"
{'salt_minion1': {'pid': 24495, 'retcode': 0, 'stderr': '', 'stdout': 'Hello world'}}

# Output in 'txt' format
$ salt --output=txt 'salt_minion1' cmd.run_all "echo Hello world"
salt_minion1: {'pid': 25668, 'retcode': 0, 'stderr': '', 'stdout': 'Hello world'}

# Output in 'json' format
$ salt --output=json 'salt_minion1' cmd.run_all "echo Hello world"
"salt_minion1": {
"pid": 24387,
"retcode": 0,
"stderr": "",
"stdout": "Hello world"

# Output in 'yaml' format
$ salt --output=yaml 'salt_minion1' cmd.run_all "echo Hello world"
pid: 25744
retcode: 0
stderr: ''
stdout: Hello world

We may use other options to change the behavior of Salt command, e.g. --timeout, --verbose, --summary.

2. Target strings

So far, we have executed the Salt command on a single minion with minion ID salt_minion1. However, with Salt, we can manage hundreds or thousands of minion using a single master, that too without writing complex scripts or using a SSH loop. Sometimes, we may need to execute a command on a particular group of machines rather than all of them. In that case, we need to write an appropriate target string. Ho to do it, we will learn in the upcoming article.

3. Execution modules and functions

Earlier, we have learned that, the Salt remote execution commands are actually the Python functions which run on target hosts. When these functions are grouped together, they make execution module. We have came across a couple of execution modules before - test and cmd. When we executed test.ping, we asked Salt to execute ping function from test module. In short, all remote execution commands must be specified in module_name.function_name format.

You can list all the available execution modules with the use of list_modules function within sys module as below:

$ salt 'salt_minion1' sys.list_modules
- aliases
- alternatives
- apache
- cmd
- composer
- test
- timezone

All these execution modules are useful in performing variety of operations on the minion. We will learn some of the basic execution modules in upcoming articles.

4. Arguments

Argument is the extra piece of information that we provide to the execution command (hence, the functions), e.g. what user is to be added, which package needs to be installed, etc. In the below example, we have provided '4' as the argument to instruct the test.fib function to display 4th element in Fibonacci sequence.

$ salt 'salt_minion1' test.fib 4
- 3
- 6.91413879395e-06

That's all for the introductory part of remote execution in Salt. I hope we will learn a lot and in much depth, as we go further in this series of articles. Thanks.


Post a Comment