From 9f3eb4816a46527d65b7b2a55a4ba71fdc9038ff Mon Sep 17 00:00:00 2001 From: Joseph Torcasso <87090265+jatorcasso@users.noreply.github.com> Date: Mon, 16 May 2022 08:55:39 -0400 Subject: [PATCH] aws_kms - minor doc fixes (#1101) aws_kms - minor doc fixes SUMMARY Minor doc fixes ISSUE TYPE Docs Pull Request COMPONENT NAME aws_kms aws_kms_info Reviewed-by: Mark Chappell Reviewed-by: Joseph Torcasso Reviewed-by: Alina Buzachis Reviewed-by: Markus Bergholz --- plugins/modules/aws_kms.py | 68 +++++++++++++++++-------------- plugins/modules/aws_kms_info.py | 71 +++++++++++++++++++-------------- 2 files changed, 79 insertions(+), 60 deletions(-) diff --git a/plugins/modules/aws_kms.py b/plugins/modules/aws_kms.py index cf9c4b5eb96..95bc51834cc 100644 --- a/plugins/modules/aws_kms.py +++ b/plugins/modules/aws_kms.py @@ -10,7 +10,7 @@ --- module: aws_kms version_added: 1.0.0 -short_description: Perform various KMS management tasks. +short_description: Perform various KMS management tasks description: - Manage role/user access to a KMS key. Not designed for encrypting/decrypting. options: @@ -106,7 +106,7 @@ default: present type: str enabled: - description: Whether or not a key is enabled + description: Whether or not a key is enabled. default: True type: bool description: @@ -128,12 +128,12 @@ version_added: 1.4.0 purge_tags: description: Whether the I(tags) argument should cause tags not in the list to - be removed + be removed. default: False type: bool purge_grants: description: Whether the I(grants) argument should cause grants not in the list to - be removed + be removed. default: False type: bool grants: @@ -270,17 +270,20 @@ RETURN = r''' key_id: - description: ID of key + description: ID of key. type: str returned: always sample: abcd1234-abcd-1234-5678-ef1234567890 key_arn: - description: ARN of key + description: ARN of key. type: str returned: always sample: arn:aws:kms:ap-southeast-2:123456789012:key/abcd1234-abcd-1234-5678-ef1234567890 key_state: - description: The state of the key + description: + - The state of the key. + - Will be one of C('Creating'), C('Enabled'), C('Disabled'), C('PendingDeletion'), C('PendingImport'), + C('PendingReplicaDeletion'), C('Unavailable'), or C('Updating'). type: str returned: always sample: PendingDeletion @@ -297,23 +300,29 @@ returned: always sample: AWS_KMS aws_account_id: - description: The AWS Account ID that the key belongs to + description: The AWS Account ID that the key belongs to. type: str returned: always sample: 1234567890123 creation_date: - description: Date of creation of the key + description: Date and time of creation of the key. type: str returned: always sample: "2017-04-18T15:12:08.551000+10:00" +deletion_date: + description: Date and time after which KMS deletes this KMS key. + type: str + returned: when key_state is PendingDeletion + sample: "2017-04-18T15:12:08.551000+10:00" + version_added: 3.3.0 description: - description: Description of the key + description: Description of the key. type: str returned: always sample: "My Key for Protecting important stuff" enabled: - description: Whether the key is enabled. True if C(KeyState) is true. - type: str + description: Whether the key is enabled. True if I(key_state) is C(Enabled). + type: bool returned: always sample: false enable_key_rotation: @@ -322,14 +331,14 @@ returned: always sample: false aliases: - description: list of aliases associated with the key + description: List of aliases associated with the key. type: list returned: always sample: - aws/acm - aws/ebs policies: - description: list of policy documents for the key. Empty when access is denied even if there are policies. + description: List of policy documents for the key. Empty when access is denied even if there are policies. type: list returned: always elements: str @@ -340,7 +349,7 @@ - Sid: "Allow access through EBS for all principals in the account that are authorized to use EBS" Effect: "Allow" Principal: - AWS: "*" + AWS: "*" Action: - "kms:Encrypt" - "kms:Decrypt" @@ -356,7 +365,7 @@ - Sid: "Allow direct access to key metadata to the account" Effect: "Allow" Principal: - AWS: "arn:aws:iam::111111111111:root" + AWS: "arn:aws:iam::111111111111:root" Action: - "kms:Describe*" - "kms:Get*" @@ -364,7 +373,7 @@ - "kms:RevokeGrant" Resource: "*" key_policies: - description: list of policy documents for the key. Empty when access is denied even if there are policies. + description: List of policy documents for the key. Empty when access is denied even if there are policies. type: list returned: always elements: dict @@ -400,15 +409,16 @@ Resource: "*" version_added: 3.3.0 tags: - description: dictionary of tags applied to the key + description: Dictionary of tags applied to the key. Empty when access is denied even if there are tags. type: dict returned: always sample: Name: myKey Purpose: protecting_stuff grants: - description: list of grants associated with a key - type: complex + description: List of grants associated with a key. + type: list + elements: dict returned: always contains: constraints: @@ -420,22 +430,22 @@ encryption_context_equals: "aws:lambda:_function_arn": "arn:aws:lambda:ap-southeast-2:012345678912:function:xyz" creation_date: - description: Date of creation of the grant + description: Date of creation of the grant. type: str returned: always sample: "2017-04-18T15:12:08+10:00" grant_id: - description: The unique ID for the grant + description: The unique ID for the grant. type: str returned: always sample: abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234 grantee_principal: - description: The principal that receives the grant's permissions + description: The principal that receives the grant's permissions. type: str returned: always sample: arn:aws:sts::0123456789012:assumed-role/lambda_xyz/xyz issuing_account: - description: The AWS account under which the grant was issued + description: The AWS account under which the grant was issued. type: str returned: always sample: arn:aws:iam::01234567890:root @@ -445,29 +455,29 @@ returned: always sample: arn:aws:kms:ap-southeast-2:123456789012:key/abcd1234-abcd-1234-5678-ef1234567890 name: - description: The friendly name that identifies the grant + description: The friendly name that identifies the grant. type: str returned: always sample: xyz operations: - description: The list of operations permitted by the grant + description: The list of operations permitted by the grant. type: list returned: always sample: - Decrypt - RetireGrant retiring_principal: - description: The principal that can retire the grant + description: The principal that can retire the grant. type: str returned: always sample: arn:aws:sts::0123456789012:assumed-role/lambda_xyz/xyz changes_needed: - description: grant types that would be changed/were changed. + description: Grant types that would be changed/were changed. type: dict returned: always sample: { "role": "add", "role grant": "add" } had_invalid_entries: - description: there are invalid (non-ARN) entries in the KMS entry. These don't count as a change, but will be removed if any changes are being made. + description: Whether there are invalid (non-ARN) entries in the KMS entry. These don't count as a change, but will be removed if any changes are being made. type: bool returned: always ''' diff --git a/plugins/modules/aws_kms_info.py b/plugins/modules/aws_kms_info.py index c67e58d27ec..fabff61fcc1 100644 --- a/plugins/modules/aws_kms_info.py +++ b/plugins/modules/aws_kms_info.py @@ -6,13 +6,13 @@ __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r''' --- module: aws_kms_info version_added: 1.0.0 short_description: Gather information about AWS KMS keys description: - - Gather information about AWS KMS keys including tags and grants + - Gather information about AWS KMS keys including tags and grants. author: "Will Thames (@willthames)" options: alias: @@ -42,7 +42,7 @@ - Mutually exclusive with I(alias) and I(key_id). type: dict pending_deletion: - description: Whether to get full details (tags, grants etc.) of keys pending deletion + description: Whether to get full details (tags, grants etc.) of keys pending deletion. default: False type: bool keys_attr: @@ -59,7 +59,7 @@ ''' -EXAMPLES = ''' +EXAMPLES = r''' # Note: These examples do not set authentication details, see the AWS Guide for details. # Gather information about all KMS keys @@ -76,24 +76,27 @@ "tag:Name": Example ''' -RETURN = ''' +RETURN = r''' kms_keys: - description: list of keys + description: List of keys. type: complex returned: always contains: key_id: - description: ID of key + description: ID of key. type: str returned: always sample: abcd1234-abcd-1234-5678-ef1234567890 key_arn: - description: ARN of key + description: ARN of key. type: str returned: always sample: arn:aws:kms:ap-southeast-2:123456789012:key/abcd1234-abcd-1234-5678-ef1234567890 key_state: - description: The state of the key + description: + - The state of the key. + - Will be one of C('Creating'), C('Enabled'), C('Disabled'), C('PendingDeletion'), C('PendingImport'), + C('PendingReplicaDeletion'), C('Unavailable'), or C('Updating'). type: str returned: always sample: PendingDeletion @@ -103,54 +106,59 @@ returned: always sample: ENCRYPT_DECRYPT origin: - description: - The source of the key's key material. When this value is C(AWS_KMS), + description: The source of the key's key material. When this value is C(AWS_KMS), AWS KMS created the key material. When this value is C(EXTERNAL), the key material was imported or the CMK lacks key material. type: str returned: always sample: AWS_KMS aws_account_id: - description: The AWS Account ID that the key belongs to + description: The AWS Account ID that the key belongs to. type: str returned: always sample: 1234567890123 creation_date: - description: Date of creation of the key + description: Date and time of creation of the key. type: str returned: always sample: "2017-04-18T15:12:08.551000+10:00" + deletion_date: + description: Date and time after which KMS deletes this KMS key. + type: str + returned: when key_state is PendingDeletion + sample: "2017-04-18T15:12:08.551000+10:00" + version_added: 3.3.0 description: - description: Description of the key + description: Description of the key. type: str returned: always sample: "My Key for Protecting important stuff" enabled: - description: Whether the key is enabled. True if C(KeyState) is true. - type: str + description: Whether the key is enabled. True if I(key_state) is C(Enabled). + type: bool returned: always sample: false enable_key_rotation: - description: Whether the automatically key rotation every year is enabled. Returns None if key rotation status can't be determined. + description: Whether the automatic annual key rotation is enabled. Returns None if key rotation status can't be determined. type: bool returned: always sample: false aliases: - description: list of aliases associated with the key + description: list of aliases associated with the key. type: list returned: always sample: - aws/acm - aws/ebs tags: - description: dictionary of tags applied to the key. Empty when access is denied even if there are tags. + description: Dictionary of tags applied to the key. Empty when access is denied even if there are tags. type: dict returned: always sample: Name: myKey Purpose: protecting_stuff policies: - description: list of policy documents for the key. Empty when access is denied even if there are policies. + description: List of policy documents for the key. Empty when access is denied even if there are policies. type: list returned: always elements: str @@ -185,7 +193,7 @@ - "kms:RevokeGrant" Resource: "*" key_policies: - description: list of policy documents for the key. Empty when access is denied even if there are policies. + description: List of policy documents for the key. Empty when access is denied even if there are policies. type: list returned: always elements: dict @@ -221,8 +229,9 @@ Resource: "*" version_added: 3.3.0 grants: - description: list of grants associated with a key - type: complex + description: List of grants associated with a key. + type: list + elements: dict returned: always contains: constraints: @@ -232,24 +241,24 @@ returned: always sample: encryption_context_equals: - "aws:lambda:_function_arn": "arn:aws:lambda:ap-southeast-2:012345678912:function:xyz" + "aws:lambda:_function_arn": "arn:aws:lambda:ap-southeast-2:012345678912:function:xyz" creation_date: - description: Date of creation of the grant + description: Date of creation of the grant. type: str returned: always sample: "2017-04-18T15:12:08+10:00" grant_id: - description: The unique ID for the grant + description: The unique ID for the grant. type: str returned: always sample: abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234 grantee_principal: - description: The principal that receives the grant's permissions + description: The principal that receives the grant's permissions. type: str returned: always sample: arn:aws:sts::0123456789012:assumed-role/lambda_xyz/xyz issuing_account: - description: The AWS account under which the grant was issued + description: The AWS account under which the grant was issued. type: str returned: always sample: arn:aws:iam::01234567890:root @@ -259,19 +268,19 @@ returned: always sample: arn:aws:kms:ap-southeast-2:123456789012:key/abcd1234-abcd-1234-5678-ef1234567890 name: - description: The friendly name that identifies the grant + description: The friendly name that identifies the grant. type: str returned: always sample: xyz operations: - description: The list of operations permitted by the grant + description: The list of operations permitted by the grant. type: list returned: always sample: - Decrypt - RetireGrant retiring_principal: - description: The principal that can retire the grant + description: The principal that can retire the grant. type: str returned: always sample: arn:aws:sts::0123456789012:assumed-role/lambda_xyz/xyz