Quickstart

This document briefly describes the general steps that we need to take when using the AWS Ansible Collection. And as is often the case, we will start with the installation.

Open-source version can be installed directly from Ansible Galaxy with just one short command:

$ ansible-galaxy collection install steampunk.aws

Note

To use the AWS Ansible Collection, we need to have Ansible 2.9+ installed. Previous Ansible versions do not support Ansible Collections well enough to be usable.

Instructions for installing AWS Ansible Collection from installer packages for RHEL/Centos are available upon registration. These packages are provided under these Terms and Conditions.

We also need to get the boto3 Python package. And the simplest way of installing it is using pip:

$ pip3 install --user -U boto3

Now we can create a playbook called playbook.yaml that uses modules from the AWS Ansible Collection and creates a dedicated virtual private cloud (VPC). Why create a VPC and not an instance you ask? Mainly because creating a VPC is entirely free, and we would rather see you spend your hard-earned money on things that matter.

---
- name: Create an AWS VPC
  gather_facts: false
  hosts: localhost

  tasks:
    - name: Create a VPC
      steampunk.aws.ec2_vpc:
        name: my-vpc
        cidr: 10.0.0.0/16

The last remaining thing we need to do is export the variables with AWS credentials that modules will use when talking to the AWS web API:

$ export AWS_REGION=us-east-1                   # choose whichever you prefer
$ export AWS_ACCESS_KEY=your-access-key         # change me
$ export AWS_SECRET_KEY=your-secret-access-key  # change me

With all that preparation behind us, we can finally run the playbook and enjoy some text-based entertainment:

$ ansible-playbook playbook.yaml

For the grand finale, we will make our mother proud and clean after ourselves. And because we are too lazy to write down a playbook for this, we will just run an ad-hoc command like this:

$ ansible \
    -m steampunk.aws.ec2_vpc \
    -a "name=my-vpc cidr=10.0.0.0/16 state=absent" \
    localhost

And that is it for this short introduction. Now we are ready to start exploring the Modules API documentation.