Formally start the iam deprecation process

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')