diff --git a/changelogs/fragments/documentation_update.yml b/changelogs/fragments/documentation_update.yml new file mode 100644 index 00000000000..e4160a5dea7 --- /dev/null +++ b/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)." diff --git a/plugins/modules/autoscaling_group.py b/plugins/modules/autoscaling_group.py index 520bf932076..378c84405dd 100644 --- a/plugins/modules/autoscaling_group.py +++ b/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,20 +176,20 @@ 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 @@ -195,7 +197,7 @@ 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' diff --git a/plugins/modules/autoscaling_group_info.py b/plugins/modules/autoscaling_group_info.py index 8a39e200b39..59884bfc639 100644 --- a/plugins/modules/autoscaling_group_info.py +++ b/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: diff --git a/plugins/modules/aws_az_info.py b/plugins/modules/aws_az_info.py index a373f41bc85..0c5ac8694f4 100644 --- a/plugins/modules/aws_az_info.py +++ b/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' diff --git a/plugins/modules/backup_plan.py b/plugins/modules/backup_plan.py index 9ae6f00080a..1dd672933bc 100644 --- a/plugins/modules/backup_plan.py +++ b/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: diff --git a/plugins/modules/backup_plan_info.py b/plugins/modules/backup_plan_info.py index 98f49f6b6e5..1761d2af68a 100644 --- a/plugins/modules/backup_plan_info.py +++ b/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: diff --git a/plugins/modules/backup_selection.py b/plugins/modules/backup_selection.py index ff78d0b68cf..60434289e87 100644 --- a/plugins/modules/backup_selection.py +++ b/plugins/modules/backup_selection.py @@ -43,14 +43,14 @@ description: - A list of conditions that you define to assign resources to your backup plans using tags. - Condition operators are case sensitive. - - When you specify more than one condition in I(list_of_tags), you assign all resources that match AT LEAST ONE condition (using OR logic). + - When you specify more than one condition in O(list_of_tags), you assign all resources that match AT LEAST ONE condition (using OR logic). type: list elements: dict suboptions: condition_type: description: - An operation applied to a key-value pair used to assign resources to your backup plan. - - Condition only supports C(STRINGEQUALS). + - Condition only supports V(STRINGEQUALS). type: str condition_key: description: @@ -71,7 +71,7 @@ description: - A list of conditions (expressed as a dict) that you define to assign resources to your backup plans using tags. - When you specify more than one condition in I(conditions), you only assign the resources that match ALL conditions (using AND logic). - - I(conditions) supports C(string_equals), C(string_like), C(string_not_equals), and C(string_not_like). I(list_of_tags) only supports C(string_equals). + - O(conditions) supports V(string_equals), V(string_like), V(string_not_equals), and V(string_not_like). O(list_of_tags) only supports V(string_equals). type: dict suboptions: string_equals: @@ -84,7 +84,7 @@ condition_key: description: - The key in a key-value pair. - - I(condition_key) in the I(conditions) option must use the AWS resource tag prefix, e.g. 'aws:ResourceTag/key-name' + - O(conditions.string_equals.condition_key) in the O(conditions) option must use the AWS resource tag prefix, e.g. 'aws:ResourceTag/key-name' type: str condition_value: description: The value in a key-value pair. @@ -100,7 +100,7 @@ condition_key: description: - The key in a key-value pair. - - I(condition_key) in the I(conditions) option must use the AWS resource tag prefix, e.g. 'aws:ResourceTag/key-name' + - O(conditions.string_like.condition_key) in the O(conditions) option must use the AWS resource tag prefix, e.g. 'aws:ResourceTag/key-name' type: str condition_value: description: The value in a key-value pair. @@ -115,7 +115,7 @@ condition_key: description: - The key in a key-value pair. - - I(condition_key) in the I(conditions) option must use the AWS resource tag prefix, e.g. 'aws:ResourceTag/key-name' + - O(conditions.string_not_equals.condition_key) in the O(conditions) option must use the AWS resource tag prefix, e.g. 'aws:ResourceTag/key-name' type: str condition_value: description: The value in a key-value pair. @@ -130,7 +130,7 @@ condition_key: description: - The key in a key-value pair. - - I(condition_key) in the I(conditions) option must use the AWS resource tag prefix, e.g. 'aws:ResourceTag/key-name' + - O(conditions.string_not_like.condition_key) in the O(conditions) option must use the AWS resource tag prefix, e.g. 'aws:ResourceTag/key-name' type: str condition_value: description: The value in a key-value pair. diff --git a/plugins/modules/backup_tag.py b/plugins/modules/backup_tag.py index c06d5666ee1..2fb23cffc75 100644 --- a/plugins/modules/backup_tag.py +++ b/plugins/modules/backup_tag.py @@ -29,14 +29,14 @@ tags: description: - A dictionary of tags to add or remove from the resource. - - If the value provided for a tag key is null and I(state=absent), the tag will be removed regardless of its current value. + - If the value provided for a tag key is null and O(state=absent), the tag will be removed regardless of its current value. type: dict required: true aliases: ['resource_tags'] purge_tags: description: - Whether unspecified tags should be removed from the resource. - - Note that when combined with I(state=absent), specified tag keys are not purged regardless of its current value. + - Note that when combined with O(state=absent), specified tag keys are not purged regardless of its current value. type: bool default: false diff --git a/plugins/modules/backup_tag_info.py b/plugins/modules/backup_tag_info.py index 91bd375edb4..a0cbe64feb7 100644 --- a/plugins/modules/backup_tag_info.py +++ b/plugins/modules/backup_tag_info.py @@ -37,7 +37,7 @@ RETURN = r""" tags: - description: A dict containing the tags on the resource + description: A dict containing the tags on the resource. returned: always type: dict """ diff --git a/plugins/modules/cloudformation.py b/plugins/modules/cloudformation.py index 49392fde098..c24b3d55bf6 100644 --- a/plugins/modules/cloudformation.py +++ b/plugins/modules/cloudformation.py @@ -24,7 +24,7 @@ type: bool on_create_failure: description: - - Action to take upon failure of stack creation. Incompatible with the I(disable_rollback) option. + - Action to take upon failure of stack creation. Incompatible with the O(disable_rollback) option. choices: - DO_NOTHING - ROLLBACK @@ -32,7 +32,7 @@ type: str create_timeout: description: - - The amount of time (in minutes) that can pass before the stack status becomes CREATE_FAILED + - The amount of time (in minutes) that can pass before the stack status becomes V(CREATE_FAILED). type: int template_parameters: description: @@ -42,9 +42,9 @@ type: dict state: description: - - If I(state=present), stack will be created. - - If I(state=present) and if stack exists and template has changed, it will be updated. - - If I(state=absent), stack will be removed. + - If O(state=present), stack will be created. + - If O(state=present) and if stack exists and template has changed, it will be updated. + - If O(state=absent), stack will be removed. default: present choices: [ present, absent ] type: str @@ -52,13 +52,13 @@ description: - The local path of the CloudFormation template. - This must be the full path to the file, relative to the working directory. If using roles this may look - like C(roles/cloudformation/files/cloudformation-example.json). - - If I(state=present) and the stack does not exist yet, either I(template), I(template_body) or I(template_url) + like V(roles/cloudformation/files/cloudformation-example.json). + - If O(state=present) and the stack does not exist yet, either O(template), O(template_body) or O(template_url) must be specified (but only one of them). - - If I(state=present), the stack does exist, and neither I(template), - I(template_body) nor I(template_url) are specified, the previous template will be reused. - - The I(template) parameter has been deprecated and will be remove in a release after - 2026-05-01. It is recommended to use I(template_body) with the lookup plugin. + - If O(state=present), the stack does exist, and neither O(template), + O(template_body) nor O(template_url) are specified, the previous template will be reused. + - The O(template) parameter has been deprecated and will be remove in a release after + 2026-05-01. It is recommended to use O(template_body) with the P(ansible.builtin.template#lookup) lookup plugin. type: path notification_arns: description: @@ -77,7 +77,7 @@ version_added: 1.5.0 stack_policy_on_update_body: description: - - the body of the cloudformation stack policy only applied during this update. + - The body of the cloudformation stack policy only applied during this update. type: json version_added: 1.5.0 tags: @@ -89,23 +89,23 @@ description: - Location of file containing the template body. The URL must point to a template (max size 307,200 bytes) located in an S3 bucket in the same region as the stack. - - If I(state=present) and the stack does not exist yet, either I(template), I(template_body) or I(template_url) + - If O(state=present) and the stack does not exist yet, either O(template), O(template_body) or O(template_url) must be specified (but only one of them). - - If I(state=present), the stack does exist, and neither I(template), I(template_body) nor I(template_url) are specified, + - If O(state=present), the stack does exist, and neither O(template), O(template_body) nor O(template_url) are specified, the previous template will be reused. type: str create_changeset: description: - - "If stack already exists create a changeset instead of directly applying changes. See the AWS Change Sets docs - U(https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets.html)." - - "WARNING: if the stack does not exist, it will be created without changeset. If I(state=absent), the stack will be - deleted immediately with no changeset." + - If stack already exists create a changeset instead of directly applying changes. See the AWS Change Sets docs + U(https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets.html). + - B(WARNING:) if the stack does not exist, it will be created without changeset. If O(state=absent), the stack will be + deleted immediately with no changeset. type: bool default: false changeset_name: description: - Name given to the changeset when creating a changeset. - - Only used when I(create_changeset=true). + - Only used when O(create_changeset=true). - By default a name prefixed with Ansible-STACKNAME is generated based on input parameters. See the AWS Change Sets docs for more information U(https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets.html) @@ -122,9 +122,9 @@ template_body: description: - Template body. Use this to pass in the actual body of the CloudFormation template. - - If I(state=present) and the stack does not exist yet, either I(template), I(template_body) or I(template_url) + - If O(state=present) and the stack does not exist yet, either O(template), O(template_body) or O(template_url) must be specified (but only one of them). - - If I(state=present), the stack does exist, and neither I(template), I(template_body) nor I(template_url) + - If O(state=present), the stack does exist, and neither O(template), O(template_body) nor O(template_url) are specified, the previous template will be reused. type: str events_limit: @@ -154,7 +154,7 @@ capabilities: description: - Specify capabilities that stack template contains. - - Valid values are C(CAPABILITY_IAM), C(CAPABILITY_NAMED_IAM) and C(CAPABILITY_AUTO_EXPAND). + - Valid values are V(CAPABILITY_IAM), V(CAPABILITY_NAMED_IAM) and V(CAPABILITY_AUTO_EXPAND). type: list elements: str default: [ CAPABILITY_IAM, CAPABILITY_NAMED_IAM ] @@ -301,7 +301,7 @@ sample: ["updating stack"] change_set_id: description: The ID of the stack change set if one was created - returned: I(state=present) and I(create_changeset=true) + returned: O(state=present) and O(create_changeset=true) type: str sample: "arn:aws:cloudformation:us-east-1:123456789012:changeSet/Ansible-StackName-f4496805bd1b2be824d1e315c6884247ede41eb0" stack_resources: diff --git a/plugins/modules/cloudformation_info.py b/plugins/modules/cloudformation_info.py index 697b39f0071..afc02e4ab40 100644 --- a/plugins/modules/cloudformation_info.py +++ b/plugins/modules/cloudformation_info.py @@ -104,7 +104,7 @@ cloudformation: description: - Dictionary of dictionaries containing info of stack(s). - - Keys are I(stack_name)s. + - Keys are stack_name(s). returned: always type: dict contains: @@ -249,24 +249,24 @@ } stack_events: description: All stack events for the stack. - returned: only if all_facts or stack_events is true and the stack exists + returned: only if O(all_facts) or O(stack_events) is V(true) and the stack exists type: list stack_policy: description: Describes the stack policy for the stack. - returned: only if all_facts or stack_policy is true and the stack exists + returned: only if O(all_facts) or O(stack_policy) is V(true) and the stack exists type: dict stack_template: description: Describes the stack template for the stack. - returned: only if all_facts or stack_template is true and the stack exists + returned: only if O(all_facts) or O(stack_policy) is V(true) and the stack exists type: dict stack_resource_list: description: Describes stack resources for the stack. - returned: only if all_facts or stack_resources is true and the stack exists + returned: only if O(all_facts) or O(stack_policy) is V(true) and the stack exists type: list stack_resources: description: Dictionary of stack resources keyed by the value of each resource 'LogicalResourceId' parameter and corresponding value of each resource 'PhysicalResourceId' parameter. - returned: only if all_facts or stack_resources is true and the stack exists + returned: only if O(all_facts) or O(stack_policy) is V(true) and the stack exists type: dict sample: { "AutoScalingGroup": "dev-someapp-AutoscalingGroup-1SKEXXBCAN0S7", @@ -275,11 +275,11 @@ } stack_change_sets: description: A list of stack change sets. Each item in the list represents the details of a specific changeset. - returned: only if all_facts or stack_change_sets is true and the stack exists + returned: only if O(all_facts) or O(stack_policy) is V(true) and the stack exists type: list stack_tags: description: Dictionary of key value pairs of tags. - returned: only if all_facts or stack_resources is true and the stack exists + returned: only if O(all_facts) or O(stack_policy) is V(true) and the stack exists type: dict sample: { 'TagOne': 'ValueOne', diff --git a/plugins/modules/cloudtrail.py b/plugins/modules/cloudtrail.py index e17f21c2858..45c97cc8abd 100644 --- a/plugins/modules/cloudtrail.py +++ b/plugins/modules/cloudtrail.py @@ -20,9 +20,9 @@ state: description: - Add or remove CloudTrail configuration. - - 'The following states have been preserved for backwards compatibility: I(state=enabled) and I(state=disabled).' - - I(state=enabled) is equivalet to I(state=present). - - I(state=disabled) is equivalet to I(state=absent). + - 'The following states have been preserved for backwards compatibility: O(state=enabled) and O(state=disabled).' + - O(state=enabled) is equivalet to O(state=present). + - O(state=disabled) is equivalet to O(state=absent). type: str choices: ['present', 'absent', 'enabled', 'disabled'] default: present @@ -42,7 +42,7 @@ - An existing S3 bucket where CloudTrail will deliver log files. - This bucket should exist and have the proper policy. - See U(https://docs.aws.amazon.com/awscloudtrail/latest/userguide/aggregating_logs_regions_bucket_policy.html). - - Required when I(state=present). + - Required when O(state=present). type: str s3_key_prefix: description: @@ -73,23 +73,23 @@ description: - Specifies a full ARN for an IAM role that assigns the proper permissions for CloudTrail to create and write to the log group. - See U(https://docs.aws.amazon.com/awscloudtrail/latest/userguide/send-cloudtrail-events-to-cloudwatch-logs.html). - - Required when C(cloudwatch_logs_log_group_arn). + - Required when O(cloudwatch_logs_log_group_arn). type: str cloudwatch_logs_log_group_arn: description: - A full ARN specifying a valid CloudWatch log group to which CloudTrail logs will be delivered. The log group should already exist. - See U(https://docs.aws.amazon.com/awscloudtrail/latest/userguide/send-cloudtrail-events-to-cloudwatch-logs.html). - - Required when C(cloudwatch_logs_role_arn). + - Required when O(cloudwatch_logs_role_arn). type: str kms_key_id: description: - Specifies the KMS key ID to use to encrypt the logs delivered by CloudTrail. This also has the effect of enabling log file encryption. - The value can be an alias name prefixed by "alias/", a fully specified ARN to an alias, a fully specified ARN to a key, or a globally unique identifier. - - Encryption can be disabled by setting I(kms_key_id=""). + - Encryption can be disabled by setting O(kms_key_id=""). - See U(https://docs.aws.amazon.com/awscloudtrail/latest/userguide/encrypting-cloudtrail-log-files-with-aws-kms.html). type: str notes: - - The I(purge_tags) option was added in release 4.0.0 + - The O(purge_tags) option was added in release 4.0.0. extends_documentation_fragment: - amazon.aws.common.modules @@ -151,53 +151,53 @@ RETURN = r""" exists: - description: whether the resource exists + description: whether the resource exists. returned: always type: bool sample: true trail: - description: CloudTrail resource details + description: CloudTrail resource details. returned: always type: complex sample: hash/dictionary of values contains: trail_arn: - description: Full ARN of the CloudTrail resource + description: Full ARN of the CloudTrail resource. returned: success type: str sample: arn:aws:cloudtrail:us-east-1:123456789012:trail/default name: - description: Name of the CloudTrail resource + description: Name of the CloudTrail resource. returned: success type: str sample: default is_logging: - description: Whether logging is turned on or paused for the Trail + description: Whether logging is turned on or paused for the Trail. returned: success type: bool sample: True s3_bucket_name: - description: S3 bucket name where log files are delivered + description: S3 bucket name where log files are delivered. returned: success type: str sample: myBucket s3_key_prefix: - description: Key prefix in bucket where log files are delivered (if any) + description: Key prefix in bucket where log files are delivered (if any). returned: success when present type: str sample: myKeyPrefix log_file_validation_enabled: - description: Whether log file validation is enabled on the trail + description: Whether log file validation is enabled on the trail. returned: success type: bool sample: true include_global_service_events: - description: Whether global services (IAM, STS) are logged with this trail + description: Whether global services (IAM, STS) are logged with this trail. returned: success type: bool sample: true is_multi_region_trail: - description: Whether the trail applies to all regions or just one + description: Whether the trail applies to all regions or just one. returned: success type: bool sample: true diff --git a/plugins/modules/cloudtrail_info.py b/plugins/modules/cloudtrail_info.py index 9d3e4efb3a7..2cae49b6e5c 100644 --- a/plugins/modules/cloudtrail_info.py +++ b/plugins/modules/cloudtrail_info.py @@ -8,7 +8,7 @@ --- module: cloudtrail_info version_added: 5.0.0 -short_description: Gather information about trails in AWS Cloud Trail. +short_description: Gather information about trails in AWS Cloud Trail description: - Gather information about trails in AWS CloudTrail. author: "Gomathi Selvi Srinivasan (@GomathiselviS)" diff --git a/plugins/modules/cloudwatch_metric_alarm.py b/plugins/modules/cloudwatch_metric_alarm.py index e3a1749135b..e22611d6e30 100644 --- a/plugins/modules/cloudwatch_metric_alarm.py +++ b/plugins/modules/cloudwatch_metric_alarm.py @@ -6,12 +6,12 @@ DOCUMENTATION = r""" module: cloudwatch_metric_alarm -short_description: "Create/update or delete AWS CloudWatch 'metric alarms'" +short_description: Create/update or delete AWS CloudWatch 'metric alarms' version_added: 5.0.0 description: - Can create or delete AWS CloudWatch metric alarms. - Metrics you wish to alarm on must already exist. - - Prior to release 5.0.0 this module was called C(community.aws.ec2_metric_alarm). + - Prior to release 5.0.0 this module was called M(community.aws.ec2_metric_alarm). The usage did not change. - This module was originally added to C(community.aws) in release 1.0.0. author: @@ -30,7 +30,7 @@ type: str metric_name: description: - - Name of the monitored metric (e.g. C(CPUUtilization)). + - Name of the monitored metric (e.g. V(CPUUtilization)). - Metric must already exist. required: false type: str @@ -69,7 +69,7 @@ type: str required: True dimensions: - description: a name/value pair that is part of the identity of a metric. + description: A name/value pair that is part of the identity of a metric. type: list elements: dict required: false @@ -118,13 +118,13 @@ required: false namespace: description: - - Name of the appropriate namespace (C(AWS/EC2), C(System/Linux), etc.), which determines the category it will appear under in CloudWatch. + - Name of the appropriate namespace (V(AWS/EC2), V(System/Linux), etc.), which determines the category it will appear under in CloudWatch. required: false type: str statistic: description: - Operation applied to the metric. - - Works in conjunction with I(period) and I(evaluation_periods) to determine the comparison value. + - Works in conjunction with O(period) and O(evaluation_periods) to determine the comparison value. required: false choices: ['SampleCount','Average','Sum','Minimum','Maximum'] type: str @@ -205,21 +205,21 @@ type: dict alarm_actions: description: - - A list of the names action(s) taken when the alarm is in the C(alarm) status, denoted as Amazon Resource Name(s). + - A list of the names action(s) taken when the alarm is in the V(alarm) status, denoted as Amazon Resource Name(s). required: false type: list elements: str default: [] insufficient_data_actions: description: - - A list of the names of action(s) to take when the alarm is in the C(insufficient_data) status. + - A list of the names of action(s) to take when the alarm is in the V(insufficient_data) status. required: false type: list elements: str default: [] ok_actions: description: - - A list of the names of action(s) to take when the alarm is in the C(ok) status, denoted as Amazon Resource Name(s). + - A list of the names of action(s) to take when the alarm is in the V(ok) status, denoted as Amazon Resource Name(s). required: false type: list elements: str diff --git a/plugins/modules/cloudwatch_metric_alarm_info.py b/plugins/modules/cloudwatch_metric_alarm_info.py index 1e5287dcd10..8284a363643 100644 --- a/plugins/modules/cloudwatch_metric_alarm_info.py +++ b/plugins/modules/cloudwatch_metric_alarm_info.py @@ -23,13 +23,13 @@ alarm_name_prefix: description: - An alarm name prefix to retrieve information about alarms that have names that start with this prefix. - - Can not be used with I(alarm_names). + - Can not be used with O(alarm_names). required: false type: str alarm_type: description: - Specify this to return metric alarms or composite alarms. - - Module is defaulted to return metric alarms but can return composite alarms if I(alarm_type=CompositeAlarm). + - Module is defaulted to return metric alarms but can return composite alarms if O(alarm_type=CompositeAlarm). required: false type: str default: MetricAlarm @@ -147,7 +147,7 @@ type: str namespace: description: - - Name of the appropriate namespace (C(AWS/EC2), C(System/Linux), etc.). + - Name of the appropriate namespace (V(AWS/EC2), V(System/Linux), etc.). - Determines the category it will appear under in CloudWatch. returned: always type: str diff --git a/plugins/modules/cloudwatchevent_rule.py b/plugins/modules/cloudwatchevent_rule.py index 0b318b28474..800edb1e2b3 100644 --- a/plugins/modules/cloudwatchevent_rule.py +++ b/plugins/modules/cloudwatchevent_rule.py @@ -20,10 +20,11 @@ author: - "Jim Dalton (@jsdalton) " notes: - - A rule must contain at least an I(event_pattern) or I(schedule_expression). A - rule can have both an I(event_pattern) and a I(schedule_expression), in which + - A rule must contain at least an O(event_pattern) or O(schedule_expression). A + rule can have both an O(event_pattern) and a O(schedule_expression), in which case the rule will trigger on matching events as well as on a schedule. - - When specifying targets, I(input), I(input_path), I(input_paths_map) and I(input_template) + - When specifying targets, O(targets.input), O(targets.input_path), + O(targets.input_transformer.input_paths_map) and O(targets.input_transformer.input_template) are mutually-exclusive and optional parameters. options: name: @@ -83,14 +84,14 @@ type: json description: - A JSON object that will override the event data passed to the target. - - If neither I(input) nor I(input_path) nor I(input_transformer) + - If neither O(targets.input) nor O(targets.input_path) nor O(targets.input_transformer) is specified, then the entire event is passed to the target in JSON form. input_path: type: str description: - - A JSONPath string (e.g. C($.detail)) that specifies the part of the event data to be + - A JSONPath string (e.g. V($.detail)) that specifies the part of the event data to be passed to the target. - - If neither I(input) nor I(input_path) nor I(input_transformer) + - If neither O(targets.input) nor O(targets.input_path) nor O(targets.input_transformer) is specified, then the entire event is passed to the target in JSON form. input_transformer: type: dict @@ -120,7 +121,7 @@ required: true task_count: type: int - description: The number of tasks to create based on I(task_definition). + description: The number of tasks to create based on task definition. required: false """ diff --git a/plugins/modules/cloudwatchlogs_log_group.py b/plugins/modules/cloudwatchlogs_log_group.py index 2fa7b0181c4..f47fa95ff69 100644 --- a/plugins/modules/cloudwatchlogs_log_group.py +++ b/plugins/modules/cloudwatchlogs_log_group.py @@ -14,7 +14,7 @@ - This module was originally added to C(community.aws) in release 1.0.0. notes: - For details of the parameters and returns see U(http://boto3.readthedocs.io/en/latest/reference/services/logs.html). - - Support for I(purge_tags) was added in release 4.0.0. + - Support for O(purge_tags) was added in release 4.0.0. author: - Willian Ricardo (@willricardo) options: @@ -39,20 +39,20 @@ description: - The number of days to retain the log events in the specified log group. - "Valid values are: [1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1827, 3653]" - - Mutually exclusive with I(purge_retention_policy). + - Mutually exclusive with O(purge_retention_policy). required: false type: int purge_retention_policy: description: - - "Whether to purge the retention policy or not." - - "Mutually exclusive with I(retention) and I(overwrite)." + - Whether to purge the retention policy or not. + - Mutually exclusive with O(retention) and O(overwrite). default: false required: false type: bool overwrite: description: - Whether an existing log group should be overwritten on create. - - Mutually exclusive with I(purge_retention_policy). + - Mutually exclusive with O(purge_retention_policy). default: false required: false type: bool @@ -123,7 +123,7 @@ returned: always type: dict log_groups: - description: Return the list of complex objects representing log groups + description: Return the list of complex objects representing log groups. returned: success type: complex version_added: 4.0.0 diff --git a/plugins/modules/cloudwatchlogs_log_group_info.py b/plugins/modules/cloudwatchlogs_log_group_info.py index 453d268d52b..f2770519e7a 100644 --- a/plugins/modules/cloudwatchlogs_log_group_info.py +++ b/plugins/modules/cloudwatchlogs_log_group_info.py @@ -33,7 +33,7 @@ RETURN = r""" log_groups: - description: Return the list of complex objects representing log groups + description: Return the list of complex objects representing log groups. returned: success type: complex contains: diff --git a/plugins/modules/cloudwatchlogs_log_group_metric_filter.py b/plugins/modules/cloudwatchlogs_log_group_metric_filter.py index b8bf0884b6a..8eddb671bed 100644 --- a/plugins/modules/cloudwatchlogs_log_group_metric_filter.py +++ b/plugins/modules/cloudwatchlogs_log_group_metric_filter.py @@ -34,11 +34,11 @@ type: str filter_pattern: description: - - A filter pattern for extracting metric data out of ingested log events. Required when I(state=present). + - A filter pattern for extracting metric data out of ingested log events. Required when O(state=present). type: str metric_transformation: description: - - A collection of information that defines how metric data gets emitted. Required when I(state=present). + - A collection of information that defines how metric data gets emitted. Required when O(state=present). type: dict suboptions: metric_name: @@ -84,7 +84,7 @@ RETURN = r""" metric_filters: - description: Return the origin response value + description: Return the origin response value. returned: success type: list sample: [ diff --git a/plugins/modules/ec2_ami.py b/plugins/modules/ec2_ami.py index ec6663146d7..699f22680c3 100644 --- a/plugins/modules/ec2_ami.py +++ b/plugins/modules/ec2_ami.py @@ -61,7 +61,7 @@ default: '' no_reboot: description: - - Flag indicating that the bundling process should not attempt to shutdown the instance before bundling. If this flag is True, the + - Flag indicating that the bundling process should not attempt to shutdown the instance before bundling. If this flag is V(true), the responsibility of maintaining file system integrity is left to the owner of the instance. default: false type: bool @@ -78,7 +78,7 @@ device_name: type: str description: - - The device name. For example C(/dev/sda). + - The device name. For example V(/dev/sda). required: true virtual_name: type: str @@ -91,7 +91,7 @@ - Suppresses the specified device included in the block device mapping of the AMI. volume_type: type: str - description: The volume type. Defaults to C(gp2) when not set. + description: The volume type. Defaults to V(gp2) when not set. delete_on_termination: type: bool description: Whether the device should be automatically deleted when the Instance is terminated. @@ -100,7 +100,7 @@ description: The ID of the Snapshot. iops: type: int - description: When using an C(io1) I(volume_type) this sets the number of IOPS provisioned for the volume. + description: When using O(device_mapping.volume_type=io1), this sets the number of IOPS provisioned for the volume. encrypted: type: bool description: Whether the volume should be encrypted. @@ -172,18 +172,16 @@ version_added: 5.5.0 tpm_support: description: - - Set to v2.0 to enable Trusted Platform Module (TPM) support. - - If the image is configured for NitroTPM support, the value is v2.0 . - - Requires I(boot_mode) to be set to 'uefi'. + - Set to V(v2.0) to enable Trusted Platform Module (TPM) support. + - If the image is configured for NitroTPM support, the value is V(v2.0). + - Requires O(boot_mode) to be set to V(uefi). - Requires an instance type that is compatible with Nitro. - - Requires minimum botocore version 1.26.0. - See the AWS documentation for more detail U(https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nitrotpm.html). type: str version_added: 5.5.0 uefi_data: description: - Base64 representation of the non-volatile UEFI variable store. - - Requires minimum botocore version 1.26.0. - See the AWS documentation for more detail U(https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/uefi-secure-boot.html). type: str version_added: 5.5.0 diff --git a/plugins/modules/ec2_ami_info.py b/plugins/modules/ec2_ami_info.py index 906c141e1cf..fb6a7cc2d93 100644 --- a/plugins/modules/ec2_ami_info.py +++ b/plugins/modules/ec2_ami_info.py @@ -8,9 +8,9 @@ --- module: ec2_ami_info version_added: 1.0.0 -short_description: Gather information about ec2 AMIs +short_description: Gather information about EC2 AMIs description: - - Gather information about ec2 AMIs + - Gather information about EC2 AMIs. author: - Prasad Katti (@prasadkatti) options: @@ -141,7 +141,7 @@ sample: machine launch_permissions: description: A List of AWS accounts may launch the AMI. - returned: When image is owned by calling account and I(describe_image_attributes=true). + returned: When image is owned by calling account and O(describe_image_attributes=true). type: list elements: dict contains: diff --git a/plugins/modules/ec2_eip.py b/plugins/modules/ec2_eip.py index 38bf32c87a3..52080ff3685 100644 --- a/plugins/modules/ec2_eip.py +++ b/plugins/modules/ec2_eip.py @@ -18,28 +18,28 @@ description: - The id of the device for the EIP. - Can be an EC2 Instance id or Elastic Network Interface (ENI) id. - - When specifying an ENI id, I(in_vpc) must be C(true) + - When specifying an ENI id, O(in_vpc) must be V(true). - The C(instance_id) alias was removed in release 6.0.0. required: false type: str public_ip: description: - The IP address of a previously allocated EIP. - - When I(state=present) and device is specified, the EIP is associated with the device. - - When I(state=absent) and device is specified, the EIP is disassociated from the device. + - When O(state=present) and device is specified, the EIP is associated with the device. + - When O(state=absent) and device is specified, the EIP is disassociated from the device. aliases: [ ip ] type: str state: description: - - When C(state=present), allocate an EIP or associate an existing EIP with a device. - - When C(state=absent), disassociate the EIP from the device and optionally release it. + - When O(state=present), allocate an EIP or associate an existing EIP with a device. + - When O(state=absent), disassociate the EIP from the device and optionally release it. choices: ['present', 'absent'] default: present type: str in_vpc: description: - Allocate an EIP inside a VPC or not. - - Required if specifying an ENI with I(device_id). + - Required if specifying an ENI with O(device_id). default: false type: bool reuse_existing_ip_allowed: @@ -64,17 +64,17 @@ type: bool tag_name: description: - - When I(reuse_existing_ip_allowed=true), supplement with this option to only reuse - an Elastic IP if it is tagged with I(tag_name). + - When O(reuse_existing_ip_allowed=true), supplement with this option to only reuse + an Elastic IP if it is tagged with O(tag_name). type: str tag_value: description: - - Supplements I(tag_name) but also checks that the value of the tag provided in I(tag_name) matches I(tag_value). + - Supplements O(tag_name) but also checks that the value of the tag provided in O(tag_name) matches O(tag_value). type: str public_ipv4_pool: description: - Allocates the new Elastic IP from the provided public IPv4 pool (BYOIP) - only applies to newly allocated Elastic IPs, isn't validated when I(reuse_existing_ip_allowed=true). + only applies to newly allocated Elastic IPs, isn't validated when O(reuse_existing_ip_allowed=true). type: str extends_documentation_fragment: - amazon.aws.common.modules @@ -92,7 +92,7 @@ - This module returns multiple changed statuses on disassociation or release. It returns an overall status based on any changes occurring. It also returns individual changed statuses for disassociation and release. - - Support for I(tags) and I(purge_tags) was added in release 2.1.0. + - Support for O(tags) and O(purge_tags) was added in release 2.1.0. """ EXAMPLES = r""" @@ -205,12 +205,12 @@ RETURN = r""" allocation_id: - description: allocation_id of the elastic ip + description: Allocation id of the elastic ip. returned: on success type: str sample: eipalloc-51aa3a6c public_ip: - description: an elastic ip address + description: An elastic ip address. returned: on success type: str sample: 52.88.159.209 diff --git a/plugins/modules/ec2_eip_info.py b/plugins/modules/ec2_eip_info.py index 8e775582be1..18d03160e3e 100644 --- a/plugins/modules/ec2_eip_info.py +++ b/plugins/modules/ec2_eip_info.py @@ -18,7 +18,7 @@ filters: description: - A dict of filters to apply. Each dict item consists of a filter key and filter - value. See U(https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-addresses.html#options) + value. See U(https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-addresses.html#options) for possible filters. Filter names and values are case sensitive. required: false default: {} @@ -91,7 +91,7 @@ type: str sample: "eipassoc-0fe9ce90d6e983e97" "domain": - description: The network ( vpc). + description: The network (vpc). type: str returned: always sample: "vpc"