Prev Next

RunInstances

The RunInstances operation launches a specified number of instances.

Note:

The Query version of RunInstances only allows instances of a single AMI to be launched in one call. This is different from the SOAP API call of the same name but similar to the ec2-run-instances command line tool.

A call to RunInstances is guaranteed to start no fewer than the requested minimum. 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.

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.

Request Parameters

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

Element NameDefinitionRequired?Type
ImageId Id of the AMI to launch instances based on. Yes string
MinCount Minimum number of instances to launch. Yes int
MaxCount Maximum number of instances to launch. Yes int
KeyName Name of the keypair to launch instances with. No string
SecurityGroup.n Names of the security groups to associate the instances with. No string
UserData The user data available to the launched instances. This should be base64-encoded. See the UserDataType data type for encoding details. No string

Response Tags

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

Element NameDefinitionType
RunInstancesResponse Status information about the instances started. ec2ReservationInfoType

Sample Request

https://ec2.amazonaws.com/
?Action=RunInstances
&ImageId=ami-60a54009
&MaxCount=3
&MinCount=1
&...auth parameters...

Sample Response

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

Related Operations

Prev Next