.. _pre-installation: ========================= 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 |sse| installation project. This page also provides some guidance about how to answer those questions and make those key decisions. Prerequisites ============= The pages in the |sse| installation process are intended to be read and followed in a specific order. Before you begin the installation process, first read the :ref:`overview` page. This page is the first step in the pre-installation process. .. _which-installation-scenario: Which installation scenario should you use? =========================================== The |sse| installer supports two core installation scenarios: * :ref:`installation-single-node` * :ref:`installation-multi-node` 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 |sse| manage all these nodes? * Does your network have high availability needs, such as load balancing and automatic failover? * What is your purpose for installing |sse|? For example, are you installing |sse| as a trial run before deploying to production? .. Other places where the two installation scenarios are described: .. The Installation overview topic and the two installation scenarios themselves .. Make sure that these descriptions sync. Single-node installation ------------------------ In the single-node installation scenario, you install |sse| on a single node (server) using the |sse| installer. After installation, a 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 |sse| 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 |sse| and all of its dependencies are on the same node. The disadvantages are: * Single-node installation is not recommended for production grade systems. * Your |sse| system is reliant on the availability of a single node. If that node goes down, your |sse| ecosystem goes down as well. Multi-node installation ----------------------- In the multi-node installation scenario, you install |sse| on multiple nodes (servers) using the |sse| 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 node * A Redis database node * An |api| node, also known as the RaaS node 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 |sse| architecture on the three other nodes that will host PostgreSQL, Redis, and the |raas|. .. Note:: 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. 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 |sse| 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 |sse| 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 |sse| on a single node (server) using the |sse| installer. After installation, a Salt Master, |sse|, a Redis database, and a PostgreSQL database all run on this same node. A single-node installation requires: .. list-table:: :widths: 20 50 :header-rows: 1 * - 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 |sse| on multiple nodes (servers) using the |sse| 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 * An |api| node, also known as the RaaS node 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: .. list-table:: :widths: 25 25 25 25 :header-rows: 1 * - 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 |raas| node** - 4 CPU cores 8 GB RAM - 8 CPU cores 16 GB RAM - Create an additional |sse| 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-os-do-you-need: Which operating system do you need? =================================== .. include:: _includes/operating-systems.rst Which version of PostgreSQL do you need? ======================================== .. include:: _includes/latest-postgres-version.rst PostgreSQL is a third-party open source database that is required for |sse|. Because this is third-party software, be aware of the following: * You are responsible for ongoing maintenance, backups, and other administrative tasks. For information about PostgreSQL database maintenance and administration, see the `PostgreSQL documentation `_. * Consider getting guidance from your organization's database administrator, if possible. * For a SaltStack guide on PostgreSQL tuning, see `Tuning your PostgreSQL Server for SaltStack Enterprise `_. .. Do we need a similar warning for Redis? 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 |sse| and for ensuring it is up to date. If you are installing |sse| 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, :ref:`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 |sse| 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, |sse|, 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 :ref:`downloads`. Plan how to manage upgrades --------------------------- |sse| 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 |comply| and |protect| release regular content library updates with the latest compliance and vulnerability content. These content libraries are updated outside of the regular |sse| 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? ============================================= |sse| 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. |sse| 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 |comply| with Windows servers, these Windows minions must run Salt 3000 or later. .. _is-salt-installed: 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 |sse| installation in either a :ref:`installation-single-node` or :ref:`installation-multi-node` scenario. * Installing Salt on the infrastructure that will eventually be managed by |sse|. Salt is necessary to run the |sse| installation. At a bare minimum, Salt and its dependencies must be installed on the nodes that are involved in either |sse| installation scenario. For instructions about how to install Salt and its dependencies, see :ref:`install-salt`. As for installing Salt on the infrastructure that will eventually be managed by |sse|, 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 |sse| 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 :ref:`install-salt`. The one exception to this recommendation is if you are installing |sse| 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 |sse| installer can install the latest stable version of Salt as it runs. However, the version of Salt that is installed by the |sse| 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 |sse| 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 |sse| 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. .. _is-salt-updated: 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 :ref:`update-salt`. .. Warning:: Certain Salt dependencies must be installed in order to prevent a failure in either a :ref:`installation-single-node` or :ref:`installation-multi-node` scenario. To verify that these dependencies are installed, see :ref:`install-salt`. What changes are made to an existing Salt environment? ====================================================== If your network deployed Salt extensively before you decided to install |sse|, be aware of the following changes that occur to your Salt environment when installing |sse|: * |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 |console| 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 |sse| Enterprise Help docs. * |raas| replaces the Salt Master `syndic `_ component to provide Salt Minion aggregation and scale. Salt Syndic Masters are not compatible with the |sse| architecture. Instead, each root Salt Master connects directly to the |api|. Existing Salt States, configuration settings, and Salt Minion connections are unchanged. No changes are required on the Salt Minion to use |sse|. .. _supported-browsers: Which browser does the |console| need? ====================================== The |console| supports the latest versions of Google Chrome and Mozilla Firefox. How does licensing for |sse| work? ================================== |sse| requires a license file to track minion usage and duration of contract. .. Important:: The |sse| download contains a 14-day trial license. After 14 days the |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, :ref:`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 :ref:`install-license`. 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, :ref:`install-salt`.