How to add the SaltStack Config resource in Cloud Assembly designs

If you integrated SaltStack Config with vRealize Automation, you can apply the SaltStack Config resource to install the minions on virtual machines in your deployments. After the minion is deployed, you can use SaltStack Config's powerful configuration management, drift remediation, and state management capabilities to manage your resources.

Minions are agents that run the salt-minion service. The service subscribes to jobs published by a Salt master, which is a server that runs the salt-master service. When a specific job applies to a minion, the minion executes the job.

You can use the SaltStack Config resource to deploy minions and apply state files when you deploy Linux and Windows machines. To add or update minions and state files on existing deployments, you can run the Attach SaltStack Resource day 2 action. For more about the day 2 action, see What actions can I run on Cloud Assembly deployments.

If you used the saltConfiguration property to deploy minions and state files as a day 0 action, consider updating your cloud templates to use the SaltStack Config resource. The saltConfiguration property is now deprecated. You can still use the saltConfiguration property in your cloud templates, but SaltStack Config integration features will be limited.

The Apply Salt Configuration day 2 action is still available for resources that use the saltConfiguration property.

Before you start

Verify that you installed SaltStack Config and configured the integration. See Create a SaltStack Config integration in vRealize Automation.
To familiarize yourself with how SaltStack Config works, including the key concepts of minions, see Understanding the SaltStack User Interface.
In SaltStack Config, verify that the FQDN name resolution from minion to master is working.
1. To verify the FQDN on the Salt master in SaltStack Config, select Minions > All Minons.
2. Filter the Minion ID column for the value saltmaster.
3. Click saltmaster to see the details.
4. Verify that the FQDN value is correct.
If you are deploying minions on a Linux machine, verify that the images in vSphere that you intend to deploy with a Salt minion have SSH capabilities enabled. SSH is used to remotely access the machine and deploy the minion.
If you are deploying minions on a Windows machine, see How do I deploy minions using the API (RaaS) in a Windows environment.
Verify that you can assign IP addresses to the machines you deploy.
SaltStack Config requires the machines to have IP addresses. Use the IP addresses for the public IP CIDR range for the SDDC (software-defined datacenter) where your Salt master is located.
Verify that the cloud template that you are adding the minion to is deployable before you add the SaltStack Config resource properties.
Verify that you have the following service roles:
1. Cloud Assembly administrator
2. Cloud Assembly user
3. Service Broker administrator
These service roles are required to use the SaltStack Config resource.

Add the SaltStack Config resource to the cloud template

As a cloud template developer, you can add properties to the YAML that install the SaltStack Config minion when you deploy the template.

The core properties that you add to the template include remote access for the machine you want to deploy and configuration properties for the SaltStack Config resource. The procedure only includes selected properties. The YAML includes other SaltStack Config resource properties that are not used in this example. For more information, review the schema.

Although this example shows how to add the username and password for the remote access properties, you can configure a secret property and add it to the template. For an example, see Secret Cloud Assembly properties.

Procedure

In Cloud Assembly, select Design > Cloud Templates.
Open an existing template.
Locate the SaltStack Config resource and drag it to the canvas.
Attach the SaltStack Config resource to the machine the minion will be installed on.

In the code pane, add properties to the Cloud_SaltStack_1 resource.

You are not required to include all of the possible properties. The values used in this example are explained in the table.

Cloud_SaltStack_1:
    type: Cloud.SaltStack
    properties:
      masterId: saltstack_enterprise_installer
      hosts:
        - ${resource.Cloud_vSphere_Machine_1.id}
      saltEnvironment: sse
      stateFiles:
        - /doe.sls
      variables: 
        user: joe

Description of the Cloud_SaltStack_1 properties used in this example.

Property	Description
masterId	In the example schema, the `masterId` value is `saltstack_enterprise_installer`. You might have master IDs defined in SaltStack Config inAdministration > Master Keys.
hosts	The `hosts` value is the ID of the machine or cluster of machines you want to install the minion on. By default, the machine's name is passed in as the minion ID in SaltStack Config. It is recommended that you choose machine names that are 15 characters or less, especially if you are deploying minions on Windows. Windows does not permit hostnames that exceed 15 characters. If you want to define a custom naming convention for the machines you want to deploy, see Custom naming for deployed resources in Cloud Assembly.
saltEnvironment	In this example, `sse` is a file location for the state files. You might have your state files in other file server locations in SaltStack Config in Config > File Server.
stateFiles	In this example, `doe.sls` is a state file provided in the file server directory specified as the saltEnvironment.
variables	The variables are the values that the state file uses. In this example, the `doe.sls` accepts a `user` value.

Add remoteAccess properties to the machine that hosts the Salt minion.
The value for the authentication key must be usernamePassword or generatedPublicPrivateKey. publicPrivateKey is unsupported.
```
 remoteAccess:
        authentication: usernamePassword
        username: adminUser
        password: adminPassword
```

Verify that your YAML includes the properties similar to the following sample.

resources:
  Cloud_vSphere_Machine_1:
    type: Cloud.vSphere.Machine
    properties:
      image: ubuntu
      flavor: small
      remoteAccess:
        authentication: usernamePassword
        username: adminUser
        password: adminPassword
  Cloud_SaltStack_1:
    type: Cloud.SaltStack
    properties:
      masterId: saltstack_enterprise_installer
      hosts:
        - ${resource.Cloud_vSphere_Machine_1.id}
      saltEnvironment: sse
      stateFiles:
        - /doe.sls
      variables: 
        user: joe

Test and deploy the cloud template.
If your minion deployment fails, see Troubleshooting minion deployments.
Verify the Salt Configuration properties for the deployed machine.
1. Select Deployments > Deployments and open the deployment details.
2. On the Topology tab, click the machine and expand the properties in the right-hand pane.

Verify the minion in SaltStack Config

After you install the minion on the virtual machine, locate the minion and run any jobs or commands on the resource.

Procedure

To open SaltStack Config, click the applications menu in the upper-right corner and click Cloud Services Console.
Click the SaltStack Config service tile.
In SaltStack Config, expand Minion Keys and click Accepted.
In the Minion ID column, click the filter icon and enter the name of the minion.
The minion's name defaults to the virtual machine's hostname. In this example, the minion ID is vra-vm-05.
To view the details, click the minion's name.
You can run jobs or commands on the minion. For example, Sample Disk Usage. This job returns disk usage statistics for a minion.

Troubleshooting minion deployments

Read about some common errors users experience while deploying Salt minions using the SaltStack Config resource or the saltConfiguration property.

Delayed host startup

If Windows or Linux services on the host are not ready after you deploy your cloud template, you might receive a "Minion deployment and/or state file run failed" error in Cloud Assembly.

To resolve this error, upgrade the Master Plugin to the latest stable version. After you upgrade, you can enable a configuration setting in /etc/salt/master.d/raas.conf that allows Windows and Linux services time to become active before deploying the Salt minon.

After you upgrade to the latest version of the Master Plugin, complete these steps to delay host startup:

Check the History tab on the deployment details page.
If the error message says, "Minion deployment and/or state file run failed", copy the job ID (JID) and open SaltStack Config.
In SaltStack Config, select Activity > Completed to open completed jobs.
In the JID column, click the filter icon and type the JID.
Click the JID to review the job results page.
Click the Raw tab to see the raw output for the job.
Windows
If the last line in the raw output for the job contains "Failed to connect to host: timed out", you must add this configuration setting to /etc/salt/master.d/raas.conf to delay startup by 180 seconds:
```
sseapi_win_minion_deploy_delay: 180
```
Linux
If the line last in the raw output for the job contains "Remote host is not accessible using provided credentials", you must add this configuration setting to /etc/salt/master.d/raas.conf to delay startup by 90 seconds:
```
sseapi_linux_minion_deploy_delay: 90
```
Restart the Salt master service:
```
systemctl restart salt-master
```
Re-deploy your cloud template.
If the deployment was not successful, you can increase the delay parameter and re-deploy the template.

What to do next

To use the SaltStack Config capabilities to manage your resources, see the SaltStack Config documentation.