amazon.aws.aws_ec2: источник инвентаризации EC2

Примечание

Этот плагин инвентаризации входит в коллекцию amazon.aws (версия 11.3.0).

Возможно, эта коллекция уже установлена, если вы используете пакет ansible. Она не входит в состав ansible-core. Чтобы проверить, установлена ли она, выполните ansible-galaxy collection list.

Для установки используйте: ansible-galaxy collection install amazon.aws. Для использования этого плагина инвентаризации потребуются дополнительные компоненты. Подробную информацию см. в разделе Требования.

Чтобы использовать его в плейбуке, укажите: amazon.aws.aws_ec2.

Краткое описание
Требования
Параметры
Примечания
Примеры

Краткое описание

Получает узлы инвентаризации из Amazon Web Services EC2.
Файл инвентаризации представляет собой файл конфигурации YAML и должен иметь расширение aws_ec2.{yml|yaml}. Например: my_inventory.aws_ec2.yml.

Требования

Следующие компоненты должны быть установлены на локальном узле контроллера, выполняющем эту инвентаризацию.

python >= 3.6
boto3 >= 1.35.0
botocore >= 1.35.0

Параметры

Параметр	Комментарии
access_key aliases: aws_access_key_id, aws_access_key string	Идентификатор ключа доступа AWS. Дополнительные сведения о токенах доступа см. в документации 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_access_key_id добавлен в выпуске 5.1.0 для согласованности с AWS botocore SDK. Конфигурация: Переменная окружения: `AWS_ACCESS_KEY_ID` Переменная окружения: `AWS_ACCESS_KEY`
allow_duplicated_hosts boolean добавлено в amazon.aws 5.0.0	По умолчанию возвращается первое имя, соответствующее записи в списке `hostnames`. Включите этот параметр, если вас не смущают повторяющиеся записи в инвентаре и вы хотите получить все соответствующие имена хостов. Варианты: `false` ← (по умолчанию) `true`
assume_role_arn aliases: iam_role_arn string	ARN роли IAM, которую нужно принять для выполнения поиска. Необходимо по-прежнему предоставить учетные данные AWS с достаточными правами для выполнения действия AssumeRole.
cache boolean	Включает или отключает кэширование исходных данных инвентаря; для работы требуется настроенный плагин кэширования. Варианты: `false` ← (по умолчанию) `true` Конфигурация: Запись INI: [inventory] cache = false Переменная окружения: `ANSIBLE_INVENTORY_CACHE`
cache_connection string	Данные подключения к кэшу или путь; подробности см. в документации плагина кэширования. Конфигурация: Записи INI: [defaults] fact_caching_connection = VALUE [inventory] cache_connection = VALUE Переменная окружения: `ANSIBLE_CACHE_PLUGIN_CONNECTION` Переменная окружения: `ANSIBLE_INVENTORY_CACHE_CONNECTION`
cache_plugin string	Плагин кэширования, используемый для исходных данных инвентаря. По умолчанию: `"memory"` Конфигурация: Записи INI: [defaults] fact_caching = memory [inventory] cache_plugin = memory Переменная окружения: `ANSIBLE_CACHE_PLUGIN` Переменная окружения: `ANSIBLE_INVENTORY_CACHE_PLUGIN`
cache_prefix string	Префикс для файлов/таблиц плагина кэширования. По умолчанию: `"ansible_inventory_"` Конфигурация: Записи INI: [defaults] fact_caching_prefix = ansible_inventory_ [inventory] cache_prefix = ansible_inventory_ Переменная окружения: `ANSIBLE_CACHE_PLUGIN_PREFIX` Переменная окружения: `ANSIBLE_INVENTORY_CACHE_PLUGIN_PREFIX`
cache_timeout integer	Продолжительность хранения кэша в секундах. По умолчанию: `3600` Конфигурация: Записи INI: [defaults] fact_caching_timeout = 3600 [inventory] cache_timeout = 3600 Переменная окружения: `ANSIBLE_CACHE_PLUGIN_TIMEOUT` Переменная окружения: `ANSIBLE_INVENTORY_CACHE_TIMEOUT`
compose dictionary	Создает переменные на основе выражений jinja2. По умолчанию: `{}`
endpoint_url aliases: aws_endpoint_url string	URL для подключения вместо конечных точек AWS по умолчанию. Этот параметр можно использовать для подключения к другим совместимым с AWS службам, однако коллекции amazon.aws и community.aws тестируются только с AWS. Конфигурация: Переменная окружения: `AWS_URL`
exclude_filters list / elements=dictionary добавлено в amazon.aws 1.5.0	Список фильтров. Все экземпляры, соответствующие одному из фильтров, исключаются из результата. Фильтры из `exclude_filters` имеют приоритет над ключами `include_filters` и `filters`. Список доступных фильтров приведен здесь: http://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html#options. Каждый элемент этого списка запускает поисковый запрос. Поэтому с точки зрения производительности список лучше сделать как можно короче. По умолчанию: `[]`
filters dictionary	Словарь пар значений фильтров. Список доступных фильтров приведен здесь: http://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html#options. По умолчанию: `{}`
groups dictionary	Добавляет хосты в группу на основе условий Jinja2. По умолчанию: `{}`
hostnames list / elements=any	Список переменных имени хоста в порядке приоритета. Элементы списка могут быть словарем с указанными ниже ключами или строкой. Значение может быть одним из параметров, указанных здесь: http://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html#options. Если указанного значения нет среди перечисленных выше параметров, оно будет использовано как строковый литерал. Чтобы использовать теги в качестве имен хостов, укажите синтаксис tag:Name=Value, чтобы использовать имя хоста Name_Value, или tag:Name, чтобы использовать значение тега Name. В строку имен хостов можно добавить фильтры Jinja2. Добавлено в версии 9.2.0. По умолчанию: `[]`
name string / обязательный	Имя хоста.
prefix string	Префикс, добавляемый перед `hostnames.name`. Те же параметры, что и для `hostnames.name`. Если указан `hostnames.prefix`, итоговое имя хоста будет равно `hostnames.prefix` + `hostnames.separator` + `hostnames.name`. По умолчанию: `""`
separator string	Значение-разделитель между `hostnames.prefix` и `hostnames.name`, если указан `hostnames.prefix`. По умолчанию: `"_"`
hostvars_prefix string добавлено в amazon.aws 3.1.0	Префикс имен переменных хоста, полученных из AWS.
hostvars_suffix string добавлено в amazon.aws 3.1.0	Суффикс имен переменных хоста, полученных из AWS.
include_filters list / elements=dictionary добавлено в amazon.aws 1.5.0	Список фильтров. Все экземпляры, соответствующие хотя бы одному фильтру, включаются в результат. Список доступных фильтров приведен здесь: http://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html#options. Каждый элемент этого списка запускает поисковый запрос. Поэтому с точки зрения производительности список лучше сделать как можно короче. По умолчанию: `[]`
keyed_groups list / elements=dictionary	Добавляет хосты в группу на основе значений переменной. По умолчанию: `[]`
default_value string добавлено в ansible-core 2.12	Значение по умолчанию, если значение переменной хоста равно `None` или представляет собой пустую строку. Этот параметр взаимоисключающий с `keyed_groups[].trailing_separator`.
key string	Ключ входного словаря, используемый для создания групп.
parent_group string	Родительская группа для группы, созданной по ключу.
prefix string	Имя группы, созданной по ключу, будет начинаться с этого префикса. По умолчанию: `""`
separator string	Разделитель, используемый для формирования имени группы, созданной по ключу. По умолчанию: `"_"`
trailing_separator boolean добавлено в ansible-core 2.12	Установите для этого параметра значение `false`, чтобы не добавлять `keyed_groups[].separator` после переменной хоста, если ее значение равно `None` или представляет собой пустую строку. Этот параметр взаимоисключающий с `keyed_groups[].default_value`. Варианты: `false` `true` ← (по умолчанию)
leading_separator boolean добавлено в ansible-core 2.11	Используйте вместе с `keyed_groups`. По умолчанию имя группы, созданной по ключу, для которой не задан префикс или разделитель, начинается с символа подчеркивания. Это происходит потому, что префикс по умолчанию — `""`, а разделитель по умолчанию — `"_"`. Установите для этого параметра значение `false`, чтобы не добавлять начальное подчеркивание (или другой разделитель), если префикс не задан. Если имя группы получено из сопоставления, разделитель по-прежнему используется для объединения элементов. Чтобы полностью отказаться от разделителя в имени группы, задайте для группы, созданной по ключу, пустую строку в качестве разделителя. Варианты: `false` `true` ← (по умолчанию)
profile aliases: aws_profile string	Именованный профиль AWS для аутентификации. Дополнительные сведения об именованных профилях см. в документации AWS: https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html. Параметр profile взаимоисключающий с параметрами aws_access_key, aws_secret_key и session_token. Конфигурация: Переменная окружения: `AWS_PROFILE` Переменная окружения: `AWS_DEFAULT_PROFILE`
region aliases: aws_region string	Используемый регион AWS. Дополнительные сведения см. в документации Amazon AWS: http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region. Конфигурация: Переменная окружения: `AWS_REGION`
regions list / elements=string	Список регионов, в которых следует описать экземпляры EC2. Если список пуст (значение по умолчанию), будут включены все регионы, за исключением, возможно, регионов с ограниченным доступом, таких как `us-gov-west-1` и `cn-north-1`. По умолчанию: `[]`
route53_enabled boolean добавлено в amazon.aws 10.1.0	Использовать ли DNS Route53 в качестве имени хоста. Если установлено значение `true`, будут включены имена хостов Route53. Варианты: `false` ← (по умолчанию) `true`
route53_excluded_zones list / elements=string добавлено в amazon.aws 10.1.0	Список зон Route53, которые нужно исключить. По умолчанию: `[]`
route53_hostnames list / elements=string добавлено в amazon.aws 10.1.0	Задает суффикс имени DNS Route53, который следует учитывать. Учитываются только зоны Route53, имена которых заканчиваются указанным здесь значением. По умолчанию: `[]`
secret_key aliases: aws_secret_access_key, aws_secret_key string	Секретный ключ доступа 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_secret_access_key добавлен в выпуске 5.1.0 для согласованности с AWS botocore SDK. Конфигурация: Переменная окружения: `AWS_SECRET_ACCESS_KEY` Переменная окружения: `AWS_SECRET_KEY`
session_token aliases: aws_session_token string	Токен сеанса AWS STS для использования с временными учетными данными. Дополнительные сведения о токенах доступа см. в документации AWS: https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys. Параметры session_token и profile являются взаимоисключающими. Конфигурация: Переменная окружения: `AWS_SESSION_TOKEN`

strict boolean	Если `yes`, считать недопустимые записи критической ошибкой; в противном случае пропускать их и продолжать работу. Поскольку в выражениях можно использовать факты, они могут быть доступны не всегда, поэтому по умолчанию такие ошибки игнорируются. Варианты: `false` ← (по умолчанию) `true`
strict_permissions boolean	По умолчанию этот плагин завершает работу с ошибкой при получении кода ошибки 403 (Forbidden). Можно задать для этого параметра значение False в файле конфигурации инвентаризации, чтобы ошибки 403 можно было безопасно пропускать. Варианты: `false` `true` ← (по умолчанию)
use_contrib_script_compatible_ec2_tag_keys boolean добавлен в amazon.aws 1.5.0	Предоставлять теги узлов с ключами `ec2_tag_TAGNAME`, как в старом скрипте инвентаризации `ec2.py`. Использование этой функции объявлено устаревшим; она будет удалена в одном из выпусков после 2026-12-01. Вместо этого используйте структуру `ec2_tags` (например, используйте `ec2_tags.TAGNAME` вместо `ec2_tag_TAGNAME`). Варианты: `false` ← (по умолчанию) `true`
use_contrib_script_compatible_sanitization boolean	По умолчанию этот плагин использует общую очистку имён групп, чтобы создавать безопасные и пригодные для использования в Ansible имена. Этот параметр позволяет переопределить такое поведение для упрощения перехода со старого скрипта инвентаризации `ec2.py` и соответствует очистке имён групп, выполняемой скриптом, если для его параметра ``replace_dash_in_groups`` задано значение ``False``. Чтобы воспроизвести поведение ``replace_dash_in_groups = True`` при использовании создаваемых групп, необходимо заменять дефисы на символы подчёркивания с помощью фильтра regex_replace для соответствующих записей. Чтобы это работало, необходимо также отключить параметр TRANSFORM_INVALID_GROUP_CHARS, иначе основной движок дополнительно применит стандартную очистку. Это не используется по умолчанию, поскольку такие имена нарушают работу некоторых функций: не все символы допустимы в идентификаторах Python, которыми становятся имена групп. Использование этой функции объявлено устаревшим; она будет удалена в одном из выпусков после 2026-12-01. Вместо этого используйте стандартную очистку имён групп Ansible. Варианты: `false` ← (по умолчанию) `true`
use_extra_vars boolean добавлен в ansible-core 2.11	Объединять дополнительные переменные с доступными переменными для формирования значений (наивысший приоритет). Варианты: `false` ← (по умолчанию) `true` Конфигурация: Запись INI: [inventory_plugins] use_extra_vars = false Переменная окружения: `ANSIBLE_INVENTORY_USE_EXTRA_VARS`
use_ssm_inventory boolean добавлен в amazon.aws 6.0.0	Включает получение дополнительных сведений об экземплярах EC2 из службы инвентаризации AWS Systems Manager (SSM) и добавление их в hostvars. Используя данные инвентаризации SSM, параметр `use_ssm_inventory` предоставляет дополнительные сведения и атрибуты экземпляров EC2 в инвентаризации. Эти сведения могут включать информацию об операционной системе, установленном программном обеспечении, конфигурациях сети и пользовательских атрибутах инвентаризации, определённых в SSM. Варианты: `false` ← (по умолчанию) `true`

Примечание

Перечисленные выше записи конфигурации для каждого типа записи (переменная Ansible, переменная окружения и т. д.) упорядочены от низшего приоритета к высшему. Например, переменная, расположенная ниже в списке, переопределит переменную, расположенную выше. Типы записей также упорядочены по приоритету от низшего к высшему. Например, запись в ansible.cfg (расположенная выше в списке) переопределяется переменной Ansible (расположенной ниже в списке).

Примечания

Примечание

Если учётные данные не указаны, а узлу управления назначен профиль экземпляра IAM, для аутентификации будет использоваться эта роль.
Переменная узла tags объявлена устаревшей и будет удалена в одном из выпусков после 2026-12-01. Во избежание конфликтов с зарезервированными именами переменных Ansible используйте вместо неё ec2_tags.
Переменная узла ec2_tags добавлена в версии 11.2.0.
Параметр use_contrib_script_compatible_ec2_tag_keys объявлен устаревшим и будет удалён в одном из выпусков после 2026-12-01. Вместо этого используйте структуру ec2_tags (например, используйте ec2_tags.TAGNAME вместо ec2_tag_TAGNAME).
Параметр use_contrib_script_compatible_sanitization объявлен устаревшим и будет удалён в одном из выпусков после 2026-12-01. Вместо этого используйте стандартную очистку имён групп Ansible.
На этом этапе инвентаризация ещё не завершена, поэтому автоматически заполненные группы all и ungrouped будут содержать только то, что в них явно добавили предыдущие источники инвентаризации.
«Магические переменные» времени выполнения недоступны при построении инвентаризации. Например, groups и hostvars ещё не существуют.
Внимание: Для модулей переменные окружения и файлы конфигурации считываются из контекста «узла» Ansible, а не из контекста «контроллера». Поэтому файлы, возможно, потребуется явно скопировать на «узел». Для плагинов поиска и подключения переменные окружения и файлы конфигурации считываются из контекста «контроллера» Ansible, а не из контекста «узла».
Пакет AWS SDK (boto3), используемый Ansible, также может считывать значения по умолчанию для учётных данных и других параметров, например региона, из файлов конфигурации в контексте «узла» 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: ec2_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: ec2_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: ec2_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: ec2_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'

---

# Define hostnames variables with jinja2 filters.
plugin: amazon.aws.aws_ec2
regions:
  - us-east-1
hostnames:
  - "tag:Name | replace('test', 'prod')"

---

# Define inventory with Route53 enabled and filtering specific route53 host names suffix.
plugin: amazon.aws.aws_ec2
regions:
  - us-east-1
route53_enabled: true
route53_hostnames:
  - .example.com
  - .another_example.org

---

# Define inventory with Route53 enabled and excluded zones.
plugin: amazon.aws.aws_ec2
regions:
  - us-east-1
route53_enabled: true
route53_excluded_zones:
  - ansible.bar.net
  - ansible.foo.net

Авторы

Sloane Hertel (@s-hertel)

Ссылки на коллекцию

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/amazon/aws/aws_ec2_inventory.html