AWS Documentation » Amazon EC2 » API Reference » Actions » RunInstances	« Previous Next »
	Did this page help you? Yes \| No \| Tell us about it...

RunInstances

Description

Launches the specified number of instances of an AMI for which you have permissions.

If capacity is insufficient to launch the maximum number of instances requested in one Availability Zone (the specified Availability Zone for targeted requests, or an Availability Zone chosen by EC2 for untargeted requests), Amazon EC2 launches the minimum number specified. If Amazon EC2 cannot launch the minimum number of instances requested in a single Availability Zone, no instances are launched.

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, see 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

ImageId

The ID of the AMI.

Type: String

Default: None

Required: Yes

MinCount

The 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 (the default for each account is 20, but this limit can be increased).

Required: Yes

MaxCount

The 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 (the default for each account is 20, but this limit can be increased).

Required: Yes

KeyName

The name of the key pair to use.

Type: String

Default: None

Required: No

SecurityGroupId.n

One or more security group IDs.

Type: String

Default: None

Required: Conditional

Condition: Required for nondefault VPC; optional for EC2-Classic, default VPC

SecurityGroup.n

[EC2-Classic, default VPC] One or more security group names.

Type: String

Default: None

Required: Conditional

Condition: For EC2-Classic, default VPC, you must specify either a group ID or a group name

UserData

The Base64-encoded MIME user data to be made available to the instance(s) in this reservation.

Type: String

Default: None

Required: No

AddressingType

This parameter is deprecated.

Type: String

Default: None

Required: No

InstanceType

The instance type. See Available Instance Types for more information.

Type: String

Default: m1.small

Required: No

Placement.AvailabilityZone

The Availability Zone to launch the instance into.

Type: String

Default: EC2 chooses a zone for you

Required: No

Placement.GroupName

The name of an existing placement group you want to launch the instance into (for cluster instances).

Type: String

Default: None

Required: No

Placement.Tenancy

The tenancy of the instance. An instance with a tenancy of dedicated runs on single-tenant hardware and can only be launched into a VPC.

Type: String

Default: default

Required: No

KernelId

The ID of the kernel with which to launch the instance.

Type: String

Default: None

Required: No

RamdiskId

The ID of the RAM disk. 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

Required: No

BlockDeviceMapping.n.DeviceName

The device name exposed to the instance (for example, /dev/sdh or xvdh). For more information, see Block Device Mapping.

Type: String

Default: None

Required: No

BlockDeviceMapping.n.NoDevice

Suppresses the device mapping.

Type: empty element

Default: None

Required: No

BlockDeviceMapping.n.VirtualName

The virtual device name, ephemeral[0..3]. The number of instance store volumes depends on the instance type.

Type: String

Default: None

Required: No

BlockDeviceMapping.n.Ebs.SnapshotId

The ID of the snapshot.

Type: String

Default: None

Required: No

BlockDeviceMapping.n.Ebs.VolumeSize

The size of the volume, in GiBs.

Type: Integer

Valid values: If the volume type is io1, the minimum size of the volume is 10 GiB.

Default: If you're creating the volume from a snapshot and don't specify a volume size, the default is the snapshot size.

Required: No

BlockDeviceMapping.n.Ebs.DeleteOnTermination

Whether the volume is deleted on instance termination.

Type: Boolean

Default: true

Required: No

BlockDeviceMapping.n.Ebs.VolumeType

The volume type.

Type: String

Valid values: standard | io1

Default: standard

Required: No

BlockDeviceMapping.n.Ebs.Iops

The number of I/O operations per second (IOPS) that the volume supports.

Type: Integer

Valid values: Range is 100 to 4000.

Default: None

Required: Required when the volume type is io1; not used with standard volumes.

Monitoring.Enabled

Enables monitoring for the instance.

Type: Boolean

Default: false

Required: No

SubnetId

[EC2-VPC] The ID of the subnet to launch the instance into.

Type: String

Default: None

Required: No

DisableApiTermination

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

Required: No

InstanceInitiatedShutdownBehavior

Whether the instance stops or terminates on instance-initiated shutdown.

Type: String

Valid values: stop | terminate

Default: stop

Required: No

PrivateIpAddress

[EC2-VPC] You can optionally use this parameter to assign the instance a specific available IP address from the IP address range of the subnet as the primary IP address.

Only one private IP address can be designated as primary. Therefore, you cannot specify this parameter if you are also specifying PrivateIpAddresses.n.Primary with a value of true with the PrivateIpAddresses.n.PrivateIpAddress option.

Type: String

Default: We select an IP address from the IP address range of the subnet for the instance

Required: No

ClientToken

Unique, case-sensitive identifier you provide to ensure idempotency of the request. For more information, see How to Ensure Idempotency in the Amazon Elastic Compute Cloud User Guide.

Type: String

Default: None

Constraints: Maximum 64 ASCII characters

Required: No

NetworkInterface.n.NetworkInterfaceId

Attaches an existing interface to a single instance. Requires n=1 instances.

Type: String

Default: None

Required: No

NetworkInterface.n.DeviceIndex

Applies to both attaching existing network interfaces and when creating new network interfaces.

Type: Integer

Default: None

Required: No

NetworkInterface.n.SubnetId

Applies only when creating new network interfaces.

Type: String

Default: None

Required: No

NetworkInterface.n.Description

Applies only when creating new network interfaces.

Type: String

Default: None

Required: No

NetworkInterface.n.PrivateIpAddress

The primary private IP address of the network interface. Applies only when creating new network interfaces. Requires n=1 network interfaces in launch.

Type: String

Default: None

Required: No

NetworkInterface.n.PrivateIpAddresses.n.PrivateIpAddress

The private IP address of the specified network interface. This parameter can be used multiple times to specify explicit private IP addresses for a network interface, but only one private IP address can be designated as primary.

Only one private IP address can be designated as primary. Therefore, you cannot specify this parameter with the NetworkInterface.n.PrivateIpAddresses.n.Primary value of true if you designate a primary private IP address using the NetworkInterface.n.PrivateIpAddress option.

Type: String

Default: None

Required: No

NetworkInterface.n.PrivateIpAddresses.n.Primary

Whether the private IP address is the primary private IP address.

Only one private IP address can be designated as primary. Therefore, you cannot specify this parameter with the NetworkInterface.n.PrivateIpAddresses.n.Primary value of true and the NetworkInterface.n.PrivateIpAddresses.n.PrivateIpAddress option if you designate a primary private IP address using NetworkInterface.n.PrivateIpAddress.

Type: Boolean

Default: None

Required: No

NetworkInterface.n.SecondaryPrivateIpAddressCount

The number of private IP addresses to assign to a network interface.

For a single network interface, you cannot specify this option and specify more than one private IP address using NetworkInterface.n.PrivateIpAddress.

Required: No

NetworkInterface.n.SecurityGroupId.n

Applies only when creating new network interfaces.

Type: String

Default: None

Required: No

NetworkInterface.n.DeleteOnTermination

Applies to all network interfaces.

Type: Boolean

Default: None

Required: No

IamInstanceProfile.Arn

Amazon resource name (ARN) of the IAM Instance Profile (IIP) to associate with the instances.

Type: String

Default: None

Required: No

IamInstanceProfile.Name

The name of the IAM Instance Profile (IIP) to associate with the instances.

Type: String

Default: None

Required: No

EbsOptimized

Whether the instance is optimized for EBS I/O. This optimization provides dedicated throughput to Amazon EBS and an optimized configuration stack to provide optimal EBS I/O performance. This optimization isn't available with all instance types. Additional usage charges apply when using an EBS Optimized instance.

Type: Boolean

Default: false

Required: No

Response Elements

The following elements are returned in a RunInstancesResponse element.

requestId

The ID of the request.

Type: xsd:string

reservationId

The ID of the reservation.

Type: xsd:string

ownerId

The ID of the AWS account that owns the reservation.

Type: xsd:string

groupSet

A list of security groups the instance belongs to. Each group is wrapped in an item element.

Type: GroupItemType

instancesSet

A list of instances. Each instance is wrapped in an item element.

Type: RunningInstancesItemType

requesterId

The ID of the requester that launched the instances on your behalf (for example, 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/2013-02-01/"> 
  <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> 
  <reservationId>r-47a5402e</reservationId> 
  <ownerId>111122223333</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/>
      <dnsName/>
      <reason/>
      <amiLaunchIndex>0</amiLaunchIndex>
      <instanceType>m1.small</instanceType>
      <launchTime>2007-08-07T11:51:50.000Z</launchTime>
      <placement>
        <availabilityZone>us-east-1b</availabilityZone>
        <groupName/>
        <tenancy>default</tenancy>
      </placement>
      <monitoring>
        <state>enabled</state>
      </monitoring>
      <sourceDestCheck>true</sourceDestCheck>
      <groupSet>
         <item>
            <groupId>sg-245f6a01</groupId>
            <groupName>default</groupName>
         </item>
      </groupSet>
      <virtualizationType>paravirtual</virtualizationType>
      <clientToken/>
      <hypervisor>xen</hypervisor>
      <ebsOptimized>false</ebsOptimized>
    </item>
    <item>
      <instanceId>i-2bc64242</instanceId>
      <imageId>ami-60a54009</imageId>
      <instanceState>
        <code>0</code>
        <name>pending</name>
      </instanceState>
      <privateDnsName/>
      <dnsName/>
      <amiLaunchIndex>1</amiLaunchIndex>
      <instanceType>m1.small</instanceType>
      <launchTime>2007-08-07T11:51:50.000Z</launchTime>
      <placement>
         <availabilityZone>us-east-1b</availabilityZone>
         <groupName/>
         <tenancy>default</tenancy>
      </placement>
      <monitoring>
        <state>enabled</state>
      </monitoring>
      <sourceDestCheck>true</sourceDestCheck>
      <groupSet>
         <item>
            <groupId>sg-245f6a01</groupId>
            <groupName>default</groupName>
         </item>
      </groupSet>
      <virtualizationType>paravirtual</virtualizationType>
      <hypervisor>xen</hypervisor>
      <ebsOptimized>false</ebsOptimized>
    </item>
    <item>
      <instanceId>i-2be64332</instanceId>
      <imageId>ami-60a54009</imageId>
      <instanceState>
        <code>0</code>
        <name>pending</name>
      </instanceState>
      <privateDnsName/>
      <dnsName/>
      <amiLaunchIndex>2</amiLaunchIndex>
      <instanceType>m1.small</instanceType>
      <launchTime>2007-08-07T11:51:50.000Z</launchTime>
      <placement>
         <availabilityZone>us-east-1b</availabilityZone>
         <groupName/>
         <tenancy>default</tenancy>
      </placement>
      <monitoring>
        <state>enabled</state>
      </monitoring>
      <sourceDestCheck>true</sourceDestCheck>
      <groupSet>
         <item>
            <groupId>sg-245f6a01</groupId>
            <groupName>default</groupName>
         </item>
      </groupSet>
      <virtualizationType>paravirtual</virtualizationType>
      <hypervisor>xen</hypervisor>
      <ebsOptimized>false</ebsOptimized>
    </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/2013-02-01/'>
    <requestId>e86ff3c8-2400-45e3-a4e7-f158a69283d4</requestId>
    <reservationId>r-157ad274</reservationId>
    <ownerId>111122223333</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>111122223333</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>

Example Request

The following example launches an m1.large instance into a VPC in subnet subnet-a61dafcf with a single network interface, a primary private IP address of 10.0.2.106 and two secondary private IP addresses (10.0.2.107 and 10.0.2.108

https://ec2.amazonaws.com/?Action=RunInstances
&ImageId=ami-beb0caec
&InstanceType=m1.large
&MaxCount=1
&MinCount=1
&Monitoring.Enabled=false
&NetworkInterface.0.DeviceIndex=0
&NetworkInterface.0.PrivateIpAddresses.0.Primary=true
&NetworkInterface.0.PrivateIpAddresses.0.PrivateIpAddress=10.0.2.106
&NetworkInterface.0.PrivateIpAddresses.1.Primary=false
&NetworkInterface.0.PrivateIpAddresses.1.PrivateIpAddress=10.0.2.107
&NetworkInterface.0.PrivateIpAddresses.2.Primary=false
&NetworkInterface.0.PrivateIpAddresses.2.PrivateIpAddress=10.0.2.108
&NetworkInterface.0.SubnetId=subnet-a61dafcf
&AUTHPARAMS

Example Request

This example launches a Dedicated Instance into a VPC.

https://ec2.amazonaws.com/?Action=RunInstances
&ImageId=ami-2a1fec43
&SubnetId=subnet-dea63cb7
&Placement.Tenancy=dedicated
&MinCount=1
&MaxCount=1
&AUTHPARAMS

Document Conventions	« Previous Next »
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

Example Request

Example Request

Related Actions