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

	Note
	Every instance is launched in a security group. 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. 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 ephemeral 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 comprising the launch request have access to this data (see Instance Metadata for details).

	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

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

Name	Description	Required
instancesSet	Description of the instances to launch. Type: ec2:RunInstanceItemType[]	Yes
groupSet	Description of the security groups with which to associate the instances. Type: ec2:GroupSetType[]	Yes
userData	The user data available to the launched instances. Type: ec2:UserDataType	No
addressingType	The addressing scheme with which to launch the instance. The supported addressing type is public. For the public scheme, the instance has a private and public IP address that are mapped through NAT. For more information, see Instance Addressing. Note To support our legacy cluster, early beta customers can also specify direct. In the direct scheme, the instance has a single public IP address. Type: xsd:string	No
instanceType	This specifies the instance type. Options include m1.small, m1.large, and m1.xlarge. The default value is m1.small. For more information on instance types, see Selecting Instance Types Type: xsd:string	No

<RunInstances xmlns="http://ec2.amazonaws.com/doc/2007-08-29">
    <instancesSet>
        <item>
            <imageId>ami-60a54009</imageId>
            <minCount>1</minCount>
            <maxCount>3</maxCount>
            <keyName>example-key-name</keyName>
        </item>
    </instancesSet>
    <groupSet/>
    <userData version="1.0" encoding="base64"><data>"VGhpcyBpcyBiYXNlIDY0IQ==</data></userData>
    <addressingType>public</addressingType>
</RunInstances>

<RunInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2007-08-29">
  <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>      
    </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>      
    </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>      
    </item>
  </instancesSet>
</RunInstancesResponse>