Getting started with Tanzu Salt

If you have an active Tanzu Platform or Tanzu Platform Spring Essentials subscription, you are eligible to access the Tanzu Salt service.

Tanzu Salt is available for both self-managed and SaaS deployments:

Self-managed - To get started with Tanzu Salt self-managed, see Installing and Configuring Tanzu Salt.
SaaS - To get started with Tanzu Salt SaaS, continue reading this page.
Security scanning features - To configure Tanzu Salt’s security scanning features, see Configure Tanzu Salt security scanning features.

Tanzu Salt architecture (SaaS)

Tanzu Salt for SaaS is deployed as a single-tenant instance and can scale to meet your infrastructure’s needs.

Your Tanzu Salt SaaS instance includes:

Redis database
PostgreSQL database
Tanzu Salt API server, also known as RaaS
Tanzu Salt user interface

Tanzu Salt runs on Salt, an open-source automation and configuration management engine sponsored, approved, and sanctioned by Broadcom, Inc. To begin using Tanzu Salt for configuration management, you also must install and run the Salt master service and the Salt minion service on any nodes that you intend to manage using Tanzu Salt.

You are responsible for managing the deployment, upgrade, and decommission of Salt masters and Salt minions. You can deploy Salt masters and Salt minions in public cloud providers, on-premises, or in another hosted solution. The deployment location is subject to your infrastructure needs.

Set up Tanzu Salt SaaS

Setting up Tanzu Salt SaaS includes the following tasks:

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

Step 1: Prerequisites

Before you set up Tanzu Salt SaaS, 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 Tanzu Salt service.

To…	You need to…
Sign up for VMware Cloud Services	Initiate the onboarding process from your invitation link. See How do I sign up for VMware Cloud Services for more information.
Access the Tanzu Salt service	Open a support request through the VMware Cloud Services Console. In the support request, include the following information: Your organization ID Your contact email See How do I get support for more detailed instructions on opening a support request.
Set up identity and access management for Tanzu Salt	Add users to your Organization and assign organization roles and service roles to each user. LDAP/SAML integration must be configured through the Cloud Services Console. See the following links for more information: How do I set authentication policies in my Organization How do I manage users in my organization How do I manage roles and permissions

To…

You need to…

Initiate the onboarding process from your invitation link. See How do I sign up for VMware Cloud Services for more information.

Access the Tanzu Salt service

Open a support request through the VMware Cloud Services Console. In the support request, include the following information:

Your organization ID
Your contact email

See How do I get support for more detailed instructions on opening a support request.

Set up identity and access management for Tanzu Salt

Add users to your Organization and assign organization roles and service roles to each user. LDAP/SAML integration must be configured through the Cloud Services Console.

See the following links for more information:

Step 2: Install Salt

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

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.

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.

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

Run sudo yum clean expire-cache.
Install the salt-minion service and salt-master service on your Salt master:
```
sudo yum install salt-master
sudo yum install salt-minion
```
Create a master.conf file in the /etc/salt/minion.d directory.
```
touch master.conf
```
In the master.conf file, set the Salt master’s IP address to point to itself:
```
master: localhost
```

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

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 3: 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 Tanzu Salt.

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

To install and configure the Master Plugin:

Log in to your Salt master.
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 Tanzu Salt version. For example, if the Tanzu Salt version is 8.12.1, the Master Plugin version must be 8.12.1.0 or later. You can find the version of Tanzu Salt in the Master Plugins workspace.
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 systems knowledge base article.
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 Tanzu Salt.
Restart the Salt master service.
```
sudo systemctl restart salt-master
```

Step 4: Generate an API token

Before you can connect your Salt master to Tanzu Salt, 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:

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

Complete the form.

Generate token form in the Cloud Services Console

Enter a name for the token.
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.

Define scopes for the token.

Scope	Description
Organization roles	Organization roles determine a user’s access to the organization’s resources. To access the Tanzu Salt 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 Tanzu Salt service, search for VMware Aria Automation service. Click the drop-down arrow next to the Config service, and select the Salt Master service role.

Scope

Description

Organization roles

Organization roles determine a user’s access to the organization’s resources. To access the Tanzu Salt 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 Tanzu Salt service, search for VMware Aria Automation service.

Click the drop-down arrow next to the Config service, and select the Salt Master service role.

(Optional) Set an email preference to receive a reminder when your token is about to expire.
Click Generate.

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

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 5: Connect your Salt masters to Tanzu Salt

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

To connect your Salt master:

In the Salt master’s terminal, save your API token as an environment variable.
```
export CSP_API_TOKEN=<api token value>
```

Run the sseapi-config join command to connect your Salt master to Tanzu Salt.

If you are connecting your Salt master to Tanzu Salt 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>
```

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>

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.

Region	Tanzu Salt 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 Tanzu Salt.

Restart the Salt master service.
```
systemctl restart salt-master
```
Repeat this process for each Salt master.

Note:
After you connect each Salt master to Tanzu Salt, you can delete the API token. It is only required for connecting your Salt master to Tanzu Salt.

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 Tanzu Salt. 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 6: Accept Salt master keys

After you connect your Salt master to Tanzu Salt, you must accept the Salt master’s key in the Tanzu Salt user interface.

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

To accept the Salt master’s key:

Log in to the Tanzu Salt user interface.
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 Tanzu Salt.

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.
Check the box next to the master key to select it. Then, click Accept Key.
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.
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 Tanzu Salt 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 Tanzu Salt.

Troubleshooting Tanzu Salt SaaS setup

See Troubleshooting Tanzu Salt SaaS setup for help troubleshooting common errors when setting up Tanzu Salt SaaS.

What to do next with Tanzu Salt

As an IT system administrator, you use Tanzu Salt to define optimized, compliant software states and enforce them across multi-cloud environments.

To learn about…	See…
Example use cases and tutorials for Tanzu Salt	Tanzu Salt tutorials
Deploying the Salt minion service to your network infrastructure	Extend Salt on your infrastructure
Use state files for configuration management	Creating state files and pillar data
Integrating with VMware Aria Automation	Configure an Tanzu Salt integration in VMware Aria Automation
Creating and running configuration management jobs	Using jobs in Tanzu Salt
Configuring Tanzu Salt security libraries	Configure Tanzu Salt security scanning features