Did 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
	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
	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
	If any of the AMIs have a product code attached for which the user has not subscribed, the `RunInstances` call will fail.

Request Parameters

Name	Description	Required
`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.

Name	Description
`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>

Document Conventions
Terms of Use

Did this page help you? Yes No Tell us about it...

RunInstances

Description

Request Parameters

Response Elements

Examples

Example Request

Example Response

Example Request

Example Response

Related Operations