Pre-installation planning

Overview

This topic contains the pre-installation planning checklist. It is a series of questions you need to answer and decisions you need to make before you begin your SaltStack Enterprise installation project. This topic also provides some guidance about how to answer those questions and make those key decisions.

Prerequisites

The topics in the SaltStack Enterprise installation process are intended to be read and followed in a specific order. Before you begin the installation process, first read the Installation overview topic.

This topic is the first step in the pre-installation process.

Which installation scenario should you use?

The SaltStack Enterprise installer supports two core installation scenarios:

The following sections provide detailed descriptions of these two installation scenarios. As you read the descriptions and decide which installation scenario is appropriate for your network, the key questions to answer are:

  • How many nodes does your network have? Will SaltStack Enterprise manage all these nodes?
  • Does your network have high availability needs, such as load balancing and automatic failover?
  • What is your purpose for installing SaltStack Enterprise? For example, are you installing SaltStack Enterprise as a trial run before deploying to production?

Single-node installation

In the single-node installation scenario, you install SaltStack Enterprise on a single node (server) using the SaltStack Enterprise installer. After installation, a Salt Master, the SaltStack Enterprise API server, a Redis database, and a PostgreSQL database all run on this same node.

Use the single-node installation scenario if:

  • Your network has 1,000 minions or less (nodes that Salt will manage).
  • You want to quickly install SaltStack Enterprise and evaluate it first-hand before deploying it to production. (Later when you deploy to production, you can use the multi-node installation.)

The advantages of the single-node installation scenario are:

  • It is easy and simple to install.
  • It is easy to maintain since SaltStack Enterprise and all of its dependencies are on the same node.

The disadvantages are:

  • Single-node installation is not recommended for production grade systems.
  • Your SaltStack Enterprise system is reliant on the availability of a single node. If that node goes down, your SaltStack Enterprise ecosystem goes down as well.

Multi-node installation

In the multi-node installation scenario, you install SaltStack Enterprise on multiple nodes (servers) using the SaltStack Enterprise installer. In this installation scenario, the end goal is to have four nodes, each with a different host function. Each node is also a minion to the master:

  • A Salt Master
  • A PostgreSQL database server
  • A Redis database server
  • A SaltStack Enterprise API server, also known as the RaaS server

In the multi-node installation scenario, you run an orchestration highstate designed by SaltStack. The highstate runs on your Salt Master and sets up the multi-node environment. It installs the core SaltStack Enterprise architecture on the three other nodes that will host PostgreSQL, Redis, and the SaltStack Enterprise API.

Note

It is possible to set up multiple Salt Masters or multiple SaltStack Enterprise API (RaaS) servers. 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. 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.

Use the multi-node installation scenario if:

  • Your network has more than 1,000 nodes (Salt Minions that SaltStack Enterprise will manage). Be aware that this scenario is also appropriate for smaller installations as well.
  • If you are unsure which installation scenario is best for your system, the multi-node installation is the recommended scenario.

The advantages of the multi-node installation scenario are:

  • It can scale as your network grows.
  • It is not dependent on the availability of a single node for functionality.
  • This installation scenario can support networks with high availability needs, such as load balancing and automatic failover.

The disadvantages are:

  • The installation process is more complex, requiring careful planning and thought.
  • If your network has high availability needs, you might need support and/or consultation services from SaltStack.

What system architecture do you need?

The system architecture required to install SaltStack Enterprise depends on whether you are using the single-node or multi-node installation scenario. For guidance in selecting an installation scenario, see Which installation scenario should you use?.

The following sections describe the requirements for each installation scenario.

Single-node installation requirements

In the single-node installation scenario, you install SaltStack Enterprise on a single node (server) using the SaltStack Enterprise installer. After installation, a Salt Master, SaltStack Enterprise, a Redis database, and a PostgreSQL database all run on this same node.

A single-node installation requires:

Hardware Up to 1,000 nodes (minions)
Cores 8 CPU cores
RAM 16 GB RAM
Disk space At least 40 GB free space

The disk space is used for minion return data. Increase according to your needs for data retention.

Multi-node installation requirements

In the multi-node installation scenario, install SaltStack Enterprise on multiple nodes (servers) using the SaltStack Enterprise installer. In this installation scenario, the end goal is to have four nodes, each with a different host function:

  • A Salt Master
  • A PostgreSQL database server
  • A Redis database server
  • A SaltStack Enterprise API server, also known as the RaaS server

Alternatively, you can run the Salt Master service on one node, and combine two or more of the other services on a separate node. Custom architecture requirements may require consultation services.

Before beginning a multi-node installation, ensure that you have requested the necessary nodes and virtual machines (VMs) needed for this scenario.

A multi-node installation requires:

Host 1,000 to 2,500 nodes (minions) 2,500 to 5,000 nodes (minions) Greater than 5,000 nodes (minions)
Salt Master node

4 CPU cores

8 GB RAM

8 CPU cores

16 GB RAM

Consider multiple masters
SaltStack Enterprise API node (RaaS)

4 CPU cores

8 GB RAM

8 CPU cores

16 GB RAM

Create an additional SaltStack Enterprise node per 5000 minions, hosted behind your preferred load-balancing solution
Redis node

2 CPU cores

4 GB RAM

4 CPU cores

8 GB RAM

Increase Redis CPU cores and RAM, as indicated by performance
PostgreSQL node

4 CPU cores

8 GB RAM

At least 40 GB free disk space

8 CPU cores

16 GB RAM

At least 80 GB free disk space

Increase PostgreSQL CPU cores and RAM, as indicated by performance

The disk space is used for minion return data. Increase according to your needs for data retention.

Note

The Redis and the PostgreSQL hosts need static IP addresses or DNS names and the configuration files need to reference those static IP addresses or DNS names. Depending on how the SaltStack Enterprise API host 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.

Which operating system do you need?

SaltStack Enterprise 6.3.0 is best designed to operate on either:

  • RedHat 7.4 or higher (RHEL 7)
  • CentOS 7 (Cent7)

Attention

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 through a yum update or your server does not have direct Internet access, retrieve the following packages from RedHat 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

SaltStack Enterprise also supports the following operating systems, although they are not recommended:

  • Oracle Linux 7
  • SUSE Linux Enterprise Server 15 (SLES 15)
  • SUSE Linux Enterprise Server 12 (SLES 12)

Important

This list of supported operating systems refers to the SaltStack Enterprise API server (RaaS). It does not refer to the operating systems for the Salt Masters in your network. Salt itself is designed to be operating system agnostic and can manage the nodes of most standard operating systems. For a list of supported Salt Master operating systems, see SaltStack Platform Support.

Which version of PostgreSQL do you need?

SaltStack Enterprise requires a PostgreSQL 9.6 database, but PostgreSQL 12.1 is recommended. The recommended version of PostgreSQL is included with the SaltStack Enterprise installer.

PostgreSQL is a third-party open source database that is required for SaltStack Enterprise. Because this is third-party software, be aware of the following:

Does your network have access to the Internet?

Some networks do not have consistent access to the Internet for various reasons. These systems are also referred to as air-gapped systems. Air-gapped systems pose particular challenges both for installing SaltStack Enterprise and for ensuring it is up to date.

If you are installing SaltStack Enterprise in an air-gapped system, be aware that the installation process will require greater planning and preparation on the part of you and your organization.

The folllowing section explains a few potential challenges for your consideration as you are planning your installation. For additional advice on how organizations similar to yours have solved these challenges, Contact Support.

Plan how to transfer the installation files

In order to complete the installation, you need a mechanism through which to download, verify, and extract the necessary installation files. If downloading files is impossible in your network, you need to brainstorm and prepare an alternate method to transfer the necessary installation files to the nodes on which you are installing SaltStack Enterprise and its dependencies.

You will need to transfer the files to the node(s) involved in the installation process. Place the files in the root folder.

Note

For a single-node installation, transfer the files to the node on which you are installing a Salt Master, SaltStack Enterprise, Redis, and PostgreSQL.

For a multi-node installation, transfer the files to the Salt Master from which you are running the installation orchestration.

For a list of downloads, see Downloads.

Plan how to manage upgrades

SaltStack Enterprise and its dependencies (Salt, PostgreSQL, etc.) release regular updates with enhanced features and security updates. In order to take advantage of these updates, you need to plan to check for updates and install upgrades whenever they are available.

Plan how to update security libraries

Both SaltStack Comply and SaltStack Protect release regular content library updates with the latest compliance and vulnerability content. These content libraries are updated outside of the regular SaltStack Enterprise release schedule.

Ideally, customers can automatically download and ingest security libraries over the Internet as soon as they are updated. However, it is also possible to manually download and ingest these libraries. In order to take advantage of these updates, you need to plan to check for security content updates and you need to develop a process to manually ingest this content when it is available.

Which version of Salt and Python do you need?

SaltStack Enterprise packages its own Python 3.7. It doesn’t use the Python installed on your operating systems and it does not require it to be up to date. However, it is generally recommended that you run the latest version of Python on your system.

SaltStack Enterprise is compatible with most versions of Salt, although it is strongly recommended to run the latest stable versions of Salt on your Salt Master.

If you plan to use SaltStack Comply with Windows servers, these Windows minions must run Salt 3000 or later.

Do you need to install Salt prior to installation?

In an installation context, installing Salt can have two different meanings:

  • Installing Salt on the nodes involved in the SaltStack Enterprise installation in either a Single-node installation or Multi-node installation scenario.
  • Installing Salt on the infrastructure that will eventually be managed by SaltStack Enterprise.

Salt is necessary to run the SaltStack Enterprise installation. At a bare minimum, Salt and its dependencies must be installed on the nodes that are involved in either SaltStack Enterprise installation scenario. For instructions about how to install Salt and its dependencies, see Install or upgrade Salt.

As for installing Salt on the infrastructure that will eventually be managed by SaltStack Enterprise, installing Salt beforehand is a best practice and is strongly recommended. Installing Salt simplifies and streamlines the process of updating to future versions of Salt. Before you begin your SaltStack Enterprise installation, consider installing Salt on your infrastructure and then monitoring it for a period of time to ensure it is stable and running as expected. For instructions about installing Salt, see Install or upgrade Salt.

The one exception to this recommendation is if you are installing SaltStack Enterprise in an air-gapped system, as explained in the following section.

Installing Salt in an air-gapped system

This section explains the trade-offs of installing Salt on your infrastructure in an air-gapped system.

The SaltStack Enterprise installer can install the latest stable version of Salt as it runs. However, the version of Salt that is installed by the SaltStack Enterprise installer is called the Salt Crystal package. This package is primarily intended for use in air-gapped systems where it is not possible to update Salt over the Internet. Because it is intended for use in air-gapped systems, the version of Salt in the Salt Crystal package cannot be updated over the Internet and must be manually updated. For information about updating the Salt Crystal package, see Upgrading Salt Crystal.

As the SaltStack Enterprise installer runs in the single-node installation scenario, it detects whether Salt has already been installed on the node. If it detects the Salt Master and Salt Minion software, the SaltStack Enterprise installer skips that step in the installation process. If it does not detect Salt, it installs the Salt Master and Salt Minion software from the Salt Crystal package.

The inability to update Salt regularly over the Internet could become problematic for your network unless your network is air-gapped. For that reason, it is strongly recommended that you install Salt beforehand rather than using the Salt Crystal package.

Do you need to update Python and Salt prior to installation?

Ensure you have the latest stable version of Salt and that you are running Python 3.5.3 or higher on the node that will host the Enterprise API server (RaaS).

It is best to update to the latest version of Salt if possible. For instructions about upgrading Python and Salt, see Upgrade Salt and Python.

Warning

Certain Salt dependencies must be installed in order to prevent a failure in either a Single-node installation or Multi-node installation scenario. To verify that these dependencies are installed, see Install or upgrade Salt.

What changes are made to an existing Salt environment?

If your network deployed Salt extensively before you decided to install SaltStack Enterprise, be aware of the following changes that occur to your Salt environment when installing SaltStack Enterprise:

  • Enterprise API backend services (file system, pillar store, and so on) take precedence over any other existing backends defined in your environment. You can continue to use all supported backend services. However, files that exist in the Enterprise Console will take precedence if they also exist in other file or pillar backends. For information about changing this behavior, see the Configuration topic in the SaltStack Enterprise Enterprise Help docs.
  • Enterprise API replaces the Salt Master syndic component to provide Salt Minion aggregation and scale. Salt Syndic Masters are not compatible with the SaltStack Enterprise architecture. Instead, each root Salt Master connects directly to the Enterprise API.

Existing Salt States, configuration settings, and Salt Minion connections are unchanged. No changes are required on the Salt Minion to use SaltStack Enterprise.

Which browser does the Enterprise Console need?

The Enterprise Console supports the latest versions of Google Chrome and Mozilla Firefox.

How does licensing for SaltStack Enterprise work?

SaltStack Enterprise requires a license file to track minion usage and duration of contract.

Important

The SaltStack Enterprise download contains a 14-day trial license. After 14 days the Enterprise API service no longer starts.

Customers receive a license file with the Welcome letter from SaltStack Support. If you are a current customer and have not received a license file, or if you encounter any issues with the licensing process, Contact Support.

Before 14 days, your license file must be placed on your SaltStack Enterprise server (RaaS) at /etc/raas/raas.license for continued functionality. This step is required as part of the post-installation phase. For more information, see Install the license key.

Next steps

Once you have solidified your installation plan, you must complete additional pre-installation steps. The next step is to ensure you have installed or updated Salt and its dependencies. To continue the pre-installation process, Install or upgrade Salt.