Awesome

<br /><br />

ansible-ssm

An ansible role to provision physical and virtual hosts with the AWS SSM agent.

Current version: 1.0.0

Lead Maintainer: Halim Qarroum

📋 Table of content

• Features
• Installation
• Pre-requisites
• Description
• Usage
• Playbook Variables
• Playbook Tags
• Compatibility Matrix
• See also

🚀 Install

In order to use this role, you can download it on your development machine using Ansible Galaxy.

ansible-galaxy install hqarroum.aws_ssm_agent

🔖 Features

• 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.

🎒 Pre-requisites

• You must have Ansible 2.8.0 or a superior version installed on your deployment machine. (Instructions)
• The aws-cli version 2 must be installed on your deployment machine when using auto-activation only. (Instructions)

🔰 Description

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.

🛠 Usage

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.

Create a first deployment

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.

[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>

Enable auto-activation

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"

Associate tags to your instances

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\""

Installing the AWS SSM Agent in a specific path

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.

📗 Playbook Variables

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.

🏷 Playbook Tags

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.

🏁 Compatibility Matrix

Below is a matrix of the operating systems, architectures that have been tested with this Ansible playbook.

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.

👀 See also

• The Ansible Official Documentation and the Ansible User Guide.
• The AWS Systems Manager Official Documentation page.
• The AWS Systems Manager Activations Documentation page.