AWS Cloud Control Collection for Ansible

The AWS Cloud Control Collection is an experimental alpha collection of generated modules using the Cloud Control API for interacting with AWS Services.

This work is being made available for research purposes on the Cloud Control API and community feedback on the user experience of API generated module like these. Therefore, this content is not intended for production in its current state.

Ansible version compatibility

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

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 requires Python 3.9 or greater.

AWS SDK version compatibility

Version 0.3.0 of this collection supports boto3 >= 1.25.0 and botocore >= 1.28.0

Included content

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

Installing this collection

You can install the AWS Cloud Control Collection with the Ansible Galaxy CLI:

    ansible-galaxy collection install amazon.cloud

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

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

pip install requirements.txt

Note that if you install the collection from Ansible Galaxy, it 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.cloud --upgrade

See Ansible Using collections for more details.

Using this collection

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

---
  - name: Create log group (check mode)
    amazon.cloud.logs_log_group:
      state: present
      log_group_name: "{{ log_group_name }}"
      retention_in_days: 7
      tags:
        testkey: "testvalue"
    register: log_group

Because modules may keep the same name in the amazon.cloud, amazon.aws and community.aws collections, we recommend using the FQCN.

For example, if you want to use the s3_bucket module without specyfing the FQDN, it will use the order the collections are listed and take the first matching module it finds (in this case, s3_bucket from amazon.aws).

---
  - hosts: localhost
    collections:
      - amazon.aws
      - amazon.cloud
    tasks:
      - s3_bucket:
          bucket_name: "..."

Developement

This collection can be generated using the content_builder tool. Please refer to the cloud_content generation section.

This tool can generate the api specification files and use them to generate the modules. The developer can use the api specification files and the modules.yaml file hosted in this repository. The path to these files should be provided as input to the content builder tool to generate the schema and modules. To get more details on the command and input arguments please refer to the tool's README.

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

Known issues

Modules are only as good as the API and its schema. Documentation may not be complete for all the modules' options and suboptions.
Missing supportability for important AWS resources like, EC2 instance, RDS instance, EC2 volume, Elastic Load Balancer, RDS Snapshot, EC2 snapshot, etc.
Idempotency is a function of the API and may not be fully supported.
Missing server-side pagination. This may have severe impact on performance.
Name-based identification filtering to support desired state (idempotency) logic is absent. This limitation has made us to exclude several resources and reduce the numebr of modules. A client-side filtering will definitely have a large impact on performance.
Not all the resources support the available states. In practice this means that some resources cannot be updated or listed.

Contributing to this collection

We welcome community contributions to this collection. Because this collection is auto-generated using the content_builder tool, if you find problems, please open an issue or create a Pull Request against the content_builder.

You can also join us in the:

#ansible-aws irc.libera.chat channel
#ansible (general use questions and support), #ansible-community (community and collection development questions), and other IRC channels.

The Amazon Web Services Working groups is holding a monthly community meeting at #ansible-aws IRC channel at 17:30 UTC every fourth Thursday of the month. If you have something to discuss (e.g. a PR that needs help), add your request to the meeting agenda and join the IRC #ansible-aws channel. Invite (import by URL): ics file

You don't know how to start? Refer to our contribution guide!

We use the following guidelines:

Governance

The process of decision making in this collection is based on discussing and finding consensus among participants. Every voice is important. If you have something on your mind, create an issue or dedicated discussion and let's discuss it!

Release notes

See the rendered changelog or the raw generated changelog.

Communication

We announce releases and important changes through Ansible's The Bullhorn newsletter. Be sure you are subscribed.

Join us in the #ansible (general use questions and support), #ansible-community (community and collection development questions), and other IRC channels.

We take part in the global quarterly Ansible Contributor Summit virtually or in-person. Track The Bullhorn newsletter and join us.

For more information about communication, refer to the Ansible Communication guide.

Code of Conduct

We follow the Ansible Code of Conduct in all our interactions within this project.

If you encounter abusive behavior, please refer to the policy violations section of the Code for information on how to raise a complaint.

More information

Licensing

GNU General Public License v3.0 or later.

See LICENSE to see the full text.

ansible-collections / amazon.cloud

readme