.. meta:: :description: Builds inventory from AWS EC2 instances. Requires a configuration file ending in C(.ec2.yml) or C(.ec2.yaml). If an EC2 instance has a C(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 C(id), C(name), C(private_ip), C(private_dns), C(public_ip), C(public_dns) and C(state). This plugin is an Enterprise-only feature of the AWS Ansible Collection. .. _ec2_: 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 -------- .. code-block:: yaml+jinja # 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.*, 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__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 (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