How to update configurations via the Salt state file

Details of a Salt state file

This tutorial works with a Salt state file, which is designated with the suffix .sls. It uses pkgrepo.managed and pkg.installed, which are state objects with full names salt.pkgrepo.managed and salt.pkg.installed.

The setup also relies on the Salt state module salt.modules.file. Salt modules expand Salt state files, using the Jinja language to set variables and call functions. Jinja is a simple programming language that Salt supports, along with Python, inside state files.

State files are objects, and each section of the state file builds up the base object into a logical whole unit. Terms such as base, cassandra, setSeeds and setListen seen in the code of this tutorial are names to identify each section. Some of these names have specific meaning, such as cassandra for the software to install. Salt runs these blocks of code from top to bottom, in the example of setSeeds and setListen. Salt uses seed to mean that it is seeding a location with a configuration for the minion.

Update the IP addresses for Cassandra

Salt supports regular expressions and different functions for replacing text in files on the targeted system. Alternatively, maintain files on the /srv/salt mount point, and push them out that way. This example uses the first method.

To start this tutorial, retrieve the IP address of the target machine using a module, which is a Salt function the administrator calls from the command line. The following command uses the module network.ipaddrs to access the non-loopback IP addresses on the targeted machine. The server in this example is called paris, and it is the minion, or the machine to which Salt applies a configuration:

sudo salt 'paris' network.ipaddrs
paris:
    - 172.31.46.15

That module network.ipaddrs, when used inside code, returns an array. To retrieve a value, write the code as {{salt['network.ipaddrs']()[0]}}, where ()[] means pick the first value in the array. The double curly braces are used in Jinja programming.

Next, tell Salt to replace matching text to update the IP addresses. Use the module salt.modules.file.replace. It sets the value of seeds to the string '172.31.46.15,172.31.47.43'. These are the IP addresses of the machines in the cluster.

The arguments in this string of code are:

• name: the file to update;
• pattern: the string for Salt to look for; and
• repl: the value to replace that string with.

This set of arguments is how we replace localhost with a list of IP addresses of all the nodes in the cluster. We define the cluster by letting the nodes know about each other. The double curly braces tell Salt to retrieve that value from the variable seeds {{seeds}}. Assign value with the single curly brace {% set ...}. Salt also supports loops as control structures.

{% set seeds = '172.31.46.15,172.31.47.43' %}

setSeeds:
  file.replace:
  - name: /etc/cassandra/cassandra.yaml
  - pattern: 'seeds: "127.0.0.1"'
  - repl: 'seeds: "{{seeds}}"'

Use Salt's reference documentation to see what parameters are allowed for a given configuration task. In this setup, the allowed arguments are:

salt.modules.file.replace(path, pattern, repl, count=0, flags=8,
bufsize=1, append_if_not_found=False, prepend_if_not_found=False,
not_found_content=None, backup=u'.bak', dry_run=False, search_only=False,
show_changes=True, ignore_if_missing=False, preserve_inode=True,
backslash_literal=False)

Alternatively, use the same Salt module but with network.ipaddrs coded as {{salt['network.ipaddrs']()[0]}}', under the setListen section of the Salt state file. This setup for the module retrieves a value rather than the array.

base:
  pkgrepo.managed:
    - humanname: Cassandra
    - name: deb http://www.apache.org/dist/cassandra/debian 311x main
    - dist: 311x
    - file: /etc/apt/sources.list.d/cassandra.sources.list
    - keyid: A278B781FE4B2BDA
    - keyserver: keyserver.ubuntu.com

cassandra:
  pkg.installed:
    - refresh: True
    - allow_updates: True

{% set seeds = '172.31.46.15,172.31.47.43' %}

setSeeds:
  file.replace:
  - name: /etc/cassandra/cassandra.yaml
  - pattern: 'seeds: "127.0.0.1"'
  - repl: 'seeds: "{{seeds}}"'

setListen:
  file.replace:
  - name: /etc/cassandra/cassandra.yaml
  - pattern: 'listen_address: localhost'
  - repl: 'listen_address: {{salt['network.ipaddrs']()[0]}}'

Apply the Salt state file

Now that the state file is updated to configure Cassandra as desired, Salt must execute the configuration. Salt has several ways to run a state file. The administrator can target Cassandra directly or tell Salt to look at the top file, top.sls -- which contains mapping and configuration roles from which other states branch out -- and then apply all states required on this machine. Use state.apply to tell Salt to apply the states to the minion paris:

sudo salt 'paris' state.apply

Salt responds as shown below, with output on what changes it made to the targeted file for Cassandra, /etc/cassandra/cassandra.yaml:

Finally, restart the Cassandra service from the command line:

sudo salt 'paris' cmd.run 'sudo service cassandra restart'

The configuration changes take effect when Cassandra restarts.