Skip to main content
SaltStack Support

Enterprise Installation: Using the Installer

The script installs all necessary dependencies and then applies Salt States to install SaltStack Enterprise. The required versions of PostgreSQL, Redis, PyOpenSSL, and Python Setuptools have been included for your convenience.
This is helpful for installations where servers do not have direct internet access.

The SaltStack Enterprise installer is intended only for initial installation. If you are upgrading your installation to the latest version of SaltStack Enterprise, follow the Upgrade instructions.

RHEL 7 Installation

Download the installer files.

Refer to the following SHA-256 hash for the installer download:
2e3873250a23bca7cead50a23c98df3e3b3e45bb8d8d0cc582adba9783a1c839

For more information, see Verifying files.

Complete the steps below for either a single node or multi-node installation.

Single Node Installation

If your version of RHEL 7 is lower than 7.4, you will need to update your OpenSSL version to 1.0.2k before running the installation script. If this version is not available to you via a yum update, or your server does not have direct internet access, retrieve the following packages from Red Hat or from your preferred public mirror:
  • openssl-1.0.2k-12.el7.x86_64.rpm
  • openssl-libs-1.0.2k-12.el7.x86_64.rpm

Use this method if you want to install the Salt Master, SaltStack Enterprise, Redis, and PostgreSQL on the same node. This is appropriate for installations with up to 1,000 minions.

For installations with more than 1,000 minions, please perform a multi-node installation. See Multi-node Installation.

  1. Extract the files.

unzip sse-installer-6.0.1+3.zip
cd sse_installer
  1. ​​​​​Run the command:
sudo ./setup_single_node.sh
This script configures a Salt Master and Salt Minion. It then installs PostgreSQL, Redis, SaltStack Enterprise, and the Salt Master Plugin on the same server. This should be a fresh installation of RHEL. Ideally, Salt should not yet be installed. If both the Salt Master and Salt Minion are installed, the script skips this step and proceeds with the setup of SaltStack Enterprise. If either the Salt Master or the Salt Minion packages are installed, but not both, the script will terminate. This protects the user from accidentally disrupting an existing installation.
  1. Confirm that you can log in to SaltStack Enterprise.

    Log in to the web console using your browser (Chrome is recommended).
    The default installation uses https:// and generates a self-signed certificate.

    The default credentials are as follows:

The setup_single_node.sh script does not modify firewall rules. Please ensure that access is allowed to port 443 in your firewall rules for all appropriate systems (Salt Masters, web-based interface users, remote systems calling the Enterprise API, etc).

Multi-node

Use this method when installing SaltStack Enterprise on a distributed system.
This method is required for installations with more than 1,000 minions, but is perfectly appropriate for smaller installations.

For a multi-node installation, you will need to integrate the pillar and configuration states into your existing environment (these are provided within the installation download).

The starting point for this procedure is that you have created the following node types:

  • Salt Master
  • PostgreSQL
  • Redis
  • SaltStack Enterprise API (eAPI)

Each of these servers must be a Salt Minion of the Salt Master.

  1. On the Salt Master, extract the files.
sudo unzip sse-installer-6.0.1+3.zip
sudo cd sse_installer
  1. Copy the pillar and state files into your pillar_roots and file_roots location.

For example, in a default Salt Master configuration where the pillar and configuration state file roots are /srv/pillar and /srv/salt, the commands to copy the related files into their correct locations would be:

sudo mkdir /srv/salt
sudo cp -r salt/sse /srv/salt/
sudo mkdir /srv/pillar
sudo cp -r pillar/sse /srv/pillar/

This assumes that you do not already have a folder named “sse” for some unrelated purpose under either your pillar or configuration state root.

  1. Create or update your existing Pillar “Top” file

Create or update your /srv/pillar/top.sls file with the content from the provided sse_install/pillar/top.sls file. Define the list of minion IDs for your PostgreSQL, Redis, eAPI, and Salt Masters.

For example:

{# Pillar Top File #}

{# Define SSE Servers #}

{% load_yaml as sse_servers %}
  - saltpgsql
  - saltredis
  - salteapi
  - saltmaster
{% endload %}

base:

{# Assign Pillar Data to SSE Servers #}
{% for server in sse_servers %}
'{{ server }}':
  - sse
{% endfor %}
  1. Update pillar/sse/sse_settings.yaml with the values appropriate for your environment. These settings will be used by the configuration state files to deploy and manage your SaltStack Enterprise deployment.
  • Section 1

    You will need to provide the Minion ID (as opposed to the IP or DNS name) for each server type. Please note that pg_server and redis_server items are single values. The eapi_servers and salt_masters items are lists, as these two server types have high-availability deployment options supported by the installation states.

  • Section 2

    You will need to specify the pg_endpoint for your PostgreSQL server. For this option, be sure to specify the DNS name or IP address for your PostgreSQL server (not the Minion ID). The standard PostgreSQL port is provided, but may be overridden, if desired.

    • This 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, you will want to exclude the action to highstate the PostgreSQL server in step 8 of this guide.

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

    You will also specify the username and password for the PostgreSQL user that will be used by the eAPI server(s) to authenticate to PostgreSQL.
    This user will be created for you when you run the configuration states.

  • Section 3

    You will need to specify the redis_endpoint for your Redis server.
    The standard Redis port is provided, but may be overridden.

    The redis_username and redis_password are also specified in this section.

  • Section 4

    You will next define the configuration settings for your eAPI servers.
    The initial eapi_username and eapi_password values are root and salt, respectively.

    • If this is a fresh installation, it is important that you do not change these values. During the initial run of these states, the installation process will establish the database with these default credentials then connect through the eAPI service to establish your default Targets and Jobs.

    • After your initial deployment is completed and you have tested your access to the web-based user interface, then you are strongly advised to do the following:

      1. Update the root user’s password via the web-based user interface.
      2. Update /srv/pillar/sse/sse_settings.yaml with the new password.
      3. Reapply the highstate on your Salt Master(s).

    You will need to specify the eapi_endpoint for your SaltStack Enterprise server.
    For this option, be sure to specify the DNS name or IP address for your eAPI server (not the Minion ID).

    • This is referred to as the eapi_endpoint, as some installations host multiple eAPI servers behind a load balancer.

    • You may also specify whether or not SSL should be enabled on the eAPI servers and if the SSL certificate should be validated. It is strongly recommended to enable SSL. 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 option is present to provide direction to the configuration states if Pillar data is being used in a single node deployment. In that event, all IP communication would be directed to the loopback address. Since you are using this guide, you should leave this set to False.

    • The eapi_deploy_default_spm option is present to suppress the deployment of the default Jobs, Targets, or files in the SSE Filesystem provided by SaltStack Enterprise. If are deploying an update to an existing installation and you have modified any of these items, you will likely want to set this to False. Otherwise, True is recommended.

    • The eapi_failover_master option is present to support deployments where Salt Masters (and Salt Minions) are operating in “Failover” mode. For Multi-Master configurations, SaltStack strongly recommends use of “Active” Multi-Master configurations.

    • The eapi_key option is present to allow the user to define the encryption key that SaltStack Enterprise 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:

openssl rand -hex 32
  • Section 5

The customer_id value uniquely identifies a SaltStack deployment.
Primarily, it becomes the suffix of the schema name of the raas_* database in PostgreSQL. A default is provided, but a custom key can be generated by running the command:

cat /proc/sys/kernel/random/uuid

The cluster_id value defines the ID for a set of Salt Masters, when configured in either “Active” or “Failover” Multi-Master mode. This prevents Salt Minions that are reporting to multiple Masters from being reported multiple times in the Targets view within the SaltStack Enterprise.

  1. Create or Update your existing Configuration State “Top” file.

Create or update your /srv/salt/top.sls file with the content from the provided sse_install/salt/top.sls file.

The syntax within will leverage the Pillar data provided in Section 1 to provide the Minion IDs of the nodes that will require the SSE Pillar data.

For example:

 base:

   {# Target SSE Servers, according to Pillar data #}

   # SSE PostgreSQL Server
   'I@sse_pg_server:':
     - sse.eapi_database

   # SSE Redis Server
   'I@sse_redis_server:':
     - sse.eapi_cache

   # SSE eAPI Servers
   'I@sse_eapi_servers:':
     - sse.eapi_service

   # SSE Salt Masters
   'I@sse_salt_masters:':
     - sse.eapi_plugin
  1. Sync Grains

For Pillar data to be properly generated, we must confirm that the Salt Master has all grain data from each of the Minions that will provide a part of the SaltStack Enterprise functionality.

sudo salt -L '[LIST_OF_SSE_RELATED_NODES]' saltutil.refresh_grains
  1. Refresh and Confirm Pillar Data

Prior to running the SaltStack Enterprise deployment via hightate, confirm that each of the SaltStack Enterprise related nodes has received the Pillar data defined in the sse_settings.yaml file and that it appears as expected.

sudo salt -L '[LIST_OF_SSE_RELATED_NODES]' saltutil.refresh_pillar

If your Pillar data appears to be correct, proceed with the next step.

  1. Apply the highstate to the following servers:
  • PostgreSQL Server
  • Redis Server
  • SaltStack Enterprise Server(s)
  • Salt Master(s)
sudo salt <MINION_ID_OF_RELATED_SERVER> state.highstate
During the initial application of the highstate to the first Salt Master, you may see the following message: Authentication error occurred. This displays because the master has not yet authenticated to raas, but the master plugin installation state will restart the Salt Master process and the issue will be resolved automatically.
  1. Confirm that you can log in to SaltStack Enterprise

Log in to the web-based interface using your browser (Chrome is recommended).
The default installation uses https:// and generates a self-signed certificate.

The default credentials are as follows:

The SaltStack Enterprise Installer does not modify firewall rules. Please ensure that firewall access is allowed on the following ports from the following nodes:
  • PostgreSQL is accessible by (5432 by default)
    • eAPI servers
  • Redis is accessible by (6739 by default)
    • eAPI Servers
  • eAPI endpoint is accessible by (443 by default)
    • Salt Masters
    • Web-based interface users
    • Remote systems calling the Enterprise API
  • Salt Masters are accessible by (4505/4506 by default)
    • All Salt Minions configured to use the related Salt Master

Package Key IDs

The SaltStack Enterprise Installer supports situations where target machines might not be connected to the internet. In addition, some machines might be configured to validate RPM package signatures, but might not be able to connect to the internet to automatically retrieve the correct public keys.

These keys are included in the installer zipfile for easy import on such machines. However, we strongly recommend validating that the keys provided by SaltStack match the official ones.

The key IDs are as follows, along with the canonical location of each:

Key Name Key ID Location
Fedora EPEL 352C64E5 https://getfedora.org/static/352C64E5.txt
IUS Community Project 9CD4953F https://dl.iuscommunity.org/pub/IUS-COMMUNITY-GPG-KEY
PostgreSQL Global Dev Group 442DF0F8 https://download.postgresql.org/pub/...PG-KEY-PGDG-96
SaltStack Packaging Team DE57BFBE http://repo.saltstack.com/yum/redhat...CK-GPG-KEY.pub

Importing key files

To import the .asc keyfiles in the zipfile into the RPM packaging system on the machines where you intend to install SaltStack Enterprise components, run:

rpmkeys --import *.asc

Verifying files

To validate that the installer zipfile was not altered after being created by SaltStack, compare the SHA-256 hash for your copy of the zipfile to the one included below.

You can calculate the hash for your copy with:

sha256sum sse-installer-6.0.1+3.zip

The output of the command should match the following:

2e3873250a23bca7cead50a23c98df3e3b3e45bb8d8d0cc582adba9783a1c839 sse-installer-6.0.1+3.zip
  • Was this article helpful?