How do I set up Automation Config

To set up and verify your Automation Config 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 Automation Config. You can connect Salt masters that are on-premises or in the cloud.

Prerequisites

Before you set up Automation Config, you must complete the following prerequisites:

• Verify that you have the following roles in VMware Cloud Services:
  • Organization role: Organization Owner or Organization Administrator
  • Service role: Salt master
• Set your default organization to the organization with access to the Automation Config service.

Setup overview

Setting up Automation Config includes the following tasks.

1. Install Salt on your Salt master and the nodes you intend to manage using Automation Config. See Step 1: Install Salt for more information.
2. Install or upgrade the Master Plugin on the Salt masters that must communicate with Automation Config. 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 Automation Config. See Step 3: Generate an API token for more information.
4. Connect your Salt masters to Automation Config. See Step 4: Connect your Salt masters to Automation Config for more information.
5. Accept the Salt master keys in the Automation Config user interface. See Step 5: Accept Salt master keys for more information.

Step 1: Install Salt

You must install the Salt master service and Salt minion service on your Salt master before you can use Automation Config.

Before you install Salt, install any required dependencies. See Install dependencies in the Salt Install Guide for more information. For a list of supported Salt operating systems, see Salt Supported Operating Systems.

Note: The Salt Open Project documentation is maintained by VMware.

The following instructions install the latest Salt release on RHEL 8. See the Salt Install guide for information about installing Salt on other operating systems.

1. If you are installing Salt in an offline or secure environment, you must configure a network proxy to allow the following URLs needed to install Salt.
   • https://repo.saltproject.io
   • https://pypi.org
   • https://python.org
   Confirm network activity through your network proxy before proceeding with installation.
2. 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/salt/py3/redhat/8/x86_64/latest.repo | sudo tee /etc/yum.repos.d/salt.repo

3. Run sudo yum clean expire-cache.
4. Install the salt-minion service and salt-master service on your Salt master:

   sudo yum install salt-master
   sudo yum install salt-minion

5. Create a master.conf file in the /etc/salt/minion.d directory.

   touch master.conf

6. In the master.conf file, set the Salt master’s IP address to point to itself:

   master: localhost

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

8. If you are using a network proxy, set the HTTP_PROXY and HTTPS_PROXY variables accordingly for your network settings.
   1. If you are using systemd to manage your Salt master service, add the HTTP_PROXY and HTTPS_PROXY environment variables to your salt-master.service file.
   2. Run systemctl daemon-reload.
   3. Run systemctl restart salt-master to restart the Salt master service.

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 Automation Config.

If you already have an existing Salt master, upgrade the Master Plugin to the latest available version before connecting your Salt master to Automation Config. See Using the Master Plugins workspace for more information.

To install and configure the Master Plugin:

1. Log in to your Salt master.
2. Download the latest version of the Master Plugin from the Master Plugins workspace. The Master Plugin version typically consists of four numbers, such as 8.12.1.2.
   Important:

   The version of the Master Plugin must match the first three numbers of the Automation Config version. For example, if the Automation Config version is 8.12.1, the Master Plugin version must be 8.12.1.0 or later. You can find the version of Automation Config in the Master Plugins workspace.

3. Install the Master Plugin by manually installing the Python wheel. Use the example command, replacing the exact name of the wheel file:

   salt-call --local pip.install /path/to/SSEAPE-file-name.whl

   For non air-gapped environments, dependencies are installed automatically if they are not already present when you run this command. For air-gapped environments, refer to the Install the Salt Master Plugin on air-gapped systemsknowledge base article.

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

5. Restart the Salt master service.

   sudo systemctl restart salt-master

Step 3: Generate an API token

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

Note: You must have the Organization Administrator role in your Organization to complete this step. To view your Organization roles, open the Cloud Services Console, click your user name, and select My Account > My Roles.

If you do not have the Organization Administrator role assigned to you, contact the Organization owner.

To generate an API token:

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

   

   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 Automation Config service, you must select the Organization Administrator or Organization Owner role.
      Service roles	Service roles are built-in, pre-defined sets of permissions that grant access to VMware Cloud services. To access the Automation Config service, search for VMware Aria Automation service. Click the drop-down arrow next to the Config service, and select the Salt Master service role.

   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.

Step 4: Connect your Salt masters to Automation Config

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

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 sseapi-config join command to connect your Salt master to Automation Config.
   1. If you are connecting your Salt master to Automation Config for the first time, run the following command, replacing the ssc-url and csp-url values with your region-specific URLs.

      sseapi-config join --ssc-url <SSC URL> --csp-url <CSP URL>

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

   3. If you need to redo the joining process, re-run the sseapi-config join command and pass the flag --override-oauth-app.

      sseapi-config join --ssc-url <SSC URL> --csp-url <CSP URL> --override-oauth-app

      The --override-oauth-app flag deletes the OAuth app used to get an access token and recreates it.

   Table 1. Regional URLs for Automation Config

   Region	Automation Config URL	Cloud Services URL
   US	https://ssc-gateway.mgmt.cloud.vmware.com	https://console.cloud.vmware.com
   Germany	https://de.ssc-gateway.mgmt.cloud.vmware.com	https://console.cloud.vmware.com
   India	https://in.ssc-gateway.mgmt.cloud.vmware.com	https://console.cloud.vmware.com
   Canada	https://ca.ssc-gateway.mgmt.cloud.vmware.com	https://console.cloud.vmware.com
   Australia	https://au.ssc-gateway.mgmt.cloud.vmware.com	https://console.cloud.vmware.com
   UK	https://uk.ssc-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 Automation Config.

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 Automation Config, you can delete the API token. It is only required for connecting your Salt master to Automation Config.

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 Automation Config. 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 Automation Config, you must accept the Salt master's key in the Automation Config user interface.

You must have the Superuser role in Automation Config to accept the Salt master's key. See How do I define user roles for more information.

To accept the Salt master's key:

1. Log in to the Automation Config user interface.
2. From the top left navigation bar, click the Menu, then select Administration to access the Administration workspace. Click the Master Keys tab.

   If you do not see the Master Key, see Troubleshooting Automation Config.

   Note: You can verify that a pending master key is from the correct Salt Master by checking the key fingerprint. On your Salt Master, run sseapi-config auth to view the key fingerprint, then verify it is identical to the fingerprint you see in 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 Automation Config interface. See Running an ad-hoc job from the Targets workspace for more information.

To add more Salt minions on different nodes, follow Step 1 of this procedure and omit any commands to install or enable salt-master, then edit master.conf to point to the Salt master's hostname or IP. See Configuring the Salt Minion for more information.

If the Salt master and Salt minions are not communicating, see Troubleshooting Automation Config.