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 of 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 allocates the remaining available instances using round robin.

	Note
	Every instance is launched in a security group (which you create using the `ec2-create-group` command). If you don't specify a security group at launch time, the "default" security group is used.

For Linux instances, you can provide an optional key pair ID in the launch request (created using the ec2-create-keypair or ec2-import-keypair command). 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.

The public key material is made available to the Linux 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.

	Important
	Launching public images without a key pair ID will leave them inaccessible.

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 an Amazon DevPay product code attached for which the user has not subscribed, the `ec2-run-instances` command will fail.

The short version of this command is ec2run.

Syntax

ec2-run-instances ami_id [-n instance_count] [-g group [-g group ...]] [-k keypair] [-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-mapping block_device_mapping] [--monitor] [--disable-api-termination] [--instance-initiated-shutdown-behavior behavior] [--placement-group placement-group] [--tenancy tenancy] [--subnet subnet_id] [--private-ip-address ip_address] [--client-token token] [--network-interface networkinterface]

Options

Name Description Required

ami_id

Unique ID of a machine image, returned by a call to ec2-describe-images.

Type: String

Default: None

Example: ami-15a4417c

Yes

-n , --instance-count min[-max]

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: 1

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

Example: -n 5-10

No

-g, --group group

Name of the security group.

Type: String

Default: None

Example: -g websrv

No

-k, --key keypair

The name of the key pair.

Type: String

Default: None

Example: -k websvr-keypair

No

-d, --user-data user_data

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

Type: String

Default: None

Example: -d s3-bucket:my-logs

No

-f, --user-data-file filename

Specifies the filename of the user data to be made available to the instance(s) in this reservation.

Type: String

Default: None

Example: -f user-data.txt

No

--addressing

Deprecated.

-t, --instance-type instance_type

Specifies the instance type.

Type: String

Default: m1.small

Example: -t m1.large

No

--availability-zone zone

The Availability Zone in which to run the instance.

Type: String

Default: None

Example: --availability-zone us-east-1a

No

--kernel kernel

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

Type: String

Default: None

Example: --kernel aki-ba3adfd3

No

--ramdisk ramdisk

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

Example: --ramdisk ari-abcdef01

No

-b, --block-device-mapping mapping

Defines a block device mapping for the instance. This argument is passed in the form of <devicename>=<blockdevice>. The devicename is the device name of the physical device on the instance to map. The blockdevice can be one of the following values:

none - specifies that the existing mapping on the specified image for this device should be suppressed. For example: /dev/sdc=none
ephemeral[0..3] - indicates that an instance local storage device should be mapped to this device. Example: /dev/sdc=ephemeral0
[snapshot-id]:[size]:[delete-on-termination (true|false)] - this value can be used to map a device to an existing EBS-backed volume by specifying an existing volume name. You can specify a new EBS-backed volume by skipping the snapshot ID and passing in a volume size instead; for example: /dev/sdb=:20. You can also specify whether the Amazon EBS volume should be deleted on termination; this value is true by default.

	Note
	The device mapping argument must be surrounded by double quotes on Windows systems.

You may specify multiple blockdevicemapping arguments in one call.

For more detailed information on block device mapping, go to Block Device Mapping in the Amazon Elastic Compute Cloud User Guide.

Type: String

Default: None

Example: -b "/dev/sdb=snap-92d333fb::false"

No

-m, --monitor

Enables monitoring for the instance.

Type: Boolean

Default: Disabled

Example: --monitor

No

--disable-api-termination

Disables the ability to terminate the instance using the EC2 API (i.e., "locks" the instance). To re-enable this ability, you must change the disableApiTermination attribute's value to false using ec2-modify-instance-attribute.

Type: String

Default: False (you can terminate the instance using the API)

Example: --disable-api-termination

No

--instance-initiated-shutdown-behavior behavior

If an instance shutdown is initiated, this determines whether the instance stops or terminates.

Type: String

Valid Values: stop | terminate

Default: stop

Example: --instance-initiated-shutdown-behavior stop

No

--placement-group placement-group

Name of the placement group.

Type: String

Valid Values: cluster

Default: None

Example: --placement-group XYZ-cluster

No

--tenancy 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: String

Valid Values: default | dedicated

Default: default

Example: --tenancy dedicated

No

-s, --subnet subnet_id

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

Example: -s subnet-f3e6ab83

No

--private-ip-address ip_address

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.

Type: String

Default: Amazon VPC selects an IP address from the subnet for the instance

Example: --private-ip-address 10.0.0.25

No

--client-token token

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

Example: --client-token 550e8400-e29b-41d4-a716-446655440000

No

-a, --network-interface NETWORKINTERFACE

Specifies the network attachment for the launched instance. The format of the NETWORKINTERFACE definition is as follows:

For an existing NETWORKINTERFACE - eni:dev index

For a new NETWORKINTERFACE - dev index:subnet[:description[:priv IP[:SGs[:DOT]]]] where SGs is a comma separated list of security group IDs and DOT is either true or false, denoting whether to delete the interface on terminate.

Type: String

Default: None

Examples:

Launch an instance with a specific interface for index 0 ec2run ami-0644f007 -a eni-d2b24dbb:0
Launch an instance and specify interfaces for both index 0 and index 1 ec2run ami-0644f007 -a eni-d2b24dbb:0 -a eni-12345678:1
Launch an instance and autocreate an interface for index 0 with details and a specific interface for index 1 ec2-run-instances ami-31814f58 -a :0:subnet-15ca247d:"My ENI" –a eni-12345678:1
Launch an instance with a specific interface for index 0 and autocreate an interface for index 1 with specific values ec2-run-instances ami-31814f58 -a eni-12345678:0 -a :1:subnet-15ca247d:"My ENI":10.0.0.10:sg-123456,sg-654321:false

No

Common Options

Option	Description
`--region` `REGION`	Overrides the Region specified in the `EC2_URL` environment variable and the URL specified by the `-U` option. Default: The `EC2_URL` environment variable, or `us-east-1` if the environment variable is not set. Example: `--region eu-west-1`
`-U, --url` `URL`	`URL` is the uniform resource locator of the Amazon EC2 web service entry point. Default: The `EC2_URL` environment variable, or https://ec2.amazonaws.com if the environment variable is not set. Example: `-U https://ec2.amazonaws.com`
`-K, --private-key` `EC2-PRIVATE-KEY`	The private key to use when constructing requests to Amazon EC2. Default: The value of the `EC2_PRIVATE_KEY` environment variable. Example: `-K pk-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem`
`-C, --cert` `EC2-CERT`	The X.509 certificate to use when constructing requests to Amazon EC2. Default: The value of the `EC2_CERT` environment variable. Example: `-C cert-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem`
`--connection-timeout` `TIMEOUT`	Specifies a connection timeout (in seconds). Example: --connection-timeout 30
`--request-timeout` `TIMEOUT`	Specifies a request timeout (in seconds). Example: --request-timeout 45
`-v, --verbose`	Displays verbose output by showing the SOAP request and response on the command line. This is particularly useful if you are building tools to talk directly to our SOAP API.
`-H, --headers`	Displays column headers in the output.
`--show-empty-fields`	Shows empty columns as `(nil)`.
`--hide-tags`	Do not display tags for tagged resources.
`--debug`	Prints internal debugging information. This is useful to assist us when troubleshooting problems.
`-?, --help, -h`	Displays Help.
`-`	If `-` is specified as an argument to one of the parameters, a list of arguments is read from standard input. This is useful for piping the output of one command into the input of another. Example: `ec2-describe-instances \| grep stopped \| cut -f 2 \| ec2-start-instances -`

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
Instance state. This is usually pending, which indicates that the instance(s) are preparing to launch
Key pair name (if a key pair was associated with the instance at launch)
AMI launch index
Product code (if the AMI has a product code)
Instance type
Instance launch time
Availability Zone
Kernel ID
RAM disk ID
Monitoring status
Root device type (ebs or instance-store)
Placement group the cluster instance is in
The tenancy of the instance launched (if it is running within a VPC).
Virtualization type (paravirtual or hvm)
Hypervisor type (xen or ovm)

Amazon EC2 command line tools display errors on stderr.

Examples

Example Request

This example launches three instances of the ami-b232d0db AMI.

PROMPT> ec2-run-instances ami-b232d0db -n 3 --availability-zone us-east-1a
				
RESERVATION r-385c5950 012301230123 default
INSTANCE  i-5bca5a30  ami-b232d0db  pending  0  m1.small 2010-04-07T12:25:47+0000  us-east-1a  aki-94c527fd  ari-96c527ff  monitoring-disabled  ebs  paravirtual  xen
INSTANCE  i-59ca5a32  ami-b232d0db  pending  1  m1.small 2010-04-07T12:25:47+0000  us-east-1a  aki-94c527fd  ari-96c527ff  monitoring-disabled  ebs  paravirtual  xen
INSTANCE  i-5fca5a34  ami-b232d0db  pending  2  m1.small 2010-04-07T12:25:47+0000  us-east-1a  aki-94c527fd  ari-96c527ff  monitoring-disabled  ebs  paravirtual  xen

Example Request

This example launches an Amazon EBS-based Fedora image (ami-84db39ed) and provides a block device mapping that mounts a public snapshot containing the 2000 US Census data.

PROMPT> ec2-run-instances ami-84db39ed -n 1 --b "/dev/sdb=snap-92d333fb::false"

RESERVATION     r-5488ce3c      054794666394    default
INSTANCE   i-770af21c  ami-84db39ed   pending   0   m1.small    2010-02-25T00:08:00+0000   us-east-1c  aki-94c527fd    ari-96c527ff      monitoring-disabled   ebs  paravirtual  xen

Description

Syntax

Options

Common Options

Output

Examples

Example Request

Example Request

Related Operations