Run Instances operation

The Run Instances operation enables you to launch a specified number of instances of an AMI for which you have permissions.

If Amazon EC2 cannot launch the specified minimum number of AMIs, no instances are launched. If there is insufficient capacity to launch the specified maximum number of AMIs, Amazon EC2 launches the minimum number of instances for each AMI and later allocates the remaining available instances. 

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

Sample <items> XML element for the Run Instances operations

<items>
   <item>
       <parameters>
           <image-id></image-id>
           <min-count></min-count>
           <max-count></max-count>
           <!--Optional:-->
           <key-name></key-name>
           <group-set>
               <!--Zero or more repetition-->
               <item>
                   <group-id></group-id>
               </item>
           </group-set>
           <!--Optional:-->
           <additional-info></additional-info>
           <!--Optional:-->
           <user-data>
               <!--Optional:-->
               <data></data>
           </user-data>
           <!--Optional:-->
           <instance-type></instance-type>
           <!--Optional:-->
           <placement>
               <!--Optional:-->
               <availability-zone></availability-zone>
           </placement>
           <!--Optional:-->
           <kernel-id></kernel-id>
           <!--Optional:-->
           <ramdisk-id></ramdisk-id>
           <!--Optional: -->
           <block-device-mapping>
               <!--Zero or more repetitions:-->
               <item>
                   <device-name></device-name>
                   <virtual-name></virtual-name>
                   <ebs>
                       <!--Optional:-->
                       <snapshot-id></snapshot-id>
                       <!--Optional:-->
                       <volume-size></volume-size>
                       <!--Optional:-->
                       <delete-on-termination></delete-on-termination>
                   </ebs>
                   <no-device/>
               </item>
           </block-device-mapping>
           <!--Optional:-->
           <monitoring>
               <!--Optional:-->
               <enabled></enabled>
           </monitoring>
           <!--Optional:-->
           <subnet-id></subnet-id>
           <!--Optional:-->
           <instance-initiated-shutdown-behavior/>
           <private-ip-address>10.79.250.101</private-ip-address>
       </parameters>
   </item>
</items>

The following table describes the elements for this adapter request. 

Adapter request elements for the Run Instances operation

Element

Definition

Required

<wsdl-location>

Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2

Examples:

Conditional:

  • Required if not specified in the request
  • If specified in the configuration and request, the value in the request overrides the value in the configuration
<endpoint-address>

Specifies the web service endpoint for the adapter to use while performing operations on Amazon EC2 instances across different regions
Default value: US East region: http://us-east-1.ec2.amazonaws.com/

No

<signature-properties>

Specifies the mode for signing the adapter request

Conditional:

  • Required if not specified in the configuration
  • If <signature-properties mode = "key-files">, requires <private-key-file>
     and <certificate-file>
  • If <signature-properties mode = "key-data">, requires <private-key-data> and <certificate-data>
<operation-name>

Contains the name of the operation: run-instances

Yes

<image-id>

Specifies the unique ID for the AMI

Yes

<min-count>

Specifies the minimum number of instances to launch
If Amazon EC2 cannot launch the value specified in the <min-count> element, no instances are launched.
Valid values: Any value between 1 and the maximum number of instances allowed for your Amazon EC2 account
Default value: 20

Yes

<max-count>

Specifies the maximum number of instances to launch
If Amazon EC2 cannot launch the value specified in the <max-count> element, the largest possible number greater than that specified in the <min-count> element is launched.
Valid values: Any value between 1 and the maximum number of instances allowed for your Amazon EC2 account
Default value: 20

Yes

<key-name>

Specifies the name of the key pair

No

<group-set>

Specifies the security group or groups

No

<additional-info>

Specifies additional information for the instance or instances

No

<user-data>

Contains the user data to be made available for the instance

No

<instance-type>

Failed to execute the [panel] macro.

Specifies the type of the instance
Valid values are:

  • m1.small (default)
  • m1.large
  • m1.xlarge
  • c1.medium
  • c1.xlarge
  • m2.2xlarge
  • m2.4xlarge

No

<availability-zone>

Specifies the placement constraints or availability zones for launching the required instances
For example, us-east-1a is a sample value for the availability zone element.

No

<kernel-id>

Specifies the Kernel ID with which to launch the instance

No

<block-device-mapping>

Specifies how the block devices are exposed to the instance
Each mapping is comprised of a virtual-name and a device-name.
The <block-device-mapping> element has the following child elements:

  • <device-name>
  • <virtual-name>
  • <ebs>
  • <snapshot-id>
  • <volume-size>
  • <delete-on-termination>
  • <no-device>

No

<device-name>

Contains the device name (For example, /dev/sdh)

No

<virtual-name>

virtual-name: Contains the virtual device name

No

<ebs>

Specifies the parameters used to automatically setup Amazon EBS volumes when the instance is launched

No

<snapshot-id>

Specifies the ID for the snapshot of the Amazon EBS volume

No

<volume-size>

Specifies the size of the Amazon EBS volume

No

<delete-on-termination>

Specifies whether the Amazon EBS volume must be deleted when the instances is terminated

No

<no-device>

Specifies whether the device name is suppressed while launching the instance

No

<monitoring>

Specifies whether to enable monitoring for the instance
Valid values: true, false

No

<subnet-id>

Specifies the subnet ID for the Amazon Virtual Private Cloud within which to launch the instance or instances

No

<instance-initiated-shutdown-behavior>

Specifies whether the Amazon EBS volumes used by the instance are terminated when the instance is shut down

No

<private-ip-address>

Specifies the private IP address in a virtual private cloud (VPC instance)

No

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

Sample adapter request for the Run Instances operation

<amazon-ec2-request>
   <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location>
   <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address>
   <signature-properties mode = "key-files">
       <private-key-file>C:\Security\
pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file>
       <certificate-file>C:\Security\
cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file>
   </signature-properties>
   <operation-name>run-instances</operation-name>
   <parameters>
       <image-id>ami-b232d0db</image-id>
       <min-count>1</min-count>
       <max-count>1</max-count>
       <!--Optional:-->
       <key-name>testkeys</key-name>
       <group-set>
           <!--Zero or more repetition-->
           <item>
               <group-id>testsec</group-id>
           </item>
       </group-set>
       <!--Optional:-->
       <additional-info>Test additional data</additional-info>
       <!--Optional:-->
       <user-data>
           <!--Optional:-->
           <data>Test Data</data>
       </user-data>
       <instance-type>m1.small</instance-type>
       <!--Optional:-->
       <placement>
           <!--Optional:-->
           <availability-zone>us-east-1a</availability-zone>
       </placement>
       <!--Optional:-->
       <monitoring>
           <!--Optional:-->
           <enabled>false</enabled>
       </monitoring>
   </parameters>
</amazon-ec2-request>

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

Sample adapter response for the Run Instances operation

<amazon-ec2-response>
   <metadata>
       <status>success</status>
   </metadata>
   <RunInstancesResponse>
       <requestId>2a6cc23d-d1ac-4dbf-bccc-9bf9d16be7e2</requestId>
       <reservationId>r-094ccf61</reservationId>
       <ownerId>622872856407</ownerId>
       <groupSet>
           <item>
               <groupId>testlsec</groupId>
           </item>
       </groupSet>
       <instancesSet>
           <item>
               <instanceId>i-bd90bfd5</instanceId>
               <imageId>ami-b232d0db</imageId>
               <instanceState>
                   <code>0</code>
                   <name>pending</name>
               </instanceState>
               <privateDnsName/>
               <dnsName/>
               <reason/>
               <keyName>testkeys</keyName>
               <amiLaunchIndex>0</amiLaunchIndex>
               <productCodes/>
               <instanceType>m1.small</instanceType>
               <launchTime>2010-01-06T10:36:45.000Z</launchTime>
               <placement>
                   <availabilityZone>us-east-1a</availabilityZone>
               </placement>
               <kernelId>aki-94c527fd</kernelId>
               <ramdiskId>ari-96c527ff</ramdiskId>
               <monitoring>
                   <state>disabled</state>
               </monitoring>
               <stateReason>
                   <code>pending</code>
                   <message>pending</message>
               </stateReason>
               <rootDeviceType>ebs</rootDeviceType>
               <rootDeviceName>/dev/sda1</rootDeviceName>
               <blockDeviceMapping/>
           </item>
       </instancesSet>
   </RunInstancesResponse>
</amazon-ec2-response>

The following figure shows a sample adapter request for the Run Instances operation with the <block-device mapping> element. 

Sample adapter request for the Run Instances operation with the <block-device mapping> element

<amazon-ec2-request>
   <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location>
   <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address>
   <signature-properties mode = "key-files">
       <private-key-file>C:\Security\
pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file>
       <certificate-file>C:\Security\
cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file>
   </signature-properties>
   <operation-name>run-instances</operation-name>
   <parameters>
     <image-id>ami-26df324f</image-id>
     <min-count>1</min-count>
     <max-count>1</max-count>
     <key-name>ritukeys</key-name>
     <group-set>
       <item>
         <group-id>usersec</group-id>
       </item>
     </group-set>
     <additional-info>Test additional-info tag</additional-info>
     <user-data>
       <data>Test Runinstances</data>
     </user-data>
     <instance-type>m1.small</instance-type>
     <placement>
       <availability-zone>us-east-1b</availability-zone>
     </placement>
     <kernel-id>aki-94c527fd</kernel-id>
     <ramdisk-id>ari-96c527ff</ramdisk-id>
     <block-device-mapping>
       <item>
         <device-name>/dev/sda1</device-name>
         <virtual-name>Test Volume</virtual-name>
         <ebs>
           <snapshot-id>snap-a8f58ac1</snapshot-id>
           <volume-size>15</volume-size>
           <delete-on-termination>true</delete-on-termination>
         </ebs>
       </item>
     </block-device-mapping>
     <monitoring>
       <enabled>false</enabled>
     </monitoring>
     <instance-initiated-shutdown-behavior>stop
</instance-initiated-shutdown-behavior>
   </parameters>
 </amazon-ec2-request>

The following figure shows the response for the sample Run Instances operation with the <block-device mapping> element. 

Sample adapter response for the Run Instances operation with the <block-device mapping> element

<amazon-ec2-response>
 <metadata>
   <status>success</status>
 </metadata>
 <RunInstancesResponse>
   <requestId>45771dc7-2bc5-4ff9-b2cd-4b8c26c33ca1</requestId>
   <reservationId>r-e868e280</reservationId>
   <ownerId>622872856407</ownerId>
   <groupSet>
     <item>
       <groupId>usersec</groupId>
     </item>
   </groupSet>
   <instancesSet>
     <item>
       <instanceId>i-e84c7f80</instanceId>
       <imageId>ami-26df344f</imageId>
       <instanceState>
         <code>0</code>
         <name>pending</name>
       </instanceState>
       <privateDnsName />
       <dnsName />
       <reason />
       <keyName>ritukeys</keyName>
       <amiLaunchIndex>0</amiLaunchIndex>
       <productCodes />
       <instanceType>m1.small</instanceType>
       <launchTime>2010-01-15T09:30:54.000Z</launchTime>
       <placement>
         <availabilityZone>us-east-1b</availabilityZone>
       </placement>
       <kernelId>aki-94c528fd</kernelId>
       <ramdiskId>ari-96c528ff</ramdiskId>
       <monitoring>
         <state>disabled</state>
       </monitoring>
       <stateReason>
         <code>pending</code>
         <message>pending</message>
       </stateReason>
       <rootDeviceType>ebs</rootDeviceType>
       <rootDeviceName>/dev/sda1</rootDeviceName>
       <blockDeviceMapping />
     </item>
   </instancesSet>
</RunInstancesResponse>
<amazon-ec2-response>

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*