Модуль amazon.aws.iam_role — Управление ролями AWS IAM

Примечание

Этот модуль входит в коллекцию amazon.aws (версия 8.2.1).

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

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

Для использования в плейбуке укажите: amazon.aws.iam_role.

Новая функция в community.aws 1.0.0

Описание
Требования
Параметры
Примечания
Примеры
Возвращаемые значения

Описание

Управление ролями AWS IAM.

Требования

Ниже перечислены требования, необходимые на хосте, на котором выполняется этот модуль.

python >= 3.6
boto3 >= 1.26.0
botocore >= 1.29.0

Параметры

Параметр	Комментарии
access_key aliases: aws_access_key_id, aws_access_key, ec2_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_ID`, `AWS_ACCESS_KEY` или `EC2_ACCESS_KEY` также могут использоваться в порядке убывания предпочтения. Параметры aws_access_key и profile являются взаимоисключающими. Псевдоним aws_access_key_id был добавлен в релизе 5.1.0 для согласованности с AWS botocore SDK. Псевдоним ec2_access_key устарел и будет удален в релизе после 2024-12-01. Поддержка переменной среды `EC2_ACCESS_KEY` устарела и будет удалена в релизе после 2024-12-01.
assume_role_policy_document json	Документ политики доверия, предоставляющий объекту разрешение на принятие роли. Этот параметр обязателен, когда `state=present`.
aws_ca_bundle path	Расположение пакета CA, используемого при проверке SSL-сертификатов. Переменная среды `AWS_CA_BUNDLE` также может использоваться.
aws_config dictionary	Словарь для изменения конфигурации botocore. Параметры можно найти в документации AWS https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config.
boundary aliases: boundary_policy_arn string	ARN управляемой политики IAM, используемой для ограничения разрешений, которые эта роль может передавать ролям/пользователям IAM, которые она создает. Границы не могут быть установлены для профилей экземпляров, поэтому, если указан этот параметр, то `create_instance_profile` должен быть `false`. Это предназначено для ролей/пользователей, имеющих разрешения на создание новых объектов IAM. Для получения дополнительной информации о границах см. https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html.
create_instance_profile boolean	Если не существует профиля экземпляра IAM с тем же `name`, установка `create_instance_profile=True` создаст профиль экземпляра IAM вместе с ролью. Этот параметр устарел и будет удален в релизе после 2026-05-01. Модуль amazon.aws.iam_instance_profile может использоваться для управления профилями экземпляров. По умолчанию `True` Варианты: `false` `true`
debug_botocore_endpoint_logs boolean	Использовать `botocore.endpoint` регистратор для анализа уникальных (а не общих) `"resource:action"` вызовов API, выполненных во время задачи, выводя набор в ключ resource_actions в результатах задачи. Используйте обратный вызов `aws_resource_action` для вывода в общий список, сделанный во время выполнения playbook. Переменная среды `ANSIBLE_DEBUG_BOTOCORE_LOGS` также может использоваться. Варианты: `false` ← (по умолчанию) `true`
delete_instance_profile boolean	Когда `delete_instance_profile=true` и `state=absent`, удаление роли также удалит профиль экземпляра с тем же `name`, что и роль, но только если профиль экземпляра связан с ролью. Применяется только при `state=absent`. Этот параметр устарел и будет удален в релизе после 2026-05-01. Модуль amazon.aws.iam_instance_profile может использоваться для управления профилями экземпляров. По умолчанию `False` Варианты: `false` `true`
description string	Предоставляет описание роли.
endpoint_url aliases: ec2_url, aws_endpoint_url, s3_url string	URL для подключения вместо стандартных конечных точек AWS. Хотя это можно использовать для подключения к другим совместимым с AWS службам, коллекции amazon.aws и community.aws тестируются только на AWS. Переменные среды `AWS_URL` или `EC2_URL` также могут использоваться в порядке убывания предпочтения. Псевдонимы ec2_url и s3_url устарели и будут удалены в релизе после 2024-12-01. Поддержка переменной среды `EC2_URL` устарела и будет удалена в релизе после 2024-12-01.
managed_policies aliases: managed_policy list / elements=string	Список ARN управляемых политик или понятных имен. Чтобы удалить все политики, установите `purge_policies=true` и `managed_policies=[]`. Чтобы внедрить встроенную политику, используйте amazon.aws.iam_policy.
max_session_duration integer	Максимальная продолжительность (в секундах) сессии при принятии роли. Допустимые значения находятся в диапазоне от 1 до 12 часов (от 3600 до 43200 секунд).

имя псевдонимы: role_name строка / обязательно	Имя роли. Примечание: Имена ролей уникальны в рамках учетной записи. Пути (`path`) не влияют на требования уникальности `name`. Например, нельзя иметь как `/Path1/MyRole`, так и `/Path2/MyRole` в одной учетной записи. `role_name` был добавлен в качестве псевдонима в релизе 7.2.0.
путь псевдонимы: prefix, path_prefix строка	Путь роли. Дополнительную информацию о путях IAM см. в документации по идентификаторам AWS IAM https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html. Обновление пути для существующей роли в настоящее время не поддерживается и приведет к предупреждению. `path_prefix` и `prefix` были добавлены в качестве псевдонимов в релизе 7.2.0.
профиль псевдонимы: aws_profile строка	Используемый профиль AWS для аутентификации. См. документацию AWS для получения дополнительной информации о профилях с именами https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html. Также может использоваться переменная окружения `AWS_PROFILE`. Параметр профиль взаимоисключающий с параметрами aws_access_key, aws_secret_key и security_token.
удалять_политики псевдонимы: purge_policy, purge_managed_policies булево	Когда `purge_policies=true`, любые управляемые политики, не указанные в `managed_policies`, будут откреплены. Выбор: `false` `true` ← (по умолчанию)
удалять_метки булево	Если удалять_метки=true и метки установлено, существующие метки будут очищены из ресурса, чтобы точно соответствовать тому, что определено параметром метки. Если параметр метки не установлен, метки не будут изменены, даже если удалять_метки=True. Ключи меток, начинающиеся с `aws:`, зарезервированы Amazon и не могут быть изменены. Поэтому они будут игнорироваться для целей параметра удалять_метки. См. документацию Amazon для получения дополнительной информации https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html#tag-conventions. Выбор: `false` `true` ← (по умолчанию)
регион псевдонимы: aws_region, ec2_region строка	Используемый регион AWS. Для глобальных сервисов, таких как IAM, Route53 и CloudFront, параметр регион игнорируется. Также могут использоваться переменные окружения `AWS_REGION` или `EC2_REGION`. См. документацию Amazon AWS для получения дополнительной информации http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region. Псевдоним `ec2_region` устарел и будет удален в релизе после 2024-12-01. Поддержка переменной окружения `EC2_REGION` устарела и будет удалена в релизе после 2024-12-01.
секретный_ключ псевдонимы: aws_secret_access_key, aws_secret_key, ec2_secret_key строка	Секретный ключ доступа AWS. См. документацию AWS для получения дополнительной информации о маркерах доступа https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys. Переменные окружения `AWS_SECRET_ACCESS_KEY`, `AWS_SECRET_KEY`, или `EC2_SECRET_KEY` также могут быть использованы в порядке убывания приоритета. Параметры секретный_ключ и профиль взаимоисключающие. Псевдоним aws_secret_access_key был добавлен в релизе 5.1.0 для согласованности с AWS botocore SDK. Псевдоним ec2_secret_key устарел и будет удален в релизе после 2024-12-01. Поддержка переменной окружения `EC2_SECRET_KEY` устарела и будет удалена в релизе после 2024-12-01.
токен_сессии псевдонимы: aws_session_token, security_token, aws_security_token, access_token строка	Токен сессии AWS STS для использования с временными учетными данными. См. документацию AWS для получения дополнительной информации о маркерах доступа https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys. Переменные окружения `AWS_SESSION_TOKEN`, `AWS_SECURITY_TOKEN` или `EC2_SECURITY_TOKEN` также могут быть использованы в порядке убывания приоритета. Параметры токен_сессии и профиль взаимоисключающие. Псевдонимы aws_session_token и токен_сессии были добавлены в релизе 3.2.0, при этом параметр был переименован из security_token в токен_сессии в релизе 6.0.0. Псевдонимы security_token, aws_security_token и access_token устарели и будут удалены в релизе после 2024-12-01. Поддержка переменных окружения `EC2_SECRET_KEY` и `AWS_SECURITY_TOKEN` устарела и будет удалена в релизе после 2024-12-01.
состояние строка	Создание или удаление роли IAM. Выбор: `"present"` ← (по умолчанию) `"absent"`
метки псевдонимы: resource_tags словарь	Словарь, представляющий метки, которые необходимо применить к ресурсу. Если параметр метки не установлен, метки не будут изменены.

validate_certs boolean	При установке в значение `false`, сертификаты SSL для связи с API AWS не будут проверены. Установка validate_certs=false категорически не рекомендуется. В качестве альтернативы, можно настроить aws_ca_bundle. Варианты: `false` `true` ← (по умолчанию)
wait boolean	При установке в `wait=True` модуль будет ожидать до `wait_timeout` секунд создания роли IAM перед возвратом. Варианты: `false` `true` ← (по умолчанию)
wait_timeout integer	Время ожидания завершения создания/обновления в секундах. По умолчанию: `120`

Примечания

Примечание

Внимание: Для модулей переменные среды и конфигурационные файлы считываются из контекста Ansible «хост», а не «контроллера». Поэтому, возможно, потребуется явно скопировать файлы на «хост». Для плагинов поиска и подключения переменные среды и конфигурационные файлы считываются из контекста Ansible «контроллер», а не «хост».
AWS SDK (boto3), используемый Ansible, также может считывать значения по умолчанию для учетных данных и других настроек, таких как регион, из своих конфигурационных файлов в контексте Ansible «хост» (обычно ~/.aws/credentials). Подробнее см. https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html.

Примеры

# Note: These examples do not set authentication details, see the AWS Guide for details.

- name: Create a role with description and tags
  amazon.aws.iam_role:
    name: mynewrole
    assume_role_policy_document: "{{ lookup('file','policy.json') }}"
    description: This is My New Role
    tags:
      env: dev

- name: "Create a role and attach a managed policy called 'PowerUserAccess'"
  amazon.aws.iam_role:
    name: mynewrole
    assume_role_policy_document: "{{ lookup('file','policy.json') }}"
    managed_policies:
      - arn:aws:iam::aws:policy/PowerUserAccess

- name: Keep the role created above but remove all managed policies
  amazon.aws.iam_role:
    name: mynewrole
    assume_role_policy_document: "{{ lookup('file','policy.json') }}"
    managed_policies: []

- name: Delete the role
  amazon.aws.iam_role:
    name: mynewrole
    assume_role_policy_document: "{{ lookup('file', 'policy.json') }}"
    state: absent

Значения возврата

Общие значения возврата задокументированы здесь, следующие являются полями, уникальными для данного модуля:

Ключ	Описание
iam_role сложный	Словарь, содержащий данные роли IAM. Возвращается: успех
arn строка	Amazon Resource Name (ARN), определяющий роль. Возвращается: всегда Пример: `"arn:aws:iam::1234567890:role/mynewrole"`
assume_role_policy_document словарь	Политика, предоставляющая сущности разрешение на принятие роли. Примечание: регистр ключей в этом словаре больше не преобразуется из CamelCase в snake_case. Это поведение изменилось в релизе 8.0.0. Возвращается: всегда Пример: `{"statement": [{"action": "sts:AssumeRole", "effect": "Allow", "principal": {"service": "ec2.amazonaws.com"}, "sid": ""}], "version": "2012-10-17"}`
assume_role_policy_document_raw словарь добавлено в amazon.aws 5.3.0	Примечание: это значение возврата устарело и будет удалено в релизе после 2026-05-01. `iam_role.assume_role_policy_document` и `iam_role.assume_role_policy_document_raw` теперь используют тот же формат. Возвращается: всегда Пример: `{"statement": [{"action": "sts:AssumeRole", "effect": "Allow", "principal": {"service": "ec2.amazonaws.com"}, "sid": ""}], "version": "2012-10-17"}`
attached_policies список / элементы=словарь	Список словарей, содержащих имя и ARN управляемых политик IAM, присоединённых к роли. Возвращается: всегда Пример: `[{"policy_arn": "arn:aws:iam::aws:policy/PowerUserAccess", "policy_name": "PowerUserAccess"}]`
policy_arn строка	Amazon Resource Name (ARN), определяющий управляемую политику. Возвращается: успех Пример: `"arn:aws:iam::123456789012:policy/test_policy"`
policy_name строка	Дружественное имя, идентифицирующее политику. Возвращается: успех Пример: `"test_policy"`
create_date строка	Дата и время создания роли в формате ISO 8601. Возвращается: всегда Пример: `"2016-08-14T04:36:28+00:00"`
description строка	Описание роли. Возвращается: всегда Пример: `"This is My New Role"`
max_session_duration целое число	Максимальная продолжительность сеанса (в секундах) при принятии роли. Возвращается: всегда Пример: `3600`
path строка	Путь к роли. Возвращается: всегда Пример: `"/"`
role_id строка	Уникальная строка, идентифицирующая роль. Возвращается: всегда Пример: `"ABCDEFF4EZ4ABCDEFV4ZC"`
role_last_used словарь	Содержит информацию о последнем использовании роли IAM. Возвращается: всегда Пример: `{"last_used_date": "2023-11-22T21:54:29+00:00", "region": "us-east-2"}`
last_used_date строка	Дата и время последнего использования роли в формате ISO 8601. Возвращается: всегда
region строка	Название региона Amazon Web Services, в котором роль была использована в последний раз. Возвращается: всегда
role_name строка	Дружественное имя, идентифицирующее роль. Возвращается: всегда Пример: `"myrole"`
tags словарь	Теги роли. Возвращается: всегда Пример: `{"Env": "Prod"}`

Авторы

Rob White (@wimnat)

Справочные ссылки

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