RunInstances

The RunInstances operation launches a specified number of instances.

A call to RunInstances is guaranteed to start no fewer than the requested minimum for each AMI specified. If there is insufficient capacity available then no instances will be started. Amazon EC2 will make a best effort attempt to satisfy the requested maximum values. If there is capacity to cover the specified minimum values but not the maximum values then instances of each image specified will be launched in a round robin fashion.

As an example, consider a request to launch two images (A and B), with minimum and maximum values of (5,10) and (20, 40) respectively.

If there is sufficient capacity for less than 25 instances then no instances will be launched (since the minimums of 5 and 20 cannot both be satisfied).

If there is capacity available for only 30 instances then 5 instances of A and 20 instances of B will be launched. The remaining 5 instances will be allocated in round robin fashion.

Every instance is launched in a security group. This may be specified as part of the launch request. If a security group is not indicated then instances are started in a the default security group.

An optional keypair ID may be provided for each image in the launch request. All instances that are created from images for which this is provided will have access to the associated public key at boot time (detailed below). This key may be used to provide secure access to an instance of an image on a per-instance basis. Amazon EC2 public images make use of this functionality to provide secure passwordless access to instances (and launching those images without a keypair ID will leave them inaccessible).

The public key material is made available to the instance at boot time by placing it in a file named openssh_id.pub 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 time (as part of rclocal, for example) allowing for secure password-less access. As the need arises, other formats will also be considered.

Optional user data may be provided in the launch request. All instances comprising the launch request have access to this data (see the section called “Using Instance Data” for details).

If any of the AMIs have product codes 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.

Element Name	Definition	Required?	Type
instancesSet	Description of the instances to launch.	Yes	ec2:RunInstanceItemType[]
groupSet	Description of the security groups to associate the instances with.	Yes	ec2:GroupSetType[]
userData	The user data available to the launched instances.	No	ec2:UserDataType
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. See the section called “Instance Addressing” for more information. 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.	No	xsd:string

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