Merge branch 'main' into docs_update_2

changelogs/fragments/2105-backup_vault-remove-unnecessary-return-values.yml

@@ -0,0 +1,3 @@
+---
+minor_changes:
+  - backup_vault - Update code to remove unnecessary return values returned as None (https://github.com/ansible-collections/amazon.aws/pull/2105).

changelogs/fragments/2107-s3_download.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - s3_object - fixed issue which was causing ``MemoryError`` exceptions when downloading large files (https://github.com/ansible-collections/amazon.aws/issues/2107).

changelogs/fragments/documentation_update.yml

@@ -0,0 +1,2 @@
+trivial:
+  - "Part #1 - Ensures the modules documentation follows the correct formats (see also https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html#semantic-markup-within-module-documentation)."

plugins/modules/autoscaling_group.py

@@ -12,7 +12,7 @@
 description:
   - Can create or delete AWS AutoScaling Groups.
   - Can be used with the M(community.aws.autoscaling_launch_config) module to manage Launch Configurations.
-  - Prior to release 5.0.0 this module was called C(community.aws.ec2_asg).
+  - Prior to release 5.0.0 this module was called M(community.aws.ec2_asg).
     The usage did not change.
   - This module was originally added to C(community.aws) in release 1.0.0.
 author:
@@ -42,13 +42,13 @@
   availability_zones:
     description:
       - List of availability zone names in which to create the group.
-      - Defaults to all the availability zones in the region if I(vpc_zone_identifier) is not set.
+      - Defaults to all the availability zones in the region if O(vpc_zone_identifier) is not set.
     type: list
     elements: str
   launch_config_name:
     description:
-      - Name of the Launch configuration to use for the group. See the community.aws.autoscaling_launch_config) module for managing these.
-      - If unspecified then the current group value will be used.  One of I(launch_config_name) or I(launch_template) must be provided.
+      - Name of the Launch configuration to use for the group. See the M(community.aws.autoscaling_launch_config) module for managing these.
+      - If unspecified then the current group value will be used.  One of O(launch_config_name) or O(launch_template) must be provided.
     type: str
   launch_template:
     description:
@@ -61,11 +61,11 @@
         type: str
       launch_template_name:
         description:
-          - The name of the launch template. Only one of I(launch_template_name) or I(launch_template_id) is required.
+          - The name of the launch template. Only one of O(launch_template.launch_template_name) or O(launch_template.launch_template_id) is required.
         type: str
       launch_template_id:
         description:
-          - The id of the launch template. Only one of I(launch_template_name) or I(launch_template_id) is required.
+          - The id of the launch template. Only one of O(launch_template.launch_template_name) or O(launch_template.launch_template_id) is required.
         type: str
     type: dict
   min_size:
@@ -79,19 +79,19 @@
   max_instance_lifetime:
     description:
       - The maximum amount of time, in seconds, that an instance can be in service.
-      - Maximum instance lifetime must be equal to 0, between 604800 and 31536000 seconds (inclusive), or not specified.
-      - Value of 0 removes lifetime restriction.
+      - Maximum instance lifetime must be equal to V(0), between V(604800) and V(31536000) seconds (inclusive), or not specified.
+      - Value of V(0) removes lifetime restriction.
     type: int
   mixed_instances_policy:
     description:
       - A mixed instance policy to use for the ASG.
-      - Only used when the ASG is configured to use a Launch Template (I(launch_template)).
+      - Only used when the ASG is configured to use a Launch Template (O(launch_template)).
       - 'See also U(https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-autoscaling-autoscalinggroup-mixedinstancespolicy.html)'
     required: false
     suboptions:
       instance_types:
         description:
-          - A list of instance_types.
+          - A list of instance types.
         type: list
         elements: str
         required: false
@@ -120,17 +120,19 @@
                 The minimum amount of the Auto Scaling group's capacity that must be fulfilled by On-Demand
                 Instances. This base portion is provisioned first as your group scales.
               - >-
-                Default if not set is 0. If you leave it set to 0, On-Demand Instances are launched as a
-                percentage of the Auto Scaling group's desired capacity, per the OnDemandPercentageAboveBaseCapacity setting.
+                Default if not set is V(0). If you leave it set to V(0), On-Demand Instances are launched as a
+                percentage of the Auto Scaling group's desired capacity, per the
+                O(mixed_instances_policy.instances_distribution.on_demand_percentage_above_base_capacity) setting.
             type: int
             required: false
             version_added: 1.5.0
             version_added_collection: community.aws
           on_demand_percentage_above_base_capacity:
             description:
-              - Controls the percentages of On-Demand Instances and Spot Instances for your additional capacity beyond OnDemandBaseCapacity.
-              - Default if not set is 100. If you leave it set to 100, the percentages are 100% for On-Demand Instances and 0% for Spot Instances.
-              - 'Valid range: 0 to 100'
+              - Controls the percentages of On-Demand Instances and Spot Instances for your additional capacity beyond
+                O(mixed_instances_policy.instances_distribution.on_demand_base_capacity).
+              - Default if not set is V(100). If you leave it set to V(100), the percentages are 100% for On-Demand Instances and 0% for Spot Instances.
+              - 'Valid range: V(0) to V(100).'
             type: int
             required: false
             version_added: 1.5.0
@@ -146,9 +148,9 @@
             description:
               - >-
                 The number of Spot Instance pools across which to allocate your Spot Instances. The Spot pools are determined from
-                the different instance types in the Overrides array of LaunchTemplate. Default if not set is 2.
+                the different instance types in the Overrides array of LaunchTemplate. Default if not set is V(2).
               - Used only when the Spot allocation strategy is lowest-price.
-              - 'Valid Range: Minimum value of 1. Maximum value of 20.'
+              - 'Valid Range: Minimum value of V(1). Maximum value of V(20).'
             type: int
             required: false
             version_added: 1.5.0
@@ -174,28 +176,28 @@
   replace_all_instances:
     description:
       - In a rolling fashion, replace all instances that used the old launch configuration with one from the new launch configuration.
-        It increases the ASG size by I(replace_batch_size), waits for the new instances to be up and running.
+        It increases the ASG size by O(replace_batch_size), waits for the new instances to be up and running.
         After that, it terminates a batch of old instances, waits for the replacements, and repeats, until all old instances are replaced.
         Once that's done the ASG size is reduced back to the expected size.
     default: false
     type: bool
   replace_batch_size:
     description:
-      - Number of instances you'd like to replace at a time.  Used with I(replace_all_instances).
+      - Number of instances you'd like to replace at a time.  Used with O(replace_all_instances).
     required: false
     default: 1
     type: int
   replace_instances:
     description:
-      - List of I(instance_ids) belonging to the named AutoScalingGroup that you would like to terminate and be replaced with instances
+      - List of instance ids belonging to the named AutoScalingGroup that you would like to terminate and be replaced with instances
         matching the current launch configuration.
     type: list
     elements: str
     default: []
   detach_instances:
     description:
       - Removes one or more instances from the specified AutoScalingGroup.
-      - If I(decrement_desired_capacity) flag is not set, new instance(s) are launched to replace the detached instance(s).
+      - If O(decrement_desired_capacity) flag is not set, new instance(s) are launched to replace the detached instance(s).
       - If a Classic Load Balancer is attached to the AutoScalingGroup, the instances are also deregistered from the load balancer.
       - If there are target groups attached to the AutoScalingGroup, the instances are also deregistered from the target groups.
     type: list
@@ -212,13 +214,13 @@
     version_added_collection: community.aws
   lc_check:
     description:
-      - Check to make sure instances that are being replaced with I(replace_instances) do not already have the current I(launch_config).
+      - Check to make sure instances that are being replaced with O(replace_instances) do not already have the current launch config.
     default: true
     type: bool
   lt_check:
     description:
-      - Check to make sure instances that are being replaced with I(replace_instances) do not already have the current
-        I(launch_template or I(launch_template) I(version).
+      - Check to make sure instances that are being replaced with O(replace_instances) do not already have the current
+        O(launch_template) or O(launch_template) O(launch_template.version).
     default: true
     type: bool
   vpc_zone_identifier:
@@ -229,15 +231,15 @@
   tags:
     description:
       - A list of tags to add to the Auto Scale Group.
-      - Optional key is I(propagate_at_launch), which defaults to true.
-      - When I(propagate_at_launch) is true the tags will be propagated to the Instances created.
+      - Optional key is V(propagate_at_launch), which defaults to V(true).
+      - When V(propagate_at_launch) is V(true) the tags will be propagated to the Instances created.
     type: list
     elements: dict
     default: []
   purge_tags:
     description:
-      - If C(true), existing tags will be purged from the resource to match exactly what is defined by I(tags) parameter.
-      - If the I(tags) parameter is not set then tags will not be modified.
+      - If V(true), existing tags will be purged from the resource to match exactly what is defined by O(tags) parameter.
+      - If the O(tags) parameter is not set then tags will not be modified.
     default: false
     type: bool
     version_added: 3.2.0
@@ -275,9 +277,9 @@
   termination_policies:
     description:
         - An ordered list of criteria used for selecting instances to be removed from the Auto Scaling group when reducing capacity.
-        - Using I(termination_policies=Default) when modifying an existing AutoScalingGroup will result in the existing policy being retained
-          instead of changed to C(Default).
-        - 'Valid values include: C(Default), C(OldestInstance), C(NewestInstance), C(OldestLaunchConfiguration), C(ClosestToNextInstanceHour)'
+        - Using O(termination_policies=Default) when modifying an existing AutoScalingGroup will result in the existing policy being retained
+          instead of changed to V(Default).
+        - 'Valid values include: V(Default), V(OldestInstance), V(NewestInstance), V(OldestLaunchConfiguration), V(ClosestToNextInstanceHour)'
         - 'Full documentation of valid values can be found in the AWS documentation:'
         - 'U(https://docs.aws.amazon.com/autoscaling/ec2/userguide/as-instance-termination.html#custom-termination-policy)'
     default: Default
@@ -302,7 +304,7 @@
     description:
       - A list of scaling processes to suspend.
       - 'Valid values include:'
-      - C(Launch), C(Terminate), C(HealthCheck), C(ReplaceUnhealthy), C(AZRebalance), C(AlarmNotification), C(ScheduledActions), C(AddToLoadBalancer)
+      - V(Launch), V(Terminate), V(HealthCheck), V(ReplaceUnhealthy), V(AZRebalance), V(AlarmNotification), V(ScheduledActions), V(AddToLoadBalancer)
       - 'Full documentation of valid values can be found in the AWS documentation:'
       - 'U(https://docs.aws.amazon.com/autoscaling/ec2/userguide/as-suspend-resume-processes.html)'
     default: []
@@ -315,12 +317,12 @@
     default: false
   metrics_granularity:
     description:
-      - When I(metrics_collection=true) this will determine the granularity of metrics collected by CloudWatch.
+      - When O(metrics_collection=true) this will determine the granularity of metrics collected by CloudWatch.
     default: "1Minute"
     type: str
   metrics_list:
     description:
-      - List of autoscaling metrics to collect when I(metrics_collection=true).
+      - List of autoscaling metrics to collect when O(metrics_collection=true).
     default:
       - 'GroupMinSize'
       - 'GroupMaxSize'

plugins/modules/autoscaling_group_info.py

@@ -11,7 +11,7 @@
 short_description: Gather information about EC2 Auto Scaling Groups (ASGs) in AWS
 description:
   - Gather information about EC2 Auto Scaling Groups (ASGs) in AWS.
-  - Prior to release 5.0.0 this module was called C(community.aws.ec2_asg_info).
+  - Prior to release 5.0.0 this module was called M(community.aws.ec2_asg_info).
     The usage did not change.
   - This module was originally added to C(community.aws) in release 1.0.0.
 author:

plugins/modules/aws_az_info.py

@@ -107,7 +107,7 @@
         group_name:
             description:
                 - The name of the associated group.
-                - For availability zones, this will be the same as I(region_name).
+                - For availability zones, this will be the same as RV(availability_zones.region_name).
             type: str
             returned: on success
             sample: 'us-east-1'

plugins/modules/backup_plan.py

@@ -11,7 +11,7 @@
 version_added: 6.0.0
 short_description: Manage AWS Backup Plans
 description:
-  - Creates, updates, or deletes AWS Backup Plans
+  - Creates, updates, or deletes AWS Backup Plans.
   - For more information see the AWS documentation for Backup plans U(https://docs.aws.amazon.com/aws-backup/latest/devguide/about-backup-plans.html).
 author:
   - Kristof Imre Szabo (@krisek)
@@ -33,7 +33,7 @@
   rules:
     description:
       - An array of BackupRule objects, each of which specifies a scheduled task that is used to back up a selection of resources.
-      - Required when I(state=present).
+      - Required when O(state=present).
     type: list
     elements: dict
     suboptions:
@@ -55,14 +55,14 @@
           - A value in minutes after a backup is scheduled before a job will be
             canceled if it doesn't start successfully. If this value is included, it
             must be at least 60 minutes to avoid errors.
-          - AWS default if not supplied is 480.
+          - AWS default if not supplied is V(480).
         type: int
         default: 480
       completion_window_minutes:
         description:
           - A value in minutes after a backup job is successfully started before it
             must be completed or it will be canceled by Backup.
-          - AWS default if not supplied is 10080
+          - AWS default if not supplied is V(10080).
         type: int
         default: 10080
       lifecycle:
@@ -82,8 +82,8 @@
             type: int
           delete_after_days:
             description: Specifies the number of days after creation that a recovery
-              point is deleted. Must be greater than 90 days plus
-              move_to_cold_storage_after_days.
+              point is deleted. Must be greater than V(90) days plus
+              O(rules.lifecycle.move_to_cold_storage_after_days).
             type: int
       recovery_point_tags:
         description: To help organize your resources, you can assign your own metadata to the resources that you create.
@@ -114,15 +114,15 @@
                 type: int
               delete_after_days:
                 description: Specifies the number of days after creation that a
-                  recovery point is deleted. Must be greater than 90 days plus
-                  move_to_cold_storage_after_days.
+                  recovery point is deleted. Must be greater than V(90) days plus
+                   O(rules.copy_actions.lifecycle.move_to_cold_storage_after_days).
                 type: int
       enable_continuous_backup:
         description:
           - Specifies whether Backup creates continuous backups. True causes Backup to
             create continuous backups capable of point-in-time restore (PITR). False
             (or not specified) causes Backup to create snapshot backups.
-          - AWS default if not supplied is false.
+          - AWS default if not supplied is V(false).
         type: bool
         default: false
       schedule_expression_timezone:

plugins/modules/backup_plan_info.py

@@ -70,7 +70,7 @@
             description: Tags of the backup plan
             type: str
         version_id:
-            description: Version id of the backup plan
+            description: Version id of the backup plan.
             type: str
         backup_plan:
             returned: always
@@ -83,15 +83,15 @@
                     type: str
                     sample: elastic
                 advanced_backup_settings:
-                    description: Advanced backup settings of the backup plan
+                    description: Advanced backup settings of the backup plan.
                     type: list
                     elements: dict
                     contains:
                         resource_type:
-                            description: Resource type of the advanced setting
+                            description: Resource type of the advanced setting.
                             type: str
                         backup_options:
-                            description: Options of the advanced setting
+                            description: Options of the advanced setting.
                             type: dict
                 rules:
                     description: