amazon.aws.kms_key модуль – Выполнение различных задач управления ключами KMS

Примечание

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

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

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

Для использования в книге задач укажите: amazon.aws.kms_key.

Новый в amazon.aws 5.0.0

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

Описание

Управление доступом ролей/пользователей к ключу KMS.
Не предназначен для шифрования/расшифрования.
До версии 5.0.0 этот модуль назывался community.aws.aws_kms. Использование не изменилось.
Этот модуль был первоначально добавлен в community.aws в релизе 1.0.0.

Псевдонимы: aws_kms

Требования

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

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

Параметры

Параметр	Комментарии
access_key псевдонимы: aws_access_key_id, aws_access_key, ec2_access_key строка	ID ключа доступа 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 для согласованности с SDK AWS botocore. Псевдоним ec2_access_key устарел и будет удален в релизе после 2024-12-01. Поддержка переменной среды `EC2_ACCESS_KEY` устарела и будет удалена в релизе после 2024-12-01.
alias псевдонимы: key_alias строка	Псевдоним ключа. Для безопасности, хотя KMS не требует, чтобы ключи имели псевдоним, этот модуль ожидает, что все новые ключи будут иметь псевдоним для облегчения управления. Существующие ключи без псевдонима могут быть указаны с помощью `key_id`. Используйте amazon.aws.kms_key_info, чтобы найти идентификаторы ключей. Обратите внимание, что передача `key_id` и `alias` приведет только к добавлению нового псевдонима, псевдоним никогда не будет переименован. Префикс `alias/` необязателен. Требуется, если `key_id` не указано.
aws_ca_bundle путь	Расположение пакета CA для проверки SSL-сертификатов. Также может быть использована переменная среды `AWS_CA_BUNDLE`.
aws_config словарь	Словарь для изменения конфигурации botocore. Параметры можно найти в документации AWS https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config.
debug_botocore_endpoint_logs логический тип	Использование логгера `botocore.endpoint` для анализа уникальных (а не общих) `"resource:action"` API-вызовов, выполненных во время задачи, выводя набор в ключ resource_actions в результатах задачи. Используйте обратный вызов `aws_resource_action` для вывода в общий список, созданный во время выполнения плейбука. Также может быть использована переменная среды `ANSIBLE_DEBUG_BOTOCORE_LOGS`. Варианты: `false` ← (по умолчанию) `true`
description строка	Описание CMK. Используйте описание, которое поможет определить, подходит ли CMK для задачи.
enable_key_rotation логический тип	Автоматически ли ключ должен вращаться ежегодно. Варианты: `false` `true`
enabled логический тип	Включен ли ключ. Варианты: `false` `true` ← (по умолчанию)
endpoint_url псевдонимы: ec2_url, aws_endpoint_url, s3_url строка	URL для подключения вместо стандартных конечных точек AWS. Хотя это можно использовать для подключения к другим службам, совместимым с AWS, коллекции amazon.aws и community.aws протестированы только с AWS. Также могут быть использованы переменные среды `AWS_URL` или `EC2_URL` в порядке убывания приоритета. Псевдонимы ec2_url и s3_url устарели и будут удалены в релизе после 2024-12-01. Поддержка переменной среды `EC2_URL` устарела и будет удалена в релизе после 2024-12-01.
grants список / элементы=словарь	Список прав, применяемых к ключу. Каждый элемент должен содержать `grants.grantee_principal`. Каждый элемент может необязательно содержать `grants.retiring_principal`, `grants.operations`, `grants.constraints`, `grants.name`. `grants.grantee_principal` и `grants.retiring_principal` должны быть ARNs. Полная документация по подпараметрам доступна в документации boto3: https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/kms.html#KMS.Client.create_grant По умолчанию: `[]`
constraints словарь	Constraints — это словарь, содержащий `encryption_context_subset` или `encryption_context_equals`, каждый из которых является словарем, определяющим соответствие контексту шифрования. См. https://docs.aws.amazon.com/kms/latest/APIReference/API_GrantConstraints.html или https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/kms.html#KMS.Client.create_grant
grantee_principal строка / обязательно	Полный ARN субъекта, которому предоставляются разрешения.
name строка	Наименование разрешения. Используйте это значение, чтобы предотвратить случайное создание дублирующих разрешений при повторном выполнении этого запроса.

END_OF_DOCUMENT_MARKER

operations список / элементы=строка	Список операций, которые уполномоченное лицо может выполнять с помощью CMK. Варианты: `"Decrypt"` `"Encrypt"` `"GenerateDataKey"` `"GenerateDataKeyWithoutPlaintext"` `"ReEncryptFrom"` `"ReEncryptTo"` `"CreateGrant"` `"RetireGrant"` `"DescribeKey"` `"Verify"` `"Sign"`
retiring_principal строка	Полный ARN принципала, имеющего право аннулировать/вывести из обращения предоставление.
key_id псевдонимы: key_arn строка	Идентификатор или ARN ключа. Требуется один из `alias` или `key_id`.
key_spec псевдонимы: customer_master_key_spec строка добавлено в community.aws 2.1.0	Указывает тип ключа KMS для создания. Параметры не могут быть изменены после создания ключа. Варианты: `"SYMMETRIC_DEFAULT"` ← (по умолчанию) `"RSA_2048"` `"RSA_3072"` `"RSA_4096"` `"ECC_NIST_P256"` `"ECC_NIST_P384"` `"ECC_NIST_P521"` `"ECC_SECG_P256K1"`
key_usage строка добавлено в community.aws 2.1.0	Определяет криптографические операции, для которых можно использовать ключ KMS. Параметры использования не могут быть изменены после создания ключа. Варианты: `"ENCRYPT_DECRYPT"` ← (по умолчанию) `"SIGN_VERIFY"`
multi_region логический добавлено в amazon.aws 5.5.0	Создавать или нет первичный ключ в нескольких регионах. Варианты: `false` ← (по умолчанию) `true`
pending_window псевдонимы: deletion_delay целое число добавлено в community.aws 1.4.0	Количество дней между запросом на удаление CMK и фактическим удалением. Используется только при `state=absent` и CMK еще не удален. Допустимые значения от `7` до `30` (включительно). См. также: https://docs.aws.amazon.com/kms/latest/APIReference/API_ScheduleKeyDeletion.html#KMS-ScheduleKeyDeletion-request-PendingWindowInDays
policy json	Политика, применяемая к ключу KMS. См. https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html
profile псевдонимы: aws_profile строка	Используемый профайл AWS с именем. Дополнительную информацию о профилях с именами см. в документации AWS https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html. Также можно использовать переменную среды `AWS_PROFILE`. Параметр profile несовместим с параметрами aws_access_key, aws_secret_key и security_token.
purge_grants логический	Если аргумент `grants` должен привести к удалению предоставлений, которые не указаны в списке. Варианты: `false` ← (по умолчанию) `true`
purge_tags логический	Если purge_tags=true и tags установлены, существующие теги будут очищены для точного соответствия параметру tags. Если параметр tags не установлен, теги не будут изменены, даже если purge_tags=True. Ключи тегов, начинающиеся с `aws:`, зарезервированы Amazon и не могут быть изменены. Таким образом, они будут проигнорированы в целях параметра purge_tags. Дополнительную информацию см. в документации Amazon https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html#tag-conventions. Варианты: `false` `true` ← (по умолчанию)
region псевдонимы: aws_region, ec2_region строка	Используемый регион AWS. Для глобальных сервисов, таких как IAM, Route53 и CloudFront, параметр region игнорируется. Также можно использовать переменные среды `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.

secret_key aliases: 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` в порядке убывания приоритета. Параметры secret_key и profile взаимоисключающие. Псевдоним aws_secret_access_key был добавлен в релизе 5.1.0 для согласованности с SDK AWS botocore. Псевдоним ec2_secret_key устарел и будет удален в релизе после 2024-12-01. Поддержка переменной среды `EC2_SECRET_KEY` устарела и будет удалена в релизе после 2024-12-01.
session_token aliases: 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` в порядке убывания приоритета. Параметры security_token и profile взаимоисключающие. Псевдонимы aws_session_token и session_token были добавлены в релизе 3.2.0, а параметр был переименован из security_token в session_token в релизе 6.0.0. Псевдонимы security_token, aws_security_token и access_token устарели и будут удалены в релизе после 2024-12-01. Поддержка переменных среды `EC2_SECRET_KEY` и `AWS_SECURITY_TOKEN` устарела и будет удалена в релизе после 2024-12-01.
state строка	Определяет, должен ли ключ присутствовать или отсутствовать. Обратите внимание, что удаление существующего ключа только запланирует его удаление. Передача ключа, запланированного на удаление с `state=present`, отменит удаление ключа. Варианты: `"present"` ← (по умолчанию) `"absent"`
tags aliases: resource_tags словарь	Словарь, представляющий теги, которые необходимо применить к ресурсу. Если параметр tags не задан, теги не будут изменены.
validate_certs логическое	При установке в `false`, сертификаты SSL для связи с API AWS не будут проверены. Установка validate_certs=false настоятельно не рекомендуется; вместо этого рассмотрите возможность установки aws_ca_bundle. Варианты: `false` `true` ← (по умолчанию)

Примечания

Примечание

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

Примеры

# Create a new KMS key
- amazon.aws.kms_key:
    alias: mykey
    tags:
      Name: myKey
      Purpose: protect_stuff

# Create a new multi-region KMS key
- amazon.aws.kms_key:
    alias: mykey
    multi_region: true
    tags:
      Name: myKey
      Purpose: protect_stuff

# Update previous key with more tags
- amazon.aws.kms_key:
    alias: mykey
    tags:
      Name: myKey
      Purpose: protect_stuff
      Owner: security_team

# Update a known key with grants allowing an instance with the billing-prod IAM profile
# to decrypt data encrypted with the environment: production, application: billing
# encryption context
- amazon.aws.kms_key:
    key_id: abcd1234-abcd-1234-5678-ef1234567890
    grants:
      - name: billing_prod
        grantee_principal: arn:aws:iam::123456789012:role/billing_prod
        constraints:
          encryption_context_equals:
            environment: production
            application: billing
        operations:
          - Decrypt
          - RetireGrant

- name: Update IAM policy on an existing KMS key
  amazon.aws.kms_key:
    alias: my-kms-key
    policy: '{"Version": "2012-10-17", "Id": "my-kms-key-permissions", "Statement": [ { <SOME STATEMENT> } ]}'
    state: present

- name: Example using lookup for policy json
  amazon.aws.kms_key:
    alias: my-kms-key
    policy: "{{ lookup('template', 'kms_iam_policy_template.json.j2') }}"
    state: present

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

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

Ключ	Описание
псевдонимы список / элементы=строка	Список псевдонимов, связанных с ключом. Возвращается: всегда Пример: `["aws/acm", "aws/ebs"]`
aws_account_id строка	Идентификатор учётной записи AWS, к которой относится ключ. Возвращается: всегда Пример: `"1234567890123"`
changes_needed словарь	Типы разрешений, которые будут изменены/были изменены. Возвращается: всегда Пример: `{"role": "add", "role grant": "add"}`
creation_date строка	Дата и время создания ключа. Возвращается: всегда Пример: `"2017-04-18T15:12:08.551000+10:00"`
customer_master_key_spec строка	Указывает тип ключа KMS для создания. Возвращается: всегда Пример: `"SYMMETRIC_DEFAULT"`
deletion_date строка добавлено в community.aws 3.3.0	Дата и время, после которого KMS удалит этот ключ KMS. Возвращается: когда `key_state` находится в состоянии PendingDeletion Пример: `"2017-04-18T15:12:08.551000+10:00"`
описание строка	Описание ключа. Возвращается: всегда Пример: `"My Key for Protecting important stuff"`
enable_key_rotation логическое	Включена ли автоматическая ежегодная смена ключа. Возвращает None, если статус смены ключа определить нельзя. Возвращается: всегда Пример: `false`
enabled логическое	Включен ли ключ. True, если `key_state` равен `Enabled`. Возвращается: всегда Пример: `false`
encryption_algorithms список / элементы=строка	Алгоритмы шифрования, поддерживаемые ключом KMS. Возвращается: всегда Пример: `["SYMMETRIC_DEFAULT"]`
разрешения список / элементы=словарь	Список разрешений, связанных с ключом. Возвращается: всегда
ограничения словарь	Ограничения контекста шифрования, разрешённые разрешением. См. https://docs.aws.amazon.com/kms/latest/APIReference/API_GrantConstraints.html для получения более подробной информации Возвращается: всегда Пример: `{"encryption_context_equals": {"aws:lambda:_function_arn": "arn:aws:lambda:ap-southeast-2:123456789012:function:xyz"}}`
creation_date строка	Дата создания разрешения. Возвращается: всегда Пример: `"2017-04-18T15:12:08+10:00"`
grant_id строка	Уникальный идентификатор разрешения. Возвращается: всегда Пример: `"abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234"`
grantee_principal строка	Сущность, которая получает права разрешения. Возвращается: всегда Пример: `"arn:aws:sts::123456789012:assumed-role/lambda_xyz/xyz"`
issuing_account строка	AWS учётная запись, под которой было выдано разрешение. Возвращается: всегда Пример: `"arn:aws:iam::123456789012:root"`
key_id строка	ARN ключа, к которому относится разрешение. Возвращается: всегда Пример: `"arn:aws:kms:ap-southeast-2:123456789012:key/abcd1234-abcd-1234-5678-ef1234567890"`

name string	Удобочитаемое имя, идентифицирующее грант. Возвращается: всегда Пример: `"xyz"`
operations list / elements=string	Список операций, разрешенных грантом. Возвращается: всегда Пример: `["Decrypt", "RetireGrant"]`
retiring_principal string	Принципал, который может отозвать грант. Возвращается: всегда Пример: `"arn:aws:sts::123456789012:assumed-role/lambda_xyz/xyz"`
had_invalid_entries boolean	Есть ли неверные (не-ARN) записи в записи KMS. Они не учитываются как изменение, но будут удалены, если будут внесены какие-либо изменения. Возвращается: всегда
key_arn string	ARN ключа. Возвращается: всегда Пример: `"arn:aws:kms:ap-southeast-2:123456789012:key/abcd1234-abcd-1234-5678-ef1234567890"`
key_id string	ID ключа. Возвращается: всегда Пример: `"abcd1234-abcd-1234-5678-ef1234567890"`
key_manager string	Управляющий ключом KMS. Возвращается: всегда Пример: `"AWS"`
key_policies list / elements=dictionary добавлено в community.aws 3.3.0	Список документов политик для ключа. Пусто, когда доступ запрещен, даже если есть политики. Возвращается: всегда Пример: {"Id": "auto-ebs-2", "Statement": [{"Action": ["kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt", "kms:GenerateDataKey", "kms:CreateGrant", "kms:DescribeKey"], "Condition": {"StringEquals": {"kms:CallerAccount": "123456789012", "kms:ViaService": "ec2.ap-southeast-2.amazonaws.com"}}, "Effect": "Allow", "Principal": {"AWS": ""}, "Resource": "", "Sid": "Allow access through EBS for all principals in the account that are authorized to use EBS"}, {"Action": ["kms:Describe", "kms:Get", "kms:List", "kms:RevokeGrant"], "Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::123456789012:root"}, "Resource": "", "Sid": "Allow direct access to key metadata to the account"}], "Version": "2012-10-17"}
key_spec string	Указывает тип ключа KMS для создания. Возвращается: всегда Пример: `"SYMMETRIC_DEFAULT"`
key_state string	Состояние ключа. Будет одним из `'Creating'`, `'Enabled'`, `'Disabled'`, `'PendingDeletion'`, `'PendingImport'`, `'PendingReplicaDeletion'`, `'Unavailable'` или `'Updating'`. Возвращается: всегда Пример: `"PendingDeletion"`
key_usage string	Криптографические операции, для которых можно использовать ключ. Возвращается: всегда Пример: `"ENCRYPT_DECRYPT"`
multi_region boolean добавлено в amazon.aws 5.5.0	Указывает, является ли CMK многорегиональным `True` или региональным `False` ключом. Это значение равно True для многорегиональных основных и реплицированных CMK и False для региональных CMK. Возвращается: всегда Пример: `false`
origin string	Источник ключевого материала ключа. Когда это значение равно `AWS_KMS`, AWS KMS создал ключевой материал. Когда это значение равно `EXTERNAL`, ключевой материал был импортирован или CMK не имеет ключевого материала. Возвращается: всегда Пример: `"AWS_KMS"`
tags dictionary	Словарь тегов, примененных к ключу. Пусто, когда доступ запрещен, даже если есть теги. Возвращается: всегда Пример: `{"Name": "myKey", "Purpose": "protecting_stuff"}`

Авторы

Ted Timmons (@tedder)
Will Thames (@willthames)
Mark Chappell (@tremble)

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

© 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/kms_key_module.html