.. meta::
   :description: Discover how the Steampunk AWS Collection EC2 inventory plugins works.

.. _doc_inventory:

Inventory plugins
=================

Inventory plugins offer an alternative to the more often used static inventory
files.

The following is a simple, but complete, example of using the inventory plugin:

.. code-block:: shell

    $ cat > inventory.ec2.yml <<EOF
    ---
    plugin: steampunk.aws.ec2
    groups:
      stopped_instances_in_my_vpc:
        filters:
          instance-state-name: stopped
          vpc-id: vpc-1232ef
    EOF
    $ cat > delete-stopped-vms.yml <<EOF
    - hosts: stopped_instances_in_my_vpc
      gather_facts: false
      tasks:
        - steampunk.aws.ec2_instance:
            id: "{{ id }}"
            state: absent
          delegate_to: localhost
    EOF
    $ export ANSIBLE_INVENTORY_ENABLED=steampunk.aws.ec2
    $ AWS_PROFILE=my-dev-profile ansible-playbook -i inventory.ec2.yml delete-stopped-vms.yml


The inventory file above (``inventory.ec2.yml``) filters hosts in a specific VPC in the stopped state.
Per Ansible conventions, it **must** be named ``*.ec2.{yml,yaml}`` to be parsed as a valid inventory
file, and it must also contain the ``plugin: steampunk.aws.ec2`` directive.
After enabling the inventory plugin by exporting an environment variable, we can run a playbook
that takes the filtered-i.e. stopped-hosts and removes them from AWS.


Plugin reference
----------------

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

   inventory/*