Merge pull request #664 from tremble/deprecate/iam

Formally start the iam deprecation process

SUMMARY
The iam module is based upon the deprecated boto (not boto3/botocore) SDK and its functionality has been replaced by the iam_user, iam_group and iam_role modules.
ISSUE TYPE

Feature Pull Request

COMPONENT NAME
iam
ADDITIONAL INFORMATION

Reviewed-by: Felix Fontein <None>
Reviewed-by: Markus Bergholz <git@osuv.de>
Reviewed-by: Jill R <None>
Reviewed-by: None <None>

changelogs/fragments/664-deprecate-iam.yml

@@ -0,0 +1,3 @@
+deprecated_features:
+- iam - the boto based ``iam`` module has been deprecated in favour of the boto3 based ``iam_user``, ``iam_group`` and ``iam_role`` modules.
+  The ``iam`` module will be removed in release 3.0.0 (https://github.com/ansible-collections/community.aws/pull/664).

meta/runtime.yml

@@ -449,6 +449,13 @@ plugin_routing:
           elb_target_group_facts was renamed in Ansible 2.9 to
           elb_target_group_info.
           Please update your tasks.
+    iam:
+      deprecation:
+        removal_version: 3.0.0
+        warning_text: >-
+            The iam module is based upon a deprecated version of the AWS SDKs
+            and is deprecated in favor of the iam_user, iam_group and iam_role modules.
+            Please update your tasks.
     iam_cert_facts:
       deprecation:
         removal_date: 2021-12-01

plugins/modules/iam.py

@@ -10,6 +10,11 @@
 ---
 module: iam
 version_added: 1.0.0
+deprecated:
+  removed_in: 3.0.0
+  why: The iam module is based upon a deprecated version of the AWS SDK.
+  alternative: Use M(iam_user), M(iam_group), M(iam_role), M(iam_policy) and M(iam_managed_policy) modules.
+
 short_description: Manage IAM users, groups, roles and keys
 description:
      - Allows for the management of IAM users, user API keys, groups, roles.
@@ -644,6 +649,9 @@ def main():
         check_boto3=False,
     )
 
+    module.deprecate("The 'iam' module has been deprecated and replaced by the 'iam_user', 'iam_group'"
+                     " and 'iam_role' modules'", version='3.0.0', collection_name='community.aws')
+
     if not HAS_BOTO:
         module.fail_json(msg='This module requires boto, please install it')
 

tests/sanity/ignore-2.9.txt

@@ -1533,6 +1533,8 @@ plugins/modules/iam.py import-3.5!skip
 plugins/modules/iam.py import-3.6!skip
 plugins/modules/iam.py import-3.7!skip
 plugins/modules/iam.py metaclass-boilerplate!skip
+plugins/modules/iam.py validate-modules:deprecation-mismatch  # Ansible 2.9 docs don't support deprecation properly
+plugins/modules/iam.py validate-modules:invalid-documentation  # Ansible 2.9 docs don't support deprecation properly
 plugins/modules/iam_cert.py compile-2.6!skip
 plugins/modules/iam_cert.py compile-2.7!skip
 plugins/modules/iam_cert.py compile-3.5!skip