When installing SaltStack Config, you run an orchestration highstate provided in the SaltStack Config installer. The highstate runs on your Salt master and sets up a multi-node environment. It installs the core SaltStack Config architecture on the three other nodes that will host PostgreSQL, Redis, and the RaaS node.

Attention: Deploying SaltStack Config in containers is not supported or recommended.

The end goal of installation is to have four nodes, each with a different host function. Each node is also a minion to the Salt master:

  • A Salt master node
  • A PostgreSQL database node
  • A Redis database node
  • A RaaS node, also known as the SaltStack Config node
Caution:

It is especially important to follow all the steps listed in Installing Salt on your nodes. In particular, you must install the dependencies needed for the SaltStack Config installer on all four nodes in the installation. Otherwise, the multi-node installation fails.

The necessary dependencies are:

  • OpenSSL
  • Extra Packages for Enterprise Linux (EPEL)
  • Python cryptography
  • Python OpenSSL library

High availablility

It is possible to set up multiple Salt masters or multiple RaaS nodes. It is also possible to run the Salt master service on one node, and combine two or more of the other services on a separate node. The steps to configure this kind of system architecture are not fully explained in this guide.

High availability or custom architecture requirements may require consultation services. However, before setting up multiple nodes of the same type, you typically begin with the multi-node installation scenario first and then configure additional architecture later.

For more information about high availability, see Required SaltStack Config dependencies.

Record key data for the four nodes

Before beginning the standard installation, record the key data about each of the four nodes involved in the installation. You input this data at several points during the installation process.

Record the following key data about each of the four nodes involved in the installation:

  • The IP addresses or DNS names
  • The minion IDs

Make sure that you clearly indicate which IP address and minion ID belongs to which host (the Salt master node, the RaaS node, the PostgreSQL database node, the Redis database node).

As a best practice, verify that your IP addresses or DNS names are correct as incorrect IP addresses or DNS names can cause a multi-node installation failure.

Keep this data in an easily accessible record for your own reference. As you configure the orchestration, you need to input this data into several settings and variables in the configuration files. For that reason, it’s helpful to keep this record on hand throughout the installation.

Note:

If you are in a virtualized environment, take care to specify the internal address, as opposed to the public address.

Static vs. Dynamic IP addresses

The Redis and the PostgreSQL hosts need static IP addresses or DNS names that the configuration files reference. Depending on how the RaaS node is deployed, it might need a static IP address or DNS name as well. Relying on dynamic IP addresses in configurations can change and break your environment.

Setting a custom minion ID (optional)

A minion ID is a unique name given to each minion that is managed by a Salt master. By default, the minion identifies itself to the Salt master by the system’s Hostname. However, you can assign custom IDs that are descriptive of their function or location within your network.

If you decide to customize your minion IDs, try to keep the ID brief but descriptive of its role. For example, you could use apache-server-1 to name one of your web servers or you could use datacenter-3-rack-2 after its location in a datacenter. The goal is to make the names descriptive and helpful for future reference.

To declare a minion ID:

  1. In the minion’s terminal, navigate to the directory that contains the minion’s id.conf file. By default, the directory location is etc/salt/minion.d/id.conf.
  2. Open the id.conf file in an editor. Change the id setting to your preferred minion ID. For example:
    id: postgres-database-1
  3. After changing a minion ID, the minion’s keys must be accepted (or re-accepted) by the Salt master. For specific instructions on setting up the keys, see Accept the minion keys on the master(s).

Copy and edit the top state files

During this installation task, you copy the orchestration files provided with the SaltStack Config installer to the Salt master node. Then, you edit the files to reference the three nodes for RaaS, the Redis database, and the PostgreSQL database.

To copy and edit the orchestration configuration files:

  1. On the Salt master, navigate to the sse-installer directory.
  2. Copy the pillar and state files from the sse_installer directory into the minion’s pillar_roots and file_roots using the following commands:
    sudo mkdir /srv/salt
sudo cp -r salt/sse /srv/salt/
sudo mkdir /srv/pillar
sudo cp -r pillar/sse /srv/pillar/
sudo cp -r pillar/top.sls /srv/pillar/
sudo cp -r salt/top.sls /srv/salt/
    Important:

    These instructions make some assumptions that might not be true of your directory structure, especially if you have an existing Salt installation. The instructions assume:

    • That your Salt master is using the default directory structure. If your directory structure has been modified, you may need to modify these instructions for your custom directory structure.
    • That you do not already have a folder named sse under either your pillar or configuration state root. If this folder exists, you may need to merge them manually.
    • That you do not already have a file named top.sls inside your pillar or salt directory. If this file exists, you may need to merge it with your existing file manually.
  3. In the /srv/pillar/ directory, you now have a file named top.sls that you copied over from the installation files in the previous step. Open this file in an editor.
  4. Edit this file to define the list of minion IDs (not the IP addresses or DNS names) for your PostgreSQL, Redis, RaaS, and Salt master. Use the IDs that you recorded earlier.

    For example:

    {# Pillar Top File #}

{# Define SSE Servers #}

{% load_yaml as sse_servers %}
  - postgres-database-1
  - redis-database-1
  - saltstack-enterprise-api-server-1
  - saltmaster-1
{% endload %}

base:

{# Assign Pillar Data to SSE Servers #}
{% for server in sse_servers %}
  '{{ server }}':
    - sse
{% endfor %}
  5. In the /srv/salt/ directory, you now have a file named top.sls that you copied over in step 2. Open this file in an editor and verify that it matches the following:
    base:

  {# Target SSE Servers, according to Pillar data #}
  # SSE PostgreSQL Server
  'I@sse_pg_server:{{ grains.id }}':
    - sse.eapi_database

  # SSE Redis Server
  'I@sse_redis_server:{{ grains.id }}':
    - sse.eapi_cache

  # SSE eAPI Servers
  'I@sse_eapi_servers:{{ grains.id }}':
    - sse.eapi_service

  # SSE Salt Masters
  'I@sse_salt_masters:{{ grains.id }}':
    - sse.eapi_plugin

Apply the highstates to the nodes

  1. On the Salt master, sync your grains to confirm that the Salt master has the grain data needed for each minion. This step ensures that the pillar data is properly generated for SaltStack Config functionality.

    In the command that syncs the grains, you can target all minions, or you can pass in a list of the specific minion IDs for your nodes (including the Salt master itself) in the brackets. For example:

    Target all minions

    sudo salt \* saltutil.refresh_grains

    Target a list of minions

    sudo salt -L 'salt-master-1,postgres-database-1,redis-database-1,saltstack-enterprise-api-server-1' saltutil.refresh_grains
  2. Refresh and confirm that each of the minions has received the pillar data defined in the sse_settings.yaml file and that it appears as expected.

    In the command that refreshes the pillar data, you can target all minions or you can pass in a list of the specific minion IDs for your nodes (including the Salt master itself) in the brackets. For example:

    Target all minions

    sudo salt \* saltutil.refresh_pillar

    Target a list of minions

    sudo salt -L 'salt-master-1,postgres-database-1,redis-database-1,saltstack-enterprise-api-server-1' saltutil.refresh_pillar
  3. Confirm that the return data for your pillar is correct:
    sudo salt \* pillar.items

    Verify that you see pillar data related to SaltStack Config.

    Note:

    You could also target a specific minion’s pillar data to verify the pillar data has been refreshed.

  4. Run the command that applies the orchestration highstate to the PostgreSQL server. Use the minion ID that you recorded for the PostgreSQL server earlier.

    For example:

    sudo salt postgres-database-1 state.highstate
  5. Repeat the previous step for each of the following servers, replacing the minion ID for each server:
    • The Redis node
    • The RaaS node
    • The Salt master node
    Note:

    During the initial application of the highstate to the Salt master, you might see the following error message: Authenticationerroroccurred. This error displays because the Salt master has not yet authenticated to the RaaS node, but the Master Plugin installation state will restart the Salt master service and the issue will be resolved automatically.

If you encounter any other errors while running the highstates, refer to Troubleshooting.