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.

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>

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.

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

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

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.

🏁 Compatibility Matrix

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.

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