Rename KMS modules (#1284)

Rename KMS modules SUMMARY In line with the naming guidelines, rename aws_kms and aws_kms_info ISSUE TYPE Feature Pull Request COMPONENT NAME plugins/modules/aws_kms.py plugins/modules/aws_kms_info.py plugins/modules/kms_key.py plugins/modules/kms_key_info.py ADDITIONAL INFORMATION Reviewed-by: Joseph Torcasso <None> Reviewed-by: Alina Buzachis <None>
ansible-collections · Jun 29, 2022 · 644225c · 644225c
1 parent bc70088
commit 644225c
Show file tree

Hide file tree

Showing 20 changed files with 121 additions and 94 deletions.
diff --git a/README.md b/README.md
@@ -54,8 +54,6 @@ Name | Description
 [community.aws.aws_glue_connection](https://github.com/ansible-collections/community.aws/blob/main/docs/community.aws.aws_glue_connection_module.rst)|Manage an AWS Glue connection
 [community.aws.aws_glue_job](https://github.com/ansible-collections/community.aws/blob/main/docs/community.aws.aws_glue_job_module.rst)|Manage an AWS Glue job
 [community.aws.aws_inspector_target](https://github.com/ansible-collections/community.aws/blob/main/docs/community.aws.aws_inspector_target_module.rst)|Create, Update and Delete Amazon Inspector Assessment Targets
-[community.aws.aws_kms](https://github.com/ansible-collections/community.aws/blob/main/docs/community.aws.aws_kms_module.rst)|Perform various KMS management tasks
-[community.aws.aws_kms_info](https://github.com/ansible-collections/community.aws/blob/main/docs/community.aws.aws_kms_info_module.rst)|Gather information about AWS KMS keys
 [community.aws.aws_msk_cluster](https://github.com/ansible-collections/community.aws/blob/main/docs/community.aws.aws_msk_cluster_module.rst)|Manage Amazon MSK clusters
 [community.aws.aws_msk_config](https://github.com/ansible-collections/community.aws/blob/main/docs/community.aws.aws_msk_config_module.rst)|Manage Amazon MSK cluster configurations.
 [community.aws.aws_region_info](https://github.com/ansible-collections/community.aws/blob/main/docs/community.aws.aws_region_info_module.rst)|Gather information about AWS regions.
@@ -166,6 +164,8 @@ Name | Description
 [community.aws.iam_user](https://github.com/ansible-collections/community.aws/blob/main/docs/community.aws.iam_user_module.rst)|Manage AWS IAM users
 [community.aws.iam_user_info](https://github.com/ansible-collections/community.aws/blob/main/docs/community.aws.iam_user_info_module.rst)|Gather IAM user(s) facts in AWS
 [community.aws.kinesis_stream](https://github.com/ansible-collections/community.aws/blob/main/docs/community.aws.kinesis_stream_module.rst)|Manage a Kinesis Stream.
+[community.aws.kms_key](https://github.com/ansible-collections/community.aws/blob/main/docs/community.aws.kms_key_module.rst)|Perform various KMS key management tasks
+[community.aws.kms_key_info](https://github.com/ansible-collections/community.aws/blob/main/docs/community.aws.kms_key_info_module.rst)|Gather information about AWS KMS keys
 [community.aws.lambda](https://github.com/ansible-collections/community.aws/blob/main/docs/community.aws.lambda_module.rst)|Manage AWS Lambda functions
 [community.aws.lambda_alias](https://github.com/ansible-collections/community.aws/blob/main/docs/community.aws.lambda_alias_module.rst)|Creates, updates or deletes AWS Lambda function aliases
 [community.aws.lambda_event](https://github.com/ansible-collections/community.aws/blob/main/docs/community.aws.lambda_event_module.rst)|Creates, updates or deletes AWS Lambda function event mappings

diff --git a/changelogs/fragments/1284-rename-kms.yml b/changelogs/fragments/1284-rename-kms.yml
@@ -0,0 +1,3 @@
+minor_changes:
+- aws_kms - the ``aws_kms`` module has been renamed to ``kms_key``, ``aws_kms`` remains as an alias (https://github.com/ansible-collections/community.aws/pull/1284).
+- aws_kms_info - the ``aws_kms_info`` module has been renamed to ``kms_key_info``, ``aws_kms_info`` remains as an alias (https://github.com/ansible-collections/community.aws/pull/1284).
diff --git a/docs/community.aws.aws_kms_info_module.rst → docs/community.aws.kms_key_info_module.rst b/docs/community.aws.aws_kms_info_module.rst → docs/community.aws.kms_key_info_module.rst
@@ -1,8 +1,8 @@
-.. _community.aws.aws_kms_info_module:
+.. _community.aws.kms_key_info_module:
 
 
 **************************
-community.aws.aws_kms_info
+community.aws.kms_key_info
 **************************
 
 **Gather information about AWS KMS keys**
@@ -18,6 +18,7 @@ Version added: 1.0.0
 Synopsis
 --------
 - Gather information about AWS KMS keys including tags and grants.
+- Prior to release 5.0.0 this module was called ``community.aws.aws_kms_info``. The usage did not change.
 
 
 
@@ -304,15 +305,15 @@ Examples
     # Note: These examples do not set authentication details, see the AWS Guide for details.
 
     # Gather information about all KMS keys
-    - community.aws.aws_kms_info:
+    - community.aws.kms_key_info:
 
     # Gather information about all keys with a Name tag
-    - community.aws.aws_kms_info:
+    - community.aws.kms_key_info:
         filters:
           tag-key: Name
 
     # Gather information about all keys with a specific name
-    - community.aws.aws_kms_info:
+    - community.aws.kms_key_info:
         filters:
           "tag:Name": Example
 

diff --git a/docs/community.aws.aws_kms_module.rst → docs/community.aws.kms_key_module.rst b/docs/community.aws.aws_kms_module.rst → docs/community.aws.kms_key_module.rst
@@ -1,11 +1,11 @@
-.. _community.aws.aws_kms_module:
+.. _community.aws.kms_key_module:
 
 
 *********************
-community.aws.aws_kms
+community.aws.kms_key
 *********************
 
-**Perform various KMS management tasks**
+**Perform various KMS key management tasks**
 
 
 Version added: 1.0.0
@@ -17,7 +17,9 @@ Version added: 1.0.0
 
 Synopsis
 --------
-- Manage role/user access to a KMS key. Not designed for encrypting/decrypting.
+- Manage role/user access to a KMS key.
+- Not designed for encrypting/decrypting.
+- Prior to release 5.0.0 this module was called ``community.aws.aws_kms``. The usage did not change.
 
 
 
@@ -53,7 +55,11 @@ Parameters
                 <td>
                 </td>
                 <td>
-                        <div>An alias for a key. For safety, even though KMS does not require keys to have an alias, this module expects all new keys to be given an alias to make them easier to manage. Existing keys without an alias may be referred to by <em>key_id</em>. Use <span class='module'>community.aws.aws_kms_info</span> to find key ids. Required if <em>key_id</em> is not given. Note that passing a <em>key_id</em> and <em>alias</em> will only cause a new alias to be added, an alias will never be renamed. The &#x27;alias/&#x27; prefix is optional.</div>
+                        <div>An alias for a key.</div>
+                        <div>For safety, even though KMS does not require keys to have an alias, this module expects all new keys to be given an alias to make them easier to manage. Existing keys without an alias may be referred to by <em>key_id</em>. Use <span class='module'>community.aws.kms_key_info</span> to find key ids.</div>
+                        <div>Note that passing a <em>key_id</em> and <em>alias</em> will only cause a new alias to be added, an alias will never be renamed.</div>
+                        <div>The <code>alias/</code> prefix is optional.</div>
+                        <div>Required if <em>key_id</em> is not given.</div>
                         <div style="font-size: small; color: darkgreen"><br/>aliases: key_alias</div>
                 </td>
             </tr>
@@ -154,7 +160,8 @@ Parameters
                 <td>
                 </td>
                 <td>
-                        <div>A description of the CMK. Use a description that helps you decide whether the CMK is appropriate for a task.</div>
+                        <div>A description of the CMK.</div>
+                        <div>Use a description that helps you decide whether the CMK is appropriate for a task.</div>
                 </td>
             </tr>
             <tr>
@@ -622,7 +629,9 @@ Parameters
                         </ul>
                 </td>
                 <td>
-                        <div>Whether a key should be present or absent. Note that making an existing key absent only schedules a key for deletion.  Passing a key that is scheduled for deletion with state present will cancel key deletion.</div>
+                        <div>Whether a key should be present or absent.</div>
+                        <div>Note that making an existing key <code>absent</code> only schedules a key for deletion.</div>
+                        <div>Passing a key that is scheduled for deletion with <em>state=present</em> will cancel key deletion.</div>
                 </td>
             </tr>
             <tr>
@@ -669,7 +678,7 @@ Notes
 -----
 
 .. note::
-   - There are known inconsistencies in the amount of time required for updates of KMS keys to be fully reflected on AWS. This can cause issues when running duplicate tasks in succession or using the aws_kms_info module to fetch key metadata shortly after modifying keys. For this reason, it is recommended to use the return data from this module (aws_kms) to fetch a key's metadata.
+   - There are known inconsistencies in the amount of time required for updates of KMS keys to be fully reflected on AWS. This can cause issues when running duplicate tasks in succession or using the :ref:`community.aws.kms_key_info <community.aws.kms_key_info_module>` module to fetch key metadata shortly after modifying keys. For this reason, it is recommended to use the return data from this module (:ref:`community.aws.kms_key <community.aws.kms_key_module>`) to fetch a key's metadata.
    - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE``
    - When no credentials are explicitly provided the AWS SDK (boto3) that Ansible uses will fall back to its configuration files (typically ``~/.aws/credentials``). See https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html for more information.
    - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be defined in the configuration files.
@@ -684,28 +693,28 @@ Examples
     # Managing the KMS IAM Policy via policy_mode and policy_grant_types is fragile
     # and has been deprecated in favour of the policy option.
     - name: grant user-style access to production secrets
-      community.aws.aws_kms:
+      community.aws.kms_key:
       args:
         alias: "alias/my_production_secrets"
         policy_mode: grant
         policy_role_name: "prod-appServerRole-1R5AQG2BSEL6L"
         policy_grant_types: "role,role grant"
     - name: remove access to production secrets from role
-      community.aws.aws_kms:
+      community.aws.kms_key:
       args:
         alias: "alias/my_production_secrets"
         policy_mode: deny
         policy_role_name: "prod-appServerRole-1R5AQG2BSEL6L"
 
     # Create a new KMS key
-    - community.aws.aws_kms:
+    - community.aws.kms_key:
         alias: mykey
         tags:
           Name: myKey
           Purpose: protect_stuff
 
     # Update previous key with more tags
-    - community.aws.aws_kms:
+    - community.aws.kms_key:
         alias: mykey
         tags:
           Name: myKey
@@ -715,7 +724,7 @@ Examples
     # 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
-    - community.aws.aws_kms:
+    - community.aws.kms_key:
         key_id: abcd1234-abcd-1234-5678-ef1234567890
         grants:
           - name: billing_prod
@@ -729,13 +738,13 @@ Examples
               - RetireGrant
 
     - name: Update IAM policy on an existing KMS key
-      community.aws.aws_kms:
+      community.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
-      community.aws.aws_kms:
+      community.aws.kms_key:
         alias: my-kms-key
         policy: "{{ lookup('template', 'kms_iam_policy_template.json.j2') }}"
         state: present

diff --git a/meta/runtime.yml b/meta/runtime.yml
@@ -149,6 +149,8 @@ action_groups:
   - iam_user
   - iam_user_info
   - kinesis_stream
+  - kms_key
+  - kms_key_info
   - lambda
   - lambda_alias
   - lambda_event
@@ -228,6 +230,12 @@ plugin_routing:
     aws_eks_cluster:
       # Deprecation for this alias should not *start* prior to 2024-09-01
       redirect: community.aws.eks_cluster
+    aws_kms:
+      # Deprecation for this alias should not *start* prior to 2024-09-01
+      redirect: community.aws.kms_key
+    aws_kms_info:
+      # Deprecation for this alias should not *start* prior to 2024-09-01
+      redirect: community.aws.kms_key_info
     aws_s3_bucket_info:
       # Deprecation for this alias should not *start* prior to 2024-09-01
       redirect: community.aws.s3_bucket_info