RunInstances

Amazon Elastic Compute Cloud: 2009-10-31

previous page next page

RunInstances

Description

Launches a specified number of instances of an AMI for which you have permissions.

If Amazon EC2 cannot launch the minimum number AMIs you request, no instances will be launched. If there is insufficient capacity to launch the maximum number of AMIs you request, Amazon EC2 launches the minimum number specified for each AMI and allocate the remaining available instances using round robin.

In the following example, Libby generates a request to launch two images (database and web_server):

Libby runs the RunInstances operation to launch database instances (min. 10, max. 15) and web_server instances (min. 30, max. 40).
Because there are currently 30 instances available and Libby needs a minimum of 40, no instances are launched.
Libby adjusts the number of instances she needs and runs the RunInstances operation to launch database instances (min. 5, max. 10) and web_server instances (min. 20, max. 40).
Amazon EC2 launches the minimum number of instances for each AMI (5 database, 20 web_server).
The remaining 5 instances are allocated using round robin.
Libby adjusts the number of instances she needs and runs the RunInstances operation again to launch database instances (min. 5, max. 10) and web_server instances (min. 20, max. 40).

	Note
	Every instance is launched in a security group (created using the `CreateSecurityGroup` operation.

You can provide an optional key pair ID for each image in the launch request (created using the CreateKeyPair operation). All instances that are created from images that use this key pair will have access to the associated public key at boot. You can use this key to provide secure access to an instance of an image on a per-instance basis. Amazon EC2 public images use this feature to provide secure access without passwords.

	Important
	Launching public images without a key pair ID will leave them inaccessible.

The public key material is made available to the instance at boot time by placing it in the openssh_id.pub file on a logical device that is exposed to the instance as /dev/sda2 (the instance store). The format of this file is suitable for use as an entry within ~/.ssh/authorized_keys (the OpenSSH format). This can be done at boot (e.g., as part of rc.local) allowing for secure access without passwords.

Optional user data can be provided in the launch request. All instances that collectively comprise the launch request have access to this data. For more information, go the

Amazon Elastic Compute Cloud Developer Guide or Amazon Elastic Compute Cloud User Guide.

	Note
	If any of the AMIs have a product code attached for which the user has not subscribed, the `RunInstances` call will fail.

	Important
	We strongly recommend using the 2.6.18 Xen stock kernel with High-CPU and High-Memory instances. Although the default Amazon EC2 kernels will work, the new kernels provide greater stability and performance for these instance types. For more information about kernels, go the Amazon Elastic Compute Cloud Developer Guide.

Request Parameters

Name	Description	Required
`RunInstancesType`	`RunInstancesType` element. Type: RunInstancesType Ancestor: None Children: `imageId`, `minCount`, `maxCount`, `keyName`, `groupSet`, `additionalInfo`, `userData`, `addressingType`, `instanceType`, `placement`, `kernelId`, `ramdiskId`, `blockDeviceMapping`, `monitoring`, `subnetId`, `disableApiTermination`, and `instanceInitiatedShutdownBehavior`
`imageId`	Unique ID of a machine image, returned by a call to Type: xsd:string Default: None Ancestor: `RunInstancesType` Children: None	Yes
`minCount`	Minimum number of instances to launch. If the value is more than Amazon EC2 can launch, no instances are launched at all. Type: xsd:int Default: None Constraints: Between 1 and the maximum number allowed for your account (default: 20). Ancestor: `RunInstancesType` Children: None	Yes
`maxCount`	Maximum number of instances to launch. If the value is more than Amazon EC2 can launch, the largest possible number above minCount will be launched instead. Type: xsd:int Default: None Constraints: Between 1 and the maximum number allowed for your account (default: 20). Ancestor: `RunInstancesType` Children: None	Yes
`keyName`	The name of the key pair. Type: xsd:string Default: None Ancestor: `RunInstancesType` Children: None	No
`groupSet`	Group set. Type: GroupSetType Ancestor: `RunInstancesType` Children: `item`
`item`	Group set item. Type: GroupItemType Ancestor: `groupSet` Children: `groupId`
`groupId`	Name of the security group. Type: xsd:string Default: None Ancestor: `item` Children: None	No
`additionalInfo`	Specifies additional information to make available to the instance(s). Type: xsd:string Default: None Ancestor: `RunInstancesType` Children: None	No
`userData`	MIME, Base64-encoded user data. Type: UserDataType Ancestor: `RunInstancesType` Children: `data`
`data`	MIME, Base64-encoded user data. Type: xsd:string Default: None Ancestor: `userData` Children: None	No
`addressingType`	Deprecated. Type: xsd:string Default: None Ancestor: `RunInstancesType` Children: None	No
`instanceType`	Specifies the instance type. Type: xsd:string Valid Values: `m1.small` \| `m1.large` \| `m1.xlarge` \| `c1.medium` \| `c1.xlarge` \| `m2.2xlarge` \| `m2.4xlarge` Default: m1.small Ancestor: `RunInstancesType` Children: None	No
`placement`	Placement item. Type: PlacementRequestType Ancestor: `RunInstancesType` Children: `availabilityZone`	No
`availabilityZone`	Specifies the placement constraints (Availability Zones) for launching the instances. Type: xsd:string Default: Amazon EC2 selects an Availability Zone. Ancestor: `placement` Children: None	No
`kernelId`	The ID of the kernel with which to launch the instance. Type: xsd:string Default: None Ancestor: `RunInstancesType` Children: None	No
`ramdiskId`	The ID of the RAM disk with which to launch the instance. Some kernels require additional drivers at launch. Check the kernel requirements for information on whether you need to specify a RAM disk. To find kernel requirements, go to the Resource Center and search for the kernel ID. Type: xsd:string Default: None Ancestor: `RunInstancesType` Children: None	No
`blockDeviceMapping`	Specifies how block devices are exposed to the instance. Each mapping is made up of a virtualName and a deviceName. Type: BlockDeviceMappingType Ancestor: `RunInstancesType` Children: `item`	No
`item`	Information for one block device mapping. Type: BlockDeviceMappingItemType Ancestor: `blockDeviceMapping` Children: `deviceName`, `virtualName`, `ebs`, and `noDevice`
`deviceName`	The device name (e.g., /dev/sdh). Type: xsd:string Default: None Ancestor: `item` Children: None	No
`virtualName`	The virtual device name. Type: xsd:string Default: None Ancestor: `item` Children: None	No
`ebs`	Specifies parameters used to automatically setup Amazon EBS volumes when the instance is launched. Type: EbsBlockDeviceType Ancestor: `item` Children: `snapshotId`, `volumeSize`, and `deleteOnTermination`	Yes
`snapshotId`	The ID of the snapshot. Type: xsd:string Default: None Ancestor: `ebs` Children: None	No
`volumeSize`	The size of the volume. Type: xsd:string Default: None Ancestor: `ebs` Children: None	No
`deleteOnTermination`	Specifies whether the Amazon EBS volume is deleted on instance termination. Type: xsd:boolean Default: true Ancestor: `ebs` Children: None	No
`noDevice`	Specifies the device name to suppress during instance launch. Type: EmptyElementType Ancestor: `item` Children: `none`	No
`none`	This element contains no options. Type: xsd:string Default: None Ancestor: `noDevice` Children: None	No
`monitoring`	Specifies whether to enable monitoring for the instance. Type: MonitoringInstanceType Ancestor: `RunInstancesType` Children: `enabled`	No
`enabled`	Enables monitoring for the instance. Type: xsd:boolean Default: Disabled Ancestor: `monitoring` Children: None	No
`subnetId`	Specifies the Amazon VPC subnet ID within which to launch the instance(s) for Amazon Virtual Private Cloud. Type: xsd:string Default: None Ancestor: `RunInstancesType` Children: None	No
`disableApiTermination`	Specifies whether the instance can be terminated using the APIs. You must modify this attribute before you can terminate any "locked" instances from the APIs. Type: xsd:boolean Default: true Ancestor: `RunInstancesType` Children: None	No
`instanceInitiatedShutdownBehavior`	Specifies whether the instance's Amazon EBS volumes are stopped or terminated when the instance is shut down. Type: xsd:boolean Default: true Ancestor: `RunInstancesType` Children: None	No

Response Elements

Name	Description
`RunInstancesResponseType`	`RunInstancesResponseType` element. Type: RunInstancesResponseType Ancestor: None Children: `requestId`, `reservationId`, `ownerId`, `groupSet`, `instancesSet`, and `requesterId`
`requestId`	The ID of the request. Type: xsd:string Ancestor: `RunInstancesResponseType` Children: None
`reservationId`	Unique ID of the reservation. Type: xsd:string Ancestor: `RunInstancesResponseType` Children: None
`ownerId`	AWS Access Key ID of the user who owns the reservation. Type: xsd:string Ancestor: `RunInstancesResponseType` Children: None
`groupSet`	Group set. Type: GroupSetType Ancestor: `RunInstancesResponseType` Children: `item`
`item`	Group set item. Type: GroupItemType Ancestor: `groupSet` Children: `groupId`
`groupId`	Name of the security group. Type: xsd:string Ancestor: `item` Children: None
`instancesSet`	Instance set. Type: RunningInstancesSetType Ancestor: `RunInstancesResponseType` Children: `item`
`item`	Running instance set item. Type: RunningInstancesItemType Ancestor: `instancesSet` Children: `instanceId`, `imageId`, `instanceState`, `privateDnsName`, `dnsName`, `reason`, `keyName`, `amiLaunchIndex`, `productCodes`, `instanceType`, `launchTime`, `placement`, `kernelId`, `ramdiskId`, `platform`, `monitoring`, `subnetId`, `vpcId`, `privateIpAddress`, `ipAddress`, `stateReason`, `architecture`, `rootDeviceType`, `rootDeviceName`, and `blockDeviceMapping`
`instanceId`	Unique ID of the instance launched. Type: xsd:string Ancestor: `item` Children: None
`imageId`	Image ID of the AMI used to launch the instance. Type: xsd:string Ancestor: `item` Children: None
`instanceState`	The current state of the instance. Type: InstanceStateType Ancestor: `item` Children: `code`, `name`
`code`	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: xsd:int Valid Values: `0 (pending)` \| `16 (running)` \| `32 (shutting-down)` \| `48 (terminated)` \| `64 (stopping)` \| `80 (stopped)` Ancestor: `instanceState` Children: None
`name`	The current state of the instance. Type: xsd:string Valid Values: `pending` \| `running` \| `shutting-down` \| `terminated` \| `stopping` \| `stopped` Ancestor: `instanceState` Children: None
`privateDnsName`	The private DNS name assigned to the instance. This DNS name can only be used inside the Amazon EC2 network. This element remains empty until the instance enters a running state. Type: xsd:string Ancestor: `item` Children: None
`dnsName`	The public DNS name assigned to the instance. This DNS name is contactable from outside the Amazon EC2 network. This element remains empty until the instance enters a running state. Type: xsd:string Ancestor: `item` Children: None
`reason`	Reason for the most recent state transition. This might be an empty string. Type: xsd:string Ancestor: `item` Children: None
`keyName`	If this instance was launched with an associated key pair, this displays the key pair name. Type: xsd:string Ancestor: `item` Children: None
`amiLaunchIndex`	The AMI launch index, which can be used to find this instance within the launch group. Type: xsd:string Ancestor: `item` Children: None
`productCodes`	Product codes attached to this instance. Type: ProductCodesSetType Ancestor: `item` Children: `item`
`item`	Information for one product code. Type: ProductCodesSetItemType Ancestor: `productCodes` Children: `productCode`
`productCode`	Product code. Type: xsd:string Ancestor: `item` Children: None
`instanceType`	The instance type. Type: xsd:string Ancestor: `item` Children: None
`launchTime`	The time the instance launched. Type: xsd:dateTime Ancestor: `item` Children: None
`placement`	The location where the instance launched. Type: PlacementResponseType Ancestor: `item` Children: `availabilityZone`
`availabilityZone`	Returns the Availability Zone of the instance. Type: xsd:string Ancestor: `placement` Children: None
`kernelId`	Kernel associated with this instance. Type: xsd:string Ancestor: `item` Children: None
`ramdiskId`	RAM disk associated with this instance. Type: xsd:string Ancestor: `item` Children: None
`platform`	Platform of the instance (e.g., Windows). Type: xsd:string Ancestor: `item` Children: None
`monitoring`	Specifies whether monitoring is enabled for the instance. Type: InstanceMonitoringStateType Ancestor: `item` Children: `state`
`state`	State of monitoring for the instance. Type: xsd:string Valid Values: `monitoring-enabled (enabled)` \| `monitoring-pending (pending)` \| `monitoring-disabling (disabling)` \| `monitoring-disabled (disabled)` Ancestor: `monitoring` Children: None
`subnetId`	Specifies the Amazon VPC subnet ID in which the instance is running. Type: xsd:string Ancestor: `item` Children: None
`vpcId`	Specifies the Amazon VPC in which the instance is running. Type: xsd:string Ancestor: `item` Children: None
`privateIpAddress`	Specifies the private IP address that is assigned to the instance. Type: xsd:string Ancestor: `item` Children: None
`ipAddress`	Specifies the IP address of the instance. Type: xsd:string Ancestor: `item` Children: None
`stateReason`	The reason for the state change. Type: StateReasonType Ancestor: `item` Children: `code`, `message`
`code`	Reason code for the state change. Type: xsd:string Ancestor: `stateReason` Children: None
`message`	Message for the state change. Type: xsd:string Ancestor: `stateReason` Children: None
`architecture`	The architecture of the image. Type: xsd:string Valid Values: `i386` \| `x86_64` Ancestor: `item` Children: None
`rootDeviceType`	The root device type used by the AMI. The AMI can use an Amazon EBS or instance store root device. Type: xsd:string Valid Values: `ebs` \| `instance-store` Ancestor: `item` Children: None
`rootDeviceName`	The root device name (e.g., /dev/sda1). Type: xsd:string Ancestor: `item` Children: None
`blockDeviceMapping`	Block device mapping set. Type: InstanceBlockDeviceMappingResponseType Ancestor: `item` Children: `item`
`item`	The item element. Type: InstanceBlockDeviceMappingResponseItemType Ancestor: `blockDeviceMapping` Children: `deviceName`, `ebs`
`deviceName`	Specifies how the device is exposed to the instance (e.g., /dev/sdh). Type: xsd:string Ancestor: `item` Children: None
`ebs`	Specifies parameters used to automatically setup Amazon EBS volumes when the instance is launched. Type: EbsInstanceBlockDeviceMappingResponseType Ancestor: `item` Children: `volumeId`, `status`, `attachTime`, and `deleteOnTermination`
`volumeId`	The ID of the Amazon EBS volume. Type: xsd:string Ancestor: `ebs` Children: None
`status`	Attachment state. Type: xsd:string Valid Values: `attaching` \| `attached` \| `detaching` \| `detached` Ancestor: `ebs` Children: None
`attachTime`	Time stamp when the attachment initiated. Type: xsd:dateTime Ancestor: `ebs` Children: None
`deleteOnTermination`	Specifies whether the Amazon EBS volume is deleted on instance termination. Type: xsd:boolean Ancestor: `ebs` Children: None
`requesterId`	ID of the requester. Type: xsd:string Ancestor: `RunInstancesResponseType` Children: None

Examples

Example Request

This example launches three instances of the ami-60a54009 AMI.

<RunInstances xmlns="http://ec2.amazonaws.com/doc/2009-10-31/">
   <imageId>ami-60a54009</imageId>
   <minCount>1</minCount>
   <maxCount>3</maxCount>
   <keyName>example-key-name</keyName>
     <groupSet/>
   <placement>
     <availabilityZone>us-east-1b</availabilityZone>
   </placement>
   <kernelId>aki-ba3adfd3</kernelId>
   <ramdiskId>ari-badbad00</ramdiskId>
   <blockDeviceMapping>
     <item>
       <virtualName>ami</virtualName>
       <deviceName>sda1<deviceName>
     </item>
     <item>
       <virtualName>root</virtualName>
       <deviceName>/dev/sda1</deviceName>
     </item>
     <item>
       <virtualName>instancestore0</virtualName>
       <deviceName>sdb</deviceName>
     </item>
     <item>
       <virtualName>instance1</virtualName>
       <deviceName>sdc</deviceName>
     </item>
   </blockDeviceMapping>
   <userData version="1.0" encoding="base64"><data>"VGhpcyBpcyBiYXNlIDY0IQ==</data></userData>
   <addressingType>public</addressingType>
   <monitoring>enabled</monitoring></RunInstances>

Example Response

<RunInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2009-10-31/">
  <reservationId>r-47a5402e</reservationId>
  <ownerId>AIDADH4IGTRXXKCD</ownerId>
  <groupSet>
    <item>
      <groupId>default</groupId>
    </item>
  </groupSet>
  <instancesSet>
    <item>
      <instanceId>i-2ba64342</instanceId>
      <imageId>ami-60a54009</imageId>
      <instanceState>
        <code>0</code>
        <name>pending</name>
      </instanceState>
      <privateDnsName></privateDnsName>
      <dnsName></dnsName>
      <keyName>example-key-name</keyName>
      <amiLaunchIndex>0</amiLaunchIndex>
      <instanceType>m1.small</instanceType>
      <launchTime>2007-08-07T11:51:50.000Z</launchTime>
      <placement>
        <availabilityZone>us-east-1b</availabilityZone>
      </placement>
      <monitoring>
        <enabled>true</enabled>
      </monitoring>

    </item>
    <item>
      <instanceId>i-2bc64242</instanceId>
      <imageId>ami-60a54009</imageId>
      <instanceState>
        <code>0</code>
        <name>pending</name>
      </instanceState>
      <privateDnsName></privateDnsName>
      <dnsName></dnsName>
      <keyName>example-key-name</keyName>
      <amiLaunchIndex>1</amiLaunchIndex>
      <instanceType>m1.small</instanceType>
      <launchTime>2007-08-07T11:51:50.000Z</launchTime>
      <placement>
		  <availabilityZone>us-east-1b</availabilityZone>
      </placement>
      <monitoring>
        <enabled>true</enabled>
      </monitoring>
    </item>
    <item>
      <instanceId>i-2be64332</instanceId>
      <imageId>ami-60a54009</imageId>
      <instanceState>
        <code>0</code>
        <name>pending</name>
      </instanceState>
      <privateDnsName></privateDnsName>
      <dnsName></dnsName>
      <keyName>example-key-name</keyName>
      <amiLaunchIndex>2</amiLaunchIndex>
      <instanceType>m1.small</instanceType>
      <launchTime>2007-08-07T11:51:50.000Z</launchTime>
      <placement>
		  <availabilityZone>us-east-1b</availabilityZone>
      </placement>
      <monitoring>
        <enabled>true</enabled>
      </monitoring>
    </item>
  </instancesSet>
</RunInstancesResponse>

previous page start next page

RunInstances

Amazon Elastic Compute Cloud: 2009-10-31

RunInstances

Description

Request Parameters

Response Elements

Examples

Example Request

Example Response

Related Operations