Describe Instances operation for the Amazon EC2 REST adapter

The Describe Instances operation enables you to retrieve information about instances that you own.

If you specify one or more instance IDs, the Describe Instances operation returns information for the specified instances. If you do not specify any instance IDs, the operation returns information for all relevant instances. If you specify an invalid instance ID, the operation returns a fault. If you specify an instance that you do not own, it will not be included in the results retrieved from Amazon EC2.

The following figure shows a sample <items> XML element for the Describe Instances operation.

Sample <items> XML element for the Describe Instances operation

The following table describes the elements for this adapter request.

Adapter request elements for the Describe Instances operation

Element	Definition	Required
<access-key>	Specifies the Amazon Web Services (AWS) access key You need to generate the AWS access key by going to the Security Credentials tab in the AWS console.	Conditional; You must specify the Access Key and theSecret Key together in the configuration or the adapter request. If you specify both the keys in the adapter request and in the adapter configuration, the key values in the request override the values in the configuration. If only the Access Key is specified, the adapter ignores the value.
<secret-key>	Specifies the AWS secret access key You need to generate the AWS secret access key by going to the Security Credentials tab in the AWS console.	Conditional; You must specify the Access Key and theSecret Key together in the configuration or the adapter request. If you specify both the keys in the adapter request and in the adapter configuration, the key values in the request override the values in the configuration. If only the Secret Access Key is specified, the adapter ignores the value.
<session-token>	Specifies the temporary session token generated using the AWS APIs.	Conditional; You must specify the Access Key and Secret Key as well in the configuration or the adapter request, else the <session-token> value is ignored.
<region>	Specifies the region with which you want the adapter to communicate Amazon EC2 is hosted in multiple locations world-wide. You must specify the region in which you want the adapter to perform the actions. Valid values: us-east-1 us-west-2 (default) us-west-1 eu-west-1 ap-southeast-1 ap-northeast-1 ap-southeast-2 sa-east-1	No
<operation-name>	Contains the name of the operation: describe-instances	Yes
<instance-set>	contains one or more instance IDs corresponding to the instances that you want to query for description	Yes

The following figure shows a sample adapter request for the Describe Instances operation.

Sample adapter request for the Describe Instances operation

<amazon-ec2-rest-request>
   <operation-name>describe-instances</operation-name>
   <parameters>
     <instances-set>
       <item>
         <instance-id>i-65be346c</instance-id>
       </item>
     </instances-set>
   </parameters>
</amazon-ec2-rest-request>

The following figure shows the response for the sample Describe Instances operation.

Sample adapter response for the Describe Instances operation

<amazon-ec2-rest-response>
<metadata>
   <status>success</status>
</metadata>
<DescribeInstancesResponse>
   <reservationSet>
     <item>
       <reservationId>r-b9b533b0</reservationId>
       <ownerId>246495073671</ownerId>
       <groupSet>
         <item>
           <groupId>sg-eca3addc</groupId>
           <groupName>launch-wizard-120</groupName>
         </item>
       </groupSet>
       <instancesSet>
         <item>
           <instanceId>i-65be346c</instanceId>
           <imageId>ami-ccf297fc</imageId>
           <instanceState>
             <code>16</code>
             <name>running</name>
           </instanceState>
           <privateDnsName>ip-10-237-136-102.us-west-2.compute.internal</privateDnsName>
           <dnsName>ec2-54-203-43-126.us-west-2.compute.amazonaws.com</dnsName>
           <securityGroupSet>
             <item>
               <groupId>sg-eca3addc</groupId>
               <groupName>launch-wizard-120</groupName>
             </item>
           </securityGroupSet>
           <stateReason />
           <keyName>test01</keyName>
           <amiLaunchIndex>0</amiLaunchIndex>
           <productCodes />
           <instanceType>t1.micro</instanceType>
           <launchTime>Wed Mar 26 14:41:36 IST 2014</launchTime>
           <placement>
             <availabilityZone>us-west-2b</availabilityZone>
             <groupName></groupName>
             <tenancy>default</tenancy>
           </placement>
           <kernelId>aki-fc8f11cc</kernelId>
           <ramdiskId />
           <monitoring>
             <state>disabled</state>
           </monitoring>
           <privateIpAddress>10.237.136.102</privateIpAddress>
           <ipAddress>54.203.43.126</ipAddress>
           <rootDeviceType>ebs</rootDeviceType>
           <rootDeviceName>/dev/sda1</rootDeviceName>
           <blockDeviceMapping>
             <item>
               <deviceName>/dev/sda1</deviceName>
               <ebs>
                 <volumeId>vol-3027123e</volumeId>
                 <status>attached</status>
                 <attachTime>Fri Feb 21 16:37:14 IST 2014</attachTime>
                 <deleteOnTermination>true</deleteOnTermination>
               </ebs>
             </item>
           </blockDeviceMapping>
         </item>
       </instancesSet>
     </item>
   </reservationSet>
</DescribeInstancesResponse>

Describe Instances operation for the Amazon EC2 REST adapter

On this page