community.aws.aws_ssm – execute via AWS Systems Manager

Note

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

To install it use: ansible-galaxy collection install community.aws.

To use it in a playbook, specify: community.aws.aws_ssm.

Synopsis
Requirements
Parameters
Examples

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

Pat Sharkey (@psharkey) <[email protected]>
HanumanthaRao MVL (@hanumantharaomvl) <[email protected]>
Gaurav Ashtikar (@gau1991 )<[email protected]>

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.11/collections/community/aws/aws_ssm_connection.html