community.aws.aws_ssm – execute via AWS Systems Manager

Note

This plugin is part of the community.aws collection (version 1.4.0).

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 Choices/Defaults Configuration Comments
access_key_id
string
added in 1.3.0 of community.aws
var: ansible_aws_ssm_access_key_id
The STS access key to use when connecting via session-manager.
bucket_name
string
var: ansible_aws_ssm_bucket_name
The name of the S3 bucket used for file transfers.
instance_id
string
var: ansible_aws_ssm_instance_id
The EC2 instance ID.
plugin
string
Default:
"/usr/local/bin/session-manager-plugin"
var: ansible_aws_ssm_plugin
This defines the location of the session-manager-plugin binary.
region
string
Default:
"us-east-1"
var: ansible_aws_ssm_region
The region the EC2 instance is located.
retries
integer
Default:
3
var: ansible_aws_ssm_retries
Number of attempts to connect.
secret_access_key
string
added in 1.3.0 of community.aws
var: ansible_aws_ssm_secret_access_key
The STS secret key to use when connecting via session-manager.
session_token
string
added in 1.3.0 of community.aws
var: ansible_aws_ssm_session_token
The STS session token to use when connecting via session-manager.
ssm_timeout
integer
Default:
60
var: ansible_aws_ssm_timeout
Connection timeout seconds.

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.

Authors