RunInstances

Amazon Elastic Compute Cloud: 2009-08-15

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):

  1. 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.

  2. 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.

  3. 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]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]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.
[Note]Note

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

[Important]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, and subnetId

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: virtualName, deviceName

virtualName

The virtual name.

Type: xsd:string

Default: None

Ancestor: item

Children: None

No

deviceName

The device name (e.g., /dev/sdh).

Type: xsd:string

Default: None

Ancestor: item

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 subnet ID within which to launch the instance(s) for Amazon Virtual Private Cloud.

Type: xsd:string

Default: None

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, and ipAddress

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

Ancestor: instanceState

Children: None

name

The current state of the instance.

Type: xsd:string

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. For more information, go to the Metadata section of the

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 Zones of the instances.

Type: xsd:string

Ancestor: placement

Children: None

kernelId

Optional. Kernel associated with this instance.

Type: xsd:string

Ancestor: item

Children: None

ramdiskId

Optional. 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-disabled (disabled)

Ancestor: monitoring

Children: None

subnetId

Specifies the subnet ID in which the instance is running (Amazon Virtual Private Cloud).

Type: xsd:string

Ancestor: item

Children: None

vpcId

Specifies the VPC in which the instance is running (Amazon Virtual Private Cloud).

Type: xsd:string

Ancestor: item

Children: None

privateIpAddress

Specifies the private IP address that is assigned to the instance (Amazon VPC).

Type: xsd:string

Ancestor: item

Children: None

ipAddress

Specifies the IP address of the instance.

Type: xsd:string

Ancestor: item

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-08-15/">
   <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-08-15/">
  <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