Amazon AWS Collection

The Ansible Amazon AWS collection includes a variety of Ansible content to help automate the management of AWS services. This collection is maintained by the Ansible Cloud Content team.

Description
Communication
Requirements
Included content
Installation
Use Cases
Testing
Contributing to this collection
- More information about contributing
Support
Release notes
Related Information
License Information

Description

The primary purpose of this collection is to simplify and streamline the management of AWS resources through automation. By leveraging this collection, organizations can reduce manual intervention, minimize errors, and ensure consistent and repeatable deployments. This leads to increased efficiency, faster deployments, and a more agile IT infrastructure.

AWS-related modules and plugins supported by the Ansible community are in the community.aws collection.

Being Red Hat Ansible Certified Content, this collection is eligible for support through the Ansible Automation Platform.

Communication

Join the Ansible forum:
- Get Help: get help or help others.
- Posts tagged with 'aws': subscribe to participate in collection-related conversations.
- AWS Working Group: by joining the team, you will automatically be subscribed to posts tagged with aws.
- Social Spaces: gather and interact with fellow enthusiasts.
- News & Announcements: track project-wide announcements including social events.
The Ansible Bullhorn newsletter: used to announce releases and important changes.

For more information about communication, see the Ansible communication guide.

Requirements

Ansible version compatibility

The collection supports ansible-core versions based on requires_ansible in meta/runtime.yml:

Tested with Ansible Core 2.17.0 and later, and the current development version of Ansible. Ansible Core versions prior to 2.17.0 are not supported.

Python version compatibility

This collection depends on the AWS SDK for Python (Boto3 and Botocore). Due to the AWS SDK Python Support Policy this collection requires Python 3.8 or greater.

Amazon has also announced the planned end of support for Python versions below 3.9. As such, support for Python versions below 3.9 will be removed in a release after 2026-05-01.

AWS SDK version compatibility

Starting with the 2.0.0 releases of amazon.aws and community.aws, the collection's policy is generally to support the versions of botocore and boto3 that were released within 12 months prior to the most recent major collection release, following semantic versioning (for example, 2.0.0, 3.0.0).

Version 11.0.0 of this collection supports boto3 >= 1.35.0 and botocore >= 1.35.0

All support for the original AWS SDK boto was removed in release 4.0.0.

Event source plugin compatibility

aiobotocore >= 2.14.0 is required to use the event source plugins amazon.aws.aws_cloudtrail and amazon.aws.aws_sqs_queue.

Included content

See the complete list of collection content in the Plugin Index.

In addition, this collection includes two event source plugins located under the extensions/eda/ folder:

Installation

The amazon.aws collection can be installed with the Ansible Galaxy command-line tool:

ansible-galaxy collection install amazon.aws

You can also include it in a requirements.yml file and install it with ansible-galaxy collection install -r requirements.yml, using the following format:

---
collections:
  - name: amazon.aws

Note that if you install any collections from Ansible Galaxy, they will not be upgraded automatically when you upgrade the Ansible package. To upgrade the collection to the latest available version, run the following command:

ansible-galaxy collection install amazon.aws --upgrade

A specific version of the collection can be installed by using the version keyword in the requirements.yml file:

---
collections:
  - name: amazon.aws
    version: 3.1.1

or using the ansible-galaxy command as follows:

ansible-galaxy collection install amazon.aws:==1.0.0

The python module dependencies are not installed by ansible-galaxy. They can be manually installed using pip:

pip install -r requirements.txt

or:

pip install boto3 botocore

Refer to the following for more details:

Use Cases

You can call modules by their Fully Qualified Collection Name (FQCN), such as amazon.aws.ec2_instance, or by their short name if you list the amazon.aws collection in the playbook's collections keyword:

---
  - name: Setup an instance for testing
    amazon.aws.ec2_instance:
      name: '{{ ec2_instance_name }}'
      instance_type: t2.nano
      image_id: "{{ (amis.images | sort(attribute='creation_date') | last).image_id }}"
      wait: yes
      volumes:
        - device_name: /dev/xvda
          ebs:
            volume_size: 8
            delete_on_termination: true
    register: instance

  - name: Gather {{ ec2_instance_name }} info
    amazon.aws.ec2_instance_info:
      filters:
        tag:Name: "{{ ec2_instance_name }}"
        include_attributes:
          - instanceType
          - kernel
          - ramdisk
          - userData
          - disableApiTermination
          - instanceInitiatedShutdownBehavior
          - rootDeviceName
          - blockDeviceMapping
          - productCodes
          - sourceDestCheck
          - groupSet
          - ebsOptimized
          - sriovNetSupport
          - enclaveOptions
      register: instance_info

  - name: Delete instance created for tests
    amazon.aws.ec2_instance:
      state: absent
      instance_ids: "{{ instance.instance_ids }}"
      wait: false

Testing

This collection is tested using GitHub Actions. To learn more about testing, refer to CI.md.

Contributing to this collection

We welcome community contributions to this collection. If you find problems, please open an issue

Amazon.aws

Install / Use

README