Maksim Kabakou - Fotolia

Manage Learn to apply best practices and optimize your operations.

How to update configurations via the Salt state file

Salt users must grasp the concepts around state files for configuration changes and updates. Follow along with this tutorial, which also features Cassandra, to get started.

Salt is a configuration management technology that relies on states, which contain all the information on the correct setup for an environment. To change configurations, administrators must know how to manage and manipulate the Salt state file.

Admins can use Salt to provision IT infrastructure -- such as to install Apache Cassandra -- and to make changes to it, without repetitive manual work. This Salt tutorial covers how to push out configuration changes to installed infrastructure, using Cassandra as the example.

Software typically installs configured with localhost as an IP address. That software knows nothing about a cluster of hosts until the administrator updates its config file with the cluster's IP addresses. This tutorial walks through how to update the IP addresses for Cassandra's operation and set the IP addresses of the other machines in the cluster. Follow along to update the cassandra.yaml configuration file to make these changes.

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

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 ','. 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 = ',' %}

  - name: /etc/cassandra/cassandra.yaml
  - pattern: 'seeds: ""'
  - 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,

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.

    - humanname: Cassandra
    - name: deb 311x main
    - dist: 311x
    - file: /etc/apt/sources.list.d/cassandra.sources.list
    - keyid: A278B781FE4B2BDA
    - keyserver:

    - refresh: True
    - allow_updates: True

{% set seeds = ',' %}

  - name: /etc/cassandra/cassandra.yaml
  - pattern: 'seeds: ""'
  - repl: 'seeds: "{{seeds}}"'

  - 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:

Salt output

Finally, restart the Cassandra service from the command line:

sudo salt 'paris' 'sudo service cassandra restart'

The configuration changes take effect when Cassandra restarts.

This was last published in January 2019

Dig Deeper on Configuration Management and DevOps

Join the conversation

1 comment

Send me notifications when other members comment.

Please create a username to comment.

What tasks do you perform with a Salt state file?