community.aws.aws_ssm – execute via AWS Systems Manager

Note

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

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

access_key_id

string

added in 1.3.0 of community.aws

The STS access key to use when connecting via session-manager.

Configuration:

  • Variable: ansible_aws_ssm_access_key_id

bucket_name

string

The name of the S3 bucket used for file transfers.

Configuration:

  • Variable: ansible_aws_ssm_bucket_name

instance_id

string

The EC2 instance ID.

Configuration:

  • Variable: ansible_aws_ssm_instance_id

plugin

string

This defines the location of the session-manager-plugin binary.

Default: “/usr/local/bin/session-manager-plugin”

Configuration:

  • Variable: ansible_aws_ssm_plugin

profile

string

added in 1.5.0 of community.aws

Sets AWS profile to use.

Configuration:

  • Variable: ansible_aws_ssm_profile

region

string

The region the EC2 instance is located.

Default: “us-east-1”

Configuration:

  • Variable: ansible_aws_ssm_region

retries

integer

Number of attempts to connect.

Default: 3

Configuration:

  • Variable: ansible_aws_ssm_retries

secret_access_key

string

added in 1.3.0 of community.aws

The STS secret key to use when connecting via session-manager.

Configuration:

  • Variable: ansible_aws_ssm_secret_access_key

session_token

string

added in 1.3.0 of community.aws

The STS session token to use when connecting via session-manager.

Configuration:

  • Variable: ansible_aws_ssm_session_token

ssm_timeout

integer

Connection timeout seconds.

Default: 60

Configuration:

  • Variable: ansible_aws_ssm_timeout

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