.. meta::
   :description: Discover how modules in the Steampunk AWS Ansible collection work, complete with example code.

.. _doc_modules:

Modules
=======

Modules in the Steampunk AWS Ansible collection come in pairs:

* a control module, e.g. ``ec2_instance`` and
* an info module with an ``_info`` suffix, e.g. ``ec2_instance_info``.

The former creates, modifies and deletes resources, while the latter only retrieves information
about a subbset of them.
Control modules only manage one resource of their type at a time, in addition to handling
attachments to child resources.

All modules have a consistent structure of parameters.
Each parameter can be described with one of the following categories:

* authentication parameters,
* identification parameters, which are, mostly, mandatory only on creation and
* fully optional parameters.

Sounds complicated, but that's what the documentation is here for.

The first group consists of the ``auth`` parameter and its subkeys, with a detailed explanation in
:ref:`doc_modules`.

Identification parameters are noted as such in their descriptions.
There are two ways to identify entities using these, namely with:

* the ``id`` parameter or
* a subset of parameters that, while describing the entity, also uniquely identify it.

Let's look at an example of a very basic task managing a Virtual Private Cloud, or a VPC.

.. code-block:: yaml+jinja

    - steampunk.aws.ec2_vpc:
        name: my-vpc
        cidr: 10.10.0.0/16

This task creates a (or ensures the existence of) a VPC named ``my-vpc`` using the ``10.10.0.0/16``
subnet.
When at first this subnet doesn't exist, it is created, this is obvious.
However, running the task again, idempotently, helps us explain identification parameters.
When this VPC already exists the *minimum set of parameters required for identification* is used
to select the matching VPC and do nothing, as it already exists.
For ``ec2_vpc``, the minimum set of parameters is the set of ``{name, cidr}``.

For existing resources, each module allows the use of an ``id`` parameter to select a very specific
resource.
Let's look at an example of set of tasks that ensures all default VPCs have a specific tag.

.. code-block:: yaml+jinja

    - steampunk.aws.ec2_vpc_info:
        filters:
          isDefault: true
      register: default_vpcs

    - steampunk.aws.ec2_vpc:
        id: "{{ item.id }}"
        tags:
          is-this-a-default-vpc: "yes it is"
      loop: "{{ default_vpcs.objects }}"

We've looked up all default VPCs (just in a region though) and stored the result into
``default_vpcs``, with the VPC objects themselves available in ``default_vpcs.objects``.
We then ensure our tag exists on each of those objects (again, just one).

The tags are an example of fully optional parameters - they don't serve as authentication,
they don't identify a resource and they aren't mandatory at creation - the simplest type of
parameter there is.


Module reference
----------------

.. toctree::
   :glob:
   :maxdepth: 1

   modules/*