Rename aws_s3 to s3_object (and deprecate bucket creation/deleting) (a…

…nsible-collections#869)

Rename aws_s3 to s3_object (and deprecate bucket creation/deleting)

SUMMARY
The aws_s3 module (as it's known today) is primarily for managing objects within S3.  While it provides minimal support for creating S3 buckets, the feature set is very limited.  Support for the advanced bucket management features is provided via the s3_bucket modules (such as managing encryption settings).
Because the name aws_s3 often puts the module at the top of the list of modules, well away from the s3_bucket module, it can be difficult for folks to discover the s3_bucket module leading them to assume that we simply have no support for the more complex s3_bucket management features.
As such, I suggest renaming the module to s3_object to make the intended scope more obvious and to improve the discoverability of s3_bucket.  At this time I do not recommend setting a deprecation date for the alias, the cost of an alias is minimal and we've had a lot of churn recently.
Additionally, deprecates the duplicated (but very limited) bucket creation/deletion functionality of aws_s3/s3_object
ISSUE TYPE

Feature Pull Request

COMPONENT NAME

aws_s3
(s3_object)

ADDITIONAL INFORMATION
See for example ansible-collections#866 where there was an attempt to create duplicate functionality.

Reviewed-by: Alina Buzachis <None>
Reviewed-by: Mark Chappell <None>
Reviewed-by: Jill R <None>

changelogs/fragments/869-s3_object.yml

@@ -0,0 +1,7 @@
+minor_changes:
+- aws_s3 - The ``aws_s3`` module has been renamed to ``s3_object``
+  (https://github.com/ansible-collections/amazon.aws/pull/869).
+deprecated_features:
+- s3_object - Support for creation and deletion of S3 buckets has been deprecated.  Please use the
+  ``amazon.aws.s3_bucket`` module to create and delete buckets
+  (https://github.com/ansible-collections/amazon.aws/pull/869).

meta/runtime.yml

@@ -4,7 +4,6 @@ action_groups:
   - aws_az_info
   - aws_caller_info
   - aws_s3
-  - aws_s3
   - aws_secret
   - cloudformation
   - cloudformation_info
@@ -48,14 +47,20 @@ action_groups:
   - iam
   - rds
   - s3_bucket
+  - s3_object
 plugin_routing:
+  action:
+    aws_s3:
+      redirect: amazon.aws.s3_object
   modules:
     aws_az_facts:
       deprecation:
         removal_date: 2022-06-01
         warning_text: >-
           aws_az_facts was renamed in Ansible 2.9 to aws_az_info.
           Please update your tasks.
+    aws_s3:
+      redirect: amazon.aws.s3_object
     ec2:
       deprecation:
         removal_version: 4.0.0

plugins/action/aws_s3.py → plugins/action/s3_object.py

@@ -31,7 +31,11 @@ class ActionModule(ActionBase):
     TRANSFERS_FILES = True
 
     def run(self, tmp=None, task_vars=None):
-        ''' handler for aws_s3 operations '''
+        ''' handler for s3_object operations
+
+        This adds the magic that means 'src' can point to both a 'remote' file
+        on the 'host' or in the 'files/' lookup path on the controller.
+        '''
         self._supports_async = True
 
         if task_vars is None:
@@ -59,7 +63,7 @@ def run(self, tmp=None, task_vars=None):
                         raise AnsibleActionFail(to_text(e))
 
             wrap_async = self._task.async_val and not self._connection.has_native_async
-            # execute the aws_s3 module with the updated args
+            # execute the s3_object module with the updated args
             result = merge_hash(result, self._execute_module(module_args=new_module_args, task_vars=task_vars, wrap_async=wrap_async))
 
             if not wrap_async: