From a5198172c8478bb13bc2ad360c342a944b3b63dd Mon Sep 17 00:00:00 2001 From: GomathiselviS Date: Tue, 7 May 2024 13:53:51 -0400 Subject: [PATCH] Update return block in documentation for ec2 modules (part 1) (#2072) Update return block in documentation for ec2 modules (part 1) SUMMARY Refer #1983 This PR aligns the RETURN blocks in the module documentation to accurately reflect what the module returns, ensuring consistency. Modules updated: ec2_eip_info, ec2_ami, ec2_ami_info, ec2_eni, ec2_eni_info, ec2_instance, ec2_instance_info, ec2_security_group, ec2_security_group_info ISSUE TYPE Docs Pull Request COMPONENT NAME ADDITIONAL INFORMATION Reviewed-by: Alina Buzachis Reviewed-by: Mark Chappell Reviewed-by: Mike Graves --- .../fragments/return_block_update_ec2_1.yml | 3 + plugins/modules/ec2_ami.py | 43 +++++ plugins/modules/ec2_ami_info.py | 12 +- plugins/modules/ec2_eip_info.py | 61 +++++-- plugins/modules/ec2_eni.py | 18 +- plugins/modules/ec2_eni_info.py | 2 +- plugins/modules/ec2_instance.py | 131 ++++++++++++++- plugins/modules/ec2_instance_info.py | 116 ++++++++++++- plugins/modules/ec2_security_group.py | 158 ++++++++++++++---- plugins/modules/ec2_security_group_info.py | 8 + 10 files changed, 492 insertions(+), 60 deletions(-) create mode 100644 changelogs/fragments/return_block_update_ec2_1.yml diff --git a/changelogs/fragments/return_block_update_ec2_1.yml b/changelogs/fragments/return_block_update_ec2_1.yml new file mode 100644 index 00000000000..e84796e1818 --- /dev/null +++ b/changelogs/fragments/return_block_update_ec2_1.yml @@ -0,0 +1,3 @@ +--- +trivial: + - Update return block in the module documentation ec2_eip_info, ec2_ami, ec2_ami_info, ec2_eni, ec2_eni_info, ec2_instance, ec2_instance_info, ec2_security_group, ec2_security_group_info diff --git a/plugins/modules/ec2_ami.py b/plugins/modules/ec2_ami.py index 00ead5ce5cc..ec6663146d7 100644 --- a/plugins/modules/ec2_ami.py +++ b/plugins/modules/ec2_ami.py @@ -339,6 +339,11 @@ returned: when AMI is created or already exists type: str sample: "nat-server" +enhanced_networking: + description: Specifies whether enhanced networking with ENA is enabled. + returned: when AMI is created or already exists + type: bool + sample: true hypervisor: description: Type of hypervisor. returned: when AMI is created or already exists @@ -349,11 +354,26 @@ returned: when AMI is created or already exists type: str sample: "ami-1234abcd" +image_owner_alias: + description: The owner alias ( amazon | aws-marketplace). + returned: when AMI is created or already exists + type: str + sample: "amazon" +image_type: + description: Type of image. + returned: when AMI is created or already exists + type: str + sample: "machine" is_public: description: Whether image is public. returned: when AMI is created or already exists type: bool sample: false +kernel_id: + description: The kernel associated with the image, if any. Only applicable for machine images. + returned: when AMI is created or already exists + type: str + sample: "aki-88aa75e1" launch_permission: description: Permissions allowing other accounts to access the AMI. returned: when AMI is created or already exists @@ -379,6 +399,16 @@ description: Platform of image. returned: when AMI is created or already exists type: str + sample: "Windows" +product_codes: + description: Any product codes associated with the AMI. + returned: when AMI is created or already exists + type: list + sample: [] +ramdisk_id: + description: The RAM disk associated with the image, if any. Only applicable for machine images. + returned: when AMI is created or already exists + type: str sample: null root_device_name: description: Root device name of image. @@ -390,11 +420,24 @@ returned: when AMI is created or already exists type: str sample: "ebs" +sriov_net_support: + description: Specifies whether enhanced networking with the Intel 82599 Virtual Function interface is enabled. + returned: when AMI is created or already exists + type: str + sample: "simple" state: description: State of image. returned: when AMI is created or already exists type: str sample: "available" +state_reason: + description: The reason for the state change. + returned: when AMI is created or already exists + type: dict + sample: { + 'Code': 'string', + 'Message': 'string' + } tags: description: A dictionary of tags assigned to image. returned: when AMI is created or already exists diff --git a/plugins/modules/ec2_ami_info.py b/plugins/modules/ec2_ami_info.py index 2929a0292df..906c141e1cf 100644 --- a/plugins/modules/ec2_ami_info.py +++ b/plugins/modules/ec2_ami_info.py @@ -112,7 +112,6 @@ sample: '2017-10-16T19:22:13.000Z' description: description: The description of the AMI. - returned: always type: str sample: '' ena_support: @@ -163,6 +162,11 @@ returned: always type: str sample: '123456789012' + platform_details: + description: Platform of image. + returned: always + type: str + sample: "Windows" public: description: Whether the image has public launch permissions. returned: always @@ -180,7 +184,6 @@ sample: ebs sriov_net_support: description: Whether enhanced networking is enabled. - returned: always type: str sample: simple state: @@ -192,6 +195,11 @@ description: Any tags assigned to the image. returned: always type: dict + usage_operation: + description: The operation of the Amazon EC2 instance and the billing code that is associated with the AMI. + returned: always + type: str + sample: "RunInstances" virtualization_type: description: The type of virtualization of the AMI. returned: always diff --git a/plugins/modules/ec2_eip_info.py b/plugins/modules/ec2_eip_info.py index c00dc515c84..8e775582be1 100644 --- a/plugins/modules/ec2_eip_info.py +++ b/plugins/modules/ec2_eip_info.py @@ -79,19 +79,58 @@ description: Properties of all Elastic IP addresses matching the provided filters. Each element is a dict with all the information related to an EIP. returned: on success type: list - sample: [{ - "allocation_id": "eipalloc-64de1b01", - "association_id": "eipassoc-0fe9ce90d6e983e97", - "domain": "vpc", - "instance_id": "i-01020cfeb25b0c84f", - "network_interface_id": "eni-02fdeadfd4beef9323b", - "network_interface_owner_id": "0123456789", - "private_ip_address": "10.0.0.1", - "public_ip": "54.81.104.1", - "tags": { + elements: dict + contains: + "allocation_id": + description: The ID representing the allocation of the address. + returned: always + type: str + sample: "eipalloc-64de1b01" + "association_id": + description: The ID representing the association of the address with an instance. + type: str + sample: "eipassoc-0fe9ce90d6e983e97" + "domain": + description: The network ( vpc). + type: str + returned: always + sample: "vpc" + "instance_id": + description: The ID of the instance that the address is associated with (if any). + returned: if any instance is associated + type: str + sample: "i-01020cfeb25b0c84f" + "network_border_group": + description: The name of the unique set of Availability Zones, Local Zones, or Wavelength Zones from which Amazon Web Services advertises IP addresses. + returned: if any instance is associated + type: str + sample: "us-east-1" + "network_interface_id": + description: The ID of the network interface. + returned: if any instance is associated + type: str + sample: "eni-02fdeadfd4beef9323b" + "network_interface_owner_id": + description: The ID of the network interface. + returned: if any instance is associated + type: str + sample: "0123456789" + "private_ip_address": + description: The private IP address associated with the Elastic IP address. + returned: always + type: str + sample: "10.0.0.1" + "public_ip": + description: The Elastic IP address. + returned: if any instance is associated + type: str + sample: "54.81.104.1" + "tags": + description: Any tags assigned to the Elastic IP address. + type: dict + sample: { "Name": "test-vm-54.81.104.1" } - }] """ try: diff --git a/plugins/modules/ec2_eni.py b/plugins/modules/ec2_eni.py index 604ca924a70..794ed45a958 100644 --- a/plugins/modules/ec2_eni.py +++ b/plugins/modules/ec2_eni.py @@ -217,15 +217,25 @@ returned: when state != absent type: complex contains: + attachment: + description: The network interface attachment. + type: dict + sample: { + "attach_time": "2024-04-25T20:57:20+00:00", + "attachment_id": "eni-attach-0ddce58b341a1846f", + "delete_on_termination": true, + "device_index": 0, + "instance_id": "i-032cb1cceb29250d2", + "status": "attached" + } description: description: interface description type: str sample: Firewall network interface groups: - description: list of security groups - type: list - elements: dict - sample: [ { "sg-f8a8a9da": "default" } ] + description: dict of security groups + type: dict + sample: { "sg-f8a8a9da": "default" } id: description: network interface id type: str diff --git a/plugins/modules/ec2_eni_info.py b/plugins/modules/ec2_eni_info.py index 5ef36b2581d..ca0a4bb2287 100644 --- a/plugins/modules/ec2_eni_info.py +++ b/plugins/modules/ec2_eni_info.py @@ -73,6 +73,7 @@ device_index: 1, instance_id: "i-15b8d3cadbafa1234", instance_owner_id: "123456789012", + "network_card_index": 0, status: "attached" } availability_zone: @@ -147,7 +148,6 @@ sample: [] requester_id: description: The ID of the entity that launched the ENI. - returned: always type: str sample: "AIDA12345EXAMPLE54321" requester_managed: diff --git a/plugins/modules/ec2_instance.py b/plugins/modules/ec2_instance.py index 79b333f33b1..c09cce97bea 100644 --- a/plugins/modules/ec2_instance.py +++ b/plugins/modules/ec2_instance.py @@ -673,16 +673,67 @@ returned: always type: str sample: vol-12345678 + capacity_reservation_specification: + description: Information about the Capacity Reservation targeting option. + type: complex + contains: + capacity_reservation_preference: + description: Describes the Capacity Reservation preferences. + type: str + sample: open client_token: description: The idempotency token you provided when you launched the instance, if applicable. returned: always type: str sample: mytoken + cpu_options: + description: The CPU options for the instance. + type: complex + contains: + core_count: + description: The number of CPU cores for the instance. + type: int + sample: 1 + threads_per_core: + description: The number of threads per CPU core. + type: int + sample: 2 + amd_sev_snp: + description: Indicates whether the instance is enabled for AMD SEV-SNP. + type: str + sample: enabled + current_instance_boot_mode: + description: The boot mode that is used to boot the instance at launch or start. + type: str + sample: legacy-bios ebs_optimized: description: Indicates whether the instance is optimized for EBS I/O. returned: always type: bool sample: false + ena_support: + description: Specifies whether enhanced networking with ENA is enabled. + returned: always + type: bool + sample: true + enclave_options: + description: Indicates whether the instance is enabled for Amazon Web Services Nitro Enclaves. + type: dict + contains: + enabled: + description: If this parameter is set to true, the instance is enabled for Amazon Web Services Nitro Enclaves. + returned: always + type: bool + sample: false + hibernation_options: + description: Indicates whether the instance is enabled for hibernation. + type: dict + contains: + configured: + description: If true, your instance is enabled for hibernation; otherwise, it is not enabled for hibernation. + returned: always + type: bool + sample: false hypervisor: description: The hypervisor type of the instance. returned: always @@ -739,6 +790,35 @@ returned: always type: str sample: arn:aws:license-manager:us-east-1:123456789012:license-configuration:lic-0123456789 + metadata_options: + description: The metadata options for the instance. + returned: always + type: complex + contains: + http_endpoint: + description: Indicates whether the HTTP metadata endpoint on your instances is enabled or disabled. + type: str + sample: enabled + http_protocol_ipv6: + description: Indicates whether the IPv6 endpoint for the instance metadata service is enabled or disabled. + type: str + sample: disabled + http_put_response_hop_limit: + description: The maximum number of hops that the metadata token can travel. + type: int + sample: 1 + http_tokens: + description: Indicates whether IMDSv2 is required. + type: str + sample: optional + instance_metadata_tags: + description: Indicates whether access to instance tags from the instance metadata is enabled or disabled. + type: str + sample: disabled + state: + description: The state of the metadata option changes. + type: str + sample: applied monitoring: description: The monitoring for the instance. returned: always @@ -752,7 +832,8 @@ network_interfaces: description: One or more network interfaces for the instance. returned: always - type: complex + type: list + elements: dict contains: association: description: The association information for an Elastic IPv4 associated with the network interface. @@ -799,6 +880,11 @@ returned: always type: int sample: 0 + network_card_index: + description: The index of the network card. + returned: always + type: int + sample: 0 status: description: The attachment state. returned: always @@ -825,6 +911,11 @@ returned: always type: str sample: mygroup + interface_type: + description: The type of network interface. + returned: always + type: str + sample: interface ipv6_addresses: description: One or more IPv6 addresses associated with the network interface. returned: always @@ -851,6 +942,11 @@ returned: always type: str sample: 01234567890 + private_dns_name: + description: The private DNS hostname name assigned to the instance. + type: str + returned: always + sample: ip-10-1-0-156.ec2.internal private_ip_address: description: The IPv4 address of the network interface within the subnet. returned: always @@ -864,7 +960,6 @@ contains: association: description: The association information for an Elastic IP address (IPv4) associated with the network interface. - returned: always type: complex contains: ip_owner_id: @@ -887,6 +982,11 @@ returned: always type: bool sample: true + private_dns_name: + description: The private DNS hostname name assigned to the instance. + type: str + returned: always + sample: ip-10-1-0-156.ec2.internal private_ip_address: description: The private IPv4 address of the network interface. returned: always @@ -928,7 +1028,6 @@ type: str group_id: description: The ID of the placement group the instance is in (for cluster compute instances). - returned: always type: str sample: "pg-01234566" group_name: @@ -938,16 +1037,13 @@ sample: "my-placement-group" host_id: description: The ID of the Dedicated Host on which the instance resides. - returned: always type: str host_resource_group_arn: description: The ARN of the host resource group in which the instance is in. - returned: always type: str sample: "arn:aws:resource-groups:us-east-1:123456789012:group/MyResourceGroup" partition_number: description: The number of the partition the instance is in. - returned: always type: int sample: 1 tenancy: @@ -961,11 +1057,32 @@ type: str version_added: 7.1.0 sample: + platform_details: + description: The platform details value for the instance. + returned: always + type: str + sample: Linux/UNIX private_dns_name: description: The private DNS name. returned: always type: str sample: ip-10-0-0-1.ap-southeast-2.compute.internal + private_dns_name_options: + description: The options for the instance hostname. + type: dict + contains: + enable_resource_name_dns_a_record: + description: Indicates whether to respond to DNS queries for instance hostnames with DNS A records. + type: bool + sample: false + enable_resource_name_dns_aaaa_record: + description: Indicates whether to respond to DNS queries for instance hostnames with DNS AAAA records. + type: bool + sample: false + hostname_type: + description: The type of hostname to assign to an instance. + type: str + sample: ip-name private_ip_address: description: The IPv4 address of the network interface within the subnet. returned: always @@ -1023,7 +1140,7 @@ returned: always type: str sample: my-security-group - network.source_dest_check: + source_dest_check: description: Indicates whether source/destination checking is enabled. returned: always type: bool diff --git a/plugins/modules/ec2_instance_info.py b/plugins/modules/ec2_instance_info.py index 1caea9365c4..af12729eb72 100644 --- a/plugins/modules/ec2_instance_info.py +++ b/plugins/modules/ec2_instance_info.py @@ -161,6 +161,14 @@ returned: always type: str sample: vol-12345678 + capacity_reservation_specification: + description: Information about the Capacity Reservation targeting option. + type: complex + contains: + capacity_reservation_preference: + description: Describes the Capacity Reservation preferences. + type: str + sample: open cpu_options: description: The CPU options set for the instance. returned: always @@ -181,11 +189,38 @@ returned: always type: str sample: mytoken + current_instance_boot_mode: + description: The boot mode that is used to boot the instance at launch or start. + type: str + sample: legacy-bios ebs_optimized: description: Indicates whether the instance is optimized for EBS I/O. returned: always type: bool sample: false + ena_support: + description: Specifies whether enhanced networking with ENA is enabled. + returned: always + type: bool + sample: true + enclave_options: + description: Indicates whether the instance is enabled for Amazon Web Services Nitro Enclaves. + type: dict + contains: + enabled: + description: If this parameter is set to true, the instance is enabled for Amazon Web Services Nitro Enclaves. + returned: always + type: bool + sample: false + hibernation_options: + description: Indicates whether the instance is enabled for hibernation. + type: dict + contains: + configured: + description: If true, your instance is enabled for hibernation; otherwise, it is not enabled for hibernation. + returned: always + type: bool + sample: false hypervisor: description: The hypervisor type of the instance. returned: always @@ -193,7 +228,6 @@ sample: xen iam_instance_profile: description: The IAM instance profile associated with the instance, if applicable. - returned: always type: complex contains: arn: @@ -231,6 +265,44 @@ returned: always type: str sample: "2017-03-23T22:51:24+00:00" + maintenance_options: + description: Provides information on the recovery and maintenance options of your instance. + returned: always + type: dict + contains: + auto_recovery: + description: Provides information on the current automatic recovery behavior of your instance. + type: str + sample: default + metadata_options: + description: The metadata options for the instance. + returned: always + type: complex + contains: + http_endpoint: + description: Indicates whether the HTTP metadata endpoint on your instances is enabled or disabled. + type: str + sample: enabled + http_protocol_ipv6: + description: Indicates whether the IPv6 endpoint for the instance metadata service is enabled or disabled. + type: str + sample: disabled + http_put_response_hop_limit: + description: The maximum number of hops that the metadata token can travel. + type: int + sample: 1 + http_tokens: + description: Indicates whether IMDSv2 is required. + type: str + sample: optional + instance_metadata_tags: + description: Indicates whether access to instance tags from the instance metadata is enabled or disabled. + type: str + sample: disabled + state: + description: The state of the metadata option changes. + type: str + sample: applied monitoring: description: The monitoring for the instance. returned: always @@ -291,6 +363,11 @@ returned: always type: int sample: 0 + network_card_index: + description: The index of the network card. + returned: always + type: int + sample: 0 status: description: The attachment state. returned: always @@ -317,6 +394,11 @@ returned: always type: str sample: mygroup + interface_type: + description: The type of network interface. + returned: always + type: str + sample: interface ipv6_addresses: description: One or more IPv6 addresses associated with the network interface. returned: always @@ -343,6 +425,11 @@ returned: always type: str sample: 01234567890 + private_dns_name: + description: The private DNS hostname name assigned to the instance. + type: str + returned: always + sample: ip-10-1-0-156.ec2.internal private_ip_address: description: The IPv4 address of the network interface within the subnet. returned: always @@ -356,7 +443,6 @@ contains: association: description: The association information for an Elastic IP address (IPv4) associated with the network interface. - returned: always type: complex contains: ip_owner_id: @@ -379,6 +465,11 @@ returned: always type: bool sample: true + private_dns_name: + description: The private DNS hostname name assigned to the instance. + type: str + returned: always + sample: ip-10-1-0-156.ec2.internal private_ip_address: description: The private IPv4 address of the network interface. returned: always @@ -424,11 +515,32 @@ returned: always type: str sample: default + platform_details: + description: The platform details value for the instance. + returned: always + type: str + sample: Linux/UNIX private_dns_name: description: The private DNS name. returned: always type: str sample: ip-10-0-0-1.ap-southeast-2.compute.internal + private_dns_name_options: + description: The options for the instance hostname. + type: dict + contains: + enable_resource_name_dns_a_record: + description: Indicates whether to respond to DNS queries for instance hostnames with DNS A records. + type: bool + sample: false + enable_resource_name_dns_aaaa_record: + description: Indicates whether to respond to DNS queries for instance hostnames with DNS AAAA records. + type: bool + sample: false + hostname_type: + description: The type of hostname to assign to an instance. + type: str + sample: ip-name private_ip_address: description: The IPv4 address of the network interface within the subnet. returned: always diff --git a/plugins/modules/ec2_security_group.py b/plugins/modules/ec2_security_group.py index ab910c6061e..44afa7bffe5 100644 --- a/plugins/modules/ec2_security_group.py +++ b/plugins/modules/ec2_security_group.py @@ -413,8 +413,8 @@ """ RETURN = r""" -group_name: - description: Security group name +description: + description: Description of security group sample: My Security Group type: str returned: on create/update @@ -423,11 +423,132 @@ sample: sg-abcd1234 type: str returned: on create/update -description: - description: Description of security group +group_name: + description: Security group name sample: My Security Group type: str returned: on create/update +ip_permissions: + description: The inbound rules associated with the security group. + returned: always + type: list + elements: dict + contains: + from_port: + description: If the protocol is TCP or UDP, this is the start of the port range. + type: int + sample: 80 + ip_protocol: + description: The IP protocol name or number. + returned: always + type: str + ip_ranges: + description: The IPv4 ranges. + returned: always + type: list + elements: dict + contains: + cidr_ip: + description: The IPv4 CIDR range. + returned: always + type: str + ipv6_ranges: + description: The IPv6 ranges. + returned: always + type: list + elements: dict + contains: + cidr_ipv6: + description: The IPv6 CIDR range. + returned: always + type: str + prefix_list_ids: + description: The prefix list IDs. + returned: always + type: list + elements: dict + contains: + prefix_list_id: + description: The ID of the prefix. + returned: always + type: str + to_group: + description: If the protocol is TCP or UDP, this is the end of the port range. + type: int + sample: 80 + user_id_group_pairs: + description: The security group and AWS account ID pairs. + returned: always + type: list + elements: dict + contains: + group_id: + description: The security group ID of the pair. + returned: always + type: str + user_id: + description: The user ID of the pair. + returned: always + type: str +ip_permissions_egress: + description: The outbound rules associated with the security group. + returned: always + type: list + elements: dict + contains: + ip_protocol: + description: The IP protocol name or number. + returned: always + type: str + ip_ranges: + description: The IPv4 ranges. + returned: always + type: list + elements: dict + contains: + cidr_ip: + description: The IPv4 CIDR range. + returned: always + type: str + ipv6_ranges: + description: The IPv6 ranges. + returned: always + type: list + elements: dict + contains: + cidr_ipv6: + description: The IPv6 CIDR range. + returned: always + type: str + prefix_list_ids: + description: The prefix list IDs. + returned: always + type: list + elements: dict + contains: + prefix_list_id: + description: The ID of the prefix. + returned: always + type: str + user_id_group_pairs: + description: The security group and AWS account ID pairs. + returned: always + type: list + elements: dict + contains: + group_id: + description: The security group ID of the pair. + returned: always + type: str + user_id: + description: The user ID of the pair. + returned: always + type: str +owner_id: + description: AWS Account ID of the security group + sample: 123456789012 + type: int + returned: on create/update tags: description: Tags associated with the security group sample: @@ -440,35 +561,6 @@ sample: vpc-abcd1234 type: str returned: on create/update -ip_permissions: - description: Inbound rules associated with the security group. - sample: - - from_port: 8182 - ip_protocol: tcp - ip_ranges: - - cidr_ip: "198.51.100.1/32" - ipv6_ranges: [] - prefix_list_ids: [] - to_port: 8182 - user_id_group_pairs: [] - type: list - returned: on create/update -ip_permissions_egress: - description: Outbound rules associated with the security group. - sample: - - ip_protocol: -1 - ip_ranges: - - cidr_ip: "0.0.0.0/0" - ipv6_ranges: [] - prefix_list_ids: [] - user_id_group_pairs: [] - type: list - returned: on create/update -owner_id: - description: AWS Account ID of the security group - sample: 123456789012 - type: int - returned: on create/update """ import itertools diff --git a/plugins/modules/ec2_security_group_info.py b/plugins/modules/ec2_security_group_info.py index 8b7a04ba14c..fe1002f2c0b 100644 --- a/plugins/modules/ec2_security_group_info.py +++ b/plugins/modules/ec2_security_group_info.py @@ -107,6 +107,10 @@ type: list elements: dict contains: + from_port: + description: If the protocol is TCP or UDP, this is the start of the port range. + type: int + sample: 80 ip_protocol: description: The IP protocol name or number. returned: always @@ -141,6 +145,10 @@ description: The ID of the prefix. returned: always type: str + to_group: + description: If the protocol is TCP or UDP, this is the end of the port range. + type: int + sample: 80 user_id_group_pairs: description: The security group and AWS account ID pairs. returned: always