Pre-installation planning

Overview

This page 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 Config installation project. This page also provides some guidance about how to answer those questions and make those key decisions.

Note

As part of VMware’s initiative to remove problematic terminology, the term Salt master will be replaced with Salt controller in SaltStack Config and related products and documentation. This terminology update may take a few release cycles before it is fully complete.

Prerequisites

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

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

Which installation scenario should you use?

The SaltStack Config 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 Config 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 Config? For example, are you installing SaltStack Config as a trial run before deploying to production?

Single-node installation

In the single-node installation scenario, you install SaltStack Config on a single node (server) using the SaltStack Config installer. After installation, a Salt controller (formerly called the Salt master), the RaaS node, 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 Config 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 Config 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 Config system is reliant on the availability of a single node. If that node goes down, your SaltStack Config ecosystem goes down as well.

Multi-node installation

In the multi-node installation scenario, you install SaltStack Config on multiple nodes (servers) using the SaltStack Config 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 Salt controller:

  • A Salt controller (formerly called the Salt master)
  • A PostgreSQL database node
  • A Redis database node
  • A RaaS node, also known as SaltStack Config

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

Note

It is possible to set up multiple Salt controllers or multiple RaaS nodes. It is also possible to run the Salt controller 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 (minions that SaltStack Config 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 Config 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 Config on a single node (server) using the SaltStack Config installer. After installation, a Salt controller (formerly called the Salt master), SaltStack Config, 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 Config on multiple nodes (servers) using the SaltStack Config installer. In this installation scenario, the end goal is to have four nodes, each with a different host function:

  • A Salt controller (formerly called the Salt master)
  • A PostgreSQL database server
  • A Redis database server
  • A RaaS node, also known as SaltStack Config

Alternatively, you can run the Salt controller 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 Salt controllers
RaaS node

4 CPU cores

8 GB RAM

8 CPU cores

16 GB RAM

Create an additional SaltStack Config 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 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.

Which operating system do you need?

SaltStack Config 8.3.0 is best designed to operate on either:

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

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 Config 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 RaaS node. It does not refer to the operating systems for the Salt masters (former called 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 controller (formerly called the Salt master) operating systems, see SaltStack Platform Support.

Which version of PostgreSQL do you need?

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

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

Which version of Redis do you need?

SaltStack Config requires a Redis 5.x database, but Redis 5.0.4 is recommended. The recommended version of Redis is included with the SaltStack Config installer.

Redis is a third-party, open source, in-memory data structure store. It is required for SaltStack Config. Because this is third-party software, be aware of the following:

  • You are responsible for ongoing maintenance and other administrative tasks. For information about Redis database maintenance and administration, see the Redis documentation.
  • Consider getting guidance from your organization’s database administrator, if possible.

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 Config and for ensuring it is up to date.

If you are installing SaltStack Config 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 following 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 Config 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 controller (formerly called the Salt master), SaltStack Config, Redis, and PostgreSQL.

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

For a list of downloads, see Downloads.

Plan how to manage upgrades

SaltStack Config 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 SaltStack SecOps libraries

Both SaltStack SecOps libraries release regular content updates with the latest compliance and vulnerability content. These content libraries are updated outside of the regular SaltStack Config release schedule.

Ideally, customers can automatically download and ingest security libraries over the Internet or via an http proxy 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 a plan to check for security content updates regularly, and develop a process to manually ingest this content when it is available.

Which version of Salt and Python do you need?

SaltStack Config 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 Config is compatible with most versions of Salt, although it is strongly recommended to run the latest stable versions of Salt on your Salt controller.

If you plan to use SaltStack SecOps 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 Config installation in either a Single-node installation or Multi-node installation scenario.
  • Installing Salt on the infrastructure that will eventually be managed by SaltStack Config.

Salt is necessary to run the SaltStack Config installation. At a bare minimum, Salt and its dependencies must be installed on the nodes that are involved in either SaltStack Config 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 Config, 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 Config 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 Config 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 Config installer can install the latest stable version of Salt as it runs. However, the version of Salt that is installed by the SaltStack Config 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 Config installer runs in the single-node installation scenario, it detects Salt controller service and minion service packages, the SaltStack Config installer skips that step in the installation process. If it does not detect Salt, it installs the Salt controller service and minion service 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 RaaS node.

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 Config, be aware of the following changes that occur to your Salt environment when installing SaltStack Config:

  • RaaS 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 SaltStack Config user interface will take precedence if they also exist in other file or pillar backends. For information about changing this behavior, see the Configuration page in the SaltStack Config Enterprise Help docs.
  • RaaS replaces the Salt controller (formerly called the Salt master) syndic component to provide minion aggregation and scale. Salt Syndic Salt controllers are not compatible with the SaltStack Config architecture. Instead, each root Salt controller connects directly to RaaS.

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

Which browser does the SaltStack Config user interface need?

The SaltStack Config user interface supports the latest versions of Google Chrome and Mozilla Firefox.

How does licensing for SaltStack Config work?

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

Important

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

Customers receive a license file with the Welcome letter from 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 RaaS node 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.