Salt States and Pillars

States are configuration templates. They allow you to describe what each of your systems should look like, including the applications and services that are installed and running. Salt state files are referred to as SLS (SaLt State) files.

States are applied to the target systems by matching relevant state data to clients. The state data comes from Uyuni in the form of package and custom states.

You can target clients at three specific levels of hierarchy and priority: individual clients, system groups, and organization. Individual clients have priority over groups, and groups have priority over the organization.

For example:

  • The Organization requires that version 1 is installed. All clients are part of the same Organization.

  • Group A requires that version 2 is installed. Client1, Client2, and Client3 are part of Group A.

  • Group B requires any version installed. Client4 is part of Group B.

Leading to these possible scenarios:

  • Client1 wants package removed, package is removed (Client Level)

  • Client2 wants version 2, gets version 2 (Client Level)

  • Client3 wants any version, gets version 2 (Group Level)

  • Client4 wants any version, gets version 1 (Organization Level)

For more information on Salt states, see https://docs.saltproject.io/en/latest/topics/states/.

You can create custom Salt states with Uyuni. For more information, see Custom Salt States.

1. Group States

Pillar data can be used to perform bulk actions, like applying all assigned states to clients within the group. This section contains some examples of bulk actions that you can take using group states.

To perform these actions, you will need to determine the ID of the group that you want to manipulate. You can determine the Group ID by using the spacecmd command:

spacecmd group_details

These examples use an example Group ID of GID.

To apply all states assigned to the group:

salt -I 'group_ids:GID' state.apply custom.group_GID

To apply any state (whether or not it is assigned to the group):

salt -I 'group_ids:GID' state.apply ``state``

To apply a custom state:

salt -I 'group_ids:2130' state.apply manager_org_1.``customstate``

Apply the highstate to all clients in the group:

salt -I 'group_ids:GID' state.apply

2. Salt Pillars

Uyuni exposes a small amount of internal data as pillars which can be used with custom states. Pillars are created on the Uyuni Server, and contain information about a client or group of clients. For custom information in pillars, see Custom System Information. Pillars are useful for sensitive data, configuration of clients, variables, and any arbitrary data.

Pillars are managed either automatically by Uyuni, or manually by the user.

If you change pillar data on the server (Salt master) the actual pillar data on the client (minion) is updated only after calling saltutil.refresh_pillar for the client.

Otherwise it could happen that pillar.items and pillar.get calls would produce different results with different values of pillars that were not refreshed.

To avoid hard-coding organization IDs within SUSE Linux Enterprise Server files, a pillar entry is added for each organization:

org-files-dir: relative_path_to_files

The specified file is available for all clients which belong to the organization.

This is an example of a pillar located at /etc/motd:

file.managed:
    - source: salt://{{ pillar['org-files-dir']}}/motd
    - user: root
    - group: root
    - mode: 644

For more information on Salt pillars, see https://docs.saltproject.io/en/latest/topics/pillar/.

3. Download Endpoint

By default, Uyuni assumes that the download endpoint to use is the FQDN of the Uyuni Server or Proxy. However, there are some cases where you might like to use a different FQDN as the download endpoint. The most common example is if you need to use load balancing, caching proxies, or in environments with complicated networking requirements.

To change the package download endpoint, you can manually adjust three Salt pillars: * pkg_download_point_protocol, defaults to https. * pkg_download_point_host, defaults to the FQDN of the Uyuni Server (or Proxy, if in use). * pkg_download_point_port, defaults to 443.

If you do not adjust these pillars directly, Uyuni will fall back to the default values.

Procedure: Changing the Package Download Endpoint Pillar
  1. Navigate to /srv/pillar/ and create a file called top.sls with these contents:

    base:
      '*':
        - pkg_download_points

    This example directs Salt to look at the pkg_download_points.sls file to determine the base URL to use. You can adjust this file to target different clients or groups, depending on your environment.

  2. Remain in /srv/pillar/ and create a file called pkg_download_points.sls with the base URLs you want to use. For example:

    pkg_download_point_protocol: http
    pkg_download_point_host: example.com
    pkg_download_point_port: 444
  3. OPTIONAL: If you want to use external pillars, for example Group IDs, open the master configuration file and set the ext_pillar_first parameter to true. You can then use Group IDs to set conditional values, for example:

    {% if pillar['group_ids'] is defined and 8 in pillar['group_ids'] %}
      pkg_download_point_protocol: http
      pkg_download_point_host: example.com
      pkg_download_point_port: 444
    {% else %}
      pkg_download_point_protocol: ftp
      pkg_download_point_host: example.com
      pkg_download_point_port: 445
    {%- endif %}
  4. OPTIONAL: You can also use grains to set conditional values, for example:

{% if grains['fqdn'] == 'client1.example.com' %}
    pkg_download_point: example1.com
{% elif grains['fqdn'] == 'client2.example.com'' %}
    pkg_download_point: example2.com
{% else %}
    pkg_download_point: example.com
{% endif %}