ec2 – Inventory source for AWS EC2 instances (Enterprise only)

Builds inventory from AWS EC2 instances.

Requires a configuration file ending in .ec2.yml or .ec2.yaml.

If an EC2 instance has a Name tag, it is used as the inventory hostname. Otherwise, the plugin uses ID of the EC2 instance as the inventory hostname.

The plugin fails when it detects different hosts under the same inventory hostname.

The plugin sets host variables id, name, private_ip, private_dns, public_ip, public_dns and state.

This plugin is an Enterprise-only feature of the AWS Ansible Collection.

Examples

# Make all EC2 instances in the region inventory hosts without adding them
# to any group, using private IPs as inventory hostnames (default).
plugin: steampunk.aws.ec2
# `ansible-inventory -i inventory.ec2.yaml --graph` output:
# @all:
#   |--@ungrouped:
#   |  |--backend
#   |  |--database

# Add all EC2 instances in the region to inventory group 'my_instances', using
# private DNS names as inventory hostnames
plugin: steampunk.aws.ec2
ansible_host_source: private_dns
groups:
  my_instances:
# `ansible-inventory -i inventory.ec2.yaml --graph` output:
# @all:
#   |--@my_instances:
#   |  |--backend
#   |  |--database
#   |--@ungrouped:

# Put only the specific EC2 instances in the region to various named groups,
# according to the specified criteria.
plugin: steampunk.aws.ec2
groups:
  db_servers:
    # All values of the 'db' tag, for instance mongo-master, mongo-slave, redis
    tag_keys: db
  app_servers:
    # All instances with 'service' tag set to 'frontend' or 'backend'
    tags:
      service:
        - frontend
        - backend
  infra:
    # All running instances with 'service' tag set to 'middleware' and
    # instance type of either t3.micro or t3.nano
    tags:
      service: middleware
    filters:
      instance-state-name: running
      instance-type:
        - t3.micro
        - t2.nano
# `ansible-inventory -i inventory.ec2.yaml --graph` output:
# @all:
#   |--@app_servers:
#   |  |--backend
#   |--@db_servers:
#   |  |--database
#   |--@infra:
#   |--@ungrouped:


# By default, ansible_host contains instance's private IP address:
plugin: steampunk.aws.ec2
# `ansible-inventory -i inventory.ec2.yaml --graph  --vars` output:
# @all:
#   |--@ungrouped:
#   |  |--backend
#   |  |  |--{ansible_host = 10.0.0.213}
#   |  |  |--{id = i-057333a748ef7e040}
#   |  |  |--{name = zvonko}
#   |  |  |--{private_dns = ip-10-0-0-213.eu-central-1.compute.internal}
#   |  |  |--{private_ip = 10.0.0.213}
#   |  |  |--{public_dns = }
#   |  |  |--{public_ip = 3.127.20.200}
#   |  |  |--{state = running}

# Use ansible_host_source to change the source.
plugin: steampunk.aws.ec2
ansible_host_source: public_ip
# `ansible-inventory -i inventory.ec2.yaml --graph  --vars` output:
# @all:
#   |--@ungrouped:
#   |  |--backend
#   |  |  |--{ansible_host = 3.127.20.200}
#   |  |  |--{id = i-057333a748ef7e040}
#   |  |  |--{name = zvonko}
#   |  |  |--{private_dns = ip-10-0-0-213.eu-central-1.compute.internal}
#   |  |  |--{private_ip = 10.0.0.213}
#   |  |  |--{public_dns = }
#   |  |  |--{public_ip = 3.127.20.200}
#   |  |  |--{state = running}

Parameters

ansible_host_source (optional)

Host variable to use when generating inventory hosts.

Note that even if an EC2 instance fits the criteria for inclusion in the inventory specified under groups.<group_name>, it will not be added to the inventory if the designated host variable is not defined. For example, an EC2 instance may be up and running, but does not have a public IP; if this is the case and you specify ansible_host_source=public_ip, the plugin does not add the EC2 instance as an inventory host.

type: str
default: private_ip
choices: private_ip, private_dns, public_ip, public_dns
auth (optional)

Parameters for authenticating with the AWS service. Each of them may be defined via environment variables.

type: dict
access_key (optional)

The AWS access key ID. If not set, the value of the AWS_ACCESS_KEY environment variable will be checked.

Mutually exclusive with profile.

type: str
profile (optional)

The name of the AWS profile configured with aws configure.

Can be used instead of explicitly specifying your access credentials and region.

Use default to use the default profile.

Mutually exclusive with access_key and secret_key.

type: str
region (optional)

The name of the AWS region.

If not set, the value of the AWS_REGION environment variable will be checked.

If you set a profile that specifies a default region, that region is used and you can omit this parameter. Use this parameter to override the profile’s default region.

type: str
secret_key (optional)

The AWS secret access key. If not set, the value of the AWS_SECRET_KEY environment variable will be checked.

Mutually exclusive with profile.

type: str
url (optional)

The URL to the AWS service related to the resource. By default, this is automatically determined through the region parameter.

If not set explicitly, the value of the AWS_<SERVICE>_URL environment variable will be used.

The services currently supported are EC2 and S3.

type: str
groups (optional)

Configuration of inventory groups.

If you specify this parameter, it must contain at least one group.

Note that the inventory plugin will create only the groups you specify (containing only the hosts matching the criteria for each individual group) - no additional groups will be created.

If you omit this parameter, the plugin will add all EC2 instances in the region as inventory hosts by default. In this case, all the hosts will remain ungrouped.

type: dict
<group_name> (optional)

Criteria to include EC2 instances as hosts in this inventory group.

For an EC2 instance to be included, it must satisfy all the criteria provided via tag_keys, tags and filters.

If no EC2 instances match the specified criteria, the resulting group is created but contains no members.

type: dict
filters (optional)

Additional filters for limiting EC2 instances to be added to this group as inventory hosts.

An EC2 instance will be added as an inventory host if it matches all the filters you provide.

Each filter accepts a list of values to be checked. If an EC2 instance matches any of the values, it will be included in the result.

Note that filters and their values are case sensitive.

By default, the inventory plugin ignores terminated EC2 instances. You can override this behavior by specifying allowed EC2 instance states in the instance-state-name filter.

The complete list of supported filters and their allowed values is available at https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html#options.

Use tag_keys and tags for filtering EC2 instances based on AWS tags.

type: dict
tag_keys (optional)

Include an EC2 instance as an inventory host only if it is tagged with any of the provided keys, regardless of their values.

Note that the tag keys are case sensitive.

If you need to need to filter EC2 instances on both tag keys and their values, use tags instead.

type: list
tags (optional)

Include an EC2 instance as an inventory host if it contains all of the specified tags.

Each tag accepts a list of values to be checked, e.g. Name=[instance-1, instance-2]. If an EC2 instance has the tag with any of the specified values, it will be included in the result.

Note that the tag keys and values are case sensitive.

If you only need to check the presence of specific tag keys (i.e. if you do not care about their values), use tag_keys instead.

type: dict
plugin (required)

The name of this inventory plugin.

It must always be set to steampunk.aws.ec2, so that the inventory source is picked up by this plugin.

type: str
choices: steampunk.aws.ec2