An ansible role to provision physical and virtual hosts with the AWS SSM agent.
Current version: 1.0.0
Lead Maintainer: Halim Qarroum
- Features
- Installation
- Pre-requisites
- Description
- Usage
- Playbook Variables
- Playbook Tags
- Compatibility Matrix
- See also
In order to use this role, you can download it on your development machine using Ansible Galaxy.
ansible-galaxy install hqarroum.aws_ssm_agent- Provisions the AWS SSM Agent on your physical and virtual hosts.
- Works on different flavors of Linux and Windows.
- Supports Linux distributions without package management.
- Support for auto-activation of provisioned instances using the AWS CLI and auto-creation of an IAM role for the instances.
- You must have
Ansible 2.8.0or a superior version installed on your deployment machine. (Instructions) - The
aws-cliversion 2 must be installed on your deployment machine when using auto-activation only. (Instructions)
This Ansible playbook provides developers and system engineers with the ability to deploy at scale the AWS SSM Agent on remote Linux, Mac and Windows hosts across different architectures. The AWS SSM agent will be registered as a service on the target operating system.
When dealing with managed instances, AWS SSM requires you to create an activation for one or multiple hosts that you can pass to this playbook using Ansible variables.
The below sections gives you an overview of the different actions at your disposal by using this playbook. We highly recommend that you be familiar with Ansible before using it, here is a link to the Ansible Documentation.
It is possible to specify an existing AWS SSM activation to this playbook while deploying it on your instances. This allows you to restrict the roles of your deployment machine or deployment team(s) and have them rely on the activation identifier and code that you previously created.
Below is an example of how to pass an activation identifier and activation code to your instances.
ansible-playbook playbook.yml \
-i <path-to-your-inventory> \
--extra-vars "aws_ssm_activation_code=<code> aws_ssm_activation_id=<id> aws_ssm_ec2_region=<region>"If you want to specify a different activation code and identifier to each of your instance, use your inventory to pass both variables for each one of them.
See the example
[all]
<host-1> aws_ssm_activation_code=<code> aws_ssm_activation_id=<id> aws_ssm_ec2_region=<region>
<host-2> aws_ssm_activation_code=<code> aws_ssm_activation_id=<id> aws_ssm_ec2_region=<region>You can delegate the creation of the activation to the playbook by enabling auto-activation (disabled by default) by setting the auto_activation variable to enabled. See the Playbook Variables section for more information.
This example will require the AWS CLI to be installed on your deployment machine provisioned with the appropriate IAM roles to create an activation code and an IAM Instance Role for your host(s) automatically. The AWS region will be inferred automatically from the AWS CLI.
ansible-playbook playbook.yml \
-i <path-to-your-inventory> \
--extra-vars "auto_activation=enabled"If you do not specify an activation identifier and code for your instances, you must set the auto_activation variable to enabled which will cause this role to automatically create them using the AWS CLI on your deployment machine for each provisioned instance. While doing so, it is possible to bind tags to the created activations such that these tags gets automatically associated with your instance in AWS SSM.
Below is an example of how to bind tags to your activation identifier and activation code.
ansible-playbook playbook.yml \
-i <path-to-your-inventory> \
--extra-vars "auto_activation=enabled instance_tags\"Key=foo,Value=bar\""By default, the AWS SSM Agent will be installed using the package manager available on your system (for example, Ubuntu uses apt and RedHat uses yum). However, embedded operating systems such as Yocto often don't have a package manager available, in which case it can be challenging to install software in a portable and automated way. To address this issue, the ansible-ssm role will install AWS SSM by un-archiving its binaries (according to the architecture of your hosts) on the system.
The default root path in which the un-archiving process target will be the root directory (/). This can lead to some issues on some systems for which the root file-system is mounted as read-only. In that case, you can choose in which directory to install the AWS SSM Agent by specifying the aws_ssm_agent_install_directory such as in the following example.
ansible-playbook playbook.yml \
-i <path-to-your-inventory> \
--extra-vars "auto_activation=enabled aws_ssm_agent_install_directory=/var/ssm"
⚠️ Only specify this variable if you are deploying on hosts that do not have any supported package manager available.
As seen in previous sections, this playbook exposes different variables which you can pass to the ansible-playbook command when creating a deployment to customize it, or specify them in your Ansible inventory file on a host-by-host basis. Below are descriptions of all the supported variables by this playbook.
| Variable | Description | Example values |
|---|---|---|
| aws_ssm_activation_code | Defines an AWS SSM activation code to provide to the playbook when provisioning your instances. Required if you don't enable auto-activation. | a1b2c3d4e5f6g7h8i1j2 |
| aws_ssm_activation_id | Defines an AWS SSM activation identifier to provide to the playbook when provisioning your instances. Required if you don't enable auto-activation. | 62275ac1-276f-47f0-9309-ef382c710b25 |
| aws_ssm_ec2_region | Sets the AWS region to use. | us-east-1 |
| auto_activation | Enables or disables automatic creation of an activation code for your instances using the AWS CLI. | enabled or disabled |
| aws_ssm_iam_role | The Amazon Identity and Access Management (IAM) role name that you want to assign to the managed instance. This IAM role must provide AssumeRole permissions for the Systems Manager service principal ssm.amazonaws.com . For more information, see Create an IAM service role for a hybrid environment in the AWS Systems Manager User Guide (if not provided, will be automatically created). Only valid when auto-activation is enabled. | AWSSSMInstanceRole |
| instance_tags | Defines tags to associate with AWS SSM activations created by this playbook. Only valid when auto-activation is enabled. | Key=foo,Value=bar Key=bar,Value=baz |
| aws_ssm_agent_install_directory | Defines the target installation directory for AWS SSM when no package managers are available on your system. | /var/ssm |
In addition to the Ansible variables it makes available, this playbook has the different parts of the deployment process tagged so that you can either cherry-pick the processes that interests you or rather exclude some of the tagged processes part of the deployment. Below is a table of the available tags associated with each deployment processes exposed by this playbook.
| Tag name | Process | Description |
|---|---|---|
| install-agent | AWS SSM Agent Installation | The process associated with this tag will install the AWS SSM agent in the target host given its current architecture and operating system. |
| register-service | AWS SSM Agent Service Registration | The process associated with this tag will register the provisioned AWS SSM Agent as a service on the host operating system, such that the agent will automatically start and run in the background when the host system starts. |
| register-agent | AWS SSM Agent Registration | The process associated with this tag will automatically register the provisioned AWS SSM Agent with the AWS SSM service using either the provided activation code and identifier, or if not provided, by auto-generating a new activation code and identifier locally using the AWS CLI. If you skip this tag, only the AWS SSM Agent will be provisioned on the host, but no activations will be performed. |
Below is a matrix of the operating systems, architectures that have been tested with this Ansible playbook.
| OS | Architecture | Compatible |
|---|---|---|
| Ubuntu 20.04 | x86_64 | ✅ |
| Ubuntu 18.04 | x86_64 and arm64 | ✅ |
| Ubuntu Server 14.04 LTS | x86_64 | ✅ |
| Ubuntu Server 16.04 LTS | x86_64 | ✅ |
| MacOS Big Sur | x86_64 | ✅ |
| Amazon Linux | x86_64 | ✅ |
| Amazon Linux 2 | x86_64 | ✅ |
| SUSE Linux Enterprise Server 15 | x86_64 | ✅ |
| OpenSUSE Leap 42.1 | x86_64 | ✅ |
| Red Hat Enterprise Linux | x86_64 and arm64 | ✅ |
| Debian Stretch | x86_64 | ✅ |
| CentOS | x86_64 | ✅ |
| Fedora | x86_64 | ✅ |
| Raspbian Stretch | armv7l | ✅ |
| Microsoft Windows Server 2019 | x86_64 | ✅ |
| Yocto Linux Distribution | x86_32 | ✅ |
Contributions are welcome if you have reported a successful or unsuccessful deployment of the AWS SSM Agent using this Ansible playbook on an operating system that is not listed above.
- The Ansible Official Documentation and the Ansible User Guide.
- The AWS Systems Manager Official Documentation page.
- The AWS Systems Manager Activations Documentation page.