README.md
1# Amazon AWS Collection
2[](https://api.shippable.com/projects/5e4451b6aa9a61000733064c/badge?branch=main)
3[](https://codecov.io/gh/ansible-collections/amazon.aws)
4
5The 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.
6
7AWS related modules and plugins supported by the Ansible community are in the [community.aws](https://github.com/ansible-collections/community.aws/) collection.
8
9<!--start requires_ansible-->
10## Ansible version compatibility
11
12This collection has been tested against following Ansible versions: **>=2.9.10**.
13
14Plugins and modules within a collection may be tested with only specific Ansible versions.
15A collection may contain metadata that identifies these versions.
16PEP440 is the schema used to describe the versions of Ansible.
17<!--end requires_ansible-->
18
19## Python version compatibility
20
21This collection depends on the AWS SDK for Python (Boto3 and Botocore). As AWS has [ceased supporting Python 2.6](https://aws.amazon.com/blogs/developer/deprecation-of-python-2-6-and-python-3-3-in-botocore-boto3-and-the-aws-cli/), this collection requires Python 2.7 or greater.
22
23## Included content
24
25<!--start collection content-->
26### Inventory plugins
27Name | Description
28--- | ---
29[amazon.aws.aws_ec2](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.aws_ec2_inventory.rst)|EC2 inventory source
30[amazon.aws.aws_rds](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.aws_rds_inventory.rst)|rds instance source
31
32### Lookup plugins
33Name | Description
34--- | ---
35[amazon.aws.aws_account_attribute](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.aws_account_attribute_lookup.rst)|Look up AWS account attributes.
36[amazon.aws.aws_secret](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.aws_secret_lookup.rst)|Look up secrets stored in AWS Secrets Manager.
37[amazon.aws.aws_service_ip_ranges](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.aws_service_ip_ranges_lookup.rst)|Look up the IP ranges for services provided in AWS such as EC2 and S3.
38[amazon.aws.aws_ssm](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.aws_ssm_lookup.rst)|Get the value for a SSM parameter or all parameters under a path.
39
40### Modules
41Name | Description
42--- | ---
43[amazon.aws.aws_az_info](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.aws_az_info_module.rst)|Gather information about availability zones in AWS.
44[amazon.aws.aws_caller_info](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.aws_caller_info_module.rst)|Get information about the user and account being used to make AWS calls.
45[amazon.aws.aws_s3](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.aws_s3_module.rst)|manage objects in S3.
46[amazon.aws.cloudformation](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.cloudformation_module.rst)|Create or delete an AWS CloudFormation stack
47[amazon.aws.cloudformation_info](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.cloudformation_info_module.rst)|Obtain information about an AWS CloudFormation stack
48[amazon.aws.ec2](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.ec2_module.rst)|create, terminate, start or stop an instance in ec2
49[amazon.aws.ec2_ami](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.ec2_ami_module.rst)|Create or destroy an image (AMI) in ec2
50[amazon.aws.ec2_ami_info](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.ec2_ami_info_module.rst)|Gather information about ec2 AMIs
51[amazon.aws.ec2_elb_lb](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.ec2_elb_lb_module.rst)|Creates, updates or destroys an Amazon ELB.
52[amazon.aws.ec2_eni](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.ec2_eni_module.rst)|Create and optionally attach an Elastic Network Interface (ENI) to an instance
53[amazon.aws.ec2_eni_info](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.ec2_eni_info_module.rst)|Gather information about ec2 ENI interfaces in AWS
54[amazon.aws.ec2_group](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.ec2_group_module.rst)|maintain an ec2 VPC security group.
55[amazon.aws.ec2_group_info](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.ec2_group_info_module.rst)|Gather information about ec2 security groups in AWS.
56[amazon.aws.ec2_key](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.ec2_key_module.rst)|create or delete an ec2 key pair
57[amazon.aws.ec2_metadata_facts](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.ec2_metadata_facts_module.rst)|gathers facts (instance metadata) about remote hosts within EC2
58[amazon.aws.ec2_snapshot](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.ec2_snapshot_module.rst)|Creates a snapshot from an existing volume
59[amazon.aws.ec2_snapshot_info](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.ec2_snapshot_info_module.rst)|Gather information about ec2 volume snapshots in AWS
60[amazon.aws.ec2_tag](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.ec2_tag_module.rst)|create and remove tags on ec2 resources
61[amazon.aws.ec2_tag_info](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.ec2_tag_info_module.rst)|list tags on ec2 resources
62[amazon.aws.ec2_vol](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.ec2_vol_module.rst)|Create and attach a volume, return volume id and device map
63[amazon.aws.ec2_vol_info](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.ec2_vol_info_module.rst)|Gather information about ec2 volumes in AWS
64[amazon.aws.ec2_vpc_dhcp_option](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.ec2_vpc_dhcp_option_module.rst)|Manages DHCP Options, and can ensure the DHCP options for the given VPC match what's requested
65[amazon.aws.ec2_vpc_dhcp_option_info](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.ec2_vpc_dhcp_option_info_module.rst)|Gather information about dhcp options sets in AWS
66[amazon.aws.ec2_vpc_net](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.ec2_vpc_net_module.rst)|Configure AWS virtual private clouds
67[amazon.aws.ec2_vpc_net_info](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.ec2_vpc_net_info_module.rst)|Gather information about ec2 VPCs in AWS
68[amazon.aws.ec2_vpc_subnet](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.ec2_vpc_subnet_module.rst)|Manage subnets in AWS virtual private clouds
69[amazon.aws.ec2_vpc_subnet_info](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.ec2_vpc_subnet_info_module.rst)|Gather information about ec2 VPC subnets in AWS
70[amazon.aws.s3_bucket](https://github.com/ansible-collections/amazon.aws/blob/stable-1.5/docs/amazon.aws.s3_bucket_module.rst)|Manage S3 buckets in AWS, DigitalOcean, Ceph, Walrus, FakeS3 and StorageGRID
71
72<!--end collection content-->
73
74## Installing this collection
75
76You can install the AWS collection with the Ansible Galaxy CLI:
77
78 ansible-galaxy collection install amazon.aws
79
80You can also include it in a `requirements.yml` file and install it with `ansible-galaxy collection install -r requirements.yml`, using the format:
81
82```yaml
83---
84collections:
85 - name: amazon.aws
86```
87
88The python module dependencies are not installed by `ansible-galaxy`. They can
89be manually installed using pip:
90
91 pip install requirements.txt
92
93or:
94
95 pip install boto boto3 botocore
96
97## Using this collection
98
99
100You 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:
101
102```yaml
103---
104 - name: Setup an instance for testing
105 amazon.aws.ec2_instance:
106 name: '{{ resource_prefix }}'
107 instance_type: t2.nano
108 image_id: "{{ (amis.images | sort(attribute='creation_date') | last).image_id }}"
109 wait: yes
110 volumes:
111 - device_name: /dev/xvda
112 ebs:
113 volume_size: 8
114 delete_on_termination: true
115 register: instance
116```
117
118**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.
119
120
121### See Also:
122
123* [Amazon Web Services Guide](https://docs.ansible.com/ansible/latest/scenario_guides/guide_aws.html)
124* [Ansible Using collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html) for more details.
125
126## Contributing to this collection
127
128We welcome community contributions to this collection. If you find problems, please open an issue or create a PR against the [Amazon AWS collection repository](https://github.com/ansible-collections/amazon.aws). See [Contributing to Ansible-maintained collections](https://docs.ansible.com/ansible/devel/community/contributing_maintained_collections.html#contributing-maintained-collections) for more details.
129
130You can also join us on:
131
132- Freenode IRC - ``#ansible-aws`` Freenode channel
133
134### More information about contributing
135
136- [Ansible Community Guide](https://docs.ansible.com/ansible/latest/community/index.html) - Details on contributing to Ansible
137- [Contributing to Collections](https://docs.ansible.com/ansible/devel/dev_guide/developing_collections.html#contributing-to-collections) - How to check out collection git repositories correctly
138- [Guidelines for Ansible Amazon AWS module development](https://docs.ansible.com/ansible/latest/dev_guide/platforms/aws_guidelines.html)
139- [Getting Started With AWS Ansible Module Development and Community Contribution](https://www.ansible.com/blog/getting-started-with-aws-ansible-module-development)
140
141## Release notes
142<!--Add a link to a changelog.rst file or an external docsite to cover this information. -->
143
144## Roadmap
145
146<!-- Optional. Include the roadmap for this collection, and the proposed release/versioning strategy so users can anticipate the upgrade/update cycle. -->
147
148## More information
149
150- [Ansible Collection overview](https://github.com/ansible-collections/overview)
151- [Ansible User guide](https://docs.ansible.com/ansible/latest/user_guide/index.html)
152- [Ansible Developer guide](https://docs.ansible.com/ansible/latest/dev_guide/index.html)
153- [Ansible Community code of conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html)
154
155## Licensing
156
157GNU General Public License v3.0 or later.
158
159See [COPYING](https://www.gnu.org/licenses/gpl-3.0.txt) to see the full text.
160