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 sufficient capacity to cover the specified minimum values but not the maximum values then capacity available beyond that required to cover the specified minimums will be allocated to each image specified 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 capacity available 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 worth of capacity 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.

<RunInstances xmlns="http://ec2.amazonaws.com/doc/2007-01-19">
    <instancesSet>
        <item>
            <imageId>ami-60a54009</imageId>
            <minCount>1</minCount>
            <maxCount>3</maxCount>
            <keyName>example-key-name</keyName>
        </item>
    </instancesSet>
    <groupSet/>
</RunInstances>

<RunInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2007-01-19">
  <reservationId>r-47a5402e</reservationId>
  <ownerId>UYY3TLBUXIEON5NQVUUX6OMPWBZIQNFM</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>
      <dnsName></dnsName>
      <keyName>example-key-name</keyName>
    </item>
    <item>
      <instanceId>i-2bc64242</instanceId>
      <imageId>ami-60a54009</imageId>
      <instanceState>
        <code>0</code>
	<name>pending</name>
      </instanceState>
      <dnsName></dnsName>
      <keyName>example-key-name</keyName>
    </item>
    <item>
      <instanceId>i-2be64332</instanceId>
      <imageId>ami-60a54009</imageId>
      <instanceState>
        <code>0</code>
	<name>pending</name>
      </instanceState>
      <dnsName></dnsName>
      <keyName>example-key-name</keyName>
    </item>
  </instancesSet>
</RunInstancesResponse>