Using grains in states

Grains are one of the most important features of Salt, based on which we can perform the configuration and orchestration tasks efficiently. Salt offers the flexibility to use the default grains and also to add custom grains as and when required. In this recipe, you will learn how to use grains in state configurations.

How to do it...

Configure a new minion with the hostname or minion ID as stgdc1app01 in the staging environment. In this naming convention, stg is the environment, dc1 is the location, app is the server type, and 01 is a numeric identifier for the host.

1. Run the following command to get a full list of available grains on the minion:

   [root@salt-master ~]# salt 'stgdc1app01' grains.items
   

2. Next, run the following command to get information about two specific grains that we will work with:

   [root@salt-master ~]# salt 'stgdc1app01' grains.item \ ip_interfaces fqdn
   stgdc1app01:
    fqdn: stgdc1app01
    ip_interfaces: {'lo': ['127.0.0.1'], 'eth1': ['192.168.0.3'], 'eth0': ['192.168.29.129']}
   

3. Next, create a new state called appenv by creating a directory called appenv in the base directory of the staging environment. Create a directory called files in the appenv directory and create a file named environment in the files directory. The directory structure should be as follows:

   appenv:
     - init.sls
     - files:
       - environment

4. Edit the /opt/salt-cookbook/staging/appenv/files/environment file to have the following entries:

   primary_interface: {{ ipaddress }}
   location: {{ location }}

5. Edit the /opt/salt-cookbook/staging/appenv/init.sls file and populate it with the following entries:

   appenv_file:
     file.managed:
       - name: /etc/environment
       - source: salt://appenv/files/environment
       - template: jinja
       - mode: 644
       - context:
         ipaddress: {{ grains['ip_interfaces']['eth1'][0] }}
         location: {{ grains['fqdn'][3:6] }}

6. Apply the configured state to the minion with the following command:

   [root@salt-master ~]# salt 'stgdc1app01' state.sls appenv \ saltenv=qa
   stgdc1app01:
   ----------
    ID: appenv_file
    Function: file.managed
    Name: /etc/environment
    Result: True
    Comment: File /etc/environment updated
    Changes:
    ----------
    diff:
    New file
    mode:
    0644
   
   Summary
   ------------
   Succeeded: 1
   Failed: 0
   ------------
   Total: 1
   

7. Finally, view the contents of the file on the minion:

   [root@stgdc1app01 ~]# cat /etc/environment
   primary_interface: 192.168.0.3
   location: dc1
   

How it works...

In this recipe, we demonstrated how to use grains in state configurations. The objective of this recipe is to create an environment file, which will be used by some random application and will contain information in key-value pairs about the system. However, the same method may be used to populate configuration files for various servers using grain data.

First, we display all the grains available on our new minion using the grains.items module. It gives us a long list of all the available grains in the system. Next, we display only a couple of them that we used later in our state configuration using the command:

[root@salt-master ~]# salt 'stgdc1app01' grains.item \ ip_interfaces fqdn

The ip_interfaces and fqdn grains are only two of the many default grains available in Salt. Note that the difference in the module name, in this case, grains.item is used instead of grains.items followed by the grain names ip_interfaces and fqdn. If grains.items is used, then it will display the entire list of grains even though the grains are explicitly mentioned. On running the command, we get the following output:

stgdc1app01:
  fqdn: stgdc1app01
  ip_interfaces: {'lo': ['127.0.0.1'], 'eth1': ['192.168.0.3'], 'eth0': ['192.168.29.129']}

Grains can be found in various forms, two of which can be seen here, the fqdn grain being in a simple key-value format and the ip_interfaces grain being in the same key-value format, but the value being a Python dictionary. It will display as many pairs of key-value data as there are network interfaces in the minion host.

In this recipe, we configured a file definition using the file module and a method known as templates about which we will learn in Chapter 3, Modules, Orchestration, and Scaling Salt. The basic idea is to copy a file from the master to the minion and substitute some parts of the file with explicitly passed values. We created a template called environment and made a few entries in it as follows:

primary_interface: {{ ipaddress }}
location: {{ location }}

Here, the areas enclosed in double braces are the ones which will be substituted by the values passed from the state file.

In the state configuration, the area of our interest is as follows:

- context:
      ipaddress: {{ grains['ip_interfaces']['eth1'][0] }}
      location: {{ grains['fqdn'][3:6] }}

The key context tells Salt that the key-value pairs under it are variables, which need to be passed on to the template and the values need to be substituted in the areas enclosed by double braces where the variable names need to match.

Here, we see how we can access the grain values. For fqdn it's quite simple, as we use the grains keyword with the fqdn key to access its value. Here, we also get a glimpse of Salt's flexibility using [3:6], which is a Python-specific operation to extract a certain part of the string, here it is the location that is dc1. Also, for ip_interfaces, we use the method to access dictionary values, that is, grains['ip_interfaces']['eth1']. This returns a list with one value, ['192.168.0.3'], and the [0] is used to get this value from the list.

After retrieving required values from the grains, Salt passes on the values to the template and populates the file on the minion as configured.

See also

• The Using conditionals in states and pillars and Using Python functions in conditionals recipes, to learn about how to use grains in conditionals and other Python functions
• The Setting host entries and grains recipe in Chapter 4, General Administration Tasks, to learn about how to set grains via Salt states