Amazon AWS Collection

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

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

Ansible version compatibility

This collection has been tested against following Ansible versions: >=2.9.10.

Plugins and modules within a collection may be tested with only specific Ansible versions. A collection may contain metadata that identifies these versions. PEP440 is the schema used to describe the versions of Ansible.

Python version compatibility

This collection depends on the AWS SDK for Python (Boto3 and Botocore). As AWS has ceased supporting Python 2.6, this collection requires Python 2.7 or greater.

Included content

Inventory plugins

Name	Description
amazon.aws.aws_ec2	EC2 inventory source
amazon.aws.aws_rds	rds instance source

Lookup plugins

Name	Description
amazon.aws.aws_account_attribute	Look up AWS account attributes.
amazon.aws.aws_secret	Look up secrets stored in AWS Secrets Manager.
amazon.aws.aws_service_ip_ranges	Look up the IP ranges for services provided in AWS such as EC2 and S3.
amazon.aws.aws_ssm	Get the value for a SSM parameter or all parameters under a path.

Modules

Name	Description
amazon.aws.aws_az_info	Gather information about availability zones in AWS.
amazon.aws.aws_caller_info	Get information about the user and account being used to make AWS calls.
amazon.aws.aws_s3	manage objects in S3.
amazon.aws.cloudformation	Create or delete an AWS CloudFormation stack
amazon.aws.cloudformation_info	Obtain information about an AWS CloudFormation stack
amazon.aws.ec2	create, terminate, start or stop an instance in ec2
amazon.aws.ec2_ami	Create or destroy an image (AMI) in ec2
amazon.aws.ec2_ami_info	Gather information about ec2 AMIs
amazon.aws.ec2_elb_lb	Creates, updates or destroys an Amazon ELB.
amazon.aws.ec2_eni	Create and optionally attach an Elastic Network Interface (ENI) to an instance
amazon.aws.ec2_eni_info	Gather information about ec2 ENI interfaces in AWS
amazon.aws.ec2_group	maintain an ec2 VPC security group.
amazon.aws.ec2_group_info	Gather information about ec2 security groups in AWS.
amazon.aws.ec2_key	create or delete an ec2 key pair
amazon.aws.ec2_metadata_facts	Gathers facts (instance metadata) about remote hosts within ec2
amazon.aws.ec2_snapshot	Creates a snapshot from an existing volume
amazon.aws.ec2_snapshot_info	Gather information about ec2 volume snapshots in AWS
amazon.aws.ec2_tag	create and remove tags on ec2 resources
amazon.aws.ec2_tag_info	list tags on ec2 resources
amazon.aws.ec2_vol	Create and attach a volume, return volume id and device map
amazon.aws.ec2_vol_info	Gather information about ec2 volumes in AWS
amazon.aws.ec2_vpc_dhcp_option	Manages DHCP Options, and can ensure the DHCP options for the given VPC match what's requested
amazon.aws.ec2_vpc_dhcp_option_info	Gather information about dhcp options sets in AWS
amazon.aws.ec2_vpc_net	Configure AWS virtual private clouds
amazon.aws.ec2_vpc_net_info	Gather information about ec2 VPCs in AWS
amazon.aws.ec2_vpc_subnet	Manage subnets in AWS virtual private clouds
amazon.aws.ec2_vpc_subnet_info	Gather information about ec2 VPC subnets in AWS
amazon.aws.s3_bucket	Manage S3 buckets in AWS, DigitalOcean, Ceph, Walrus, FakeS3 and StorageGRID

Installing this collection

You can install the AWS collection with the Ansible Galaxy CLI:

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

---
collections:
  - name: amazon.aws

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

pip install requirements.txt

or:

pip install boto boto3 botocore

Using this collection

You can either call modules by their Fully Qualified Collection Namespace (FQCN), such as amazon.aws.ec2_instance, or you can call modules 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: '{{ resource_prefix }}'
      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

NOTE: For Ansible 2.9, you may not see deprecation warnings when you run your playbooks with this collection. Use this documentation to track when a module is deprecated.

See Also:

• Amazon Web Services Guide
• Ansible Using collections for more details.

Contributing to this collection

We welcome community contributions to this collection. If you find problems, please open an issue or create a PR against the Amazon AWS collection repository. See Contributing to Ansible-maintained collections for more details.

You can also join us on:

• Freenode IRC - #ansible-aws Freenode channel

More information about contributing

• Ansible Community Guide - Details on contributing to Ansible
• Contributing to Collections - How to check out collection git repositories correctly
• Guidelines for Ansible Amazon AWS module development
• Getting Started With AWS Ansible Module Development and Community Contribution

Release notes

Roadmap

More information

• Ansible Collection overview
• Ansible User guide
• Ansible Developer guide
• Ansible Community code of conduct

Licensing

GNU General Public License v3.0 or later.

See COPYING to see the full text.