Install and configure the Salt Master plugin

Overview

This page explains how to install, configure, and upgrade the Salt Master plugin. The Salt Master plugin enables your masters to communicate with SaltStack Enterprise. The Salt Master plugin includes a variety of settings you can adjust to improve performance, which is particularly useful for large or busy environments. For more information about the Salt Master plugin and how it fits in SaltStack Enterprise architecture, see Salt Master(s) and the Salt Master plugin.

Typically, you install the Salt Master plugin on every Salt Master in your environment that will communicate with SaltStack Enterprise. For example, if you are using a configuration with more than one Salt Master (sometimes called a multi-master setup), each Salt Master needs to the Salt Master plugin.

For more information about updating performance-related settings, see the Salt Master Plugin page in the SaltStack Enterprise Help Documentation embedded in the Enterprise Console. For help finding the documentation, see Finding Enterprise Documentation.

Prerequisites

Installing and configuring the Salt Master plugin is one post-installation step in a series of several steps that should be followed in a specific order. First, complete one of the installation scenarios and then read the Install the license key post-installation page.

When do you need to install the Salt Master plugin?

You need to install the Salt Master plugin on all of your Salt Masters after a fresh installation of SaltStack Enterprise. The Salt Master plugin is not necessary on Salt Masters that do not need to communicate with SaltStack Enterprise.

If you used the Single-node installation installation scenario, you do not need to install the Salt Master plugin on the node on which you installed SaltStack Enterprise and its related architecture. The installer automatically installs the Salt Master plugin on the Salt Master node. However, the Salt Master plugin is installed only on the Salt Master where you ran the installer. If you have multiple Salt Masters, you still need to install the Salt Master plugin on your other Salt Masters.

If you recently upgraded to a newer version of SaltStack Enterprise, you should also re-install the Salt Master plugin. For the full instructions on upgrading and installing the Salt Master plugin after an upgrade, see Upgrade from a previous version.

If you are manually installing SaltStack Enterprise (not recommended), you should complete the following before you install the Salt Master plugin:

  • Install and configure the PostgreSQL database
  • Install and configure the Redis database
  • Enable SSL (optional)

Install the Salt Master plugin

To install the Salt Master plugin on your Salt Master:

  1. Log in to your Salt Master.

  2. If necessary, download the Salt Master plugin wheel. See Downloads.

  3. Install the Salt Master plugin by manually installing the updated Python wheel. Use the following example commands, replacing the exact name of the wheel file:

    sudo pip3 install SSEAPE-file-name.whl --prefix /usr
    
    sudo pip3 install SSEAPE-file-name.whl
    

    Note

    Some users might need to alter the syntax to pip3.6 or pip36 for their operating systems.

After installing the Salt Master plugin, proceed to the next section.

Configure the Salt Master plugin

To configure the Salt Master after installing the Salt Master plugin:

  1. Log in to your Salt Master and verify the /etc/salt/master.d directory exists, or create it.

  2. Generate the master configuration settings.

    Danger

    If you want to preserve your settings when upgrading your installation, make a backup of your existing master plugin configuration file before running this step. Then copy relevant settings from your existing configuration to the newly generated file.

    sudo sseapi-config --all > /etc/salt/master.d/raas.conf
    

    If running this command causes an error, it might be related to the method you used when initially installing Salt. If you installed Salt through the all-in-one installer, your SaltStack Enterprise installation likely includes an offline packager, called the Salt Crystal, that requires special upgrade instructions. For more information, see Troubleshooting.

  3. Edit the generated raas.conf file and update the values as follows to validate the certificate the Enterprise API users and set its IP address.

    Value Description
    sseapi_ssl_validate_cert

    Validates the certificate the Enterprise API uses. The default is True.

    If you are using your own CA-issued certificates, set this value to True and configure the sseapi_ssl_ca, sseapi_ssl_cert, and sseapi_ssl_cert: settings.

    Otherwise, set this to False to not validate the certificate.

    sseapi_ssl_validate_cert: False
    
    sseapi_server HTTP IP address of your Enterprise API (RaaS) node, for example, http://example.com, or https://example.com if SSL is enabled.
  4. OPTIONAL: This step is necessary for manual installations only. To verify you can connect to SSL before connecting the Salt Master plugin, edit the generated raas.conf file to update the following values. If you do not update these values, the Salt Master plugin uses the default generated certificate.

    Value Description
    sseapi_ssl_ca The path to a CA file.
    sseapi_ssl_cert The path to the certificate. The default value is /etc/pki/raas/certs/localhost.crt.
    sseapi_ssl_key The path to the certificate’s private key. The default value is /etc/pki/raas/certs/localhost.key.
    id Comment this line out by adding a # at the beginning. It is not required.
  5. Restart the Salt Master.

    sudo systemctl restart salt-master
    
  6. OPTIONAL: You might want to run a test job to ensure the Salt Master plugin is now enabling communication between the Salt Master and the Enterprise API (RaaS) node.

    salt -v '*' test.ping
    

Even if no activity shows, for example because no minions are connected, this is likely a sign of a correct configuration.

Next steps

After installing and configuring the Salt Master plugin, you must complete additional post-installation steps. The next step is to log in to the Enterprise Console for the first time. To continue the post-installation process, see Log in for the first time and change default credentials.