Skip to content

Salt

Jump to bottom
Andreas Dørum edited this page May 30, 2016 · 22 revisions

What is Salt?

Salt is a Python-based open source configuration management software tool, and a remote execution engine. See the Using Salt for a quick intro on how Salt works.

Salt terminology

See the Glossary page for an explanation of the terminology used in Salt.

How is Salt set up?

We are using Salt version 2015.8.10.

Files layout

All of the Salt files are in the saltstack/ directory which can be seen below:

saltstack/
├── etc/      // Salt master and minion configurations
├── pillar/   // Salt Pillar 
├── reactor/  // Salt Reactor 
├── salt/     // Salt States
└── vagrant/  // Salt files and keys for Vagrant

The Salt master server needs to have the state, pillar and reactor data in its file roots. This is defined in saltstack/etc/master.conf

Salt Top files

To determine which minions receive which state and pillar data, Salt uses "Top files" (.sls). See the Salt Top file docs for more information on how we target different minions.

The Top files for this project:

Salt Grains

Salt Grains store information about the underlying system such as OS version. If you take a look at the Top files from the section above above we use grains to target some of the minions.

We use grains to define the which version of the Minecraft packages to use, as seen in the grain example below.

Grain example for a Minecraft minion

# The role of this machine.
role: minecraft

# Minecraft Forge server version. See /pillar/minecraft/forge/
forge_version: 189

# ComputerCraft mod version. See /pillar/minecraft/mods/computercraft/
computercraft_version: 179

# Determines how much memory Minecraft uses. See /pillar/minecraft/sizes/
size: verysmall

Working with Salt

Note: Most of these commands should be run in a terminal on the Salt master server as a privileged user. You can run commands a privileged user by prepending sudo to the commands.

Getting the status of minions

Note: This is not a real ICMP ping, but rather a Salt test.

Check status of all minions:

salt '*' test.ping

Check status of a single minion:

salt <minion-name> test.ping

Applying state changes to minions

First do a dry run to see what state changes will be applied:

salt <minion-name> state.apply test=True

Actually apply the state changes to the minion:

salt <minion-name> state.apply

Getting pillar and grain information

You can read out the pillar and grain data for a minion by running the following:

salt <minion-name> pillar.items

salt <minion-name> grains.items

Salt Cloud

Salt Cloud is the part of Salt that enables it to manage virtual machines on a variety of cloud platforms. This interface is tightly integrated with Salt, and new virtual machines are automatically connected to your Salt master after creation.

We use Salt Cloud in the project to integrate with the Azure infrastructure, so that we may dynamically create Minecraft instances. See Getting Started With Azure for more information on how Salt Cloud integrates with Azure.

In order for Salt Cloud to know which cloud platform and which type of virtual machine to create, it uses Salt Cloud providers and profiles configuration files.

We have defined these in saltstack/pillar/cloud.sls.

Salt Cloud provider

The Salt Cloud provider defines which cloud platform to use, any necessary credentials and certificates and other settings.

Here's a simple example provider for Azure:

my-azure-config:
  driver: azure
  subscription_id: 3287abc8-f98a-c678-3bde-326766fd3617
  certificate_path: /etc/salt/azure.pem

Salt Cloud profiles

Salt Cloud profiles are extensions of the provider configurations. The profiles define features, such as size, of the minions created by Salt.

A simple example profile for Azure:

azure-ubuntu:
  provider: my-azure-config
  image: 'b39f27a8b8c64d52b05eac6a62ebad85__Ubuntu-12_04_3-LTS-amd64-server-20131003-en-us-30GB'
  size: Small
  location: 'East US'
  ssh_username: azureuser
  ssh_password: verybadpass
  slot: production
  media_link: 'http://portalvhdabcdefghijklmn.blob.core.windows.net/vhds'
  virtual_network_name: azure-virtual-network
  subnet_name: azure-subnet

Using Salt Cloud

Note: The Azure cloud infrastructure needs to be up and running in order for Salt Cloud to be able to create and manage nodes.

Before using Salt Cloud, remember to take a look the Cloud pillar file, saltstack/pillar/cloud.sls to see what provider and profiles are available.

Creating a minion with Salt Cloud

In order to create a single minion with Salt Cloud, simply run the following:

salt-cloud -p <profile-name> <minion-name>

Destroying a minion with Salt Cloud

If you wish to destroy a single minion with Salt Cloud, simply run the following:

salt-cloud -d <minion-name>

Debugging Salt

Salt Event System

The Salt Event System is used to fire off events enabling third party applications or external processes to react to behavior within Salt.

See Salt Event for more information on the Salt Event bus.

Listening to the Salt Event bus

Print out the event bus for debugging:

salt-run state.event pretty=True

Salt documentation

For debugging Salt, please refer to the official Salt documentation:

Clone this wiki locally