To set up and verify your SaltStack Config Cloud instance, you install Salt and the Master Plugin on your Salt master, generate an API token in the Cloud Services Console, and then connect your Salt master to SaltStack Config Cloud. You can connect Salt masters that are on-premises or in the cloud.

Prerequisites

Before you set up SaltStack Config Cloud, you must complete the following prerequisites:
  • Verify that you have the following roles in VMware Cloud Services:
    • Organization role: Organization Owner or Organization Admin
    • Service role: Superuser for the SaltStack Config Cloud service
  • Set your default organization to the organization with access to the SaltStack Config Cloud service.

Setup overview

Setting up SaltStack Config Cloud includes the following tasks.

  1. Install Salt on your Salt master and the nodes you intend to manage using SaltStack Config Cloud. See Step 1: Install Salt for more information.
  2. Install or upgrade the Master Plugin on the Salt masters that must communicate with SaltStack Config Cloud. See Step 2: Install and configure the Master Plugin for more information.
  3. Generate an API token to enable your Salt masters to connect to SaltStack Config Cloud. See Step 3: Generate an API token for more information.
  4. Connect your Salt masters to SaltStack Config Cloud. See Step 4: Connect your Salt masters to SaltStack Config Cloud for more information.
  5. Accept the Salt master keys in the SaltStack Config Cloud user interface. See Step 5: Accept Salt master keys for more information.

Step 1: Install Salt

Before you can use SaltStack Config Cloud, you must install Salt on your Salt master.

You must install the Salt master service and Salt minion service on the Salt master node. The following instructions install the latest Salt release on RHEL 8. For information about installing Salt on other operating systems or Python versions, see the Salt Install Guide.

  1. In the Salt master's terminal, run the following commands to install the Salt Project repository and key:
    sudo rpm --import https://repo.saltproject.io/py3/redhat/8/x86_64/latest/SALTSTACK-GPG-KEY.pub
    curl -fsSL https://repo.saltproject.io/py3/redhat/8/x86_64/latest.repo | sudo tee /etc/yum.repos.d/salt.repo
  2. Run sudo yum clean expire-cache.
  3. Install the salt-minion service and salt-master service on your Salt master:
    sudo yum install salt-master
    sudo yum install salt-minion
  4. Create a master.conf file in the /etc/salt/minion.d directory. In this file, set the Salt master’s IP address to point to itself:
    master: localhost
  5. Start the Salt master service and Salt minion service:
    sudo systemctl enable salt-master && sudo systemctl start salt-master
    sudo systemctl enable salt-minion && sudo systemctl start salt-minion

Step 2: Install and configure the Master Plugin

After you install Salt on your infrastructure, you must install and configure the Master Plugin, which enables your Salt masters to communicate with SaltStack Config Cloud.

If you already have an existing Salt master, upgrade the Master Plugin before connecting your Salt master to SaltStack Config Cloud. See Upgrade the Master Plugin for more information.

To install and configure the Master Plugin:

  1. Log in to your Salt master.
  2. Install the PyJWT library and the Pika Python library on your Salt master using the following commands:
    salt-call --local pip.install pika==1.2.0 target='/usr'
    salt-call --local pip.install pyjwt==2.3.0 target='/usr'
  3. If necessary, download the Master Plugin wheel from Customer Connect.

    The Master Plugin is included in the Automated Installer .tar.gz file. After you download and extract the .tar.gz file, you can find the Master Plugin in the sse-installer/salt/sse/eapi_plugin/files directory.

  4. 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

    salt-call --local pip.install SSEAPE-file-name.whl target='/usr'
    Ubuntu
    salt-call --local pip.install SSEAPE-file-name.whl target='/usr'
  5. Generate the master configuration settings.
    1. Verify the /etc/salt/master.d directory exists, or create it.
    2. Run the following command to generate the master configuration file.
      sudo sseapi-config --all > /etc/salt/master.d/raas.conf

      If running this command causes an error, see Troubleshooting SaltStack Config Cloud.

  6. Restart the Salt master service.
    sudo systemctl restart salt-master

Step 3: Generate an API token

Before you can connect your Salt master to SaltStack Config Cloud, you must generate an API token using the Cloud Services Console. This token is used to authenticate your Salt master with VMware Cloud Services.

To generate an API token:

  1. On the Cloud Services Console toolbar, click your user name and select My Account > API Tokens.
  2. Click Generate Token.

    API tokens page in CSP

  3. Complete the form.

    Generate token form in CSP

    1. Enter a name for the token.
    2. Select the token's Time to Live (TTL). The default duration is six months.
      Note: A non-expiring token can be a security risk if compromised. If this happens, you must revoke the token.
    3. Define scopes for the token.
      Scope Description
      Organization roles

      Organization roles determine a user's access to the organization's resources.

      To access the SaltStack Config Cloud service, you must select the Organization Admin or Organization Owner roles.

      The Organization Admin role selected on the Generate New API Token page
      Service roles

      Service roles are built-in, pre-defined sets of permissions that grant access to VMware Cloud services.

      To access the SaltStack Config Cloud service, search for the SaltStack Config service, and select the Salt Master service role.

      The Salt master service role selected for the SaltStack Config service
    4. (Optional) Set an email preference to receive a reminder when your token is about to expire.
    5. Click Generate.

      The newly generated API token appears in the Token Generated window.

  4. Save the token credentials to a secure location.

    After you generate the token, you will only be able to see the token's name on the API Tokens page, not the credentials. To regenerate the token, click Regenerate.

  5. Click Continue.

Step 4: Connect your Salt masters to SaltStack Config Cloud

After you generate an API token, you can use it to connect your Salt master to SaltStack Config Cloud.

To connect your Salt master:

  1. In the Salt master's terminal, save your API token as an environment variable.
    export CSP_API_TOKEN=<api token value>
  2. Run the following command to connect your Salt master to SaltStack Config Cloud, replacing the ssc-url and csp-url values with your region-specific URLs.
    sseapi-config join --ssc-url <SSC URL> --csp-url <CSP URL>
    Note:

    If you are using sudo, run the following command:

    sudo CSP_API_TOKEN=<api token value> sseapi-config join --ssc-url <SSC URL> --csp-url <CSP URL>
    Region name SSC URL CSP URL
    US https://ssc-gateway.mgmt.cloud.vmware.com https://console.cloud.vmware.com
    DE (Germany) https://de.ssc-gateway.mgmt.cloud.vmware.com https://console.cloud.vmware.com
    IN (India) https://in.ssc-gateway.mgmt.cloud.vmware.com https://console.cloud.vmware.com
    The following code sample shows an example successful response in the US region.
    2022-08-16 21:28:26 [INFO] SSEAPE joining SSC Cloud... v8.9.1.1 2022-08-16T15:28:12
    2022-08-16 21:28:26 [INFO] Retrieving CSP auth token.
    2022-08-16 21:28:27 [INFO] Creating new oauth app.
    2022-08-16 21:28:27 [INFO] Finished with oauth app [Salt Master App for master id:my-salt-master] in org [6bh70973-b1g2-716c-6i21-i9974a6gdc85].
    2022-08-16 21:28:29 [INFO] Added service role [saltstack:master] for oauth app [Salt Master App for master id:my-salt-master].
    2022-08-16 21:28:29 [INFO] Created pillar [CSP_AUTH_TOKEN].
    2022-08-16 21:28:29 [INFO] Updated master config. Please restart master for config changes to take effect.
    2022-08-16 21:28:29 [INFO] Updated master cloud.conf.
    2022-08-16 21:28:29 [INFO] Validating connectivity to SaltStack Cloud instance [https://ssc-gateway.mgmt.cloud.vmware.com]
    2022-08-16 21:28:29 [INFO] Successfully validated connectivity to SaltStack Cloud instance [https://ssc-gateway.mgmt.cloud.vmware.com]. Response: {'version': 'v8.9.0.5', 'vipVersion': '8.9.0'}
    2022-08-16 21:28:29 [INFO] Finished SSEAPE joining SSC Cloud... v8.9.1.1 2022-08-16T15:28:12
    

    If running this command causes an error, see Troubleshooting SaltStack Config Cloud.

  3. Restart the Salt master service.
    systemctl restart salt-master
  4. Repeat this process for each Salt master.
    Note: After you connect each Salt master to SaltStack Config Cloud, you can delete the API token. It is only required for connecting your Salt master to SaltStack Config Cloud.

After you run the sseapi-config command, an OAuth app is created in your Organization for each Salt master. Salt masters use the OAuth app to get an access token which is appended to every request to SaltStack Config Cloud. You can view the details of the OAuth app by selecting Organization > OAuth Apps.

The command also creates pillar data called CSP_AUTH_TOKEN on the Salt master. Pillars are structures of data stored on the Salt master and passed through to one or more minions that have been authorized to access that data. The pillar data is stored in /srv/pillar/csp.sls and contains the client ID, the secret, your organization ID, and CSP URL. If you need to rotate your secret, you can re-run the sseapi-config join command.

Example pillar data:

CSP_AUTH_TOKEN:
   csp_client_id: kH8wIvNxMJEGGmk7uCx4MBfPswEw7PpLaDh
   csp_client_secret: ebH9iuXnZqUOkuWKwfHXPjyYc5Umpa00mI9Wx3dpEMlrUWNy95
   csp_org_id: 6bh70973-b1g2-716c-6i21-i9974a6gdc85
   csp_url: https://console.cloud.vmware.com

Step 5: Accept Salt master keys

After you connect your Salt master to SaltStack Config Cloud, you must accept the Salt master's key in the SaltStack Config Cloud user interface.

To accept the Salt master's key:

  1. Log in to the SaltStack Config user interface.
  2. From the top left navigation bar, click the Menu menu icon, then select Administration to access the Administration workspace. Click the Master Keys tab.
  3. Check the box next to the master key to select it. Then, click Accept Key.
  4. If you already connected your Salt minions to your Salt master, an alert appears indicating that you have pending minion keys to accept. To accept these minion keys, go to Minion Keys > Pending.
    1. Check the boxes next to your minions to select them. Then, click Accept Key.

    The key is now accepted. After several seconds, the minion appears under the Accepted tab and in the Targets workspace.

You can verify that your Salt master and Salt minions are communicating by running a test.ping command in the SaltStack Config user interface. See Running an ad-hoc job from the Targets workspace for more information.