amazon.aws.aws_ec2 库存 – EC2 库存源
注意
此库存插件是 amazon.aws 集合（版本 9.0.0）的一部分。
如果您使用的是 ansible 包，您可能已经安装了此集合。它不包含在 ansible-core 中。要检查是否已安装，请运行 ansible-galaxy collection list。
要安装它，请使用：ansible-galaxy collection install amazon.aws。您需要其他要求才能使用此库存插件，请参阅 要求 了解详情。
要在 playbook 中使用它，请指定：amazon.aws.aws_ec2。
概要
从 Amazon Web Services EC2 获取库存主机。
库存文件是一个 YAML 配置文件，必须以
aws_ec2.{yml|yaml}结尾。示例：my_inventory.aws_ec2.yml。
要求
在执行此库存的本地控制器节点上需要以下要求。
python >= 3.6
boto3 >= 1.28.0
botocore >= 1.31.0
参数
参数 |
说明 |
|---|---|
AWS 访问密钥 ID。 有关访问令牌的更多信息，请参阅 AWS 文档 https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys。 aws_access_key 和 profile 选项是互斥的。 为了与 AWS botocore SDK 保持一致，在 5.1.0 版本中添加了 aws_access_key_id 别名。 ec2_access_key 别名已被弃用，将在 2024-12-01 之后的版本中删除。 配置
|
|
默认情况下，返回与 hostnames 列表的条目匹配的第一个名称。 如果您不介意在清单中出现重复条目，并且希望获取所有匹配的主机名，请打开此标志。 选项
|
|
要承担以执行查找的 IAM 角色的 ARN。 您仍然应提供具有执行 AssumeRole 操作足够权限的 AWS 凭证。 |
|
切换以启用/禁用清单源数据的缓存，需要设置缓存插件才能工作。 选项
配置
|
|
缓存连接数据或路径，请阅读缓存插件文档以了解详细信息。 配置
|
|
用于清单源数据的缓存插件。 默认值： 配置
|
|
用于缓存插件文件/表的前缀 默认值： 配置
|
|
缓存持续时间，以秒为单位 默认值： 配置
|
|
从 Jinja2 表达式创建变量。 默认值： |
|
一个过滤器列表。任何匹配其中一个过滤器的实例都会从结果中排除。 来自 可用的过滤器在此处列出 http://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html#options。 此列表中的每个条目都会触发一个搜索查询。因此，从性能的角度来看，最好使列表尽可能短。 默认值： |
|
过滤器值对的字典。 可用的过滤器在此处列出 http://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html#options。 默认值： |
|
基于 Jinja2 条件将主机添加到组。 默认值： |
|
主机名变量的优先级顺序列表。 列表中的元素可以是一个带有下面提到的键的字典或一个字符串。 可以是 http://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html#options 中指定的选项之一。 如果提供的值在上述选项中不存在，它将被用作文字字符串。 要使用标签作为主机名，请使用语法 tag:Name=Value 来使用主机名 Name_Value，或 tag:Name 来使用 Name 标签的值。 默认值： |
|
主机的名称。 |
|
要添加到 name 前面的前缀。与 name 相同的选项。 如果指定了 prefix，则最终主机名将是 prefix + separator + name。 默认值： |
|
当指定 prefix 时，用于分隔 prefix 和 name 的值。 默认值： |
|
来自 AWS 的主机变量名称的前缀。 |
|
来自 AWS 的主机变量名称的后缀。 |
|
一个过滤器列表。任何匹配至少一个过滤器的实例都包含在结果中。 可用的过滤器在此处列出 http://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html#options。 此列表中的每个条目都会触发一个搜索查询。因此，从性能的角度来看，最好使列表尽可能短。 默认值： |
|
根据变量的值将主机添加到组。 默认值： |
|
当主机变量的值为空字符串时的默认值。 此选项与 |
|
用于生成组的输入字典中的键 |
|
键组的父组 |
|
键组名称将以此前缀开头 默认值： |
|
用于构建键组名称的分隔符 默认值： |
|
将此选项设置为 此选项与 选项
|
|
与 keyed_groups 结合使用。 默认情况下，没有提供前缀或分隔符的键组的名称将以下划线开头。 这是因为默认前缀为 “” 且默认分隔符为 “_”。 如果未提供前缀，请将此选项设置为 False 以省略前导下划线（或其他分隔符）。 如果组名称来自映射，则分隔符仍用于连接项目。 要完全不在组名称中使用分隔符，请将键组的分隔符设置为空字符串。 选项
|
|
用于身份验证的命名 AWS 配置文件。 有关命名配置文件的更多信息，请参阅 AWS 文档 https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html。 profile 选项与 aws_access_key、aws_secret_key 和 security_token 选项互斥。 boto_profile 别名已弃用，将在 2024-12-01 之后的版本中删除。 配置
|
|
要使用的 AWS 区域。 有关更多信息，请参阅 Amazon AWS 文档 http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region。 配置
|
|
用于描述 EC2 实例的区域列表。 如果为空（默认值），则这将包括所有区域，但可能包括 us-gov-west-1 和 cn-north-1 等受限制的区域。 默认值： |
|
AWS 私有访问密钥。 有关访问令牌的更多信息，请参阅 AWS 文档 https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys。 secret_key 和 profile 选项互斥。 为了与 AWS botocore SDK 保持一致，在 5.1.0 版本中添加了 aws_secret_access_key 别名。 ec2_secret_key 别名已弃用，将在 2024-12-01 之后的版本中删除。 配置
|
|
用于临时凭证的 AWS STS 会话令牌。 有关访问令牌的更多信息，请参阅 AWS 文档 https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys。 security_token 和 profile 选项互斥。 别名 aws_session_token 和 session_token 在 3.2.0 版本中添加，参数在 6.0.0 版本中从 security_token 重命名为 session_token。 security_token、aws_security_token 和 access_token 别名已弃用，将在 2024-12-01 之后的版本中删除。 配置
|
|
如果 由于可以在表达式中使用事实，因此它们可能并非始终可用，默认情况下我们会忽略这些错误。 选项
|
|
默认情况下，如果遇到 403（禁止）错误代码，则此插件将失败。 你可以在清单配置文件中将此选项设置为 False，这将允许优雅地跳过 403 错误。 选项
|
|
使用像旧的 ec2.py 清单脚本一样的 ec2_tag_TAGNAME 键公开主机标签。 不鼓励使用此功能，我们建议迁移到新的 ``tags`` 结构。 选项
|
|
默认情况下，此插件使用通用的组名清理来创建安全且可用于 Ansible 的组名。此选项允许您覆盖该清理，以便允许从旧的清单脚本进行迁移，并匹配脚本的 ``replace_dash_in_groups`` 选项设置为 ``False`` 时的组清理。要使用构造的组来复制 ``replace_dash_in_groups = True`` 的行为，您需要使用 regex_replace 过滤器将这些条目的连字符替换为下划线。 为了使其工作，您还应该关闭 TRANSFORM_INVALID_GROUP_CHARS 设置，否则核心引擎将只是在其上使用标准的清理。 这不是默认设置，因为此类名称会破坏某些功能，因为并非所有字符都是有效的 Python 标识符，而组名最终会被用作 Python 标识符。 选项
|
|
将额外的变量合并到可用于组合的变量中（优先级最高）。 选项
配置
|
|
启用从 AWS Systems Manager (SSM) 清单服务中获取额外的 EC2 实例信息到 hostvars。 通过利用 SSM 清单数据，use_ssm_inventory 选项提供有关您的清单中 EC2 实例的额外详细信息和属性。这些详细信息可能包括操作系统信息、已安装的软件、网络配置以及 SSM 中定义的自定义清单属性。 选项
|
注释
注意
如果没有提供凭据，并且控制节点具有关联的 IAM 实例配置文件，则该角色将用于身份验证。
注意： 对于模块，环境变量和配置文件是从 Ansible “主机” 上下文而不是 “控制器” 上下文中读取的。因此，可能需要将文件显式复制到“主机”。对于查找和连接插件，环境变量和配置文件是从 Ansible “控制器” 上下文而不是 “主机” 上下文中读取的。
Ansible 使用的 AWS SDK (boto3) 也可能会从 Ansible “主机” 上下文中的配置文件（通常是
~/.aws/credentials）中读取凭据和其他设置（例如区域）的默认值。有关详细信息，请参阅 https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html。
示例
# Minimal example using environment vars or instance role credentials
# Fetch all hosts in us-east-1, the hostname is the public DNS if it exists, otherwise the private IP address
plugin: amazon.aws.aws_ec2
regions:
- us-east-1
---
# Example using filters, ignoring permission errors, and specifying the hostname precedence
plugin: amazon.aws.aws_ec2
# The values for profile, access key, secret key and token can be hardcoded like:
profile: aws_profile
# or you could use Jinja as:
# profile: "{{ lookup('env', 'AWS_PROFILE') | default('aws_profile', true) }}"
# Populate inventory with instances in these regions
regions:
- us-east-1
- us-east-2
filters:
## All instances with their `Environment` tag set to `dev`
# tag:Environment: dev
# All dev and QA hosts
tag:Environment:
- dev
- qa
instance.group-id: sg-xxxxxxxx
# Ignores 403 errors rather than failing
strict_permissions: false
# Note: I(hostnames) sets the inventory_hostname. To modify ansible_host without modifying
# inventory_hostname use compose (see example below).
hostnames:
- tag:Name=Tag1,Name=Tag2 # Return specific hosts only
- tag:CustomDNSName
- dns-name
- name: 'tag:Name=Tag1,Name=Tag2'
- name: 'private-ip-address'
separator: '_'
prefix: 'tag:Name'
- name: 'test_literal' # Using literal values for hostname
separator: '-' # Hostname will be aws-test_literal
prefix: 'aws'
# Returns all the hostnames for a given instance
allow_duplicated_hosts: false
---
# Example using constructed features to create groups and set ansible_host
plugin: amazon.aws.aws_ec2
regions:
- us-east-1
- us-west-1
# keyed_groups may be used to create custom groups
strict: false
keyed_groups:
# Add e.g. x86_64 hosts to an arch_x86_64 group
- prefix: arch
key: 'architecture'
# Add hosts to tag_Name_Value groups for each Name/Value tag pair
- prefix: tag
key: tags
# Add hosts to e.g. instance_type_z3_tiny
- prefix: instance_type
key: instance_type
# Create security_groups_sg_abcd1234 group for each SG
- key: 'security_groups|json_query("[].group_id")'
prefix: 'security_groups'
# Create a group for each value of the Application tag
- key: tags.Application
separator: ''
# Create a group per region e.g. aws_region_us_east_2
- key: placement.region
prefix: aws_region
# Create a group (or groups) based on the value of a custom tag "Role" and add them to a metagroup called "project"
- key: tags['Role']
prefix: foo
parent_group: "project"
# Set individual variables with compose
compose:
# Use the private IP address to connect to the host
# (note: this does not modify inventory_hostname, which is set via I(hostnames))
ansible_host: private_ip_address
---
# Example using include_filters and exclude_filters to compose the inventory.
plugin: amazon.aws.aws_ec2
regions:
- us-east-1
- us-west-1
include_filters:
- tag:Name:
- 'my_second_tag'
- tag:Name:
- 'my_third_tag'
exclude_filters:
- tag:Name:
- 'my_first_tag'
---
# Example using groups to assign the running hosts to a group based on vpc_id
plugin: amazon.aws.aws_ec2
profile: aws_profile
# Populate inventory with instances in these regions
regions:
- us-east-2
filters:
# All instances with their state as `running`
instance-state-name: running
keyed_groups:
- prefix: tag
key: tags
compose:
ansible_host: public_dns_name
groups:
libvpc: vpc_id == 'vpc-####'
---
# Define prefix and suffix for host variables coming from AWS.
plugin: amazon.aws.aws_ec2
regions:
- us-east-1
hostvars_prefix: 'aws_'
hostvars_suffix: '_ec2'