oam/knowledge base/salt.md

Salt

Table of contents

1. TL;DR
2. Key management
3. Execute commands on minions
4. Targeting
5. States
   1. Create states
   2. Apply states
6. The Top file
   1. Create the Top file
7. Formulas repo
8. Batch size
9. Terminology
10. Further readings

TL;DR

# View all minion connections with their status.
salt-key --list all

# Accept minions' keys.
salt-key --accept='key'
salt-key --accept-all

# Test minions for reachability.
salt '*' test.ping
salt -L 'minion-1,minion-2' test.ping
salt --batch-size 10 '*' test.ping

# Run a shell command.
salt '*' cmd.run 'ls -l /etc'
salt -G 'os:Ubuntu' cmd.run 'echo bye'

# Show disk usage.
salt '*' disk.usage
salt 'minion-1' disk.usage

# Install packages.
salt '*' pkg.install 'cowsay'
salt -E 'minion[0-9]' pkg.install 'parallel'

# List network interfaces.
salt '*' network.interfaces
salt -C 'G@os:Ubuntu and minion* or S@192.168.50.*' network.interfaces

Key management

Will use salt-key.
This needs to be done on the master host.

• View all minion connections and whether the connection is accepted, rejected, or pending:

  salt-key --list all
  

• Before a minion can connect, you must accept its key:

  salt-key --accept='key'
  salt-key --accept-all
  

Execute commands on minions

After you have accepted each key, you can send a command from your master host.

All managed systems simultaneously and immediately execute the command, then return the output to the master.

# Test minions for reachability.
salt '*' test.ping

# Run a shell command.
salt '*' cmd.run 'ls -l /etc'

# Show disk usage.
salt '*' disk.usage

# Install a package.
salt '*' pkg.install cowsay

# List network interfaces.
salt '*' network.interfaces

Targeting

Targeting is how one selects minions when running commands, applying configurations, and when doing almost anything else in Salt that involves a minion.

# Target specific minions.
salt 'minion1' disk.usage
salt -L 'minion1,minion2' test.ping

# Target a set of minions using globbing.
salt 'minion*' disk.usage

# Target a set of minions using the grains system.
salt -G 'os:Ubuntu' test.ping

# Target a set of minion using regular expressions.
salt -E 'minion[0-9]' test.ping

# Mix them all up.
salt -C 'G@os:Ubuntu and minion* or S@192.168.50.*' test.ping

States

Configuration management lets you create re-usable configuration templates, called states, that describe everything required to put a system component or application into a known configuration.
States are described using YAML, making them simpler to create and read.

Commands in state files are executed from top to bottom. The requisite system lets you explicitly determine the order.

Create states

Just create a YAML file like this:

install_network_packages:
  pkg.installed:
    - pkgs:
        - rsync
        - lftp
        - curl

and give it the .sls extension.

Apply states

Use the state.apply command to apply a state from the command line on the master host.

salt 'minion2' state.apply 'nettools'

It will return an output that will list the changes made by the state.

The functions are idempotent, so applying the state twice will return an output that says everything is already OK and no changes have been made.

The Top file

Top files apply multiple state files to minions. What states are applied to each system are determined by the targets that are specified in the Top file.

Create the Top file

Each system can receive multiple configurations.
Start with the most general configurations, and work your way down to the specifics.

Targets are used within the Top file to define which states are applied to which minion.
When the Top file is evaluated, minions execute all states that are defined for any target they match.

For example, if you apply a Top file like this one:

base:
  '*':
    - vim
    - scripts
    - users
  '*web*':
    - apache
    - python
    - django
  '*db*':
    - mysql

a system with a minion ID of atl-web4-prod would apply the vim, scripts, users, apache, python, and django states.

Now create the following top.sls file:

base:
  '*':
    - common
  'minion1':
    - nettools

and, on your master, run the following command to apply the Top file:

salt '*' state.apply

minion1 and minion2 will both apply the common state, and minion1 will also apply the nettools state.

Formulas repo

The Salt Community provides a vast repository of Formulas at https://github.com/saltstack-formulas.

Batch size

Limit how many systems are updated at once using the --batch-size option:

salt --batch-size 10 '*' state.apply

Terminology

Term	Definition
Formula	A collection of Salt state and Salt pillar files that configure an application or system component. Most formulas are made up of several Salt states spread across multiple Salt state files.
State	A reusable declaration that configures a specific part of a system. Each Salt state is defined using a state declaration.
State Declaration	A top level section of a state file that lists the state function calls and arguments that make up a state. Each state declaration starts with a unique ID.
State Functions	Commands that you call to perform a configuration task on a system.
State File	A file with an SLS extension that contains one or more state declarations.
Pillar File	A file with an SLS extension that defines custom variables and data for a system.

Further readings

• Website
• Github
• Installation
• States
• Targeting
• Top files