Amazon Elastic Compute Cloud
API Reference (API Version 2011-12-15)
Print this pageEmail this pageGo to the ForumsView the PDFShare this page on TwitterShare this page on FacebookBookmark this page on DeliciousSubmit this page to RedditSubmit this page to DiggDid this page help you?  Yes  No   Tell us about it...

RunInstances

Description

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

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

[Note]Note

Every instance is launched in a security group (created using the CreateSecurityGroup operation). If you don't specify a security group in the RunInstances request, the "default" security group is used.

For Linux instances, you can provide an optional key pair ID in the launch request (created using the CreateKeyPair or ImportKeyPair operation). The instances will have access to the 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.

You can provide optional user data in the launch request. All instances that collectively comprise the launch request have access to this data. For more information, go to Instance Metadata in the Amazon Elastic Compute Cloud User 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.

Request Parameters

NameDescriptionRequired

ImageId

ID of the AMI you want to launch.

Type: String

Default: 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: Integer

Default: None

Constraints: Between 1 and the maximum number allowed for your account (default: 20).

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

Default: None

Constraints: Between 1 and the maximum number allowed for your account (default: 20).

Yes

KeyName

The name of the key pair to use.

Type: String

Default: None

No

SecurityGroupId.n

One or more security group IDs.

Type: String

Default: None

Condition: Required for VPC security groups; optional for EC2 security groups

Conditional

SecurityGroup.n

One or more security group names.

Type: String

Default: None

Condition: Valid only for EC2 security groups; for EC2 groups either a group ID or a group name is accepted

Conditional

UserData

Base64-encoded MIME user data to be made available to the instance(s) in this reservation.

Type: String

Default: None

No

AddressingType

This parameter is deprecated.

Type: String

Default: None

No

InstanceType

The instance type.

Type: String

Valid Values: m1.small | m1.large | m1.xlarge | c1.medium | c1.xlarge | m2.xlarge | m2.2xlarge | m2.4xlarge | cc1.4xlarge | cg1.4xlarge | t1.micro

Default: m1.small

No

Placement.AvailabilityZone

The Availability Zone you want to launch the instance into.

Type: xsd:string

Default: EC2 chooses a zone for you

No

Placement.GroupName

The name of an existing placement group you want to launch the instance into (for cluster instances).

Type: xsd:string

Default: None

No

Placement.Tenancy

The tenancy of the instance you want to launch. An instance with a tenancy of dedicated runs on single-tenant hardware and can only be launched into a VPC.

Type: xsd:string

Default: default

No

KernelId

The ID of the kernel with which to launch the instance.

Type: String

Default: None

No

RamdiskId

The ID of the RAM disk to select. 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, refer to the Resource Center and search for the kernel ID.

Type: String

Default: None

No

BlockDeviceMapping.n.DeviceName

The device name (e.g., /dev/sdh, or xvdh). The device can be mapped to an EBS volume, a virtual device, or to nothing. If you are using this device to map an EBS volume, follow this with the EBS volume specific parameters. For information about block device mapping, go to Block Device Mapping in the Amazon Elastic Compute Cloud User Guide.

Type: String

Default: None

No

BlockDeviceMapping.n.NoDevice

Specifies that no device should be mapped. This parameter takes an empty string as input.

Type: Empty String

Default: None

No

BlockDeviceMapping.n.VirtualName

The virtual device name (e.g., /ephemeral0, /ephemeral1 etc). The count following ephemeral goes up based on your instance type. For a small image, it has an ephemeral0 (ext3, 15GB) and an ephemeral1 (swap, 1GB). For information about block device mapping, go to Block Device Mapping in the Amazon Elastic Compute Cloud User Guide.

Type: String

Default: None

No

BlockDeviceMapping.n.Ebs.SnapshotId

The ID of the snapshot.

Type: String

Default: None

No

BlockDeviceMapping.n.Ebs.VolumeSize

The size of the volume, in GiBs. Required if you are not creating a volume from a snapshot.

Type: Integer

Default: None

No

BlockDeviceMapping.n.Ebs.DeleteOnTermination

Whether the Amazon EBS volume is deleted on instance termination.

Type: Boolean

Default: true

No

Monitoring.Enabled

Enables monitoring for the instance.

Type: Boolean

Default: false

No

SubnetId

If you're using Amazon Virtual Private Cloud, this specifies the ID of the subnet you want to launch the instance into.

Type: String

Default: None

No

DisableApiTermination

Specifies whether you can terminate the instance using the EC2 API. A value of true means you can't terminate the instance using the API (i.e., the instance is "locked"); a value of false means you can. If you set this to true, and you later want to terminate the instance, you must first change the disableApiTermination attribute's value to false using ModifyInstanceAttribute.

Type: Boolean

Default: false

No

InstanceInitiatedShutdownBehavior

Determines whether the instance stops or terminates on instance-initiated shutdown.

Type: String

Valid Values: stop | terminate

Default: stop

No

PrivateIpAddress

If you're using Amazon Virtual Private Cloud, you can optionally use this parameter to assign the instance a specific available IP address from the subnet (e.g., 10.0.0.25).

Type: String

Default: Amazon VPC selects an IP address from the subnet for the instance

No

ClientToken

Unique, case-sensitive identifier you provide to ensure idempotency of the request. For more information, go to How to Ensure Idempotency in the Amazon Elastic Compute Cloud User Guide.

Type: String

Default: None

Constraints: Maximum 64 ASCII characters

No

NetworkInterface.n.NetworkInterfaceId

Attaches an existing interface to a single instance. Requires n=1 instances.

Type: String

Default:

No

NetworkInterface.n.DeviceIndex

Applies to both attaching existing network interfaces and when creating new network interfaces.

Type: Integer

Default:

No

NetworkInterface.n.SubnetId

Applies only when creating new network interfaces.

Type: String

Default:

No

NetworkInterface.n.Description

Applies only when creating new network interfaces.

Type: String

Default:

No

NetworkInterface.n.PrivateIpAddress

Applies only when creating new network interfaces. Requires n=1 network interfaces in launch.

Type: String

Default:

No

NetworkInterface.n.SecurityGroupId.n

Applies only when creating new network interfaces.

Type: String

Default:

No

NetworkInterface.n.DeleteOnTermination

Applies to all network interfaces.

Type: Boolean

Default:

No

Response Elements

The elements in the following table are wrapped in a RunInstancesResponse structure.

NameDescription

requestId

The ID of the request.

Type: xsd:string

reservationId

Unique ID of the reservation.

Type: xsd:string

ownerId

ID of the AWS account that owns the reservation.

Type: xsd:string

groupSet

List of security groups the instance belongs to. Each group's information is wrapped in an item element.

Type: GroupItemType

instancesSet

A list of instances. Each instance's information is wrapped in an item element.

Type: RunningInstancesItemType

requesterId

ID of the requester that launched the instances on your behalf (e.g., AWS Management Console, Auto Scaling).

Type: xsd:string

Examples

Example Request

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

https://ec2.amazonaws.com/?Action=RunInstances
&ImageId=ami-60a54009
&MaxCount=3
&MinCount=1
&Placement.AvailabilityZone=us-east-1b
&Monitoring.Enabled=true
&AUTHPARAMS

Example Response

<RunInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2011-12-15/"> 
  <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> 
  <reservationId>r-47a5402e</reservationId> 
  <ownerId>999988887777</ownerId>
  <groupSet>
    <item>
      <groupId>sg-245f6a01</groupId>
      <groupName>default</groupName>
    </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>
      <sourceDestCheck>true</sourceDestCheck>
      <groupSet>
         <item>
            <groupId>sg-245f6a01</groupId>
            <groupName>default</groupName>
         </item>
      </groupSet>
      <virtualizationType>paravirtual</virtualizationType>
      <clientToken/>
      <tagSet/>
      <hypervisor>xen</hypervisor>
    </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>
      <sourceDestCheck>true</sourceDestCheck>
      <groupSet>
         <item>
            <groupId>sg-245f6a01</groupId>
            <groupName>default</groupName>
         </item>
      </groupSet>
      <virtualizationType>paravirtual</virtualizationType>
      <clientToken/>
      <tagSet/>
      <hypervisor>xen</hypervisor>
    <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>
      <sourceDestCheck>true</sourceDestCheck>
      <groupSet>
         <item>
            <groupId>sg-245f6a01</groupId>
            <groupName>default</groupName>
         </item>
      </groupSet>
      <virtualizationType>paravirtual</virtualizationType>
      <clientToken/>
      <tagSet/>
      <hypervisor>xen</hypervisor>
    </item>
  </instancesSet>
  </RunInstancesResponse>

Example Request

This example launches an instance of the ami-31814f58 AMI and attaches an elastic network interface to it.

https://ec2.amazonaws.com/?Action=RunInstances
ImageId=ami-31814f58
&InstanceType=m1.small
&MaxCount=1
&MinCount=1
&Monitoring.Enabled=false
&SubnetId=subnet-b2a249da
&AUTHPARAMS

Example Response

<RunInstancesResponse xmlns='http://ec2.amazonaws.com/doc/2011-11-15/'>
    <requestId>e86ff3c8-2400-45e3-a4e7-f158a69283d4</requestId>
    <reservationId>r-157ad274</reservationId>
    <ownerId>602767649040</ownerId>
    <groupSet/>
    <instancesSet>
        <item>
            <instanceId>i-0ee0356c</instanceId>
            <imageId>ami-31814f58</imageId>
            <instanceState>
                <code>0</code>
                <name>pending</name>
            </instanceState>
            <privateDnsName/>
            <dnsName/>
            <reason/>
            <amiLaunchIndex>0</amiLaunchIndex>
            <productCodes/>
            <instanceType>m1.small</instanceType>
            <launchTime>2011-12-20T08:29:31.000Z</launchTime>
            <placement>
                <availabilityZone>us-east-1b</availabilityZone>
                <groupName/>
                <tenancy>default</tenancy>
            </placement>
            <kernelId>aki-805ea7e9</kernelId>
            <monitoring>
                <state>disabled</state>
            </monitoring>
            <subnetId>subnet-b2a249da</subnetId>
            <vpcId>vpc-1ea24976</vpcId>
            <privateIpAddress>10.0.0.142</privateIpAddress>
            <sourceDestCheck>true</sourceDestCheck>
            <groupSet>
                <item>
                    <groupId>sg-050c1369</groupId>
                    <groupName>default</groupName>
                </item>
            </groupSet>
            <stateReason>
                <code>pending</code>
                <message>pending</message>
            </stateReason>
            <architecture>i386</architecture>
            <rootDeviceType>ebs</rootDeviceType>
            <rootDeviceName>/dev/sda1</rootDeviceName>
            <blockDeviceMapping/>
            <virtualizationType>paravirtual</virtualizationType>
            <clientToken/>
            <hypervisor>xen</hypervisor>
            <networkInterfaceSet>
                <item>
                    <networkInterfaceId>eni-c6bb50ae</networkInterfaceId>
                    <subnetId>subnet-b2a249da</subnetId>
                    <vpcId>vpc-1ea24976</vpcId>
                    <description/>
                    <ownerId>602767649040</ownerId>
                    <status>in-use</status>
                    <privateIpAddress>10.0.0.142</privateIpAddress>
                    <sourceDestCheck>true</sourceDestCheck>
                    <groupSet>
                        <item>
                            <groupId>sg-050c1369</groupId>
                            <groupName>default</groupName>
                        </item>
                    </groupSet>
                    <attachment>
                        <attachmentId>eni-attach-0326646a</attachmentId>
                        <deviceIndex>0</deviceIndex>
                        <status>attaching</status>
                        <attachTime>2011-12-20T08:29:31.000Z</attachTime>
                        <deleteOnTermination>true</deleteOnTermination>
                    </attachment>
                </item>
            </networkInterfaceSet>
        </item>
    </instancesSet>
</RunInstancesResponse>