From 7185809e9f419381c02279b19759a496e81f8f99 Mon Sep 17 00:00:00 2001 From: Alina Buzachis Date: Fri, 10 May 2024 13:54:39 +0200 Subject: [PATCH] Ensures the modules documentation follows the correct formats Signed-off-by: Alina Buzachis --- plugins/modules/ec2_eni.py | 62 ++++----- plugins/modules/ec2_eni_info.py | 6 +- plugins/modules/ec2_import_image.py | 8 +- plugins/modules/ec2_instance.py | 102 +++++++-------- plugins/modules/ec2_instance_info.py | 8 +- plugins/modules/ec2_key.py | 40 +++--- plugins/modules/ec2_security_group.py | 144 ++++++++++----------- plugins/modules/ec2_security_group_info.py | 6 +- plugins/modules/ec2_snapshot.py | 18 +-- plugins/modules/ec2_snapshot_info.py | 18 +-- plugins/modules/ec2_spot_instance.py | 22 ++-- plugins/modules/ec2_spot_instance_info.py | 2 +- plugins/modules/ec2_tag.py | 12 +- plugins/modules/ec2_tag_info.py | 2 +- 14 files changed, 225 insertions(+), 225 deletions(-) diff --git a/plugins/modules/ec2_eni.py b/plugins/modules/ec2_eni.py index 794ed45a958..979d20fa4e6 100644 --- a/plugins/modules/ec2_eni.py +++ b/plugins/modules/ec2_eni.py @@ -11,8 +11,8 @@ short_description: Create and optionally attach an Elastic Network Interface (ENI) to an instance description: - Create and optionally attach an Elastic Network Interface (ENI) to an instance. - - If I(eni_id) or I(private_ip) is provided, the existing ENI (if any) will be modified. - - The I(attached) parameter controls the attachment status of the network interface. + - If O(eni_id) or O(private_ip) is provided, the existing ENI (if any) will be modified. + - The O(attached) parameter controls the attachment status of the network interface. author: - "Rob White (@wimnat)" - "Mike Healey (@healem)" @@ -20,7 +20,7 @@ eni_id: description: - The ID of the ENI (to modify). - - If I(eni_id=None) and I(state=present), a new ENI will be created. + - If O(eni_id=None) and O(state=present), a new ENI will be created. type: str instance_id: description: @@ -41,7 +41,7 @@ security_groups: description: - List of security groups associated with the interface. - - Ignored when I(state=absent). + - Ignored when O(state=absent). type: list elements: str default: [] @@ -63,8 +63,8 @@ type: bool force_detach: description: - - Force detachment of the interface. This applies either when explicitly detaching the interface by setting I(instance_id=None) - or when deleting an interface with I(state=absent). + - Force detachment of the interface. This applies either when explicitly detaching the interface by setting O(instance_id=None) + or when deleting an interface with O(state=absent). default: false type: bool delete_on_termination: @@ -82,20 +82,20 @@ secondary_private_ip_addresses: description: - A list of IP addresses to assign as secondary IP addresses to the network interface. - - This option is mutually exclusive of I(secondary_private_ip_address_count). + - This option is mutually exclusive of O(secondary_private_ip_address_count). required: false type: list elements: str purge_secondary_private_ip_addresses: description: - - To be used with I(secondary_private_ip_addresses) to determine whether or not to remove any secondary IP addresses other than those specified. - - Set I(secondary_private_ip_addresses=[]) to purge all secondary addresses. + - To be used with O(secondary_private_ip_addresses) to determine whether or not to remove any secondary IP addresses other than those specified. + - Set O(secondary_private_ip_addresses=[]) to purge all secondary addresses. default: false type: bool secondary_private_ip_address_count: description: - The number of secondary IP addresses to assign to the network interface. - - This option is mutually exclusive of I(secondary_private_ip_addresses). + - This option is mutually exclusive of O(secondary_private_ip_addresses). required: false type: int allow_reassignment: @@ -107,10 +107,10 @@ type: bool name: description: - - Name for the ENI. This will create a tag with the key C(Name) and the value assigned here. - - This can be used in conjunction with I(subnet_id) as another means of identifiying a network interface. - - AWS does not enforce unique C(Name) tags, so duplicate names are possible if you configure it that way. - If that is the case, you will need to provide other identifying information such as I(private_ip_address) or I(eni_id). + - Name for the ENI. This will create a tag with the key V(Name) and the value assigned here. + - This can be used in conjunction with O(subnet_id) as another means of identifiying a network interface. + - AWS does not enforce unique V(Name) tags, so duplicate names are possible if you configure it that way. + If that is the case, you will need to provide other identifying information such as O(private_ip_address) or O(eni_id). required: false type: str extends_documentation_fragment: @@ -119,9 +119,9 @@ - amazon.aws.tags - amazon.aws.boto3 notes: - - This module identifies and ENI based on either the I(eni_id), a combination of I(private_ip_address) and I(subnet_id), - or a combination of I(instance_id) and I(device_id). Any of these options will let you specify a particular ENI. - - Support for I(tags) and I(purge_tags) was added in release 1.3.0. + - This module identifies and ENI based on either the O(eni_id), a combination of O(private_ip_address) and O(subnet_id), + or a combination of O(instance_id) and O(device_id). Any of these options will let you specify a particular ENI. + - Support for O(tags) and O(purge_tags) was added in release 1.3.0. """ EXAMPLES = r""" @@ -213,7 +213,7 @@ RETURN = r""" interface: - description: Network interface attributes + description: Network interface attributes. returned: when state != absent type: complex contains: @@ -229,56 +229,56 @@ "status": "attached" } description: - description: interface description + description: Interface description. type: str sample: Firewall network interface groups: - description: dict of security groups + description: Dict of security groups. type: dict sample: { "sg-f8a8a9da": "default" } id: - description: network interface id + description: Network interface id. type: str sample: "eni-1d889198" mac_address: - description: interface's physical address + description: Interface's physical address. type: str sample: "00:00:5E:00:53:23" name: - description: The name of the ENI + description: The name of the ENI. type: str sample: "my-eni-20" owner_id: - description: aws account id + description: AWS account id. type: str sample: 812381371 private_ip_address: - description: primary ip address of this interface + description: Primary ip address of this interface. type: str sample: 10.20.30.40 private_ip_addresses: - description: list of all private ip addresses associated to this interface + description: List of all private ip addresses associated to this interface. type: list elements: dict sample: [ { "primary_address": true, "private_ip_address": "10.20.30.40" } ] source_dest_check: - description: value of source/dest check flag + description: Value of source/dest check flag. type: bool sample: True status: - description: network interface status + description: Network interface status. type: str sample: "pending" subnet_id: - description: which vpc subnet the interface is bound + description: Which vpc subnet the interface is bound. type: str sample: subnet-b0a0393c tags: - description: The dictionary of tags associated with the ENI + description: The dictionary of tags associated with the ENI. type: dict sample: { "Name": "my-eni", "group": "Finance" } vpc_id: - description: which vpc this network interface is bound + description: Which vpc this network interface is bound. type: str sample: vpc-9a9a9da """ diff --git a/plugins/modules/ec2_eni_info.py b/plugins/modules/ec2_eni_info.py index ca0a4bb2287..23e25d22011 100644 --- a/plugins/modules/ec2_eni_info.py +++ b/plugins/modules/ec2_eni_info.py @@ -17,14 +17,14 @@ eni_id: description: - The ID of the ENI. - - This option is mutually exclusive of I(filters). + - This option is mutually exclusive of O(filters). type: str version_added: 1.3.0 filters: description: - A dict of filters to apply. Each dict item consists of a filter key and a filter value. See U(https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeNetworkInterfaces.html) for possible filters. - - This option is mutually exclusive of I(eni_id). + - This option is mutually exclusive of O(eni_id). type: dict default: {} extends_documentation_fragment: @@ -97,7 +97,7 @@ } ] id: - description: The id of the ENI (alias for network_interface_id). + description: The id of the ENI (alias for RV(network_interface_id)). returned: always type: str sample: "eni-392fsdf" diff --git a/plugins/modules/ec2_import_image.py b/plugins/modules/ec2_import_image.py index c167d5ce8c0..7ace4c7aa6b 100644 --- a/plugins/modules/ec2_import_image.py +++ b/plugins/modules/ec2_import_image.py @@ -16,8 +16,8 @@ options: state: description: - - Use I(state=present) to import single or multi-volume disk images or EBS snapshots into an Amazon Machine Image (AMI). - - Use I(state=absent) to cancel an in-process import virtual machine task. + - Use O(state=present) to import single or multi-volume disk images or EBS snapshots into an Amazon Machine Image (AMI). + - Use O(state=absent) to cancel an in-process import virtual machine task. default: "present" choices: ["present", "absent"] type: str @@ -101,7 +101,7 @@ encrypted: description: - Specifies whether the destination AMI of the imported image should be encrypted. - - The default KMS key for EBS is used unless you specify a non-default KMS key using I(kms_key_id). + - The default KMS key for EBS is used unless you specify a non-default KMS key using O(kms_key_id). type: bool hypervisor: description: @@ -113,7 +113,7 @@ - An identifier for the symmetric KMS key to use when creating the encrypted AMI. This parameter is only required if you want to use a non-default KMS key; if this parameter is not specified, the default KMS key for EBS is used. - If a I(kms_key_id) is specified, the I(encrypted) flag must also be set. + If a O(kms_key_id) is specified, the O(encrypted) flag must also be set. type: str license_type: description: diff --git a/plugins/modules/ec2_instance.py b/plugins/modules/ec2_instance.py index c09cce97bea..c42e3b5a586 100644 --- a/plugins/modules/ec2_instance.py +++ b/plugins/modules/ec2_instance.py @@ -20,27 +20,27 @@ instance_ids: description: - If you specify one or more instance IDs, only instances that have the specified IDs are returned. - - Mutually exclusive with I(exact_count). + - Mutually exclusive with O(exact_count). type: list elements: str default: [] state: description: - Goal state for the instances. - - "I(state=present): ensures instances exist, but does not guarantee any state (e.g. running). Newly-launched instances will be run by EC2." - - "I(state=running): I(state=present) + ensures the instances are running" - - "I(state=started): I(state=running) + waits for EC2 status checks to report OK if I(wait=true)" - - "I(state=stopped): ensures an existing instance is stopped." - - "I(state=rebooted): convenience alias for I(state=stopped) immediately followed by I(state=running)" - - "I(state=restarted): convenience alias for I(state=stopped) immediately followed by I(state=started)" - - "I(state=terminated): ensures an existing instance is terminated." - - "I(state=absent): alias for I(state=terminated)" + - "O(state=present): ensures instances exist, but does not guarantee any state (e.g. running). Newly-launched instances will be run by EC2." + - "O(state=running): O(state=present) + ensures the instances are running." + - "O(state=started): O(state=running) + waits for EC2 status checks to report OK if O(wait=true)." + - "O(state=stopped): ensures an existing instance is stopped." + - "O(state=rebooted): convenience alias for O(state=stopped) immediately followed by O(state=running)." + - "O(state=restarted): convenience alias for O(state=stopped) immediately followed by O(state=started)." + - "O(state=terminated): ensures an existing instance is terminated." + - "O(state=absent): alias for O(state=terminated)." choices: [present, terminated, running, started, stopped, restarted, rebooted, absent] default: present type: str wait: description: - - Whether or not to wait for the desired I(state) (use (wait_timeout) to customize this). + - Whether or not to wait for the desired O(state) (use O(wait_timeout) to customize this). default: true type: bool wait_timeout: @@ -53,22 +53,22 @@ - Instance type to use for the instance, see U(https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html). - Only required when instance is not already present. - - At least one of I(instance_type) or I(launch_template) must be specificed when launching an + - At least one of O(instance_type) or O(launch_template) must be specificed when launching an instance. type: str count: description: - Number of instances to launch. - Setting this value will result in always launching new instances. - - Mutually exclusive with I(exact_count). + - Mutually exclusive with O(exact_count). type: int version_added: 2.2.0 exact_count: description: - - An integer value which indicates how many instances that match the I(filters) parameter should be running. + - An integer value which indicates how many instances that match the O(filters) parameter should be running. - Instances are either created or terminated based on this value. - If termination takes place, least recently created instances will be terminated based on Launch Time. - - Mutually exclusive with I(count), I(instance_ids). + - Mutually exclusive with O(count), O(instance_ids). type: int version_added: 2.2.0 user_data: @@ -79,45 +79,45 @@ description: - Preconfigured user-data to enable an instance to perform an Ansible Automation Platform callback (Linux only). - - For Windows instances, to enable remote access via Ansible set I(windows) to C(true), and + - For Windows instances, to enable remote access via Ansible set O(windows) to V(true), and optionally set an admin password. - - If using I(windows) and I(set_password), callback ton Ansible Automation Platform will not + - If using O(windows) and O(set_password), callback ton Ansible Automation Platform will not be performed but the instance will be ready to receive winrm connections from Ansible. - - Mutually exclusive with I(user_data). + - Mutually exclusive with O(user_data). type: dict aliases: ['tower_callback'] suboptions: windows: description: - - Set I(windows=True) to use powershell instead of bash for the callback script. + - Set O(windows=True) to use powershell instead of bash for the callback script. type: bool default: False set_password: description: - - Optional admin password to use if I(windows=True). + - Optional admin password to use if O(windows=True). type: str tower_address: description: - IP address or DNS name of Tower server. Must be accessible via this address from the VPC that this instance will be launched in. - - Required if I(windows=False). + - Required if O(windows=False). type: str job_template_id: description: - Either the integer ID of the Tower Job Template, or the name. Using a name for the job template is not supported by Ansible Tower prior to version 3.2. - - Required if I(windows=False). + - Required if O(windows=False). type: str host_config_key: description: - Host configuration secret key generated by the Tower job template. - - Required if I(windows=False). + - Required if O(windows=False). type: str image: description: - An image to use for the instance. The M(amazon.aws.ec2_ami_info) module may be used to retrieve images. - One of I(image) or I(image_id) are required when instance is not already present. + One of O(image) or O(image_id) are required when instance is not already present. type: dict suboptions: id: @@ -133,20 +133,20 @@ - a string AKI to override the AMI kernel. image_id: description: - - I(ami) ID to use for the instance. One of I(image) or I(image_id) are required when instance is not already present. - - This is an alias for I(image.id). + - I(ami) ID to use for the instance. One of O(image) or O(image_id) are required when instance is not already present. + - This is an alias for O(image.id). type: str security_groups: description: - A list of security group IDs or names (strings). - - Mutually exclusive with I(security_group). + - Mutually exclusive with O(security_group). type: list elements: str default: [] security_group: description: - A security group ID or name. - - Mutually exclusive with I(security_groups). + - Mutually exclusive with O(security_groups). type: str name: description: @@ -167,7 +167,7 @@ suboptions: interfaces: description: - - A list of ENI IDs (strings) or a list of objects containing the key I(id). + - A list of ENI IDs (strings) or a list of objects containing the key O(id). type: list elements: str assign_public_ip: @@ -217,15 +217,15 @@ volumes: description: - A list of block device mappings, by default this will always use the AMI root device so the volumes option is primarily for adding more storage. - - A mapping contains the (optional) keys C(device_name), C(virtual_name), C(ebs.volume_type), C(ebs.volume_size), C(ebs.kms_key_id), - C(ebs.snapshot_id), C(ebs.iops), and C(ebs.delete_on_termination). + - A mapping contains the (optional) keys V(device_name), V(virtual_name), V(ebs.volume_type), V(ebs.volume_size), V(ebs.kms_key_id), + V(ebs.snapshot_id), V(ebs.iops), and V(ebs.delete_on_termination). - For more information about each parameter, see U(https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_BlockDeviceMapping.html). type: list elements: dict launch_template: description: - The EC2 launch template to base instance configuration on. - - At least one of I(instance_type) or I(launch_template) must be specificed when launching an + - At least one of O(instance_type) or O(launch_template) must be specificed when launching an instance. type: dict suboptions: @@ -247,7 +247,7 @@ type: str availability_zone: description: - - Specify an availability zone to use the default subnet it. Useful if not specifying the I(vpc_subnet_id) parameter. + - Specify an availability zone to use the default subnet it. Useful if not specifying the O(vpc_subnet_id) parameter. - If no subnet, ENI, or availability zone is provided, the default subnet in the default VPC will be used in the first AZ (alphabetically sorted). type: str instance_initiated_shutdown_behavior: @@ -257,8 +257,8 @@ type: str tenancy: description: - - What type of tenancy to allow an instance to use. Default is shared tenancy. Dedicated tenancy will incur additional charges. - - This field is deprecated and will be removed in a release after 2025-12-01, use I(placement) instead. + - What type of tenancy to allow an instance to use. Default is V(shared) tenancy. Dedicated tenancy will incur additional charges. + - This field is deprecated and will be removed in a release after 2025-12-01, use O(placement) instead. choices: ['dedicated', 'default'] type: str termination_protection: @@ -277,13 +277,13 @@ cpu_credit_specification: description: - For T series instances, choose whether to allow increased charges to buy CPU credits if the default pool is depleted. - - Choose C(unlimited) to enable buying additional CPU credits. + - Choose V(unlimited) to enable buying additional CPU credits. choices: ['unlimited', 'standard'] type: str cpu_options: description: - Reduce the number of vCPU exposed to the instance. - - Those parameters can only be set at instance launch. The two suboptions threads_per_core and core_count are mandatory. + - Those parameters can only be set at instance launch. The two suboptions O(cpu_options.threads_per_core) and O(cpu_options.core_count) are mandatory. - See U(https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-optimize-cpu.html) for combinations available. type: dict suboptions: @@ -326,7 +326,7 @@ placement_group: description: - The placement group that needs to be assigned to the instance. - - This field is deprecated and will be removed in a release after 2025-12-01, use I(placement) instead. + - This field is deprecated and will be removed in a release after 2025-12-01, use O(placement) instead. type: str placement: description: @@ -361,7 +361,7 @@ tenancy: description: - Type of tenancy to allow an instance to use. Default is shared tenancy. Dedicated tenancy will incur additional charges. - - Support for I(tenancy=host) was added in amazon.aws 7.6.0. + - Support for O(tenancy=host) was added in amazon.aws 7.6.0. type: str required: false choices: ['dedicated', 'default', 'host'] @@ -384,7 +384,7 @@ description: - Modify the metadata options for the instance. - See U(https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) for more information. - - The two suboptions I(http_endpoint) and I(http_tokens) are supported. + - The two suboptions O(http_endpoint) and O(http_tokens) are supported. type: dict version_added: 2.0.0 suboptions: @@ -414,14 +414,14 @@ version_added: 4.0.0 type: str description: - - Whether the instance metadata endpoint is available via IPv6 (C(enabled)) or not (C(disabled)). + - Whether the instance metadata endpoint is available via IPv6 (V(enabled)) or not (V(disabled)). choices: [enabled, disabled] default: 'disabled' instance_metadata_tags: version_added: 4.0.0 type: str description: - - Whether the instance tags are availble (C(enabled)) via metadata endpoint or not (C(disabled)). + - Whether the instance tags are availble (V(enabled)) via metadata endpoint or not (V(disabled)). choices: [enabled, disabled] default: 'disabled' @@ -606,26 +606,26 @@ RETURN = r""" instance_ids: - description: a list of ec2 instance IDs matching the provided specification and filters + description: A list of ec2 instance IDs matching the provided specification and filters. returned: always type: list sample: ["i-0123456789abcdef0", "i-0123456789abcdef1"] version_added: 5.3.0 changed_ids: - description: a list of the set of ec2 instance IDs changed by the module action + description: A list of the set of ec2 instance IDs changed by the module action. returned: when instances that must be present are launched type: list sample: ["i-0123456789abcdef0"] version_added: 5.3.0 terminated_ids: - description: a list of the set of ec2 instance IDs terminated by the module action + description: A list of the set of ec2 instance IDs terminated by the module action. returned: when instances that must be absent are terminated type: list sample: ["i-0123456789abcdef1"] version_added: 5.3.0 instances: - description: a list of ec2 instances - returned: when wait == true or when matching instances already exist + description: A list of ec2 instances. + returned: when O(wait=true) or when matching instances already exist type: complex contains: ami_launch_index: @@ -634,7 +634,7 @@ type: int sample: 0 architecture: - description: The architecture of the image + description: The architecture of the image. returned: always type: str sample: x86_64 @@ -644,7 +644,7 @@ type: complex contains: device_name: - description: The device name exposed to the instance (for example, /dev/sdh or xvdh). + description: The device name exposed to the instance (for example, RV(/dev/sdh) or RV(xvdh)). returned: always type: str sample: /dev/sdh @@ -669,7 +669,7 @@ type: str sample: attached volume_id: - description: The ID of the EBS volume + description: The ID of the EBS volume. returned: always type: str sample: vol-12345678 @@ -730,7 +730,7 @@ type: dict contains: configured: - description: If true, your instance is enabled for hibernation; otherwise, it is not enabled for hibernation. + description: If RV(true), your instance is enabled for hibernation; otherwise, it is not enabled for hibernation. returned: always type: bool sample: false @@ -750,7 +750,7 @@ type: str sample: "arn:aws:iam::123456789012:instance-profile/myprofile" id: - description: The ID of the instance profile + description: The ID of the instance profile. returned: always type: str sample: JFJ397FDG400FG9FD1N diff --git a/plugins/modules/ec2_instance_info.py b/plugins/modules/ec2_instance_info.py index af12729eb72..03cb231b4ec 100644 --- a/plugins/modules/ec2_instance_info.py +++ b/plugins/modules/ec2_instance_info.py @@ -10,7 +10,7 @@ version_added: 1.0.0 short_description: Gather information about ec2 instances in AWS description: - - Gather information about ec2 instances in AWS + - Gather information about ec2 instances in AWS. author: - Michael Schuett (@michaeljs1990) - Rob White (@wimnat) @@ -32,7 +32,7 @@ type: dict minimum_uptime: description: - - Minimum running uptime in minutes of instances. For example if I(uptime) is C(60) return all instances that have run more than 60 minutes. + - Minimum running uptime in minutes of instances. For example if O(uptime) is V(60) return all instances that have run more than 60 minutes. required: false aliases: ['uptime'] type: int @@ -132,7 +132,7 @@ type: complex contains: device_name: - description: The device name exposed to the instance (for example, /dev/sdh or xvdh). + description: The device name exposed to the instance (for example, RV(/dev/sdh) or RV(xvdh)). returned: always type: str sample: /dev/sdh @@ -645,7 +645,7 @@ sample: vpc-0011223344 attributes: description: The details of the instance attribute specified on input. - returned: when include_attribute is specified + returned: when O(include_attribute) is specified type: dict sample: { diff --git a/plugins/modules/ec2_key.py b/plugins/modules/ec2_key.py index ea4d7f7e4f2..e4ace3d2c26 100644 --- a/plugins/modules/ec2_key.py +++ b/plugins/modules/ec2_key.py @@ -41,7 +41,7 @@ - Note that ED25519 keys are not supported for Windows instances, EC2 Instance Connect, and EC2 Serial Console. - By default Amazon will create an RSA key. - - Mutually exclusive with parameter I(key_material). + - Mutually exclusive with parameter O(key_material). type: str choices: - rsa @@ -50,15 +50,15 @@ file_name: description: - Name of the file where the generated private key will be saved. - - When provided, the I(key.private_key) attribute will be removed from the return value. + - When provided, the O(key.private_key) attribute will be removed from the return value. - The file is written out on the 'host' side rather than the 'controller' side. - - Ignored when I(state=absent) or I(key_material) is provided. + - Ignored when O(state=absent) or O(key_material) is provided. type: path version_added: 6.4.0 notes: - - Support for I(tags) and I(purge_tags) was added in release 2.1.0. - - For security reasons, this module should be used with B(no_log=true) and (register) functionalities - when creating new key pair without providing I(key_material). + - Support for O(tags) and O(purge_tags) was added in release 2.1.0. + - For security reasons, this module should be used with O(no_log=true) and (register) functionalities + when creating new key pair without providing O(key_material). extends_documentation_fragment: - amazon.aws.common.modules - amazon.aws.region.modules @@ -112,49 +112,49 @@ RETURN = r""" changed: - description: whether a keypair was created/deleted + description: Whether a keypair was created/deleted. returned: always type: bool sample: true msg: - description: short message describing the action taken + description: Short message describing the action taken. returned: always type: str sample: key pair created key: - description: details of the keypair (this is set to null when state is absent) + description: Details of the keypair (this is set to null when state is absent). returned: always type: complex contains: fingerprint: - description: fingerprint of the key - returned: when state is present + description: Fingerprint of the key. + returned: when O(state=present) type: str sample: 'b0:22:49:61:d9:44:9d:0c:7e:ac:8a:32:93:21:6c:e8:fb:59:62:43' name: - description: name of the keypair - returned: when state is present + description: Name of the keypair. + returned: when O(state=present) type: str sample: my_keypair id: - description: id of the keypair - returned: when state is present + description: Id of the keypair. + returned: when O(state=present) type: str sample: key-123456789abc tags: - description: a dictionary representing the tags attached to the key pair - returned: when state is present + description: A dictionary representing the tags attached to the key pair. + returned: when O(state=present) type: dict sample: '{"my_key": "my value"}' private_key: - description: private key of a newly created keypair - returned: when a new keypair is created by AWS (I(key_material) is not provided) and I(file_name) is not provided. + description: Private key of a newly created keypair. + returned: when a new keypair is created by AWS (O(key_material) is not provided) and O(file_name) is not provided. type: str sample: '-----BEGIN RSA PRIVATE KEY----- MIIEowIBAAKC... -----END RSA PRIVATE KEY-----' type: - description: type of a newly created keypair + description: Type of a newly created keypair. returned: when a new keypair is created by AWS type: str sample: rsa diff --git a/plugins/modules/ec2_security_group.py b/plugins/modules/ec2_security_group.py index 44afa7bffe5..9428dcfed2d 100644 --- a/plugins/modules/ec2_security_group.py +++ b/plugins/modules/ec2_security_group.py @@ -18,20 +18,20 @@ name: description: - Name of the security group. - - One of and only one of I(name) or I(group_id) is required. - - Required if I(state=present). + - One of and only one of O(name) or O(group_id) is required. + - Required if O(state=present). required: false type: str group_id: description: - Id of group to delete (works only with absent). - - One of and only one of I(name) or I(group_id) is required. + - One of and only one of O(name) or O(group_id) is required. required: false type: str description: description: - Description of the security group. - - Required when I(state) is C(present). + - Required when O(state) is V(present). required: false type: str vpc_id: @@ -42,7 +42,7 @@ rules: description: - List of firewall inbound rules to enforce in this group (see example). If none are supplied, - no inbound rules will be enabled. Rules list may include its own name in I(group_name). + no inbound rules will be enabled. Rules list may include its own name in O(group_name). This allows idempotent loopback additions (e.g. allow group to access itself). required: false type: list @@ -53,18 +53,18 @@ elements: raw description: - The IPv4 CIDR range traffic is coming from. - - You can specify only one of I(cidr_ip), I(cidr_ipv6), I(ip_prefix), I(group_id) + - You can specify only one of O(cidr_ip), O(cidr_ipv6), O(ip_prefix), O(group_id) and I(group_name). - - Support for passing nested lists of strings to I(cidr_ip) has been deprecated and will + - Support for passing nested lists of strings to O(cidr_ip) has been deprecated and will be removed in a release after 2024-12-01. cidr_ipv6: type: list elements: raw description: - The IPv6 CIDR range traffic is coming from. - - You can specify only one of I(cidr_ip), I(cidr_ipv6), I(ip_prefix), I(group_id) + - You can specify only one of O(cidr_ip), O(cidr_ipv6), O(ip_prefix), O(group_id) and I(group_name). - - Support for passing nested lists of strings to I(cidr_ipv6) has been deprecated and will + - Support for passing nested lists of strings to O(cidr_ipv6) has been deprecated and will be removed in a release after 2024-12-01. ip_prefix: type: list @@ -72,74 +72,74 @@ description: - The IP Prefix U(https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-prefix-lists.html) that traffic is coming from. - - You can specify only one of I(cidr_ip), I(cidr_ipv6), I(ip_prefix), I(group_id) - and I(group_name). + - You can specify only one of O(cidr_ip), O(cidr_ipv6), O(ip_prefix), O(group_id) + and O(group_name). group_id: type: list elements: str description: - The ID of the Security Group that traffic is coming from. - - You can specify only one of I(cidr_ip), I(cidr_ipv6), I(ip_prefix), I(group_id) - and I(group_name). + - You can specify only one of O(cidr_ip), O(cidr_ipv6), O(ip_prefix), O(group_id) + and O(group_name). group_name: type: list elements: str description: - Name of the Security Group that traffic is coming from. - If the Security Group doesn't exist a new Security Group will be - created with I(group_desc) as the description. - - I(group_name) can accept values of type str and list. - - You can specify only one of I(cidr_ip), I(cidr_ipv6), I(ip_prefix), I(group_id) - and I(group_name). + created with O(group_desc) as the description. + - O(group_name) can accept values of type str and list. + - You can specify only one of O(cidr_ip), O(cidr_ipv6), O(ip_prefix), O(group_id) + and O(group_name). group_desc: type: str description: - - If the I(group_name) is set and the Security Group doesn't exist a new Security Group will be - created with I(group_desc) as the description. + - If the O(group_name) is set and the Security Group doesn't exist a new Security Group will be + created with O(group_desc) as the description. proto: type: str description: - - The IP protocol name (C(tcp), C(udp), C(icmp), C(icmpv6)) or + - The IP protocol name (V(tcp), V(udp), V(icmp), V(icmpv6)) or number (U(https://en.wikipedia.org/wiki/List_of_IP_protocol_numbers)). - default: 'tcp' + default: tcp from_port: type: int description: - The start of the range of ports that traffic is going to. - - A value can be between C(0) to C(65535). - - When I(proto=icmp) a value of C(-1) indicates all ports. - - Mutually exclusive with I(icmp_code), I(icmp_type) and I(ports). + - A value can be between V(0) to V(65535). + - When O(proto=icmp) a value of V(-1) indicates all ports. + - Mutually exclusive with O(icmp_code), O(icmp_type) and O(ports). to_port: type: int description: - The end of the range of ports that traffic is going to. - - A value can be between C(0) to C(65535). - - When I(proto=icmp) a value of C(-1) indicates all ports. - - Mutually exclusive with I(icmp_code), I(icmp_type) and I(ports). + - A value can be between V(0) to V(65535). + - When O(proto=icmp) a value of V(-1) indicates all ports. + - Mutually exclusive with O(icmp_code), O(icmp_type) and O(ports). ports: type: list elements: str description: - A list of ports that traffic is going to. - - Elements of the list can be a single port (for example C(8080)), or a range of ports - specified as C(-), (for example C(1011-1023)). - - Mutually exclusive with I(icmp_code), I(icmp_type), I(from_port) and I(to_port). + - Elements of the list can be a single port (for example V(8080)), or a range of ports + specified as V(-), (for example V(1011-1023)). + - Mutually exclusive with O(icmp_code), O(icmp_type), O(from_port) and O(to_port). icmp_type: version_added: 3.3.0 type: int description: - The ICMP type of the packet. - - A value of C(-1) indicates all ICMP types. - - Requires I(proto=icmp) or I(proto=icmpv6). - - Mutually exclusive with I(ports), I(from_port) and I(to_port). + - A value of V(-1) indicates all ICMP types. + - Requires O(proto=icmp) or O(proto=icmpv6). + - Mutually exclusive witho(ports),O(from_port) and O(to_port). icmp_code: version_added: 3.3.0 type: int description: - The ICMP code of the packet. - - A value of C(-1) indicates all ICMP codes. - - Requires I(proto=icmp) or I(proto=icmpv6). - - Mutually exclusive with I(ports), I(from_port) and I(to_port). + - A value of V(-1) indicates all ICMP codes. + - Requires O(proto=icmp) or O(proto=icmpv6). + - Mutually exclusive with O(ports), O(from_port) and O(to_port). rule_desc: type: str description: A description for the rule. @@ -158,18 +158,18 @@ elements: raw description: - The IPv4 CIDR range traffic is going to. - - You can specify only one of I(cidr_ip), I(cidr_ipv6), I(ip_prefix), I(group_id) + - You can specify only one of O(cidr_ip), O(cidr_ipv6), O(ip_prefix), O(group_id) and I(group_name). - - Support for passing nested lists of strings to I(cidr_ip) has been deprecated and will + - Support for passing nested lists of strings to O(cidr_ip) has been deprecated and will be removed in a release after 2024-12-01. cidr_ipv6: type: list elements: raw description: - The IPv6 CIDR range traffic is going to. - - You can specify only one of I(cidr_ip), I(cidr_ipv6), I(ip_prefix), I(group_id) - and I(group_name). - - Support for passing nested lists of strings to I(cidr_ipv6) has been deprecated and will + - You can specify only one of O(cidr_ip), O(cidr_ipv6), O(ip_prefix), O(group_id) + and O(group_name). + - Support for passing nested lists of strings to O(cidr_ipv6) has been deprecated and will be removed in a release after 2024-12-01. ip_prefix: type: list @@ -177,73 +177,73 @@ description: - The IP Prefix U(https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-prefix-lists.html) that traffic is going to. - - You can specify only one of I(cidr_ip), I(cidr_ipv6), I(ip_prefix), I(group_id) - and I(group_name). + - You can specify only one of O(cidr_ip), O(cidr_ipv6), O(ip_prefix), O(group_id) + and O(group_name). group_id: type: list elements: str description: - The ID of the Security Group that traffic is going to. - - You can specify only one of I(cidr_ip), I(cidr_ipv6), I(ip_prefix), I(group_id) - and I(group_name). + - You can specify only one of O(cidr_ip), O(cidr_ipv6), O(ip_prefix), O(group_id) + and O(group_name). group_name: type: list elements: str description: - Name of the Security Group that traffic is going to. - If the Security Group doesn't exist a new Security Group will be - created with I(group_desc) as the description. - - You can specify only one of I(cidr_ip), I(cidr_ipv6), I(ip_prefix), I(group_id) - and I(group_name). + created with O(group_desc) as the description. + - You can specify only one of O(cidr_ip), O(cidr_ipv6), O(ip_prefix), O(group_id) + and O(group_name). group_desc: type: str description: - - If the I(group_name) is set and the Security Group doesn't exist a new Security Group will be - created with I(group_desc) as the description. + - If the O(group_name) is set and the Security Group doesn't exist a new Security Group will be + created with O(group_desc) as the description. proto: type: str description: - - The IP protocol name (C(tcp), C(udp), C(icmp), C(icmpv6)) or + - The IP protocol name (V(tcp), V(udp), V(icmp), V(icmpv6)) or number (U(https://en.wikipedia.org/wiki/List_of_IP_protocol_numbers)). default: 'tcp' from_port: type: int description: - The start of the range of ports that traffic is going to. - - A value can be between C(0) to C(65535). - - When I(proto=icmp) a value of C(-1) indicates all ports. - - Mutually exclusive with I(icmp_code), I(icmp_type) and I(ports). + - A value can be between V(0) to V(65535). + - When O(proto=icmp) a value of V(-1) indicates all ports. + - Mutually exclusive with O(icmp_code), O(icmp_type) and O(ports). to_port: type: int description: - The end of the range of ports that traffic is going to. - A value can be between C(0) to C(65535). - - When I(proto=icmp) a value of C(-1) indicates all ports. - - Mutually exclusive with I(icmp_code), I(icmp_type) and I(ports). + - When O(proto=icmp) a value of V(-1) indicates all ports. + - Mutually exclusive with O(icmp_code), O(icmp_type) and O(ports). ports: type: list elements: str description: - A list of ports that traffic is going to. - - Elements of the list can be a single port (for example C(8080)), or a range of ports - specified as C(-), (for example C(1011-1023)). - - Mutually exclusive with I(icmp_code), I(icmp_type), I(from_port) and I(to_port). + - Elements of the list can be a single port (for example V(8080)), or a range of ports + specified as V(-), (for example V(1011-1023)). + - Mutually exclusive with O(icmp_code), O(icmp_type), O(from_port) and O(to_port). icmp_type: version_added: 3.3.0 type: int description: - The ICMP type of the packet. - - A value of C(-1) indicates all ICMP types. - - Requires I(proto=icmp) or I(proto=icmpv6). - - Mutually exclusive with I(ports), I(from_port) and I(to_port). + - A value of CV(-1) indicates all ICMP types. + - Requires O(proto=icmp) or O(proto=icmpv6). + - Mutually exclusive with O(ports), O(from_port) and O(to_port). icmp_code: version_added: 3.3.0 type: int description: - The ICMP code of the packet. - - A value of C(-1) indicates all ICMP codes. - - Requires I(proto=icmp) or I(proto=icmpv6). - - Mutually exclusive with I(ports), I(from_port) and I(to_port). + - A value of V(-1) indicates all ICMP codes. + - Requires O(proto=icmp) or O(proto=icmpv6). + - Mutually exclusive with O(ports), O(from_port) and O(to_port). rule_desc: type: str description: A description for the rule. @@ -280,7 +280,7 @@ - If a rule declares a group_name and that group doesn't exist, it will be automatically created. In that case, group_desc should be provided as well. The module will refuse to create a depended-on group without a description. - - Prior to release 5.0.0 this module was called C(amazon.aws.ec2_group_info). The usage did not + - Prior to release 5.0.0 this module was called M(amazon.aws.ec2_group_info). The usage did not change. """ @@ -414,17 +414,17 @@ RETURN = r""" description: - description: Description of security group + description: Description of security group. sample: My Security Group type: str returned: on create/update group_id: - description: Security group id + description: Security group id. sample: sg-abcd1234 type: str returned: on create/update group_name: - description: Security group name + description: Security group name. sample: My Security Group type: str returned: on create/update @@ -545,19 +545,19 @@ returned: always type: str owner_id: - description: AWS Account ID of the security group + description: AWS Account ID of the security group. sample: 123456789012 type: int returned: on create/update tags: - description: Tags associated with the security group + description: Tags associated with the security group. sample: Name: My Security Group Purpose: protecting stuff type: dict returned: on create/update vpc_id: - description: ID of VPC to which the security group belongs + description: ID of VPC to which the security group belongs. sample: vpc-abcd1234 type: str returned: on create/update diff --git a/plugins/modules/ec2_security_group_info.py b/plugins/modules/ec2_security_group_info.py index fe1002f2c0b..a6474b07d6e 100644 --- a/plugins/modules/ec2_security_group_info.py +++ b/plugins/modules/ec2_security_group_info.py @@ -26,7 +26,7 @@ notes: - By default, the module will return all security groups in a region. To limit results use the appropriate filters. - - Prior to release 5.0.0 this module was called C(amazon.aws.ec2_group_info). The usage did not + - Prior to release 5.0.0 this module was called M(amazon.aws.ec2_group_info). The usage did not change. extends_documentation_fragment: @@ -108,7 +108,7 @@ elements: dict contains: from_port: - description: If the protocol is TCP or UDP, this is the start of the port range. + description: If the O(protocol) is V(TCP) or V(UDP), this is the start of the port range. type: int sample: 80 ip_protocol: @@ -146,7 +146,7 @@ returned: always type: str to_group: - description: If the protocol is TCP or UDP, this is the end of the port range. + description: If the O(protocol) is V(TCP) or V(UDP), this is the end of the port range. type: int sample: 80 user_id_group_pairs: diff --git a/plugins/modules/ec2_snapshot.py b/plugins/modules/ec2_snapshot.py index 1ca33b039b1..280e9fbbb11 100644 --- a/plugins/modules/ec2_snapshot.py +++ b/plugins/modules/ec2_snapshot.py @@ -35,7 +35,7 @@ snapshot_tags: description: - A dictionary of tags to add to the snapshot. - - If the volume has a C(Name) tag this will be automatically added to the + - If the volume has a V(Name) tag this will be automatically added to the snapshot. type: dict required: false @@ -66,28 +66,28 @@ type: str last_snapshot_min_age: description: - - If the volume's most recent snapshot has started less than I(last_snapshot_min_age) minutes ago, a new snapshot will not be created. + - If the volume's most recent snapshot has started less than O(last_snapshot_min_age) minutes ago, a new snapshot will not be created. required: false default: 0 type: int modify_create_vol_permission: description: - - If set to C(true), ec2 snapshot's createVolumePermissions can be modified. + - If set to V(true), ec2 snapshot's createVolumePermissions can be modified. required: false type: bool version_added: 6.1.0 purge_create_vol_permission: description: - Whether unspecified group names or user IDs should be removed from the snapshot createVolumePermission. - - Must set I(modify_create_vol_permission) to C(True) for when I(purge_create_vol_permission) is set to C(True). + - Must set O(modify_create_vol_permission) to V(True) for when O(purge_create_vol_permission) is set to V(True). required: False type: bool default: False version_added: 6.1.0 group_names: description: - - The group to be added or removed. The possible value is C(all). - - Mutually exclusive with I(user_ids). + - The group to be added or removed. The possible value is V(all). + - Mutually exclusive with O(user_ids). required: false type: list elements: str @@ -96,9 +96,9 @@ user_ids: description: - The account user IDs to be added or removed. - - If createVolumePermission on snapshot is currently set to Public i.e. I(group_names=all), - providing I(user_ids) will not make createVolumePermission Private unless I(create_volume_permission) is set to C(true). - - Mutually exclusive with I(group_names). + - If createVolumePermission on snapshot is currently set to Public i.e. O(group_names=all), + providing O(user_ids) will not make createVolumePermission Private unless O(create_volume_permission) is set to V(true). + - Mutually exclusive with O(group_names). required: false type: list elements: str diff --git a/plugins/modules/ec2_snapshot_info.py b/plugins/modules/ec2_snapshot_info.py index f2db12cbbc7..5c3078e884a 100644 --- a/plugins/modules/ec2_snapshot_info.py +++ b/plugins/modules/ec2_snapshot_info.py @@ -49,23 +49,23 @@ max_results: description: - The maximum number of snapshot results returned in paginated output. - - When used only a single page along with a C(next_token_id) response element will be returned. - - The remaining results of the initial request can be seen by sending another request with the returned C(next_token_id) value. - - This value can be between 5 and 1000; if I(next_token_id) is given a value larger than 1000, only 1000 results are returned. + - When used only a single page along with a O(next_token_id) response element will be returned. + - The remaining results of the initial request can be seen by sending another request with the returned O(next_token_id) value. + - This value can be between 5 and 1000; if O(next_token_id) is given a value larger than 1000, only 1000 results are returned. - If this parameter is not used, then DescribeSnapshots returns all results. - - This parameter is mutually exclusive with I(snapshot_ids). + - This parameter is mutually exclusive with O(snapshot_ids). required: False type: int next_token_id: description: - - Contains the value returned from a previous paginated request where I(max_results) was used and the results exceeded the value of that parameter. - - Pagination continues from the end of the previous results that returned the I(next_token_id) value. - - This parameter is mutually exclusive with I(snapshot_ids) + - Contains the value returned from a previous paginated request where O(max_results) was used and the results exceeded the value of that parameter. + - Pagination continues from the end of the previous results that returned the O(next_token_id) value. + - This parameter is mutually exclusive with O(snapshot_ids) required: false type: str notes: - By default, the module will return all snapshots, including public ones. To limit results to snapshots owned by - the account use the filter 'owner-id'. + the account use the filter V(owner-id). extends_documentation_fragment: - amazon.aws.region.modules @@ -206,7 +206,7 @@ - Contains the value returned from a previous paginated request where C(max_results) was used and the results exceeded the value of that parameter. - This value is null when there are no more results to return. type: str - returned: when option C(max_results) is set in input + returned: when option O(max_results) is set in input """ try: diff --git a/plugins/modules/ec2_spot_instance.py b/plugins/modules/ec2_spot_instance.py index 1bd56472409..c8851887cbc 100644 --- a/plugins/modules/ec2_spot_instance.py +++ b/plugins/modules/ec2_spot_instance.py @@ -50,7 +50,7 @@ security_groups: description: - Security group name (or list of group names) to use with the instance. - - Only supported with EC2 Classic. To launch in a VPC, use C(group_id) + - Only supported with EC2 Classic. To launch in a VPC, use O(group_id). type: list elements: str key_name: @@ -75,7 +75,7 @@ suboptions: device_name: description: - - The device name (for example, /dev/sdh or xvdh ). + - The device name (for example, /dev/sdh or xvdh). type: str virtual_name: description: @@ -84,7 +84,7 @@ ebs: description: - Parameters used to automatically set up EBS volumes when the instance is launched, - see U(https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.request_spot_instances) + see U(https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.request_spot_instances). type: dict no_device: description: @@ -103,12 +103,12 @@ arn: description: - The Amazon Resource Name (ARN) of the instance profile. - - Only one of I(arn) or I(name) may be specified. + - Only one of O(launch_specification.iam_instance_profile.arn) or I(launch_specification.iam_instance_profile.name) may be specified. type: str name: description: - The name of the instance profile. - - Only one of I(arn) or I(name) may be specified. + - Only one of O(launch_specification.iam_instance_profile.arn) or I(launch_specification.iam_instance_profile.name) may be specified. type: str image_id: description: @@ -254,8 +254,8 @@ state: description: - Whether the spot request should be created or removed. - - When I(state=present), I(launch_specification) is required. - - When I(state=absent), I(spot_instance_request_ids) is required. + - When O(state=present), O(launch_specification) is required. + - When O(state=absent), O(spot_instance_request_ids) is required. default: 'present' choices: [ 'absent', 'present' ] type: str @@ -267,7 +267,7 @@ spot_type: description: - The type of spot request. - - After being interrupted a C(persistent) spot instance will be started once there is capacity to fill the request again. + - After being interrupted a V(persistent) spot instance will be started once there is capacity to fill the request again. default: 'one-time' choices: [ "one-time", "persistent" ] type: str @@ -283,7 +283,7 @@ terminate_instances: description: - Boolean value to set whether or not to terminate instances associated to spot request. - - Can be used only when I(state=absent). + - Can be used only when O(state=absent). default: False type: bool version_added: 5.4.0 @@ -341,7 +341,7 @@ RETURN = r""" spot_request: - description: The spot instance request details after creation + description: The spot instance request details after creation. returned: when success type: dict sample: { @@ -399,7 +399,7 @@ } cancelled_spot_request: - description: The spot instance request details that has been cancelled + description: The spot instance request details that has been cancelled. returned: always type: str sample: 'Spot requests with IDs: sir-1234abcd have been cancelled' diff --git a/plugins/modules/ec2_spot_instance_info.py b/plugins/modules/ec2_spot_instance_info.py index 7dc4abce831..e1fbea8693d 100644 --- a/plugins/modules/ec2_spot_instance_info.py +++ b/plugins/modules/ec2_spot_instance_info.py @@ -62,7 +62,7 @@ RETURN = r""" spot_request: - description: The gathered information about specified spot instance requests. + description: The gathered information about specified spot instance requests. returned: when success type: list elements: dict diff --git a/plugins/modules/ec2_tag.py b/plugins/modules/ec2_tag.py index 9773325c768..efe3bae9462 100644 --- a/plugins/modules/ec2_tag.py +++ b/plugins/modules/ec2_tag.py @@ -22,7 +22,7 @@ state: description: - Whether the tags should be present or absent on the resource. - - The use of I(state=list) to interrogate the tags of an instance was + - The use of O(state=list) to interrogate the tags of an instance was deprecated in release 1.0.0 and is no longer available in release 4.0.0. The 'list' functionality has been moved to a dedicated module M(amazon.aws.ec2_tag_info). @@ -32,13 +32,13 @@ tags: description: - A dictionary of tags to add or remove from the resource. - - If the value provided for a key is not set and I(state=absent), the tag will be removed regardless of its current value. + - If the value provided for a key is not set and O(state=absent), the tag will be removed regardless of its current value. type: dict required: true purge_tags: description: - Whether unspecified tags should be removed from the resource. - - Note that when combined with I(state=absent), specified tags with non-matching values are not purged. + - Note that when combined with O(state=absent), specified tags with non-matching values are not purged. type: bool default: false @@ -99,15 +99,15 @@ 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 added_tags: - description: A dict of tags that were added to the resource + description: A dict of tags that were added to the resource. returned: If tags were added type: dict removed_tags: - description: A dict of tags that were removed from the resource + description: A dict of tags that were removed from the resource. returned: If tags were removed type: dict """ diff --git a/plugins/modules/ec2_tag_info.py b/plugins/modules/ec2_tag_info.py index 1efcd55822d..029d4e131b6 100644 --- a/plugins/modules/ec2_tag_info.py +++ b/plugins/modules/ec2_tag_info.py @@ -44,7 +44,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 """