RunInstances

Amazon Elastic Compute Cloud: 2008-12-01

previous page next page

RunInstances

The RunInstances operation launches a specified number of instances.

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 (see CreateSecurityGroup. If you do not specify a security group at launch, the instances start in your default security group.

You can provide an optional key pair ID for each image in the launch request (for more information, see CreateKeyPair). 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, see Instance Metadata.

[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 the c1.medium and c1.xlarge 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, see Kernels, RAM Disks, and Block Device Mappings.

Request Parameters

The following table describes the request parameters for RunInstances. Parameter names are case sensitive.

Name Description Required

imageId

Unique ID of a machine image, returned by a call to RegisterImage.

Type: xsd:string

Yes

minCount

Minimum number of instances to launch. If minCount is more than Amazon EC2 can launch, no instances are launched at all.

Type: xsd:int

Yes

maxCount

Maximum number of instances to launch. If maxCount is more than Amazon EC2 can launch, the largest possible number above minCount will be launched instead.

Type: xsd:int

Yes

keyName

The name of the key pair.

Type: xsd:string

No

groupSet

Description of the security groups with which to associate the instances.

Type: GroupSetType[]

Yes

userData

The user data available to the launched instances.

Type: UserDataType[]

No

instanceType

This specifies the instance type.

Options include m1.small, m1.large, m1.xlarge, c1.medium, and c1.xlarge.

The default value is m1.small.

For more information on instance types, see Instance Types.

Type: xsd:string

No

placement

Specifies the placement constraints (Availability Zones) for launching the instances.

To display the list of available Availability Zones, use the DescribeAvailabilityZones operation.

Type: PlacementRequestType

By default, Amazon EC2 selects an Availability Zone for you. For more information, see Availability Zones.

No

kernelId

The ID of the kernel with which to launch the instance. For information on finding available kernel IDs, see ec2-describe-images.

Example: aki-ba3adfd3

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.

Example: ari-badbad00

No

blockDeviceMapping

Specifies how block devices are exposed to the instance. Each mapping is made up of a virtualName and a deviceName.

Virtual name example: instancestore0

Device name example: sdb

Type: BlockDeviceMappingItemType[]

No

Response Elements

The following table describes the default response tags included in RunInstances responses.

Name Description

RunInstancesResponse

Status information about the instances launched.

Type: ReservationInfoType

Sample Request

<RunInstances xmlns="http://ec2.amazonaws.com/doc/2008-12-01">
   <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>
</RunInstances>

Sample Response

<RunInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2008-12-01">
  <reservationId>r-47a5402e</reservationId>
  <ownerId>495219933132</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>
    </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>
    </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>
    </item>
  </instancesSet>
</RunInstancesResponse>

Related Operations

previous page start next page