community.aws.aws_ssm connection – execute via AWS Systems Manager

Note

This connection plugin is part of the community.aws collection (version 5.0.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. You need further requirements to be able to use this connection plugin, see Requirements for details.

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 community.aws 1.3.0

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

bucket_sse_kms_key_id

string

added in community.aws 2.2.0

KMS key id to use when encrypting objects using bucket_sse_mode=aws:kms. Ignored otherwise.

Configuration:

  • Variable: ansible_aws_ssm_bucket_sse_kms_key_id

bucket_sse_mode

string

added in community.aws 2.2.0

Server-side encryption mode to use for uploads on the S3 bucket used for file transfer.

Choices:

  • "AES256"

  • "aws:kms"

Configuration:

  • Variable: ansible_aws_ssm_bucket_sse_mode

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 community.aws 1.5.0

Sets AWS profile to use.

Configuration:

  • Variable: ansible_aws_ssm_profile

reconnection_retries

integer

Number of attempts to connect.

Default: 3

Configuration:

  • Variable: ansible_aws_ssm_retries

region

string

The region the EC2 instance is located.

Default: "us-east-1"

Configuration:

  • Variable: ansible_aws_ssm_region

secret_access_key

string

added in community.aws 1.3.0

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

Configuration:

  • Variable: ansible_aws_ssm_secret_access_key

session_token

string

added in community.aws 1.3.0

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.

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