ec2-run-instances

Amazon Elastic Compute Cloud: 2009-10-31

previous page next page

ec2-run-instances

Description

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

If Amazon EC2 cannot launch the minimum number AMIs you request, no instances will be launched. If there is insufficient capacity to launch the maximum number of AMIs you request, Amazon EC2 launches the minimum number specified for each AMI and allocate the remaining available instances using round robin.

In the following example, Libby generates a request to launch two images (database and web_server):

  1. Libby runs the RunInstances operation to launch database instances (min. 10, max. 15) and web_server instances (min. 30, max. 40).

    Because there are currently 30 instances available and Libby needs a minimum of 40, no instances are launched.

  2. Libby adjusts the number of instances she needs and runs the RunInstances operation to launch database instances (min. 5, max. 10) and web_server instances (min. 20, max. 40).

    Amazon EC2 launches the minimum number of instances for each AMI (5 database, 20 web_server).

    The remaining 5 instances are allocated using round robin.

  3. Libby adjusts the number of instances she needs and runs the RunInstances operation again to launch database instances (min. 5, max. 10) and web_server instances (min. 20, max. 40).

[Note]Note

Every instance is launched in a security group (created using the CreateSecurityGroup operation.

You can provide an optional key pair ID for each image in the launch request (created using the CreateKeyPair operation). All instances that are created from images that use this key pair will have access to the associated 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]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.

Optional user data can be provided in the launch request. All instances that collectively comprise the launch request have access to this data. For more information, go the

Amazon Elastic Compute Cloud Developer Guide or Amazon Elastic Compute Cloud User Guide.
[Note]Note

If any of the AMIs have a product code attached for which the user has not subscribed, the RunInstances call will fail.

[Important]Important

We strongly recommend using the 2.6.18 Xen stock kernel with High-CPU and High-Memory instances. Although the default Amazon EC2 kernels will work, the new kernels provide greater stability and performance for these instance types. For more information about kernels, go the Amazon Elastic Compute Cloud Developer Guide.

Syntax

ec2-run-instances ami_id [-n instance_count] [-g group [-g group ...]] [-k keyname] [-d user_data | -f user_data_file] [ --addressing addressing_type] [ --type instance_type] [ --availability-zone zone] [ --kernel kernel_id] [ --ramdisk ramdisk_id] [ --block-device-mappingblock_device_mapping]

Options

Name Description Required

ami_id

Unique ID of a machine image, returned by a call to

Type: String

Default: None

Example: ami-15a4417c

Yes

-k keyname

The name of the key pair.

Type: String

Default: None

Example: MyKeyPair

No

group

Name of the security group.

Type: String

Default: None

Example: websrv

No

-f user-data-file

Specifies additional information to make available to the instance(s).

Type: String

Default: None

Example: MyDataFile.txt

No

-d user_data

MIME, Base64-encoded user data.

Type: String

Default: None

Example: my user data

No

--type instance_type

Specifies the instance type.

Type: String

Valid Values: m1.small | m1.large | m1.xlarge | c1.medium | c1.xlarge | m2.2xlarge | m2.4xlarge

Default: m1.small

Example: m1.large

No

--availability-zone zone

Specifies the placement constraints (Availability Zones) for launching the instances.

Type: String

Default: Amazon EC2 selects an Availability Zone.

Example: us-east-1b

No

kernel

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

Type: String

Default: None

Example: aki-ba3adfd3

No

ramdisk

The ID of the RAM disk with which to launch the instance. 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, go to the Resource Center and search for the kernel ID.

Type: String

Default: None

Example: ari-badbad00

No

--block-device-mapping mapping

The device name (e.g., /dev/sdh).

Type: String

Default: None

Example: /dev/sdh

No

--block-device-mapping mapping

The virtual device name.

Type: String

Default: None

Example:

No

--snapshot snapshot

The ID of the snapshot.

Type: String

Default: None

Example: snap-78a54011

No

--size size

The size of the volume.

Type: String

Default: None

Example: 10

No

--delete-on-termination

Specifies whether the Amazon EBS volume is deleted on instance termination.

Type: Boolean

Default: true

Example: --delete-on-termination

No

--monitored

Enables monitoring for the instance.

Type: Boolean

Default: Disabled

Example: --monitored

No

--subnet

Specifies the Amazon VPC subnet ID within which to launch the instance(s) for Amazon Virtual Private Cloud.

Type: String

Default: None

Example: MyPrivateSubnet

No

--disable-api-termination

Specifies whether the instance can be terminated using the APIs. You must modify this attribute before you can terminate any "locked" instances from the APIs.

Type: Boolean

Default: true

Example: --disable-api-termination

No

--instance-initiated-shutdown-behavior

Specifies whether the instance's Amazon EBS volumes are stopped or terminated when the instance is shut down.

Type: Boolean

Default: true

Example: --instance-initiated-shutdown-behavior

No

-n instance_count

The number of instances to launch. If Amazon EC2 cannot launch the specified number of instances, no instances will launch. If this is specified as a range (min-max), Amazon EC2 will try to launch the maximum number, but no fewer than the minimum number.

Type: String

Default: None

Constraints: Between 1 and the maximum number allowed for your account (default: 20).

Example: 5-10

Yes

Output

The command returns a table that contains the following information:

  • Output type identifier ("INSTANCE")

  • Instance ID which uniquely identifies each running instance

  • AMI ID of the image on which the instance(s) are based

  • DNS name associated with the instance (only present for instances in the running state)

  • Instance state. This is usually pending, which indicates that the instance(s) are preparing to launch

  • Key name. If a key was associated with the instance at launch its name is displayed

  • AMI launch index

  • Instance type. Specifies the instance type (CPU and memory configuration)

  • Instance launch time. Specifies when the instance launched

  • Availability Zone. Specifies the zone in which the instance launched

Amazon EC2 displays errors on stderr.

Examples

Example Request

This example launches three instances of the ami-60a54009 AMI.

PROMPT> ec2-run-instances ami-60a54009 -n 3 --availability-zone us-east-1a

RESERVATION    r-237fed4a    853279305796    default
INSTANCE  i-d9add0b0  ami-60a54009  pending   0  m1.small  2009-05-14T12:38:24+0000  us-east-1a  aki-a71cf9ce  ari-a51cf9cc  monitoring-disabled
INSTANCE  i-dbadd0b2  ami-60a54009  pending   1  m1.small  2009-05-14T12:38:24+0000  us-east-1a  aki-a71cf9ce  ari-a51cf9cc  monitoring-disabled
INSTANCE  i-ddadd0b4  ami-60a54009  pending   2  m1.small  2009-05-14T12:38:24+0000  us-east-1a  aki-a71cf9ce  ari-a51cf9cc  monitoring-disabled
previous page start next page