Creating associations that run Ansible playbooks
You can create State Manager associations that run Ansible playbooks by
using the AWS-ApplyAnsiblePlaybooks
SSM document. State Manager is a
capability of Amazon Systems Manager. This document offers the following benefits for running
playbooks:
-
Support for running complex playbooks
-
Support for downloading playbooks from GitHub and Amazon Simple Storage Service (Amazon S3)
-
Support for compressed playbook structure
-
Enhanced logging
-
Ability to specify which playbook to run when playbooks are bundled
Note
Systems Manager includes two SSM documents that allow you to create State Manager associations
that run Ansible playbooks: AWS-RunAnsiblePlaybook
and
AWS-ApplyAnsiblePlaybooks
. The AWS-RunAnsiblePlaybook
document is deprecated. It remains available in Systems Manager for legacy purposes. We
recommend that you use the AWS-ApplyAnsiblePlaybooks
document because
of the enhancements described here.
Associations that run Ansible playbooks aren't supported on macOS.
Support for running complex playbooks
The AWS-ApplyAnsiblePlaybooks
document supports bundled, complex
playbooks because it copies the entire file structure to a local directory before
executing the specified main playbook. You can provide source playbooks in Zip files or
in a directory structure. The Zip file or directory can be stored in
GitHub or Amazon S3.
Support for downloading playbooks from GitHub
The AWS-ApplyAnsiblePlaybooks
document uses the
aws:downloadContent
plugin to download playbook files. Files can be
stored in GitHub in a single file or as a combined set of playbook files.
To download content from GitHub, specify information about your
GitHub repository in JSON format. Here is an example.
{ "owner":"
TestUser
", "repository":"GitHubTest
", "path":"scripts/python/test-script
", "getOptions":"branch:master
", "tokenInfo":"{{ssm-secure:secure-string-token
}}" }
Support for downloading playbooks from Amazon S3
You can also store and download Ansible playbooks in Amazon S3 as either a single .zip file or a directory structure. To download content from Amazon S3, specify the path to the file. Here are two examples.
Example 1: Download a specific playbook file
{ "path":"https://s3.amazonaws.com.cn/
amzn-s3-demo-bucket/playbook.yml
" }
Example 2: Download the contents of a directory
{ "path":"https://s3.amazonaws.com.cn/
amzn-s3-demo-bucket/ansible/webservers/
" }
Important
If you specify Amazon S3, then the Amazon Identity and Access Management (IAM) instance profile on your managed nodes must include permissions for the S3 bucket. For more information, see Configure instance permissions required for Systems Manager.
Support for compressed playbook structure
The AWS-ApplyAnsiblePlaybooks
document allows you to run compressed .zip
files in the downloaded bundle. The document checks if the downloaded files contain a
compressed file in .zip format. If a .zip is found, the document automatically
decompresses the file and then runs the specified Ansible
automation.
Enhanced logging
The AWS-ApplyAnsiblePlaybooks
document includes an optional parameter for
specifying different levels of logging. Specify -v for low verbosity, -vv or –vvv for
medium verbosity, and -vvvv for debug level logging. These options directly map to
Ansible verbosity options.
Ability to specify which playbook to run when playbooks are bundled
The AWS-ApplyAnsiblePlaybooks
document includes a required parameter for
specifying which playbook to run when multiple playbooks are bundled. This option
provides flexibility for running playbooks to support different use cases.
Understanding installed dependencies
If you specify True for the InstallDependencies parameter, then Systems Manager verifies that your nodes have the following dependencies installed:
-
Ubuntu Server/Debian Server: Apt-get (Package Management), Python 3, Ansible, Unzip
-
Amazon Linux: Ansible
-
RHEL: Python 3, Ansible, Unzip
If one or more of these dependencies aren't found, then Systems Manager automatically installs them.
Create an association that runs Ansible playbooks (console)
The following procedure describes how to use the Systems Manager console to create a
State Manager association that runs Ansible playbooks by using the
AWS-ApplyAnsiblePlaybooks
document.
To create an association that runs Ansible playbooks (console)
Open the Amazon Systems Manager console at https://console.amazonaws.cn/systems-manager/
. In the navigation pane, choose State Manager.
-
Choose State Manager, and then choose Create association.
-
For Name, specify a name that helps you remember the purpose of the association.
-
In the Document list, choose
AWS-ApplyAnsiblePlaybooks
. -
In the Parameters section, for Source Type, choose either GitHub or S3.
GitHub
If you choose GitHub, enter repository information in the following format.
{ "owner":"
user_name
", "repository":"name
", "path":"path_to_directory_or_playbook_to_download
", "getOptions":"branch:branch_name
", "tokenInfo":"{{(Optional)_token_information
}}" }S3
If you choose S3, enter path information in the following format.
{ "path":"https://s3.amazonaws.com.cn/
path_to_directory_or_playbook_to_download
" } -
For Install Dependencies, choose an option.
-
(Optional) For Playbook File, enter a file name. If a Zip file contains the playbook, specify a relative path to the Zip file.
-
(Optional) For Extra Variables, enter variables that you want State Manager to send to Ansible at runtime.
-
(Optional) For Check, choose an option.
-
(Optional) For Verbose, choose an option.
-
For Targets, choose an option. For information about using targets, see Understanding targets and rate controls in State Manager associations.
-
In the Specify schedule section, choose either On schedule or No schedule. If you choose On schedule, then use the buttons provided to create a cron or rate schedule for the association.
-
In the Advanced options section, for Compliance severity, choose a severity level for the association. Compliance reporting indicates whether the association state is compliant or noncompliant, along with the severity level you indicate here. For more information, see About State Manager association compliance.
-
In the Rate control section, configure options to run State Manager associations across a fleet of managed nodes. For information about using rate controls, see Understanding targets and rate controls in State Manager associations.
In the Concurrency section, choose an option:
-
Choose targets to enter an absolute number of targets that can run the association simultaneously.
-
Choose percentage to enter a percentage of the target set that can run the association simultaneously.
In the Error threshold section, choose an option:
-
Choose errors to enter an absolute number of errors that are allowed before State Manager stops running associations on additional targets.
-
Choose percentage to enter a percentage of errors that are allowed before State Manager stops running associations on additional targets.
-
(Optional) For Output options, to save the command output to a file, select the Enable writing output to S3 box. Enter the bucket and prefix (folder) names in the boxes.
Note
The S3 permissions that grant the ability to write the data to an S3 bucket are those of the instance profile assigned to the managed node, not those of the IAM user performing this task. For more information, see Configure instance permissions required for Systems Manager or Create an IAM service role for a hybrid environment. In addition, if the specified S3 bucket is in a different Amazon Web Services account, verify that the instance profile or IAM service role associated with the managed node has the necessary permissions to write to that bucket.
-
Choose Create Association.
Note
If you use tags to create an association on one or more target nodes, and then you remove the tags from a node, that node no longer runs the association. The node is disassociated from the State Manager document.
Create an association that runs Ansible playbooks (CLI)
The following procedure describes how to use the Amazon Command Line Interface (Amazon CLI) to create a
State Manager association that runs Ansible playbooks by using the
AWS-ApplyAnsiblePlaybooks
document.
To create an association that runs Ansible playbooks (CLI)
Install and configure the Amazon Command Line Interface (Amazon CLI), if you haven't already.
For information, see Installing or updating the latest version of the Amazon CLI.
-
Run one of the following commands to create an association that runs Ansible playbooks by targeting nodes using tags. Replace each
example resource placeholder
with your own information. Command (A) specifies GitHub as the source type. Command (B) specifies Amazon S3 as the source type.(A) GitHub source
Here is an example.
aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" \ --targets "Key=tag:OS,Values=Linux" \ --parameters '{"SourceType":["GitHub"],"SourceInfo":["{\"owner\":\"ansibleDocumentTest\", \"repository\": \"Ansible\", \"getOptions\": \"branch:master\"}"],"InstallDependencies":["True"],"PlaybookFile":["hello-world-playbook.yml"],"ExtraVariables":["SSM=True"],"Check":["False"],"Verbose":["-v"]}' \ --association-name "AnsibleAssociation" \ --schedule-expression "cron(0 2 ? * SUN *)"
(B) S3 source
Here is an example.
aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" \ --targets "Key=tag:OS,Values=Linux" \ --parameters '{"SourceType":["S3"],"SourceInfo":["{\"path\":\"https://s3.amazonaws.com.cn/amzn-s3-demo-bucket/playbook.yml\"}"],"InstallDependencies":["True"],"PlaybookFile":["playbook.yml"],"ExtraVariables":["SSM=True"],"Check":["False"],"Verbose":["-v"]}' \ --association-name "AnsibleAssociation" \ --schedule-expression "cron(0 2 ? * SUN *)"
Note
State Manager associations don't support all cron and rate expressions. For more information about creating cron and rate expressions for associations, see Reference: Cron and rate expressions for Systems Manager.
The system attempts to create the association on the nodes and immediately apply the state.
-
Run the following command to view an updated status of the association you just created.
aws ssm describe-association --association-id "
ID
"