Getting started using saltstack

manager Wed, 02/10/2016 - 11:27

On line saltstack manual

https://docs.saltstack.com/en/latest/topics/tutorials/index.html

Example install for Centos 7

# yum install https://repo.saltstack.com/py3/redhat/salt-py3-repo-latest.el7.noarch.rpm
# yum install salt-master
# yum install salt-minion
# yum install salt-ssh salt-syndic salt-cloud salt-api

Edit config files # vim /etc/salt/master

   - #interface: 0.0.0.0
   + interface: 10.0.0.1

# vim /etc/salt/minion

  - #master: salt
  + master: 10.0.0.1

Start processes in the background as demons

# salt-master -d
# salt-minion -d

Useful commands

$ sudo salt \* sys.list_modules

$ sudo salt \* sys.list_functions

$ sudo salt \* sys.doc

Only on Redhat servers list all status

$ sudo salt -G 'os_family:redhat' status.all_status

Change to yaml output only on Redhat servers show all memory info

$ sudo salt --output=yaml -G 'os_family:r*' status.meminfo

Examples

$ sudo salt \* --output=yaml grains.item os
orasos:
  os: Fedora

US-JSly1:
  os: Windows

$ sudo salt \* --output=yaml grains.item os_family
orasos:
  os_family: RedHat

US-JSly1:
  os_family: Windows

$ sudo salt --output=yaml -G 'os_family:redhat' grains.item mem_total
orasos:
  mem_total: 2997

$ sudo salt \* --output=yaml grains.items
returns a big list of all the grains on the systems

The cmd module contains functions to shell out on minions, such as cmd.run and cmd.run_all:

$ sudo salt '*' cmd.run 'ls -l /etc'

The pkg functions automatically map local system package managers to the same salt functions.  This means that pkg.install will install packages via yum on Red Hat based systems, apt on Debian systems, etc.:

$ sudo salt '*' pkg.install vim

 

The network.interfaces function will list all interfaces on a minion, along with their IP addresses, netmasks, MAC addresses, etc:

$ sudo salt '*' network.interfaces

To see all the functions in sys

$ sudo salt '*' sys.list_functions

To see all the functions in sys for ssh

$ sudo salt '*' sys.list_functions ssh

To find out more information about a function, including
examples of how to use it, we can use the sys.doc function, as follows:

# sudo salt '*' sys.doc test.fib

Docs for a function are returned along with the error by default.

Controlling Your Minions with Remote Execution

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

  • Targeting options are used to target minions. We'll learn more about targeting minions later in the chapter.
  • Output options are also very useful. The information that minions return after a command is formed as basic data structures. This means that we can display it in different formats.

For prettier output that still shows the data structures clearly, use the json outputter,
as shown in the following code:

# sudo salt --out=json '*' cmd.run_all 'echo HELLO'
  {
    "myminion": {
    "pid": 14506,
    "retcode": 0,
    "stderr": "",
    "stdout": "HELLO"
    }
  }

You can also output it as YAML or just silence the output altogether using yaml or quiet , as we do in the following code:

# sudo salt --out=yaml '*' cmd.run_all 'echo HELLO'
myminion:
  pid: 14585
  retcode: 0
  stderr: ''
  stdout: HELLO
# sudo salt --out=quiet '*' cmd.run_all 'echo HELLO'

Installing packages

Package installation and management are another important aspect of system administration. For this purpose, Salt provides the pkg module. We can use pkg.install to install packages, as follows:

# sudo salt '*' sys.doc pkg.install

# sudo salt '*' pkg.install htop
myminion:
----------
htop:
----------
new:
1.0.2-3
old:

We can also remove packages with pkg.remove :

# sudo salt '*' pkg.remove htop
myminion:
----------
htop:
----------
new:
old:
1.0.2-3
# sudo salt '*' pkg.version htop

Managing services

# sudo salt '*' service.status apache2
myminion:
  True
# sudo salt '*' service.stop apache2
myminion:
  True
# sudo salt '*' service.status apache2
myminion:
  False
# sudo salt '*' service.start apache2
myminion:
  True

 

SALT STATES

Now that the basics are covered the time has come to evaluate States. Salt States, or the State System is the component of Salt made for configuration management.

The state system is already available with a basic Salt setup, no additional configuration is required. States can be set up immediately.

Note:

Before diving into the state system, a brief overview of how states are constructed will make many of the concepts clearer. Salt states are based on data modeling and build on a low level data structure that is used to execute each state function. Then more logical layers are built on top of each other.

The high layers of the state system which this tutorial will cover consists of everything that needs to be known to use states, the two high layers covered here are the sls layer and the highest layer highstate.

Understanding the layers of data management in the State System will help with understanding states, but they never need to be used. Just as understanding how a compiler functions assists when learning a programming language, understanding what is going on under the hood of a configuration management system will also prove to be a valuable asset.

THE FIRST SLS FORMULA

The state system is built on SLS (SaLt State) formulas. These formulas are built out in files on Salt's file server. To make a very basic SLS formula open up a file under /srv/salt named vim.sls. The following state ensures that vim is installed on a system to which that state has been applied.

/srv/salt/vim.sls:

vim:
  pkg.installed

Now install vim on the minions by calling the SLS directly:

salt '*' state.apply vim

This command will invoke the state system and run the vim SLS.

ADDING SOME DEPTH

Obviously maintaining SLS formulas right in a single directory at the root of the file server will not scale out to reasonably sized deployments. This is why more depth is required. Start by making an nginx formula a better way, make an nginx subdirectory and add an init.sls file:

/srv/salt/nginx/init.sls:

nginx:
  pkg.installed: []
  service.running:
    - require:
      - pkg: nginx

A few concepts are introduced in this SLS formula.

First is the service statement which ensures that the nginx service is running.

Of course, the nginx service can't be started unless the package is installed -- hence the require statement which sets up a dependency between the two.

The require statement makes sure that the required component is executed before and that it results in success.

Note

The require option belongs to a family of options called requisites. Requisites are a powerful component of Salt States, for more information on how requisites work and what is available see: Requisites

Also evaluation ordering is available in Salt as well: Ordering States

This new sls formula has a special name -- init.sls. When an SLS formula is named init.sls it inherits the name of the directory path that contains it. This formula can be referenced via the following command:

salt '*' state.apply nginx

Note

state.apply is just another remote execution function, just like test.version or disk.usage. It simply takes the name of an SLS file as an argument.

GRAINS

Salt comes with an interface to derive information about the underlying system. This is called the grains interface, because it presents salt with grains of information. Grains are collected for the operating system, domain name, IP address, kernel, OS type, memory, and many other system properties.

The grains interface is made available to Salt modules and components so that the right salt minion commands are automatically available on the right systems.

Grain data is relatively static, though if system information changes (for example, if network settings are changed), or if a new value is assigned to a custom grain, grain data is refreshed.

Note

Grains resolve to lowercase letters. For example, FOO, and foo target the same grain.

LISTING GRAINS

Available grains can be listed by using the 'grains.ls' module:

salt '*' grains.ls

Grains data can be listed by using the 'grains.items' module:

salt '*' grains.items

USING GRAINS IN A STATE

To use a grain in a state you can access it via {{ grains['key'] }}.

GRAINS IN THE MINION CONFIG

Grains can also be statically assigned within the minion configuration file. Just add the option grains and pass options to it:

grains:
  roles:
    - webserver
    - memcache
  deployment: datacenter4
  cabinet: 13
  cab_u: 14-15

Then status data specific to your servers can be retrieved via Salt, or used inside of the State system for matching. It also makes it possible to target based on specific data about your deployment, as in the example above.

GRAINS IN /ETC/SALT/GRAINS

If you do not want to place your custom static grains in the minion config file, you can also put them in /etc/salt/grains on the minion. They are configured in the same way as in the above example, only without a top-level grains: key:

roles:
  - webserver
  - memcache
deployment: datacenter4
cabinet: 13
cab_u: 14-15

Note

Grains in /etc/salt/grains are ignored if you specify the same grains in the minion config.

Note

Grains are static, and since they are not often changed, they will need a grains refresh when they are updated. You can do this by calling: salt minion saltutil.refresh_modules