         | Did this page help you? Yes No Tell us about it... |
ec2-describe-instances
Description
Returns information about instances that you own.
If you specify one or more instance IDs, Amazon EC2 returns information for those instances. If you do not specify instance IDs, Amazon EC2 returns information for all relevant instances. If you specify an invalid instance ID, an error is returned. If you specify an instance that you do not own, it will not be included in the returned results.
Recently terminated instances might appear in the returned results.This interval is usually less than one hour.
You can filter the results to return information only about instances that match criteria you specify. For example, you could get information about only instances launched with a certain key pair. You can specify multiple values for a filter (e.g., the instance was launched with either key pair A or key pair B). An instance must match at least one of the specified values for it to be included in the results.
You can specify multiple filters (e.g., the instance was launched with a certain key pair and uses an Amazon EBS volume as the root device). An instance must match all the filters for it to be included in the results. If there's no match, no special message is returned; the response is simply empty.
You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\.
The following table shows the available filters.
| Filter Name | Description |
|---|---|
|
|
Instance architecture. Type: String Valid Values: |
|
|
Instance's Availability Zone. Type: String |
|
|
Attach time for an Amazon EBS volume mapped to the instance, e.g., 2010-09-15T17:15:20.000Z Type: xsd:dateTime |
|
|
Whether the Amazon EBS volume is deleted on instance termination. Type: Boolean |
|
|
Device name (e.g., /dev/sdh) for an Amazon EBS volume mapped to the instance. Type: String |
|
|
Status for an Amazon EBS volume mapped to the instance. Type: String Valid Values: |
|
|
ID for an Amazon EBS volume mapped to the instance. Type: String |
|
|
Idempotency token you provided when you launched the instance. Type: String |
|
|
Public DNS name of the instance. Type: String |
|
|
ID of a EC2 security group the instance is in. This filter does not work for VPC security groups (instead, use Type: String |
|
|
Name of a EC2 security group the instance is in. This filter does not work for VPC security groups (instead, use Type: String |
|
|
ID of the image used to launch the instance. Type: String |
|
|
ID of the instance. Type: String |
|
|
Whether this is a Spot Instance. Type: String Valid Values: |
|
|
Code identifying the instance's state. A 16-bit unsigned integer. The high byte is an opaque internal value and should be ignored. The low byte is set based on the state represented Type: Integer Valid Values: |
|
|
Instance's state. Type: String Valid Values: |
|
|
Type of instance (e.g., m1.small). Type: String |
|
|
ID of a VPC security group the instance is in. This filter does not work for EC2 security groups (instead, use Type: String |
|
|
Name of a VPC security group the instance is in. This filter does not work for EC2 security groups (instead, use Type: String |
|
|
Public IP address of the instance. Type: String |
|
|
Kernel ID. Type: String |
|
|
Name of the key pair used when the instance was launched. Type: String |
|
|
When launching multiple instances at once, this is the index for the instance in the launch group (e.g., 0, 1, 2, etc.). Type: String |
|
|
Time instance was launched, e.g., 2010-08-07T11:54:42.000Z. Type: xsd:dateTime |
|
|
Whether monitoring is enabled for the instance. Type: String Valid Values: |
|
|
AWS account ID of the instance owner. Type: String |
|
|
Name of the placement group the instance is in. Type: String |
|
|
Use Type: String Valid Value: |
|
|
Private DNS name of the instance. Type: String |
|
|
Private IP address of the instance. Type: String |
|
|
Product code associated with the AMI used to launch the instance. Type: String |
|
|
RAM disk ID. Type: String |
|
|
Reason for the instance's current state (e.g., shows "User Initiated [date]" when you stop or terminate the instance). Similar to the state-reason-code filter. Type: String |
|
|
ID of the entity that launched the instance on your behalf (e.g., AWS Management Console, Auto Scaling, etc.) Type: String |
|
|
ID of the instance's reservation. A reservation ID is created any time you launch an instance. A reservation ID has a one-to-one relationship with an instance launch request, but can be associated with more than one instance if you launch multiple instances using the same launch request. For example, if you launch one instance, you’ll get one reservation ID. If you launch ten instances using the same launch request, you’ll also get one reservation ID. Type: String |
|
|
Root device name of the instance (e.g., /dev/sda1). Type: String |
|
|
Root device type the instance uses. Type: String Valid Values: |
|
|
Whether the instance performs source/destination checking. A value of Type: Boolean |
|
|
ID of the Spot Instance request. Type: String |
|
|
Reason code for the state change. Type: String |
|
|
Message for the state change. Type: String |
|
|
ID of the subnet the instance is in (if using Amazon Virtual Private Cloud). Type: String |
|
|
Key of a tag assigned to the resource. This filter is independent of the For more information about tags, go to Using Tags in the Amazon Elastic Compute Cloud User Guide. Type: String |
|
|
Value of a tag assigned to the resource. This filter is independent of the Type: String |
|
|
Filters the results based on a specific tag/value combination. Example: To list just the resources assigned tag Purpose=X, then specify:
Example: To list just resources assigned tag Purpose=X OR Purpose=Y, then specify:
|
|
|
Virtualization type of the instance. Type: String Valid Values: |
|
|
ID of the VPC the instance is in (if using Amazon Virtual Private Cloud). Type: String |
|
|
Hypervisor type of the instance. Type: String Valid Values: |
The short version of this command is ec2din.
Syntax
ec2-describe-instances [
instance_id ...]
[[--filter name=value] ...]
Options
| Name | Description | Required |
|---|---|---|
|
|
Instance IDs to describe. Type: String Default: Returns all instances, or only those otherwise specified. Example: i-15a4417c |
No |
|
|
A filter for limiting the results. See the preceding table for a list of allowed filter names and values. If you're using the command line tools on a Windows system, you might need to use quotation marks (i.e., "name=value"). Type: String Default: Describes all instances you own or those you specify by ID. Example: --filter "tag-key=Production" |
No |
Common Options
| Option | Description |
|---|---|
|
|
Overrides the Region specified in the Default: The Example: |
|
|
Default: The Example: |
|
|
The private key to use when constructing requests to Amazon EC2. Default: The value of the Example: |
|
|
The X.509 certificate to use when constructing requests to Amazon EC2. Default: The value of the Example: |
|
|
Specifies a connection timeout (in seconds). Example: --connection-timeout 30 |
|
|
Specifies a request timeout (in seconds). Example: --request-timeout 45 |
|
|
Displays verbose output by showing the SOAP request and response on the command line. This is particularly useful if you are building tools to talk directly to our SOAP API. |
|
|
Displays column headers in the output. |
|
|
Shows empty columns as |
|
|
Do not display tags for tagged resources. |
|
|
Prints internal debugging information. This is useful to assist us when troubleshooting problems. |
|
|
Displays Help. |
|
|
If Example: |
Output
The command returns a table that contains the following information:
Output type identifier ("RESERVATION")
Reservation ID
AWS account ID
Name of each security group the instance is in (for instances not running in a VPC)
Output type identifier ("INSTANCE")
Instance ID for each running instance
AMI ID of the image on which the instance is based
Public DNS name associated with the instance. This is only present for instances in the running state.
Private DNS name associated with the instance. This is only present for instances in the running state.
Instance state
Key name. If a key was associated with the instance at launch, its name will appear.
AMI launch index
Product codes attached to the instance
Instance type
Instance launch time
Availability Zone
Kernel ID
RAM disk ID
Monitoring state
Public IP address
Private IP address
The tenancy of the instance (if the instance is running within a VPC). An instance with a tenancy of dedicated runs on single-tenant hardware.
Subnet ID (if the instance is running in a VPC)
VPC ID (if the instance is running in a VPC)
Type of root device (ebs or instance-store)
Placement group the cluster instance is in
Virtualization type (paravirtual or hvm)
IDs of each security group the instance is in (for instances running in a VPC)
Any tags assigned to the instance
Hypervisor type (xen or ovm)
BLOCKDEVICE identifier for each Amazon EBS volume the instance is using, along with the device name, the volume ID, and the timestamp
Amazon EC2 command line tools display errors on stderr.
Examples
Example Request
This example describes the current state of the instances owned by your AWS account.
PROMPT> ec2-describe-instances
RESERVATION r-705d5818 999988887777 default
INSTANCE i-53cb5b38 ami-b232d0db ec2-184-73-10-99.compute-1.amazonaws.com domU-12-31-39-00-A5-11.compute-1.internal running 0 m1.small 2010-04-07T12:49:28+0000 us-east-1a aki-94c527fd ari-96c527ff monitoring-disabled 184.73.10.99 10.254.170.223 ebs paravirtual xen
BLOCKDEVICE /dev/sda1 vol-a36bc4ca 2010-04-07T12:28:01.000Z
BLOCKDEVICE /dev/sdb vol-a16bc4c8 2010-04-07T12:28:01.000Z
RESERVATION r-705d5818 999988887777 default
INSTANCE i-39c85852 ami-b232d0db terminated gsg-keypair 0 m1.small 2010-04-07T12:21:21+0000 us-east-1a aki-94c527fd ari-96c527ff monitoring-disabled ebs paravirtual xen
RESERVATION r-9284a1fa 999988887777 default
INSTANCE i-996fc0f2 ami-3c47a355 ec2-184-73-195-182.compute-1.amazonaws.com domU-12-31-39-09-25-62.compute-1.internal running keypair 0 m1.small 2010-03-17T13:17:41+0000 us-east-1a aki-a71cf9ce ari-a51cf9cc monitoring-disabled 184.73.195.182 10.210.42.144 instance-store paravirtual xen
Example Request
This example filters the results to display only the m1.small or m1.large instances that have an Amazon EBS volume that is both attached and set to delete on termination.
PROMPT> ec2-describe-instances --filter "instance-type=m1.small" --filter "instance-type=m1.large" --filter "block-device-mapping.status=attached" --filter "block-device-mapping.delete-on-termination=true"
RESERVATION r-bc7e30d7 999988887777 default
INSTANCE i-c7cd56ad ami-b232d0db ec2-72-44-52-124.compute-1.amazonaws.com domU-12-31-39-01-76-06.compute-1.internal running GSG_Keypair 0 m1.small 2010-08-17T01:15:16+0000 us-east-1b aki-94c527fd ari-96c527ff monitoring-disabled 72.44.52.124 10.255.121.240 ebs paravirtual xen
BLOCKDEVICE /dev/sda1 vol-a482c1cd 2010-08-17T01:15:26.000Z
