Install and configure the Master Plugin

As part of the post-installation process, you need to install, configure, and upgrade the Master Plugin. The Master Plugin enables your Salt masters to communicate with SaltStack Config. The Master Plugin includes a variety of settings you can adjust to improve performance, which are particularly useful for large or busy environments.

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

For more information about updating performance-related settings, see the Master Plugin page in the SaltStack Config product documentation.

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

Before you start

Installing and configuring the 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 Master Plugin?

You need to install the Master Plugin on all of your masters after a fresh installation of SaltStack Config. The Master Plugin is not necessary on masters that do not need to communicate with SaltStack Config.

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

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

If you are manually installing SaltStack Config (not recommended), you should complete the following before you install the Master Plugin:

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

Install the Master Plugin

To install the Master Plugin on your Salt master:

Log in to your master.
If necessary, download the Master Plugin wheel from Customer Connect.
Install the Master Plugin by manually installing the updated Python wheel. Use the following example commands, replacing the exact name of the wheel file:
RHEL/CentOS
```
sudo pip3 install SSEAPE-file-name.whl --prefix /usr
```
Ubuntu
```
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.

Configure the Master Plugin

To configure the master after installing the Master Plugin:

Log in to your master and verify the /etc/salt/master.d directory exists, or create it.
Generate the master configuration settings.
Caution: 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 SaltStack Config installer, your installation likely includes an offline package, called the Salt Crystal, that requires special upgrade instructions. For more information, see the Troubleshooting page.

Edit the generated raas.conf file and update the values as follows to validate the certificate the API (RaaS) uses and set its IP address.


Value	Description
`sseapi_ssl_validate_cert`	Validates the certificate the API (RaaS) 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 RaaS node, for example, `http://example.com`, or `https://example.com` if SSL is enabled.
`sseapi_command_age_limit`	Sets the age (in seconds) after which old, potentially stale jobs are skipped. For example, to skip jobs older than a day, set it to: sseapi_command_age_limit:86400 Skipped jobs will continue to exist in the database and display with a status of `Completed` in the SaltStack Config user interface. Some environments may need the Salt master to be offline for long periods of time and will need the Salt master to run any jobs that were queued after it comes back online. If this applies to your environment, set the age limit to `0`.

OPTIONAL: This step is necessary for manual installations only. To verify you can connect to SSL before connecting the Master Plugin, edit the generated raas.conf file to update the following values. If you do not update these values, the 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.

OPTIONAL: Update performance-related settings. For large or busy environments, you can improve the performance of the communications between the Salt master and SaltStack Config by adjusting the following settings.
- Enable event queuing (available in salt 2019.2.2 and later). Events can be queued on the Salt master and sent to the event returner in a batched fashion using a single transaction for multiple events. By default, this queuing mechanism is disabled. To enable event queuing, set the following in your Salt Master Plugin configuration file:
```
event_return_queue:2500
event_return_queue_max_seconds:5
```
  The suggested maximum event queue size is 2500 as shown. The queue will be flushed, forwarding events to the event returner, when the queue is full. A lower value may be a better fit for smaller or less busy environments.
  In some cases, the Salt event bus may not busy enough to cause the queue to regularly reach its maximum size. Setting event_return_queue_max_seconds will cause the queue to be flushed when the oldest event in the queue is older than the configured value regardless of how many events are in the queue.
- Enable and configure the eventqueue and rpcqueue engines:
  These engines offload some communications with SaltStack Config from performance-critical code paths to dedicated processes. While the engines are waiting to communicate withSaltStack Config, payloads are stored in the Salt master’s local filesystem so the data can persist across restarts of the Salt master.
  To enable the engines, uncomment the following settings in the Salt Master Plugin configuration file (raas.conf):
```
engines:
  - sseapi: {}
  - eventqueue: {}
  - rpcqueue: {}
  - jobcompletion: {}
```
  To configure the eventqueue engine, uncomment and update the following settings:
```
sseapi_event_queue:
  name: sseapi-events
  strategy: always
  push_interval: 5
  batch_limit: 2000
  age_limit: 86400
  size_limit: 35000000
  vacuum_interval: 86400
  vacuum_limit: 350000
  forward: []
```
  The queue parameters can be adjusted with consideration to how they work together. For example, assuming an average of 400 events per second on the Salt event bus, the settings shown above allow for about 24 hours of queued event traffic to collect on the Salt master before the oldest events are discarded due to size or age limits.
  To configure the rpcqueue engine, uncomment and update the following settings:
```
sseapi_rpc_queue:
    name: sseapi-rpc
    strategy: always
    push_interval: 5
    batch_limit: 500
    age_limit: 3600
    size_limit: 360000
    vacuum_interval: 86400
    vacuum_limit: 100000
```
- Enable load caching:
```
sseapi_local_cache:
    load:3600
```
  Note: If the rpcqueue engine is enabled, load caching must also be enabled in order for the Salt master to handle jobs correctly.
- Limit minion grains payload sizes:
```
sseapi_max_minion_grains_payload:2000
```
- Enable skipping jobs that are older than a defined time (in seconds). For example, use 86400 to set it to skip jobs older than a day. When set to 0, this feature is disabled:
```
sseapi_command_age_limit:0
```
  Note:
  This is useful during upgrade, to prevent old commands stored in the database from running unexpectedly.
Together, event queuing in Salt and the queuing engines, load caching, grains payload size limit, and command age limit in the Salt Master Plugin increase the throughput and reduce the latency of communications between the Salt master and SaltStack Config in the most performance-sensitive code paths.
Restart the master service.
```
sudo systemctl restart salt-master
```
OPTIONAL: You might want to run a test job to ensure the Master Plugin is now enabling communication between the master and the RaaS node.
```
salt -v '*' test.ping
```

Even if no activity shows, such as if no minions are connected, this is likely a sign of a correct configuration.

Configuration settings reference

These settings in the configuration file enable each Salt master to connect to the API (RaaS). You can find these settings in the /etc/salt/master.d/raas.conf configuration file.

Important:

Salt master settings in the raas.conf file take precedence over existing settings in /etc/salt/master. If you have customized the fileserver_backend or ext_pillar settings in /etc/salt/master, you need to manually merge these settings so that they appear in one file only. You can optionally re-order the backends to change precedence.

The following table explains the general configuration settings:


Option	Description
`id`	Salt master ID, autogenerated if not set
`sseapi_server`	URL of SSEAPI server, e.g. `https://sse.example.com:443`
`engines`	Salt engines to enable, recommend `sseapi`, `jobcompletion`, `eventqueue`, and `jobcompletion`
`master_job_cache`	`sseapi` to use the SaltStack Config master job cache
`event_return`	Salt event returner, recommend `sseapi` to use the SaltStack Config event returner
`ext_pillar`	external pillar sources, recommended `sseapi`
`fileserver_backend`	file server backends, recommended `sseapi` and `roots`
`sseapi_update_interval`	how frequently to update from file server (seconds, default 60)
`sseapi_poll_interval`	how frequently to poll SaltStack Config for new data (seconds, default 30)
`sseapi_timeout`	timeout for API (RaaS) calls (seconds, default 200)
`sseapi_pubkey_path`	path to public key file for authenticating the Salt master to SaltStack Config
`sseapi_key_rotation`	Salt master SaltStack Config authentication key rotation interval (seconds, default 86400)
`sseapi_cache_pillar`	whether to cache pillar data within SaltStack Config (True or False, default False)
`sseapi_cluster_id`	(optional) Salt master cluster name, for grouping Salt masters into clusters within SaltStack Config
`sseapi_failover_master`	whether this Salt master is a failover Salt master (True or False, default False)
`sseapi_command_age_limit`	whether to skip API (RaaS) commands older than a defined time (seconds, 0 to disable, default 0)

The following table explains the SSL settings:


Option	Description
`sseapi_ssl_key`	path to the certificate’s private key
`sseapi_ssl_cert`	path to the certificate
`sseapi_ssl_validate_cert`	whether to validate the SaltStack Config SSL certificate (True or False, default True)

The following table explains the Event Queue Engine settings, which appear under the sseapi_event_queue heading:


Option	Description
`name`	Event queue name (default `sseapi-events`, no need to change this)
`strategy`	When to queue events (`always`, `on_failure`, or `never`, default `never`)
`push_interval`	How often to push events to SaltStack Config (seconds, default 5)
`batch_limit`	Maximum number of events to push to SaltStack Config per interval (default 2000)
`age_limit`	Maximum queued event age; drop oldest events (seconds, default 86400)
`size_limit`	Maximum queue size; drop oldest events (events, default 35000000)
`vacuum_interval`	How often to vacuum the queue database (seconds, default 86400)
`vacuum_limit`	Maximum queue size when vacuuming the queue database (events, default 350000)
`forward`	Additional salt returners to send events to when flushing the queue (default none) The `forward` configuration item can specify a list of one or more Salt returner names. Each time the event queue is flushed, queued events will be sent to SaltStack Config as well as to each returner in this list. This enables the eventqueue engine’s queueing and persistence functionality to be added to any standard Salt returner. The following is a configuration excerpt that causes events to be written to a local file each time they are sent to SaltStack Config: sseapi_event_queue: # ...other queue settings... forward: - rawfile_json # rawfile_json returner configuration rawfile_json.filename: /var/log/salt/events.json

The following table explains the RPC Queue Engine settings, which appear under the sseapi_rpc_queue heading:


Option	Description
`name`	Event queue name (default `sseapi-rpc`, no need to change this)
`strategy`	When to queue events (`always`, `on_failure`, or `never`, default `never`)
`push_interval`	How often to send calls to SaltStack Config (seconds, default 5)
`batch_limit`	Maximum number of calls to push to SaltStack Config per interval (default 500)
`age_limit`	Maximum queued call age; drop oldest entries (seconds, default 3600)
`size_limit`	Maximum queue size; drop oldest entries (events, default 360000)
`vacuum_interval`	How often to vacuum the queue database (seconds, default 86400)
`vacuum_limit`	Maximum queue size when vacuuming the queue database (entries, default 100000)

The following table explains the Path settings. After initial configuration generation be careful changing these settings. Modules will be copied into these directories from the installation process. However, adding extra paths will not have an adverse effect.


Option	Description
`beacons_dirs`	beacons External Modules Path(s)
`engines_dirs`	engines External Modules Path(s)
`fileserver_dirs`	fileserver External Modules Path(s)
`pillar_dirs`	pillar External Modules Path(s)
`returner_dirs`	returner External Modules Path(s)
`roster_dirs`	roster External Modules Path(s)
`runner_dirs`	runner External Modules Path(s)
`module_dirs`	Salt External Modules Path(s)
`proxy_dirs`	proxy External Modules Path(s)
`metaproxy_dirs`	metaproxy External Modules Path(s)
`states_dirs`	states External Modules Path(s)

What to do next

After installing and configuring the Master Plugin, you must complete additional post-installation steps. The next step is to configure the RaaS node. To continue the post-installation process, see Check the RaaS configuration file.