.. meta::
   :description: Read more about the general steps you need to take when using the AWS Ansible Collection.


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

.. _registration: https://steampunk.si/#try-aws
.. _Terms and Conditions: https://steampunk.si/pdf/Terms_and_Conditions.pdf

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.

.. code-block:: yaml

   ---
   - 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 :ref:`doc_modules` API documentation.