Installing Automation Config

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

Attention: Deploying Automation 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 Automation 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 Automation 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 Automation 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:

In the minion’s terminal, navigate to the directory that contains the minion’s minion.conf file. By default, the directory location is etc/salt/minion.d.
Open the minion.conf file in an editor. Change the id setting to your preferred minion ID. For example:
```
id: postgres-database-1
```
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 Automation 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:

On the Salt master, navigate to the sse-installer directory.
Copy the pillar and state files from the sse_installer directory into the Salt Master’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.
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.

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 %}

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

Edit the Automation Config settings pillar file

During this installation task, you edit five different sections in the Automation Config settings pillar mapping file to provide the values that are appropriate for your environment. These settings are used by the configuration state files to deploy and manage your Automation Config deployment.

To copy and edit the Automation Config settings state file:

On the Salt master, navigate to the /srv/pillar/sse/ directory.
Open the sse_settings.yaml file in an editor. Section 1 of this file contains four variables that correspond to the four nodes. Change the values of the four variables to the minion IDs (not the IP addresses or DNS names) for the corresponding nodes. Use the minion IDs that you recorded earlier.
For example:
```
# PostgreSQL Server (Single value)
pg_server: postgres-database-1

# Redis Server (Single value)
redis_server: redis-database-1

# SaltStack Enterprise Servers (List one or more)
eapi_servers:
  - saltstack-enterprise-api-server-1

# Salt Masters (List one or more)
salt_masters:
  - saltmaster-1
```
Note: The pg_server and redis_server variables are single variables because most network configurations only have one PostgreSQL and Redis database. By contrast, the variables for the eapi_servers and salt-masters are formatted in a list because it is possible to have more than one RaaS node and Salt master.
In Section 2 of this file, edit the variables to specify the endpoint and port of your PostgreSQL node:
- pg_endpoint - Change the value to the IP address or DNS name (not the minion ID) of your PostgreSQL server. If you are in a virtualized environment, take care to specify the internal address, as opposed to the public address.
- pg_port - The standard PostgreSQL port is provided, but may be overridden, if needed.
- pg_username and pg_password - Enter the credentials for the user that the API (RaaS) will use to authenticate to PostgreSQL. This user is created when you run the configuration orchestration highstate.
Note: The variable is specified as the pg_endpoint as some installations may have configured a separate PostgreSQL server (or cluster) that is not managed by this installation process. If that is the case, exclude the action. Do not apply the highstate to the PostgreSQL server during the Apply Highstates to the nodes step later in the process.
Repeat the previous step to edit Section 3 of this file, but instead edit the corresponding variables to specify the endpoint and port of your Redis node.
In Section 4 of this file, edit the variables related to the RaaS node:
- If this is a fresh installation, do not change the default values for the eapi_username and eapi_password variables. During the configuration orchestration, the installation process establishes the database with these default credentials. It needs these credentials to connect through the eAPI service to establish your default Targets and Jobs in Automation Config. You will change the default password in a later post-installation step.
- For the eapi_endpoint variable, change the value to the IP address or DNS (not the minion ID) of your RaaS node.
  Note: The variable is specified as the eapi_endpoint as some installations host multiple eAPI servers behind a load balancer.
- The eapi_ssl_enabled variable is set to True by default. When set to True, SSL is enabled. You are strongly recommended to leave this enabled. SSL validation is not required by the installer, but is likely a security requirement in environments that host their own certificate authority.
- The eapi_standalone variable is set to False by default. This variable provides direction to the configuration states if Pillar data is being used in a single-node installation scenario. In that scenario, all IP communication would be directed to the loopback address. In the multi-installation scenario, you should leave this set to False.
- The eapi_failover_master variable is set to False by default. This variable supports deployments where Salt masters (and minions) are operating in failover mode.
- The eapi_key variable defines the encryption key thatAutomation Config uses to manage encrypted data in the PostgreSQL database. This key should be unique for each installation. A default is provided, but a custom key can be generated by running the following command in a separate terminal outside of the editor:
```
openssl rand -hex 32
```
In Section 5 of this file, edit the variables to add your unique customer identifiers:
- The customer_id variable uniquely identifies a SaltStack deployment. It becomes the suffix of the schema name of the raas_* (API (RaaS)) database in PostgreSQL. A default is provided, but a custom key can be generated by running the following command in a separate terminal outside of the editor:
```
cat /proc/sys/kernel/random/uuid
```
- The cluster_id variable defines the ID for a set of Salt masters when it is configured in either Active or Failover Multi-Master mode. This ID prevents minions that are reporting to multiple Salt masters from being reported multiple times within the Automation Config.

Apply the highstates to the nodes

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 Automation 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
```
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
```
Confirm that the return data for your pillar is correct:
```
sudo salt \* pillar.items
```
Verify that you see pillar data related to Automation Config.

Note:
You could also target a specific minion’s pillar data to verify the pillar data has been refreshed.
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
```
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.