kentoh - Fotolia


Learn how to use Salt orchestration with an example

Admins can use orchestration features in Salt to centrally control a group of minions and machines. Follow this example, which features Orchestrate Runner, to get started.

Configuration management relies on orchestration technology to update managed systems. Salt orchestration is centralized by the Orchestrate Runner feature.

Salt Orchestrate Runner controls the activities of minions -- the individual IT systems that Salt manages -- from the master. Orchestrate Runner enables admins to coordinate the activities of multiple machines from a central place. It also gives Salt users an enterprise view of IT deployment architecture.

A simple example of Salt orchestration is to use the tool to install Elastic's ElasticSearch tool on 10 servers. You could send instructions to minions on all 10 machines, which is automated and saves manual work. However, you might want to first create additional loopback network interfaces so that you can run more than one instance of Elasticsearch on each machine. These commands should run in a certain order rather than all at once, which requires orchestration on top of automation. Another benefit of Salt orchestration is that Orchestrate Runner recognizes dependencies between operations on different machines, so it stops when there is a failure.

Command syntax and folder structure

Salt's commands for Orchestrate Runner are similar to those for minions, with some notable differences.

The command syntax in the Salt state files, which use the suffix .sls, is the same, except that Orchestrate Runner uses state.orchestrate and salt-run, while minion commands use salt. For Salt users who run minions without a master, try salt-call.

While there are many ways to run Salt modules and functions, administrators can get a sense of the Salt orchestration commands by comparing them with those for minions. To apply state, for example, for a state file ng, the command structure for Orchestrate Runner is:

sudo salt-run state.orchestrate

By comparison, for minions, the command below applies state to all minions and runs all the .sls files in /srv/salt.

sudo salt '*' state.apply

The orchestration state file lives in the /srv/salt/orch folder, not /srv/salt, which is the default location for minion instructions.

A Salt orchestration example

To understand how Salt orchestration works in real IT deployments, follow this example based on deploying web server and load balancing tool Ngnix.

The user creates the .sls file /srv/salt/orch/ng.sls for Nginx configuration. The sequence either installs Nginx or verifies that it is running and then creates a second loopback IP address, The tgt argument means to run this configuration sequence against the server named paris.

Use, and then give the command next to name. Here, it runs ifconfig.

Salt runs the commands in the .sls file from top to bottom, with no dependency between them in this example.

  pkg.installed: []
    - tgt: 'paris'
    - require:
      - pkg: nginx

    - name: ifconfig lo:0 netmask up

Run the configuration sequence sudo salt-run state.orchestrate, and observe the output:

          ID: nginx
    Function: pkg.installed
      Result: True
     Comment: All specified packages are already installed
     Started: 17:30:43.612915
    Duration: 300.927 ms
          ID: nginx
    Function: service.running
      Result: True
     Comment: The service nginx is already running
     Started: 17:30:43.914993
    Duration: 27.888 ms
          ID: set_loopback
        Name: ifconfig lo:0 netmask up
      Result: True
     Comment: Command "ifconfig lo:0 netmask up" run
     Started: 17:30:43.944570
    Duration: 6.45 ms

Summary for paris_master
Succeeded: 3 (changed=1)
Failed:    0
Total states run:     3
Total run time: 335.265 ms

Then, run ifconfig on that server. The new loopback interface is added:

lo:0      Link encap:Local Loopback  
         inet addr:  Mask:
         UP LOOPBACK RUNNING  MTU:65536  Metric:1

This Salt orchestration example illustrates that a single state file can include multiple commands that result in complex automated steps.

While this example did not include command dependencies, Orchestrate Runner does support them. For example, you can write Python code to raise an error if something is missing or otherwise fails in the configuration. In that case, return the error to Orchestrate Runner by putting a value in the Python object __context__['retcode']. To create dependencies between commands in a state file, use global state objects require or require_any.

Orchestrate Runner is no more complicated than minions, and it follows the same syntax for the Salt user. The only difference is that Orchestrate Runner works at the master level, which provides a central point to control more than one minion and operation simultaneously. Play with its possibilities via in-line Jinja template variables, custom execution modules and other devices.

Next Steps

Check out the author's other tutorials for Salt operations to practice its command structure, use of state files and minion management.

Dig Deeper on Systems automation and orchestration

Software Quality
App Architecture
Cloud Computing
Data Center