AWS Cloud Operations Blog

Running Salt States Using Amazon EC2 Systems Manager

Like Ansible, Salt is a popular tool for configuration management. As with other tools in the same category, one of the key challenges is efficiently managing the deployment and execution of the automation directives.

Amazon EC2 Systems Manager is a powerful configuration management platform. One of its key benefits is that it allows customers to use whatever configuration management tool they are currently using. In the Running Ansible Playbooks using EC2 Systems Manager Run Command and State Manager post, I explained how Systems Manager can be used to manage configuration management states using Ansible.

In this post, I explore how to use Salt (on master-less mode), while leveraging the power, simplicity, and security of Systems Manager. I also introduce a new Systems Manager document that makes it easier for customers to run Salt states.

Systems Manager overview

Systems Manager uses documents to define actions to be executed on your managed instances.

Some of the benefits of using Systems Manager:

  • Improved security posture
    • There is no need to open incoming ports to remotely execute the directives. This eliminates the need for using SSH.
    • You can use granular IAM policies to restrict and control access to the platform
    • All command execution is audited via AWS CloudTrail.
  • Performance and reliability
    • Asynchronously execute commands.
    • Commands are delivered and executed even when the system comes back from being offline.
    • Execute at scale by taking advantage of velocity control and sending commands based on tags.
    • Control deployment rate if errors increase during deployment.

 

Salt overview

Salt uses the concept of states. A state is a set of configuration directives that represents what software should be installed and how it should be configured.

In typical deployments, Salt is used with a master server. The servers that receive automation directives are called minions. However, Salt states can also be run locally in what is called master-less mode. Using this feature, you can leverage Systems Manager to distribute and execute the Salt state files using Amazon EC2 State Manager or Run Command.

AWS-RunSaltState document

The new document that automates the process of running Salt states locally using Systems Manager is AWSRunSaltState. It is available to use via the console or API. Here are the different parts of the document and how it works:

  • Parameters
  • Steps
  • Salt-call

Parameters

The AWSRunSaltState document provides a number of parameters to execute the Salt states:

  • State – Allows for input YAML to define the Salt state automation.
  • Stateurl – (Optional) Provides a URL to a file that contains the YAML text for the Salt state. The URL can be in http or s3 format.
  • Pillars – (Optional) Passes additional variables to be used during the execution. Salt uses the concept of pillars to define data that can be used to configure the managed instances (minions).
  • Test – If true, performs a dry-run of the state. This reports on the actions to be performed by the automation but does not execute them.

Steps

The AWSRunSaltState document performs a few validations, then executes the automation using the YAML definitions passed by the parameters. Here is a summary of how the logic works:

  • Checks the Salt version to determine if Salt is present on the system.
  • Determines if the State parameter was passed as YAML using the State text or as a URL using Stateurl. Based on the input, it copies the data to a temporary state file for later execution.
  • Determines if the test option was selected and executes the proper command.

Salt-call

Salt includes an application called salt-call that can be used on managed instances to execute Salt states locally. The AWSRunSaltState document uses this application to execute the Salt state locally.

Walkthrough using Systems Manager and State Manager

Here’s an example of using State Manager with the new document to execute Salt state files.

Prerequisites

Complete the following requirements before going through this walkthrough:

  • Target instances must be managed by Systems Manager. For more information, see Installing SSM Agent.
  • Salt must be pre-installed on the target instance or execution fails. This document runs Salt states locally. For more information, see the following section on installing Salt for master-less execution.
  • For S3 URLs in the playbook field, the AWS CLI must be installed on the target instance or server.

Installing Salt for master-less execution

If you already have Salt installed on the target instances, you can skip this section.

Install Salt on the target instances to run what is called a master-less minion. Execute the following on the Linux instance:

curl -L https://bootstrap.saltstack.com -o bootstrap_salt.sh

sudo sh bootstrap_salt.sh

 

You could also run these two commands using Systems Manager Run Command and the AWS-RunShellScript document. This installs the necessary files to run Salt in master-less mode, using the salt-call application to execute the automation. This command is installed as part of the master-less bootstrapping.

Using State Manager and the AWSRunSalt document

The following YAML Salt state file contains automation that installs Apache if it is not already installed.

 

apache:

pkg.installed:

{% if grains['os'] == 'Amazon' %}

- name: httpd

{% elif grains['os'] == 'Ubuntu' %}

- name: apache2

{% endif %}

To use this Salt state file with Systems Manager, follow these steps:

  1. In the EC2 console, choose State Manager, Create Association.
  2. From the Document list, choose the new document “AWS-RunSaltState”.
  3. For Document Version, leave $DEFAULT selected.
  4. Under Targets, choose Manually Selecting instances and select the instance or instances to target with the Salt state. Alternatively, use a tag to select the instances to target.
  5. Under Schedule, enter how frequently to run the association.
  6. Under Parameters, for State, paste the YAML text for the Salt state. Leave Stateurl empty.
  7. For Pillars, enter the additional variables to use for the Salt state. Make sure the values are entered in the following format:

{“SSM”:”True”}

You can also use nested dict:

{‘pkg’: {‘apache’: ‘httpd’}}

  1. (Optional) Choose the test option.
  2. (Optional) Enter a comment for this association.
  3. Choose Run.
  4. To verify the output from the console, choose the Association ID link for this run.

After the association runs for the first time, you can see the results of the execution by navigating to the association and looking at the Status column. Now, every time the association runs, it run the salt state and this in turn ensures that the software is installed and running.

Integration with Parameter Store

All Systems Manager documents support referencing settings or secrets stored in Parameter Store, which provides a secure storage for configuration data such as passwords, database connection strings, and license code. For more information, see Systems Manager Parameter Store.

To use data stored in Parameter Store with Salt, reference it as part of the State code using the following format:

{{ssm:parameter_name}}

 

For example, to run a simple touch command to create a file in the /tmp directory and pass the file name as a saved setting, make sure that the parameter is created in Parameter Store. The Salt state file looks like the following:

mycommand:

cmd.run:

- name: touch /tmp/{{ssm:tempfilename}} /

 

Summary

In this post, I introduced the new Systems Manager document to execute Salt state files using State Manager and Run Command. I also demonstrated how you can use this new document to deploy and manage your Salt automation.

You can also use this Systems Manager document with the Run Command option and leverage velocity control. For an example on how to do this, see the Running Ansible Playbooks using EC2 Systems Manager Run Command and State Manager post.

 

About the Author

Andres Silva is a Senior Technical Account Manager for AWS Enterprise Support. He has been working with AWS technology for more than 6 years. Andres works with Enterprise customers to design, implement and support complex cloud infrastructures. When he is not building cloud automation he enjoys skateboarding with his 2 kids.