AWS EC2

Describe EC2 instance

Describe an EC2 instance.

Inputs

Field

Type

Description

region [required]

enum

default: us-east-1

instanceId [required]

string

Outputs

Expand All

Field

Type

Description

instance [required]

object

AmiLaunchIndex

number

The AMI launch index, which can be used to find this instance in the launch group.

ImageId

string

The ID of the AMI used to launch the instance.

InstanceId

string

The ID of the instance.

InstanceType

string

The instance type.

KernelId

string

The kernel associated with this instance, if applicable.

KeyName

string

The name of the key pair, if this instance was launched with an associated key pair.

LaunchTime

date-time

The time the instance was launched.

Monitoring

object

The monitoring for the instance.

State

string

Indicates whether detailed monitoring is enabled. Otherwise, basic monitoring is enabled.

Placement

object

The location where the instance launched, if applicable.

AvailabilityZone

string

The Availability Zone of the instance. If not specified, an Availability Zone will be automatically chosen for you based on the load balancing criteria for the Region. This parameter is not supported by CreateFleet.

Affinity

string

The affinity setting for the instance on the Dedicated Host. This parameter is not supported for the ImportInstance command. This parameter is not supported by CreateFleet.

GroupName

string

The name of the placement group that the instance is in. If you specify GroupName, you can't specify GroupId.

PartitionNumber

number

The number of the partition that the instance is in. Valid only if the placement group strategy is set to partition. This parameter is not supported by CreateFleet.

HostId

string

The ID of the Dedicated Host on which the instance resides. This parameter is not supported for the ImportInstance command. This parameter is not supported by CreateFleet.

Tenancy

string

The tenancy of the instance (if the instance is running in a VPC). An instance with a tenancy of dedicated runs on single-tenant hardware. The host tenancy is not supported for the ImportInstance command. This parameter is not supported by CreateFleet. T3 instances that use the unlimited CPU credit option do not support host tenancy.

SpreadDomain

string

Reserved for future use. This parameter is not supported by CreateFleet.

HostResourceGroupArn

string

The ARN of the host resource group in which to launch the instances. If you specify a host resource group ARN, omit the Tenancy parameter or set it to host. This parameter is not supported by CreateFleet.

GroupId

string

The ID of the placement group that the instance is in. If you specify GroupId, you can't specify GroupName.

Platform

string

The value is Windows for Windows instances; otherwise blank.

PrivateDnsName

string

The private DNS hostname name assigned to the instance. This DNS hostname can only be used inside the Amazon EC2 network. This name is not available until the instance enters the running state.
[EC2-VPC] The Amazon-provided DNS server resolves Amazon-provided private DNS hostnames if you've enabled DNS resolution and DNS hostnames in your VPC. If you are not using the Amazon-provided DNS server in your VPC, your custom domain name servers must resolve the hostname as appropriate.

PrivateIpAddress

string

The private IPv4 address assigned to the instance.

ProductCodes

[object]

The product codes attached to this instance, if applicable.

ProductCodeId

string

The product code.

ProductCodeType

string

The type of product code.

PublicDnsName

string

(IPv4 only) The public DNS name assigned to the instance. This name is not available until the instance enters the running state. For EC2-VPC, this name is only available if you've enabled DNS hostnames for your VPC.

PublicIpAddress

string

The public IPv4 address, or the Carrier IP address assigned to the instance, if applicable. A Carrier IP address only applies to an instance launched in a subnet associated with a Wavelength Zone.

RamdiskId

string

The RAM disk associated with this instance, if applicable.

State

object

The current state of the instance.

Code

number

The state of the instance as a 16-bit unsigned integer. The high byte is all of the bits between 2^8 and (2^16)-1, which equals decimal values between 256 and 65,535. These numerical values are used for internal purposes and should be ignored. The low byte is all of the bits between 2^0 and (2^8)-1, which equals decimal values between 0 and 255. The valid values for instance-state-code will all be in the range of the low byte and they are:
0 : pending
16 : running
32 : shutting-down
48 : terminated
64 : stopping
80 : stopped
You can ignore the high byte value by zeroing out all of the bits above 2^8 or 256 in decimal.

Name

string

The current state of the instance.

StateTransitionReason

string

The reason for the most recent state transition. This might be an empty string.

SubnetId

string

The ID of the subnet in which the instance is running.

VpcId

string

The ID of the VPC in which the instance is running.

Architecture

string

The architecture of the image.

BlockDeviceMappings

[object]

Any block device mapping entries for the instance.

DeviceName

string

The device name (for example, /dev/sdh or xvdh).

Ebs

object

Parameters used to automatically set up EBS volumes when the instance is launched.

AttachTime

date-time

The time stamp when the attachment initiated.

DeleteOnTermination

boolean

Indicates whether the volume is deleted on instance termination.

Status

string

The attachment state.

VolumeId

string

The ID of the EBS volume.

AssociatedResource

string

The ARN of the Amazon ECS or Fargate task to which the volume is attached.

VolumeOwnerId

string

The ID of the Amazon Web Services account that owns the volume. This parameter is returned only for volumes that are attached to Fargate tasks.

ClientToken

string

The idempotency token you provided when you launched the instance, if applicable.

EbsOptimized

boolean

Indicates whether the instance is optimized for Amazon EBS I/O. This optimization provides dedicated throughput to Amazon EBS and an optimized configuration stack to provide optimal I/O performance. This optimization isn't available with all instance types. Additional usage charges apply when using an EBS Optimized instance.

EnaSupport

boolean

Specifies whether enhanced networking with ENA is enabled.

Hypervisor

string

The hypervisor type of the instance. The value xen is used for both Xen and Nitro hypervisors.

IamInstanceProfile

object

The IAM instance profile associated with the instance, if applicable.

Arn

string

The Amazon Resource Name (ARN) of the instance profile.

Id

string

The ID of the instance profile.

InstanceLifecycle

string

Indicates whether this is a Spot Instance or a Scheduled Instance.

ElasticGpuAssociations

[object]

Deprecated. Amazon Elastic Graphics reached end of life on January 8, 2024. For workloads that require graphics acceleration, we recommend that you use Amazon EC2 G4ad, G4dn, or G5 instances.

ElasticGpuId

string

The ID of the Elastic Graphics accelerator.

ElasticGpuAssociationId

string

The ID of the association.

ElasticGpuAssociationState

string

The state of the association between the instance and the Elastic Graphics accelerator.

ElasticGpuAssociationTime

string

The time the Elastic Graphics accelerator was associated with the instance.

ElasticInferenceAcceleratorAssociations

[object]

The elastic inference accelerator associated with the instance.

ElasticInferenceAcceleratorArn

string

The Amazon Resource Name (ARN) of the elastic inference accelerator.

ElasticInferenceAcceleratorAssociationId

string

The ID of the association.

ElasticInferenceAcceleratorAssociationState

string

The state of the elastic inference accelerator.

ElasticInferenceAcceleratorAssociationTime

date-time

The time at which the elastic inference accelerator is associated with an instance.

NetworkInterfaces

[object]

The network interfaces for the instance.

Association

object

The association information for an Elastic IPv4 associated with the network interface.

CarrierIp

string

The carrier IP address associated with the network interface.

CustomerOwnedIp

string

The customer-owned IP address associated with the network interface.

IpOwnerId

string

The ID of the owner of the Elastic IP address.

PublicDnsName

string

The public DNS name.

PublicIp

string

The public IP address or Elastic IP address bound to the network interface.

Attachment

object

The network interface attachment.

AttachTime

date-time

The time stamp when the attachment initiated.

AttachmentId

string

The ID of the network interface attachment.

DeleteOnTermination

boolean

Indicates whether the network interface is deleted when the instance is terminated.

DeviceIndex

number

The index of the device on the instance for the network interface attachment.

Status

string

The attachment state.

NetworkCardIndex

number

The index of the network card.

EnaSrdSpecification

object

Contains the ENA Express settings for the network interface that's attached to the instance.

EnaSrdEnabled

boolean

Indicates whether ENA Express is enabled for the network interface.

EnaSrdUdpSpecification

object

Configures ENA Express for UDP network traffic.

EnaSrdUdpEnabled

boolean

Indicates whether UDP traffic to and from the instance uses ENA Express. To specify this setting, you must first enable ENA Express.

Description

string

The description.

Groups

[object]

The security groups.

GroupName

string

The name of the security group.

GroupId

string

The ID of the security group.

Ipv6Addresses

[object]

The IPv6 addresses associated with the network interface.

Ipv6Address

string

The IPv6 address.

IsPrimaryIpv6

boolean

Determines if an IPv6 address associated with a network interface is the primary IPv6 address. When you enable an IPv6 GUA address to be a primary IPv6, the first IPv6 GUA will be made the primary IPv6 address until the instance is terminated or the network interface is detached. For more information, see RunInstances.

MacAddress

string

The MAC address.

NetworkInterfaceId

string

The ID of the network interface.

OwnerId

string

The ID of the Amazon Web Services account that created the network interface.

PrivateDnsName

string

The private DNS name.

PrivateIpAddress

string

The IPv4 address of the network interface within the subnet.

PrivateIpAddresses

[object]

The private IPv4 addresses associated with the network interface.

Association

object

The association information for an Elastic IP address for the network interface.

CarrierIp

string

The carrier IP address associated with the network interface.

CustomerOwnedIp

string

The customer-owned IP address associated with the network interface.

IpOwnerId

string

The ID of the owner of the Elastic IP address.

PublicDnsName

string

The public DNS name.

PublicIp

string

The public IP address or Elastic IP address bound to the network interface.

Primary

boolean

Indicates whether this IPv4 address is the primary private IP address of the network interface.

PrivateDnsName

string

The private IPv4 DNS name.

PrivateIpAddress

string

The private IPv4 address of the network interface.

SourceDestCheck

boolean

Indicates whether source/destination checking is enabled.

Status

string

The status of the network interface.

SubnetId

string

The ID of the subnet.

VpcId

string

The ID of the VPC.

InterfaceType

string

The type of network interface. Valid values: interface, efa, trunk.

Ipv4Prefixes

[object]

The IPv4 delegated prefixes that are assigned to the network interface.

Ipv4Prefix

string

One or more IPv4 prefixes assigned to the network interface.

Ipv6Prefixes

[object]

The IPv6 delegated prefixes that are assigned to the network interface.

Ipv6Prefix

string

One or more IPv6 prefixes assigned to the network interface.

ConnectionTrackingConfiguration

object

A security group connection tracking configuration that enables you to set the timeout for connection tracking on an Elastic network interface. For more information, see Connection tracking timeouts in the Amazon Elastic Compute Cloud User Guide.

TcpEstablishedTimeout

number

Timeout (in seconds) for idle TCP connections in an established state. Min: 60 seconds. Max: 432000 seconds (5 days). Default: 432000 seconds. Recommended: Less than 432000 seconds.

UdpStreamTimeout

number

Timeout (in seconds) for idle UDP flows classified as streams which have seen more than one request-response transaction. Min: 60 seconds. Max: 180 seconds (3 minutes). Default: 180 seconds.

UdpTimeout

number

Timeout (in seconds) for idle UDP flows that have seen traffic only in a single direction or a single request-response transaction. Min: 30 seconds. Max: 60 seconds. Default: 30 seconds.

OutpostArn

string

The Amazon Resource Name (ARN) of the Outpost.

RootDeviceName

string

The device name of the root device volume (for example, /dev/sda1).

RootDeviceType

string

The root device type used by the AMI. The AMI can use an EBS volume or an instance store volume.

SecurityGroups

[object]

The security groups for the instance.

GroupName

string

The name of the security group.

GroupId

string

The ID of the security group.

SourceDestCheck

boolean

Indicates whether source/destination checking is enabled.

SpotInstanceRequestId

string

If the request is a Spot Instance request, the ID of the request.

SriovNetSupport

string

Specifies whether enhanced networking with the Intel 82599 Virtual Function interface is enabled.

StateReason

object

The reason for the most recent state transition.

Code

string

The reason code for the state change.

Message

string

The message for the state change.
Server.InsufficientInstanceCapacity: There was insufficient capacity available to satisfy the launch request.
Server.InternalError: An internal error caused the instance to terminate during launch.
Server.ScheduledStop: The instance was stopped due to a scheduled retirement.
Server.SpotInstanceShutdown: The instance was stopped because the number of Spot requests with a maximum price equal to or higher than the Spot price exceeded available capacity or because of an increase in the Spot price.
Server.SpotInstanceTermination: The instance was terminated because the number of Spot requests with a maximum price equal to or higher than the Spot price exceeded available capacity or because of an increase in the Spot price.
Client.InstanceInitiatedShutdown: The instance was shut down using the shutdown -h command from the instance.
Client.InstanceTerminated: The instance was terminated or rebooted during AMI creation.
Client.InternalError: A client error caused the instance to terminate during launch.
Client.InvalidSnapshot.NotFound: The specified snapshot was not found.
Client.UserInitiatedHibernate: Hibernation was initiated on the instance.
Client.UserInitiatedShutdown: The instance was shut down using the Amazon EC2 API.
Client.VolumeLimitExceeded: The limit on the number of EBS volumes or total storage was exceeded. Decrease usage or request an increase in your account limits.

Tags

[object]

Any tags assigned to the instance.

Key

string

The key of the tag. Constraints: Tag keys are case-sensitive and accept a maximum of 127 Unicode characters. May not begin with aws:.

Value

string

The value of the tag.
Constraints: Tag values are case-sensitive and accept a maximum of 256 Unicode characters.

VirtualizationType

string

The virtualization type of the instance.

CpuOptions

object

The CPU options for the instance.

CoreCount

number

The number of CPU cores for the instance.

ThreadsPerCore

number

The number of threads per CPU core.

AmdSevSnp

string

Indicates whether the instance is enabled for AMD SEV-SNP. For more information, see AMD SEV-SNP.

CapacityReservationId

string

The ID of the Capacity Reservation.

CapacityReservationSpecification

object

Information about the Capacity Reservation targeting option.

CapacityReservationPreference

string

Describes the instance's Capacity Reservation preferences. Possible preferences include:
open - The instance can run in any open Capacity Reservation that has matching attributes (instance type, platform, Availability Zone).
none - The instance avoids running in a Capacity Reservation even if one is available. The instance runs in On-Demand capacity.

CapacityReservationTarget

object

Information about the targeted Capacity Reservation or Capacity Reservation group.

CapacityReservationId

string

The ID of the targeted Capacity Reservation.

CapacityReservationResourceGroupArn

string

The ARN of the targeted Capacity Reservation group.

HibernationOptions

object

Indicates whether the instance is enabled for hibernation.

Configured

boolean

If this parameter is set to true, your instance is enabled for hibernation; otherwise, it is not enabled for hibernation.

Licenses

[object]

The license configurations for the instance.

LicenseConfigurationArn

string

The Amazon Resource Name (ARN) of the license configuration.

MetadataOptions

object

The metadata options for the instance.

State

string

The state of the metadata option changes.
pending - The metadata options are being updated and the instance is not ready to process metadata traffic with the new selection.
applied - The metadata options have been successfully applied on the instance.

HttpTokens

string

The state of token usage for your instance metadata requests.
If the state is optional, you can choose to retrieve instance metadata with or without a signed token header on your request. If you retrieve the IAM role credentials without a token, the version 1.0 role credentials are returned. If you retrieve the IAM role credentials using a valid signed token, the version 2.0 role credentials are returned.
If the state is required, you must send a signed token header with any instance metadata retrieval requests. In this state, retrieving the IAM role credential always returns the version 2.0 credentials; the version 1.0 credentials are not available.
Default: optional

HttpPutResponseHopLimit

number

The desired HTTP PUT response hop limit for instance metadata requests. The larger the number, the further instance metadata requests can travel.
Default: 1
Possible values: Integers from 1 to 64

HttpEndpoint

string

Indicates whether the HTTP metadata endpoint on your instances is enabled or disabled. If the value is disabled, you cannot access your instance metadata.

HttpProtocolIpv6

string

Indicates whether the IPv6 endpoint for the instance metadata service is enabled or disabled. Default: disabled

InstanceMetadataTags

string

Indicates whether access to instance tags from the instance metadata is enabled or disabled. For more information, see Work with instance tags using the instance metadata.

EnclaveOptions

object

Indicates whether the instance is enabled for Amazon Web Services Nitro Enclaves.

Enabled

boolean

If this parameter is set to true, the instance is enabled for Amazon Web Services Nitro Enclaves; otherwise, it is not enabled for Amazon Web Services Nitro Enclaves.

BootMode

string

The boot mode of the instance. For more information, see Boot modes in the Amazon EC2 User Guide.

PlatformDetails

string

The platform details value for the instance. For more information, see AMI billing information fields in the Amazon EC2 User Guide.

UsageOperation

string

The usage operation value for the instance. For more information, see AMI billing information fields in the Amazon EC2 User Guide.

UsageOperationUpdateTime

date-time

The time that the usage operation was last updated.

PrivateDnsNameOptions

object

The options for the instance hostname.

HostnameType

string

The type of hostname to assign to an instance.

EnableResourceNameDnsARecord

boolean

Indicates whether to respond to DNS queries for instance hostnames with DNS A records.

EnableResourceNameDnsAAAARecord

boolean

Indicates whether to respond to DNS queries for instance hostnames with DNS AAAA records.

Ipv6Address

string

The IPv6 address assigned to the instance.

TpmSupport

string

If the instance is configured for NitroTPM support, the value is v2.0. For more information, see NitroTPM in the Amazon EC2 User Guide.

MaintenanceOptions

object

Provides information on the recovery and maintenance options of your instance.

AutoRecovery

string

Provides information on the current automatic recovery behavior of your instance.

CurrentInstanceBootMode

string

The boot mode that is used to boot the instance at launch or start. For more information, see Boot modes in the Amazon EC2 User Guide.

amzRequestId [required]

string