community.aws.aws_ssm connection – connect to EC2 instances via AWS Systems Manager

Note

This connection plugin is part of the community.aws collection (version 7.1.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 an AWS SSM Session.

Requirements

The below requirements are needed on the local controller node that executes this connection.

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:

bucket_endpoint_url

string

added in community.aws 5.3.0

The S3 endpoint URL of the bucket used for file transfers.

Configuration:

  • Variable: ansible_aws_ssm_bucket_endpoint_url

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:

  • Environment variable: AWS_PROFILE

  • 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:

s3_addressing_style

string

added in community.aws 5.2.0

The addressing style to use when using S3 URLs.

When the S3 bucket isn’t in the same region as the Instance explicitly setting the addressing style to ‘virtual’ may be necessary https://repost.aws/knowledge-center/s3-http-307-response as this forces the use of a specific endpoint.

Choices:

  • "path"

  • "virtual"

  • "auto" ← (default)

Configuration:

  • Variable: ansible_aws_ssm_s3_addressing_style

secret_access_key

string

added in community.aws 1.3.0

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

Configuration:

session_token

string

added in community.aws 1.3.0

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

Configuration:

ssm_document

string

added in community.aws 5.2.0

SSM Session document to use when connecting.

To configure the remote_user (when become=False, it is possible to use an SSM Session document and define the runAsEnabled and runAsDefaultUser parameters. See also https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-schema.html

Configuration:

  • Variable: ansible_aws_ssm_document

ssm_timeout

integer

Connection timeout seconds.

Default: 60

Configuration:

  • Variable: ansible_aws_ssm_timeout

Notes

Note

  • The community.aws.aws_ssm connection plugin does not support using the ``remote_user`` and ``ansible_user`` variables to configure the remote user. The ``become_user`` parameter should be used to configure which user to run commands as. Remote commands will often default to running as the ``ssm-agent`` user, however this will also depend on how SSM has been configured.

  • This plugin requires an S3 bucket to send files to/from the remote instance. This is required even for modules which do not explicitly send files (such as the shell or command modules), because Ansible sends over the .py files of the module itself, via S3.

  • Files sent via S3 will be named in S3 with the EC2 host ID (e.g. i-123abc/) as the prefix.

  • The files in S3 will be deleted by the end of the playbook run. If the play is terminated ungracefully, the files may remain in the bucket. If the bucket has versioning enabled, the files will remain in version history. If your tasks involve sending secrets to/from the remote instance (e.g. within a shell command, or a SQL password in the community.postgresql.postgresql_query module) then those passwords will be included in plaintext in those files in S3 indefinitely, visible to anyone with access to that bucket. Therefore it is recommended to use a bucket with versioning disabled/suspended.

  • The files in S3 will be deleted even if the keep_remote_files setting is true.

Examples

---
# Wait for SSM Agent to be available on the Instance
- name: Wait for connection to be available
  vars:
    ansible_connection: aws_ssm
    ansible_aws_ssm_bucket_name: nameofthebucket
    ansible_aws_ssm_region: us-west-2
    # When the S3 bucket isn't in the same region as the Instance
    # Explicitly setting the addressing style to 'virtual' may be necessary
    # https://repost.aws/knowledge-center/s3-http-307-response
    ansible_aws_ssm_s3_addressing_style: virtual
  tasks:
    - name: Wait for connection
      wait_for_connection:

# 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)
# plugin: aws_ec2
# regions:
#   - us-east-1
# hostnames:
#   - instance-id
# # This will return the Instances with the tag "SSMTag" set to "ssmlinux"
# 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
# =====================================================
# # aws_ec2.yml (Dynamic Inventory - Windows)
# plugin: aws_ec2
# regions:
#   - us-east-1
# hostnames:
#   - instance-id
# # This will return the Instances with the tag "SSMTag" set to "ssmwindows"
# 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 CMK used for the 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

# Install a Nginx Package on Linux Instance; using the specified SSM document
- 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_document: nameofthecustomdocument
  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.