community.aws.aws_ssm connection – execute via AWS Systems Manager
Note
This connection plugin is part of the community.aws collection (version 2.6.1).
You might already have this collection installed if you are using the ansible package.
It is not included in ansible-core.
To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.aws.
To use it in a playbook, specify: community.aws.aws_ssm.
Synopsis
This connection plugin allows ansible to execute tasks on an EC2 instance via the aws ssm CLI.
Requirements
The below requirements are needed on the local controller node that executes this connection.
The remote EC2 instance must be running the AWS Systems Manager Agent (SSM Agent).
The control machine must have the aws session manager plugin installed.
The remote EC2 linux instance must have the curl installed.
Parameters
Parameter |
Comments |
|---|---|
The STS access key to use when connecting via session-manager. Configuration:
|
|
The name of the S3 bucket used for file transfers. Configuration:
|
|
KMS key id to use when encrypting objects using Configuration:
|
|
Server-side encryption mode to use for uploads on the S3 bucket used for file transfer. Choices:
Configuration:
|
|
The EC2 instance ID. Configuration:
|
|
This defines the location of the session-manager-plugin binary. Default: “/usr/local/bin/session-manager-plugin” Configuration:
|
|
Sets AWS profile to use. Configuration:
|
|
Number of attempts to connect. Default: 3 Configuration:
|
|
The region the EC2 instance is located. Default: “us-east-1” Configuration:
|
|
The STS secret key to use when connecting via session-manager. Configuration:
|
|
The STS session token to use when connecting via session-manager. Configuration:
|
|
Connection timeout seconds. Default: 60 Configuration:
|
Examples
# Stop Spooler Process on Windows Instances
- name: Stop Spooler Service on Windows Instances
vars:
ansible_connection: aws_ssm
ansible_shell_type: powershell
ansible_aws_ssm_bucket_name: nameofthebucket
ansible_aws_ssm_region: us-east-1
tasks:
- name: Stop spooler service
win_service:
name: spooler
state: stopped
# Install a Nginx Package on Linux Instance
- name: Install a Nginx Package
vars:
ansible_connection: aws_ssm
ansible_aws_ssm_bucket_name: nameofthebucket
ansible_aws_ssm_region: us-west-2
tasks:
- name: Install a Nginx Package
yum:
name: nginx
state: present
# Create a directory in Windows Instances
- name: Create a directory in Windows Instance
vars:
ansible_connection: aws_ssm
ansible_shell_type: powershell
ansible_aws_ssm_bucket_name: nameofthebucket
ansible_aws_ssm_region: us-east-1
tasks:
- name: Create a Directory
win_file:
path: C:\Windows\temp
state: directory
# Making use of Dynamic Inventory Plugin
# =======================================
# aws_ec2.yml (Dynamic Inventory - Linux)
# This will return the Instance IDs matching the filter
#plugin: aws_ec2
#regions:
# - us-east-1
#hostnames:
# - instance-id
#filters:
# tag:SSMTag: ssmlinux
# -----------------------
- name: install aws-cli
hosts: all
gather_facts: false
vars:
ansible_connection: aws_ssm
ansible_aws_ssm_bucket_name: nameofthebucket
ansible_aws_ssm_region: us-east-1
tasks:
- name: aws-cli
raw: yum install -y awscli
tags: aws-cli
# Execution: ansible-playbook linux.yaml -i aws_ec2.yml
# The playbook tasks will get executed on the instance ids returned from the dynamic inventory plugin using ssm connection.
# =====================================================
# aws_ec2.yml (Dynamic Inventory - Windows)
#plugin: aws_ec2
#regions:
# - us-east-1
#hostnames:
# - instance-id
#filters:
# tag:SSMTag: ssmwindows
# -----------------------
- name: Create a dir.
hosts: all
gather_facts: false
vars:
ansible_connection: aws_ssm
ansible_shell_type: powershell
ansible_aws_ssm_bucket_name: nameofthebucket
ansible_aws_ssm_region: us-east-1
tasks:
- name: Create the directory
win_file:
path: C:\Temp\SSM_Testing5
state: directory
# Execution: ansible-playbook win_file.yaml -i aws_ec2.yml
# The playbook tasks will get executed on the instance ids returned from the dynamic inventory plugin using ssm connection.
# Install a Nginx Package on Linux Instance; with specific SSE for file transfer
- name: Install a Nginx Package
vars:
ansible_connection: aws_ssm
ansible_aws_ssm_bucket_name: nameofthebucket
ansible_aws_ssm_region: us-west-2
ansible_aws_ssm_bucket_sse_mode: 'aws:kms'
ansible_aws_ssm_bucket_sse_kms_key_id: alias/kms-key-alias
tasks:
- name: Install a Nginx Package
yum:
name: nginx
state: present
Authors
Pat Sharkey (@psharkey)
HanumanthaRao MVL (@hanumantharaomvl)
Gaurav Ashtikar (@gau1991)
Hint
Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.