ec2-run-instances

Amazon Elastic Compute Cloud: 2009-03-01

previous page next page

ec2-run-instances

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] [ --instance-type instance_type] [ --availability-zone zone] [ --kernel kernel_id] [ --ramdisk ramdisk_id] [ --block-device-mappingblock_device_mapping]

Description

Launches one or more instances of the specified AMI.

Every instance is launched in a security group. If you do not specify a security group at launch, the instances start in your default security group. For more information on creating security groups, see

CreateSecurityGroup.

An optional instance type can be specified. For information about instance types, see Instance Types.

You can provide an optional key pair ID for each image in the launch request (for more information, see CreateKeyPair). 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, see Instance Metadata.

[Note]Note

If the AMI has a Amazon DevPay product code attached for which the user has not subscribed, the ec2-run-instances call will fail.

[Important]Important

We strongly recommend using the 2.6.18 Xen stock kernel with the c1.medium and c1.xlarge 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, see Kernels, RAM Disks, and Block Device Mappings.

Options

Option Description Required

ami_id

The identifier that was assigned to the AMI when it was registered.

Example: r-15a4417c

Yes

-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.

Default: 1

Example: -n 5

No

-g group

The security group(s) within which to launch the instances. This determines the ingress firewall rules applied to the instances. If you specify more than one group, the security policy will be the union of the security policies of the specified groups.

Default: The default group.

Example: -g fooGroup

No

-k keyname

The key pair to make available to these instances at boot.

Example: -k fooKeyPair

No

-d user_data

Data to make available to the instances. This data is read from the command line of the USER_DATA argument. If you want the data to be read from a file, see the -f option.

Example: -d "my user data"

No

-f user_data_file

Data to make available to these instances. The data is read from the file specified by FILE_NAME. To specify user data on the command line, use the -d option.

Example: -f data.zip

No

--instance-type instance_type

The type of instance to launch. For more information, see Instance Types.

Example: --instance-type m1.small

No

--availability-zone zone

The Availability Zone in which to launch the instance(s). For more information, see ec2-describe-availability-zones.

Example: us-east-1a

No

--kernel kernel_id

The ID of the kernel with which to launch the instance. For information on finding available kernel IDs, see ec2-describe-images.

Example: --kernel aki-ba3adfd3

No

--ramdisk ramdisk_id

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.

Example: --ramdisk ari-badbad00

No

--block-device-mapping mappings

Default block-device-mapping scheme with which to launch the AMI. This defines how block devices are exposed to an instance of this AMI if the instance type supports the specified device.

The scheme is a comma-separated list of key=value pairs, where each key is a virtual name and each value is the desired device name. Virtual names include:

  • ami—The root file system device, as seen by the instance

  • root—The root file system device, as seen by the kernel

  • swap—The swap device, as seen by the instance

  • ephemeralN—The Nth ephemeral store

Example: --block-device-mapping ami=sda1,root=/dev/sda1,ephemeral0=sda2,swap=sda3

Example: --block-device-mapping ami=0,root=/dev/dsk/c0d0s0,ephemeral0=1

No

Output

Amazon EC2 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. For more information, see Instance Metadata.

  • Instance type. For more information on instance types, see Instance Types.

  • Instance launch time. Specifies when the instance launched.

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

Amazon EC2 displays errors on stderr.

Example

This example launches five instances of the ami-6ba54002 AMI.

PROMPT> ec2-run-instances ami-6ba54002 -n 5 --availability-zone us-east-1a 
RESERVATION r-0ea54067 495219933132 default
INSTANCE i-3ea74257 ami-6ba54002 pending 0 m1.small 2007-07-11T16:40:44+0000 us-east-1a
INSTANCE i-31a74258 ami-6ba54002 pending 1 m1.small 2007-07-11T16:40:44+0000 us-east-1a
INSTANCE i-31a74259 ami-6ba54002 pending 2 m1.small 2007-07-11T16:40:44+0000 us-east-1a
INSTANCE i-31a7425a ami-6ba54002 pending 3 m1.small 2007-07-11T16:40:44+0000 us-east-1a
INSTANCE i-31a7425b ami-6ba54002 pending 4 m1.small 2007-07-11T16:40:44+0000 us-east-1a
INSTANCE i-31a7425c ami-6ba54002 pending 5 m1.small 2007-07-11T16:40:44+0000 us-east-1a

Related Topics

previous page start next page