The Master Plugins workspace provides you the ability to update the Master Plugin version on your Salt master to match the version of SaltStack Config. This feature is supported for both cloud and on-premises deployments. You can also download the latest version of the Master Plugin.

The Master Plugins workspace provides information about the plugin status, plugin version, Salt version, last update JID, and more. The latest version of sseapiclient is also available through the Master Plugins workspace. See Using the API for more information.

The Master Plugin enables your Salt masters to communicate with SaltStack Config. The plugin also includes a variety of settings you can adjust to improve performance. See the Master Plugin configuration settings reference for more information.

RaaS holds the current and previous versions of the Master Plugin. When the Salt master connects to RaaS, the Salt master checks if RaaS has plugin versions it does not have. If the Salt master does not have those plugin versions, the Salt master retrieves the plugins from RaaS and caches them locally in /var/cache/salt/master/plugin_cache/.

The plugin is not updated automatically when a new version of SaltStack Config is available. You must initiate the update process yourself. As a best practice, you should update to the latest version of the plugin when it is available.

The Master Plugin update process relies on Salt's service module and service.running state to restart the Salt master after the plugin update. The service module depends on your distribution's init manager, such as systemd.

Note:

If you are running the Salt master in a container or on a distribution that does not use an init manager, you must manually restart the Salt master after the update. If you do not restart the Salt master, the Master Plugins workspace will report that the Salt master is running an outdated plugin version.

Before you start

Before you can use the Master Plugins workspace, you must complete the following prerequisites:

  • Install the Master Plugin on your Salt master. See Install and configure the Master Plugin for more information.
  • Verify that the Salt master's key has been accepted in the SaltStack Config user interface.
  • Verify that the Salt master is running as root. If the Salt master is running as a non-root user, the update fails.
  • Ensure that your Salt master is running Salt version 3002.1 or later. If your Salt master is running version 3002 or earlier, you must update the Salt version before you can use the Master Plugins workspace. See Upgrade Salt for more information.
  • Ensure that your Salt master is running version 8.11.2 or later of the Master Plugin. If your Salt master is running 8.11.1 or earlier, you must manually upgrade the plugin before you can use the Master Plugins workspace. See Upgrade the Master Plugin using the CLI for more information.

Update the Master Plugin

You can update the Master Plugin version on one or more Salt masters.

Note:

You can only update the Master Plugin version through the Master Plugins workspace if the plugin status is Needs update. If the plugin status indicates that the Salt master requires manual intervention, you must log in to your Salt master to resolve the issue. See Troubleshoot plugin updates for more information.

To update the Master Plugin:

  1. In SaltStack Config, select Administration > Master Plugins.
  2. Select a Salt master with a Needs update plugin status.
  3. Click Update.
  4. Review the information in the dialog box to ensure that you selected the correct Salt master.
  5. Click Update.
  6. To monitor the progress of the update, click the Last update JID.
  7. In the Master Plugins workspace, confirm that the plugin status has changed to Up to date.

    If the update fails, see Troubleshoot plugin updates.

Troubleshoot plugin updates

If your plugin update fails, you must manually resolve the issue by logging in to your Salt master. There is no automated revert for failed plugin updates.

Plugin updates could fail due to:
  • Infrastructure issues
  • Configuration issues with virtual machines
  • Connection issues with the Salt master

Try the following steps to identify the cause for the failed update:

  1. Check the Last update JID and review the raw data for any errors.
  2. Run systemctl status salt-master to check the status of the salt-master service.
  3. Run salt-master -l debug to start the Salt master in debug mode.
  4. Download the Master Plugin from the Master Plugins workspace and manually install the plugin.