Salt Cookbook

Let's see how we can install the Salt master on various types of OS.

The salt-master is the package for the Salt master service and it also requires a few other dependencies, such as the ZeroMQ library, msgpack, jinja, yaml, and so on, which is automatically pulled along with the package from the configured repositories.

Most of the Salt configuration parameters are set by default and need not be explicitly mentioned in the file. The options can be found commented in the file and act as the defaults. However, if they need to be changed, then they can be uncommented and necessary changes can be made.

We have explicitly uncommented the autosign_file parameter and set the value as /etc/salt/autosign.conf:

autosign_file: /etc/salt/autosign.conf

We then populated the file with a wildcard entry, that is, *, to allow all minions' certificate requests to be automatically signed and accepted by the master.

Finally, the service daemons for salt master are started/restarted, configured to start automatically at boot time, and firewalls are configured to open the ports 4505 and 4506 for communication with the minions using the system-specific commands.

In the primary configuration /etc/salt/master file, we will configure the section called file_roots. Under this parameter option, we will name each environment we want to configure and the path of the directory that will contain the configuration files for that environment.

Environments in Salt are designed to keep the configuration files for each environment isolated into respective containers for different stages of deployment such as development, QA, staging, and production. Ideally, the configurations can be written in either of the environments such as staging, and after a proper test phases, they can be migrated to the production environment.

Here, we opted for the /opt/salt-cookbook path to be the base directory of all our configurations. Next, we have chosen four environments for our infrastructure, namely, base, staging, production, and development. The base environment is the default in Salt and the path /srv/salt is taken as the base directory for all configurations if not configured explicitly as we have done earlier.

We then created the directory paths we want to use as the environment paths and mentioned them under the file_roots parameter, specifying the environment name and the path that points the configuration files for that environment:

file_roots:
  <environment_name>:
    - <environment_directory_path>

Pillars are one of the best features of Salt, which enable us to isolate data that needs to be kept secure such as keys and passwords. Next, we have chosen the /opt/salt-cookbook/pillar path to be our base directory for all pillar data and created directories for each environment that will contain pillar data, which is usable in that environment only.

We then edited the Salt master configuration file to include the environment names and their paths under the pillar_roots section for Salt to identify them as the pillar configuration paths:

pillar_roots:
  <environment_name>:
    - <pillar_directory_path>

Finally, we restarted the Salt master daemon for the changes to take effect.

It is also to be noted that when executing the salt command, the environment has to be mentioned for the minion(s). This is generally done with the saltenv option on the command line. However, this parameter can also be specified in the minion configuration /etc/salt/minion file, as follows:

environment: production

If this parameter is not set, the base environment is taken as the default environment.

We will create pillar data for the development environment.

In Salt, a pillar is a feature used to store data such as keys and passwords or any other type of data such as repetitive directory paths or usernames that are then accessed from states. All minion-specific data to be seen only by the minion is stored in pillars and is visible to the minion for which the data is meant and configured. In this recipe, we created pillar data in the development environment for a user state, which we will configure in the next recipe.

First, we created a directory similar to the name of the state that we will configure in the pillar directory path of the development environment:

[root@salt-master ~]# mkdir \
/opt/salt-cookbook/pillar/development/user

Next, we created a file called init.sls in the directory created earlier, where we will create the pillar data. The default file in a pillar directory is named init.sls, where .sls is the file extension for all Salt state, pillar, and top files. Salt manages the SLS files internally. If the user pillar is referenced, we must understand that it's the content of the init.sls file in the user directory that is being referred to. The contents of all SLS files in Salt are in the YAML format, and indentations are very important both for parsing by Salt and to keep the configurations organized.

In the init.sls file, we populated the pillar data that we need. Basically, we configured the first user of a user list of developers mentioning various parameters for the user, such as their username, user ID, password in hash format (note that it is enclosed in quotes to avoid problems with special characters), and the comment:

dev_user:
  name: thomas
  password: "$1$PG1inys0$kB2I83KzEVzVs9G7xLHjA1"
  uid: 1001
  comment: "Thomas"

If we are planning to add multiple users, the format can be as shown here:

dev_user:
  thomas:
    password: "$1$PG1inys0$kB2I83KzEVzVs9G7xLHjA1"
    uid: 1001
    comment: "Thomas"

The methods to parse this kind of YAML definition will be discussed later in the book.

Next, we created a file called top.sls in the base pillar directory of the development environment. The contents of the top.sls file determine which nodes or minions will have access to which pillar data. We created the following contents in the file:

development:
  '*':
    - user

The first line mentions the environment. Without this line, the base environment will be used as the default. The * operator in the second line is a wildcard, which means that all minions will have access to the user pillar data. This line can be manipulated to add various types of matchers to target minions that will be discussed later in the book. The third line mentions the name of the pillar directory that we created. If only the name of the directory is mentioned, we have to understand that the contents of the init.sls files are being referred to. If we create a file called devs.sls in the user directory, then the contents of that file can be mentioned in the top.sls file as user.devs, shown as follows:

development:
  '*':
    - user.devs

When the states are run on the minions, this file is checked and these definitions determine if that particular minion is allowed to access the contents of this pillar.

In Salt, states are written to determine which and what kind of resources will be added to a system. States are written with the help of built-in state modules, a full list of which can be found at http://docs.saltstack.com/en/latest/ref/states/all/. Using these state modules, we can configure a massive amount of system resources, a few being users, groups, files, repositories, packages, services, code repositories, and so on. These states are then configured to be available to desired nodes or minions based on various properties.

In this recipe, we configured a user to be added to a system in the development environment, irrespective of the operating system.

First, we created a directory with the name of the state, that is, the user in the base directory of the development environment. Then, we created a file named init.sls, which is the default file in a state directory. Salt State File or SLS is used as the only file type of all Salt configuration files.

In the first line, we defined a custom name of this resource that can be any name, we named it generic_user. This name can be used in subsequent resources, when referencing this resource and have to be unique in the complete state space being used by the minion. However, this is optional as the definition could also be written as follows:

{{ pillar['dev_user']['name'] }}:
  user.present:
    - shell: /bin/bash
    - home: /home/{{ pillar['dev_user']['name'] }}

Here, we also learn about how to refer to pillar data when writing states. It is usually in the following format:

{{ pillar[<first_key>][<second_key>]... }}

However, do note that, in the reference, the directory name of the pillar, that is, user is never used. Instead, the reference begins from the first YAML key found in the file, that is, dev_user, followed by the next mentioned key. Also, note that the first keys are always unique in the environment for a minion, that is, dev_user can only be used once as the first key. If a second file is created, called devs.sls, and the first key is named dev_user, there will be a conflict of key names and Salt synchronization will fail.

The following method can also be used to achieve the same objective:

{{ pillar['pillar.get']('dev_user:name', 'defaultuser') }}:

This is a better method as it also gives us the option to mention a default value if the pillar is not available.

The second line mentions the built-in state module name, that is, user and the function is present. There can be multiple functions for a module name and this can be looked up in the URL mentioned earlier in this recipe. For the user module, the two functions available are present and absent, which in turn take multiple parameters such as name, uid, gid, password, and so on.

Next, we see how each of the function parameters are populated for the user using static data, as well as pillar data:

- name: {{ pillar['dev_user']['name'] }}
- shell: /bin/bash
- home: /home/{{ pillar['dev_user']['name'] }}
- uid: {{ pillar['dev_user']['uid'] }}

The state configured in the previous recipe will now be applied to minions in the development environment.

The top.sls file in Salt determines which state will be applied to which minions. It has an extension of .sls similar to all other files in Salt. It is written in the YAML format and takes minion matchers in the form of wildcards, nodegroups, lists, grains, and so on. We will look at all of the ways to match minions throughout the book when we go through each of these components.

First, we created the top.sls file in the base directory of the development environment, that is, /opt/salt-cookbook/development, and then we populated it with the required definitions.

The first line indicates the environment we are configuring the top file for, that is, development. Without this, the base environment will be used as default. The next line indicates a wildcard * meaning that it will match all minions and apply the listed state to all of them. Then, we listed the user state that we already configured:

development:
  '*':
    - user

We can also match minions when applying states in the top.sls file in the following manner:

development:
  '*':
    - user
  'salt-minion':
    - match: list
    - hostconfig

Here, we see a second block of node definition and state that introduces a new key called match. Instead of the wildcard in the preceding block, this block has the name of a minion node called salt-minion, which is the hostname of the minion node that will synchronize with the master and the second line in the block:

- match: list

This line indicates that the type of minion parameter to match is a list, which is nothing but the hostname of the minion. The line that has the name of the minion can be a comma-separated line of multiple hostnames:

'webserver,dbserver,appserver,proxyserver'

The list matcher will match the line as a list of minion names. Then, we mentioned a state called hostconfig, which is also the name of a state not configured in the book so far. This example means that the hostconfig state will be applied to all the minions in the list, which in this case is the minion named salt-minion.

In Salt, minions can be matched in more ways than shown in this recipe, such as nodegroups, grains, IP/subnets, and so on. We will learn how to apply them in Chapter 3, Modules, Orchestration, and Scaling Salt.

We will install the Salt minion on a second node and name the node salt-minion. First, we will install the salt-minion package.

In Salt, the client nodes on which the configured states are applied are known as minions. The minion configuration file is /etc/salt/minion, which contains the configurable parameters for the minion, and most of the parameters use the default values as mentioned in the file and are commented. Any change in the parameters can be made by uncommenting and editing the parameters.

In this recipe, we configured the repositories from which to fetch the salt-minion package. We then installed the package and the dependencies get automatically fetched from the repositories.

Next, we edited the /etc/salt/minion file, uncommented the master parameter, and edited it to have the value salt-master (as we named our salt master salt-master in the earlier recipes). Do note that, for this parameter to work on the minions, there needs to be a DNS entry or an entry in /etc/hosts of the minions for the salt-master pointing to the IP of the Salt master. This parameter enables the minion to communicate with the Salt master on the TCP ports 4505 and 4506, as we configured in the first recipe of this chapter.

The rest of the parameters can be left as defaults. Finally, we started the salt-master daemon and configured it to start automatically at boot time.

There is one more parameter in the /etc/salt/minion file, which may be interesting for some. The id parameter enables us to set the minion ID explicitly, without which the hostname of the minion is taken up as the minion ID by default. The minion ID is the name that the Salt master is able to see when the minion requests its certificate to be signed and authenticated by the master. After the certificate signing is complete, the master knows the minion by the same minion ID and any communication which involves the minion name from the master to the minion happens using this minion ID.

For example, the minion node can have a hostname prodapp01, but we can set its minion ID in the /etc/salt/minion file, as follows:

id: appserver

This parameter will make this node known to the Salt master as appserver and not prodapp01, although the hostname is prodapp01. Without this parameter, the master will know this node as prodapp01.

file_client:  local

file_roots:
  base:
    - /opt/salt-cookbook/base
  development:
    - /opt/salt-cookbook/development

pillar_roots:
  base:
    - /opt/salt-cookbook/pillar/base
  development:
    - /opt/salt-cookbook/pillar/development

Uncomment and edit the /etc/salt/minion file to set the environment parameter:

environment: development

grains:
  environment: development
  location: datacenter1
  server_type: webserver

environment: development
location: datacenter1
server_type: webserver

The environment parameter in a Salt minion determines which environment the minion belongs to. This parameter helps Salt to determine which directory path it should look for on the master to fetch the correct configuration for the minion as per the environment specified.

As we specified in this recipe:

environment: development

When the minion calls and requests the master for its configuration, it looks for the development environment configured on the master and, if it finds one, it then looks for its base path, which in our case is /opt/salt-cookbook/development. It then looks for the relevant files in this directory.

However, do note that this environment parameter is useful when the minion calls the master, that is, the pull mechanism takes place. When the master pushes the configurations to minions, we can specify the environment while doing so but it only tells the master which directory path it should serve the files from. However, it does not tell the master which minions to target. To target minions from the development environment when pushing configurations from the master, we have to use grains, which we will discuss next.

In Salt, grains are information about system properties that helps Salt to target minions and configure pillars and states based on these properties. Salt makes a lot of grains available to us by default, a few being os, cpu, memory, hostname, domain name, IP addresses, MAC addresses, and so on. However, this feature becomes more useful when we are able to configure custom grains to suit our needs such as location, server type, application name, database name, and so on.

Grains can be configured in a couple of ways. The first option is to configure grains in the minion configuration file, that is, /etc/salt/minion, and the second option is to do this in a different file called /etc/salt/grains. In both cases, grains are configured as YAML key-value pairs.

grains:
  environment: development
  location: datacenter1
  server_type: webserver

environment: development
location: datacenter1
server_type: webserver

We will perform both the push and the pull mechanisms for applying states to minions.

[root@salt-master ~]# salt 'salt-minion' state.sls user \ saltenv=development
salt-minion:
----------
          ID: generic_user
    Function: user.present
        Name: thomas
      Result: True
     Comment: New user thomas created
     Changes:
              ----------
              fullname:

              gid:
                  1001
              groups:
                  - thomas
              home:
                  /home/thomas
              homephone:

              name:
                  thomas
              passwd:
                  x
              password:
                  $1$PG1inys0$kB2I83KzEVzVs9G7xLHjA1
              roomnumber:

              shell:
                  /bin/bash
              uid:
                  1001
              workphone:


Summary
------------
Succeeded: 1
Failed:    0
------------
Total:     1

[root@salt-master ~]# salt 'salt-minion' state.highstate \ saltenv=development

[root@salt-master]# salt 'salt-minion' state.highstate \ saltenv=development --state-output=terse
salt-minion:
  Name: thomas - Function: user.present - Result: Changed

Summary
------------
Succeeded: 1
Failed:    0
------------
Total:     1

root@salt-minion:~# salt-call state.highstate
[INFO    ] Loading fresh modules for state activity
[INFO    ] Fetching file from saltenv 'development', ** skipped ** latest already in cache 'salt://top.sls'
[INFO    ] Creating module dir '/var/cache/salt/minion/extmods/modules'
[INFO    ] Syncing modules for environment 'development'
[INFO    ] Loading cache from salt://_modules, for development)
[INFO    ] Caching directory '_modules/' for environment 'development'
[INFO    ] Creating module dir '/var/cache/salt/minion/extmods/states'
[INFO    ] Syncing states for environment 'development'
[INFO    ] Loading cache from salt://_states, for development)
[INFO    ] Caching directory '_states/' for environment 'development'
[INFO    ] Creating module dir '/var/cache/salt/minion/extmods/grains'
[INFO    ] Syncing grains for environment 'development'
[INFO    ] Loading cache from salt://_grains, for development)
[INFO    ] Caching directory '_grains/' for environment 'development'
[INFO    ] Creating module dir '/var/cache/salt/minion/extmods/renderers'
[INFO    ] Syncing renderers for environment 'development'
[INFO    ] Loading cache from salt://_renderers, for development)
[INFO    ] Caching directory '_renderers/' for environment 'development'
[INFO    ] Creating module dir '/var/cache/salt/minion/extmods/returners'
[INFO    ] Syncing returners for environment 'development'
[INFO    ] Loading cache from salt://_returners, for development)
[INFO    ] Caching directory '_returners/' for environment 'development'
[INFO    ] Creating module dir '/var/cache/salt/minion/extmods/outputters'
[INFO    ] Syncing outputters for environment 'development'
[INFO    ] Loading cache from salt://_outputters, for development)
[INFO    ] Caching directory '_outputters/' for environment 'development'
[INFO    ] Loading fresh modules for state activity
[INFO    ] Fetching file from saltenv 'development', ** skipped ** latest already in cache 'salt://user/init.sls'
[INFO    ] Running state [thomas] at time 19:04:47.080222
[INFO    ] Executing state user.present for thomas
[INFO    ] Executing command 'useradd -s /bin/bash -u 1001 -m -d /home/thomas thomas' in directory '/root'
[INFO    ] {'shell': '/bin/bash', 'workphone': '', 'uid': 1001, 'passwd': 'x', 'roomnumber': '', 'groups': ['thomas'], 'home': '/home/thomas', 'password': '$1$PG1inys0$kB2I83KzEVzVs9G7xLHjA1', 'name': 'thomas', 'gid': 1001, 'fullname': '', 'homephone': ''}
[INFO    ] Completed state [thomas] at time 19:04:47.209616
local:
----------
          ID: generic_user
    Function: user.present
        Name: thomas
      Result: True
     Comment: New user thomas created
     Changes:
              ----------
              fullname:

              gid:
                  1001
              groups:
                  - thomas
              home:
                  /home/thomas
              homephone:

              name:
                  thomas
              passwd:
                  x
              password:
                  $1$PG1inys0$kB2I83KzEVzVs9G7xLHjA1
              roomnumber:

              shell:
                  /bin/bash
              uid:
                  1001
              workphone:


Summary
------------
Succeeded: 1
Failed:    0
------------
Total:     1

root@salt-minion:~# salt-call state.sls user saltenv=development

In this recipe, we have seen how to apply Salt states to minions. Let's now look at the steps in details.

First, we tested if the certificate request for the minion had been accepted and signed by the master because we had configured it to accept all minions by defining the wildcard in the /etc/salt/autosign.conf file.

Next, we tested communication between the master and the minion with the salt binary and using what we call built-in execution modules in Salt. The test.ping module checks if the minion is available and is responding to the master and grains.items returns all the built-in and custom grains on the minion. Here, test.ping and grains.items are the execution modules and are just a couple of the numerous modules available in Salt.

Next, we look at how to actually apply the configured states to minions.

First, we see the push mechanism from the master to the minion:

[root@salt-master ~]# salt 'salt-minion' state.sls user \ saltenv=development

Here, we see the salt binary being used along with the name (minion id) of the minion, followed by another execution module state.sls, and then the name of the state that we had configured. Finally, the name of the environment is specified without which Salt will look for the base environment and fail. Any configured state can be used in this format to apply to minions, and this method is independent of the top.sls file that we configured in the base directory of the development environment.

Next, we see an alternate method to apply states to minions:

[root@salt-master ~]# salt 'salt-minion' state.highstate \ saltenv=development

Here we see the same command, without the state name and a new execution module called state.highstate. When state.highstate is mentioned, it applies all the states that have been configured for the minion in the top.sls file of that environment. Only the user state gets applied to the minion because that is the only state we have configured in top.sls so far.

The third command produces a slightly different output:

[root@salt-master]# salt 'salt-minion' state.highstate \ saltenv=development --state-output=terse

This command has a new option and its value is --state-output=terse. This option is specified if we do not want a detailed output as the first and second commands. However, it does the same task as the first and second commands

Next, we look at the method of doing the same task by fetching the states on the minion from the master by using the pull mechanism:

root@salt-minion:~# salt-call state.highstate

Here, we used the salt-call binary, which is available only on Salt minions along with the state.highstate execution module. This command will automatically take the environment from the minion configuration file, that is, /etc/salt/minion and look for the minion states in the development environment and apply all the states configured for this minion in the top.sls file. Note the output, we see the minion caching all required data in the system from the master before applying the states. This caching process will take place each time the data in the master changes and the salt-call command is run.

The other method (not used very often) to apply specific states to the minion and from the minion is shown next. These states can also be part of highstate, if added to the top file:

root@salt-minion:~# salt-call state.sls user saltenv=development

Here, we see the minion using the salt-call binary, but mentioning the state.sls execution module to specify a particular state instead of all the states, that is, the user state. However, do note that, for this to be successful, the Salt environment must be mentioned as shown, without which it will look for the base environment and fail.

Now let's see, how to apply Salt states on masterless minions.

root@salt-minion:~# salt-call --local state.highstate