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

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

- 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