ec2-run-instances

Description

Launches a 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 (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.

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 (for example, 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, 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 ec2-run-instances command fails.

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] [--secondary-private-ip-address ip_address | --secondary-private-ip-address-count count] [-p, --iam-profile arn|name] | --ebs-optimized

Options

Name	Description
`ami_id`	The ID of the AMI, returned by a call to ec2-describe-images. Type: String Default: None Required: Yes Example: ami-15a4417c
`-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 (the default for each account is 20, but this limit can be increased). Required: No Example: -n 5-10
`-g`, `--group` `group`	The name of the security group. Type: String Default: None Required: No Example: -g websrv
`-k`, `--key` `keypair`	The name of the key pair. Type: String Default: None Required: No Example: -k websvr-keypair
`-d`, `--user-data` `user_data`	Base64-encoded MIME user data to be made available to the instance(s) in this reservation. Type: String Default: None Required: No Example: -d s3-bucket:my-logs
`-f`, `--user-data-file` `filename`	The file name of the user data to be made available to the instance(s) in this reservation. Type: String Default: None Required: No Example: -f user-data.txt
`--addressing`	Deprecated.
`-t`, `--instance-type` `instance_type`	The instance type. See Available Instance Types for more information. Type: String Valid values: `t1.micro` \| `m1.small` \| `m1.medium` \| `m1.large` \| `m1.xlarge` \| `m3.xlarge` \| `m3.2xlarge` \| `c1.medium` \| `c1.xlarge` \| `m2.xlarge` \| `m2.2xlarge` \| `m2.4xlarge` \| `cr1.8xlarge` \| `hi1.4xlarge` \| `hs1.8xlarge` \| `cc1.4xlarge` \| `cc2.8xlarge` \| `cg1.4xlarge` Default: m1.small Required: No Example: -t m1.large
`-z`, `--availability-zone` `zone`	The Availability Zone in which to run the instance. Type: String Default: None Required: No Example: --availability-zone us-east-1a
`--kernel` `kernel`	The ID of the kernel with which to launch the instance. Type: String Default: None Required: No Example: --kernel aki-ba3adfd3
`--ramdisk` `ramdisk`	The ID of the RAM disk to select. Note It is recommended that PV-GRUB be used instead of kernels and RAM disks. For more information, go to PV-GRUB: A New Amazon Kernel Image in the Amazon Elastic Compute Cloud User Guide. Type: String Default: None Required: No Example: --ramdisk ari-abcdef01
`-b, --block-device-mapping` `mapping`	The 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` - Suppresses an existing mapping of the device from the AMI used to launch the instance. For example: "`/dev/sdc=none`". `ephemeral[0..3]` - An instance store volume to be mapped to the device. For example: "`/dev/sdc=ephemeral0`". [snapshot-id]:[volume-size]:[true\|false]:[standard\|io1[:iops]] - An EBS volume to be mapped to the device. [snapshot-id] To create a volume from a snapshot, specify the snapshot ID. [volume-size] To create an empty EBS volume, omit the snapshot ID and specify a volume size instead. For example: "`/dev/sdh=:20`". [delete-on-termination] To prevent the volume from being deleted on termination of the instance, specify `false`. The default is `true`. [volume-type] To create a Provisioned IOPS volume, specify `io1`. The default volume type is `standard`. If the volume type is `io1`, you can also provision the number of IOPS that the volume supports. For example, "`/dev/sdh=snap-7eb96d16::false:io1:500`". You can specify multiple `blockdevicemapping` parameters in one call. For more detailed information about block device mapping, see Block Device Mapping in the Amazon Elastic Compute Cloud User Guide. Type: String Default: None Required: No Example: -b "/dev/sdb=snap-92d333fb::false" Note On Windows, the `mapping` argument must be enclosed in double quotes, as shown in the example.
`-m`, `--monitor`	Enables monitoring for the instance. Type: Boolean Default: Disabled Required: No Example: --monitor
`--disable-api-termination`	Whether the instance can be terminated using the EC2 API. A value of `true` means you can't terminate the instance using the API (the instance is "locked"). A value of `false` means you can terminate the instance using the API (the instance is "unlocked"). Set this attribute to `true` to prevent the instance from being terminated using the EC2 API. Type: Boolean Default: `false` Required: No Example: --disable-api-termination true
`--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` Required: No Example: --instance-initiated-shutdown-behavior stop
`--placement-group` `placement-group`	The name of the placement group. Type: String Valid values: `cluster` Default: None Required: No Example: --placement-group XYZ-cluster
`--tenancy` `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 Valid values: `default` \| `dedicated` Default: default Required: No Example: --tenancy dedicated
`-s`, `--subnet` `subnet_id`	[EC2-VPC] The ID of the subnet to launch the instance into. Type: String Default: None Required: No Example: -s subnet-f3e6ab83
`--private-ip-address` `ip_address`	[EC2-VPC] You can optionally use this parameter to assign the instance a specific available primary private IP address from the subnet. Type: String Default: We select an IP address from the IP address range of the subnet for the instance Required: No Example: --private-ip-address 10.0.0.25
`--secondary-private-ip-address` `IP_ADDRESS`	[EC2-VPC] Assigns the specified IP address as a secondary private IP address to the network interface or instance. This option can be used multiple times to assign multiple secondary IP addresses. You can do one of the following: Use the `-–secondary-private–ip-address` option without a value, and AWS will automatically assign a secondary private IP address within the subnet range. Use the `--secondary-private-ip-address` option and provide a specific IP address that you want to assign. On Windows clients, you must enclose the IP addresses in quotes. You cannot specify this parameter when also specifying `--secondary-private-ip-address-count`. Type: String Default: None Required: No Example: --secondary-private-ip-address "10.0.2.18" -–secondary-private-ip-address "10.0.2.28"
`--secondary-private-ip-address-count` `COUNT`	[EC2-VPC] The number of secondary IP addresses to assign to the network interface or instance. You cannot specify this parameter when also specifying `--secondary-private-ip-address` Type: Integer Default: None Required: No Example: --secondary-private-ip-address-count 2
`--client-token` `token`	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 Example: --client-token 550e8400-e29b-41d4-a716-446655440000
`-a,` `--network-interface NETWORKINTERFACE`	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`[:SIP `count` [:`SIPs`]]]]]]] where SGs is a comma separated list of security group IDs; DOT is either true or false, denoting whether to delete the interface on terminate; SIP count is the number of secondary IP addresses to assign; and SIPs is a list of secondary IP addresses. You cannot specify both SIP count and SIPs. Type: String Default: None Required: No 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` Launch an instance with a specific interface for index 0 with specific secondary IP addresses `ec2-run-instances ami-31814f58 -a eni-12345678:0 -a :1:subnet-15ca247d:"MyENI":::::"10.0.0.18,10.0.0.25"`
`-p`, `--iam-profile` `arn\|name`	The IAM instance profile to associate with the launched instance(s). IAM instance profiles enable you to manage permissions for applications running on EC2. This is either the Amazon Resource Name (ARN) of the instance profile (for example, arn:aws:iam::111111111111:instance-profile/s3access) or the name of the role (for example, s3access). Type: String Default: None Required: No Example: arn:aws:iam::111111111111:instance-profile/s3access
`--ebs-optimized` `Boolean`	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 option isn't available on all instance types. Additional usage charge apply when using this option. Type: Boolean Default: `false` Required: No Example: --ebs-optimized true

Common Options

Option	Description
`--region` `REGION`	Overrides the region specified by the `EC2_URL` environment variable and the URL specified by the `-U` option. Default: The value of the `EC2_URL` environment variable, or `us-east-1` if `EC2_URL` isn't set. Example: `--region eu-west-1`
`-U, --url` `URL`	The uniform resource locator (URL) of the Amazon EC2 web service entry point. Default: The value of the `EC2_URL` environment variable, or https://ec2.amazonaws.com if `EC2_URL` isn't set. Example: `-U https://ec2.amazonaws.com`
`-K, --private-key` `EC2-PRIVATE-KEY`	The private key that identifies you to Amazon EC2. For more information, see Tell the Tools Who You Are. Default: The value of the `EC2_PRIVATE_KEY` environment variable. If `EC2_PRIVATE_KEY` isn't set, you must specify this option. Example: `-K pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem`
`-C, --cert` `EC2-CERT`	The X.509 certificate that identifies you to Amazon EC2. Default: The value of the `EC2_CERT` environment variable. If `EC2_CERT` isn't set, you must specify this option. Example: `-C cert-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem`
`-O, --aws-access-key` `AWS_ACCESS_KEY`	The access key ID associated with your AWS account. For more information, see Tell the Tools Who You Are. Default: The value of the `AWS_ACCESS_KEY` environment variable. If `AWS_ACCESS_KEY` isn't set, you must specify this option. Example: `-O AKIAIOSFODNN7EXAMPLE` Note For more information, see the following section, Deprecated Options.
`-W, --aws-secret-key` `AWS_SECRET_KEY`	The secret access key associated with your AWS account. Default: The value of the `AWS_SECRET_KEY` environment variable. If `AWS_SECRET_KEY` isn't set, you must specify this option. Example: `-W wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY` Note For more information, see the following section, Deprecated Options.
`-T, --security-token TOKEN` `AWS_DELEGATION_TOKEN`	The AWS delegation token. Default: The value of the environment variable (if set).
`--connection-timeout` `TIMEOUT`	The connection timeout, in seconds. Example: `--connection-timeout 30`
`--request-timeout` `TIMEOUT`	The request timeout, in seconds. Example: `--request-timeout 45`
`-v, --verbose`	Displays verbose output, including the API request and response on the command line. This is useful if you are building tools to talk directly to our Query API.
`-H, --headers`	Includes column headers in the command output.
`--show-empty-fields`	Shows empty columns as `(nil)`.
`--hide-tags`	Omits tags for tagged resources.
`--debug`	Displays internal debugging information. This can assist us when helping you troubleshooting problems.
`-?, --help, -h`	Displays usage information for the command.
`-`	Reads arguments from standard input. This is useful when piping the output from one command to the input of another. Example: `ec2-describe-instances \| grep stopped \| cut -f 2 \| ec2-start-instances -`

Deprecated Options

For a limited time, you can still use the private key and X.509 certificate instead of your access key ID and secret access key. However, we recommend that you start using your access key ID (-O, --aws-access-key) and secret access key (-W, --aws-secret-key) now, as the private key (-K, --private-key) and X.509 certificate (-C, --cert) won't be supported after the transition period elapses. For more information, see Tell the Tools Who You Are.

Option Description

Option	Description
`-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-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.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-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem`

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

Output

This command returns a table that contains the following rows of information for each instance. Each field is separated by a comma. Some of these values may be empty.

The reservation information
- The RESERVATION identifier
- The ID of the reservation
- The AWS account ID of the instance owner
- The name of each security group the instance is in
The instance information
- The INSTANCE identifier
- The ID of the instance
- The AMI ID of the image on which the instance is based
- The public DNS name associated with the instance. This is only present for instances in the running state.
- The private DNS name associated with the instance. This is only present for instances in the running state.
- The state of the instance
- The key name. If a key was associated with the instance at launch, its name will appear.
- The AMI launch index
- The product codes associated with the instance
- The instance type
- The instance launch time
- The Availability Zone
- The ID of the kernel
- The ID of the RAM disk
- The platform (windows or empty)
- The monitoring state
- The public IP address
- The private IP address
- [EC2-VPC] The ID of the VPC
- [EC2-VPC] The subnet ID
- The type of root device (ebs or instance-store)
- The instance lifecycle
- The Spot Instance request ID
- The instance license
- The placement group the cluster instance is in
- The virtualization type (paravirtual or hvm)
- The hypervisor type (xen or ovm)
- The client token
- The ID of each security group the instance is in
- The tenancy of the instance (default or dedicated)
- Whether or not the instance is EBS optimized (true or false)
- The Amazon Resource Name (ARN) of the IAM role
[EC2-VPC] The network interface information. There will be a set of the following for each network interface
1. The network interface information
  - The NIC identifier
  - The network interface ID
  - The subnet ID
  - The VPC ID
  - The owner ID
  - The network interface status
  - The private IP address of the network interface
  - The private DNS name
  - Whether or not source destination check is enabled (true or false)
2. The network interface attachment information
  - The NICATTACHMENT identifier
  - The attachment ID
  - The device index
  - The device status
  - The attachment timestamp
  - Whether or not the attachment is deleted on termination (true or false)
3. The network interface association information
  - The NICASSOCIATION identifier
  - The public IP address
  - The public IP address owner
  - The private IP address
4. The security group information
  - The GROUP identifier
  - The security group identifier
  - The security group name
5. The private IP address information
  - The PRIVATEIPADDRESS identifier
  - The private IP address

Amazon EC2 command line tools display errors on stderr.

Examples

Example Request

This example launches three instances of the ami-1a2b3c4d AMI.

PROMPT> ec2-run-instances ami-1a2b3c4d -n 3 --availability-zone us-east-1a
RESERVATION	r-1a2b3c4d	111122223333	
INSTANCE	i-1a2b3c4d	ami-1a2b3c4d			pending	gsg-keypair	0		m1.small	YYYY-MM-DDTHH:MM:SS+0000	us-east-1a	aki-1a2b3c4d			monitoring-disabled					ebs					paravirtual	xen		sg-1a2b3c4d	default	false	
INSTANCE	i-2a2b3c4d	ami-1a2b3c4d			pending	gsg-keypair	1		m1.small	YYYY-MM-DDTHH:MM:SS+0000	us-east-1a	aki-1a2b3c4d			monitoring-disabled					ebs					paravirtual	xen		sg-1a2b3c4d	default	false	
INSTANCE	i-3a2b3c4d	ami-1a2b3c4d			pending	gsg-keypair	2		m1.small	YYYY-MM-DDTHH:MM:SS+0000	us-east-1a	aki-1a2b3c4d			monitoring-disabled					ebs					paravirtual	xen		sg-1a2b3c4d	default	false

Example Request

This example launches an Amazon EBS-based Windows image (ami-2879f118) and provides a block device mapping that mounts a public snapshot with the snap-1a2b3c4d ID.

PROMPT> ec2-run-instances ami-2879f118 -n 1 --b "/dev/sdb=snap-1a2b3c4d::false"
RESERVATION	r-1a2b3c4d	111122223333	
INSTANCE	i-1a2b3c4d	ami-84db39ed			pending	gsg-keypair	0		m1.small	YYYY-MM-DDTHH:MM:SS+0000	us-east-1c			windows	monitoring-disabled					ebs					hvm	xen		sg-1a2b3c4d	default	false

Example Request

This example launches an instance with a primary IP address of 10.0.0.146 and two secondary private IP addresses of 10.0.0.148 and of 10.0.0.150 in subnet-1a2b3c4d.

PROMPT> ec2-run-instances ami-1a2b3c4d -k gsg-keypair -s subnet-1a2b3c4d -t c1.medium --private-ip-address 10.0.0.146 --secondary-private-ip-address 10.0.0.148 --secondary-private-ip-address 10.0.0.150
RESERVATION	r-1a2b3c4d	111122223333		
INSTANCE	i-1a2b3c4d	ami-1a2b3c4d			pending	gsg-keypair	0		c1.medium	YYYY-MM-DDTHH:MM:SS+0000	us-west-2b			windows	monitoring-disabled		10.0.0.146	vpc-1a2b3c4d	subnet-1a2b3c4d	ebs					hvm	xen		sg-1a2b3c4d	dedicated	false	
NIC	eni-1a2b3c4d	subnet-1a2b3c4d	vpc-1a2b3c4d	111122223333	in-use	10.0.1.146		true
NICATTACHMENT	eni-attach-1a2b3c4d	0	attaching	YYYY-MM-DDTHH:MM:SS+0000	true
GROUP	sg-1a2b3c4d	default
PRIVATEIPADDRESS	10.0.0.146
PRIVATEIPADDRESS	10.0.0.148
PRIVATEIPADDRESS	10.0.0.150

Example Request

This example launches a Dedicated Instance into a VPC.

PROMPT> ec2-run-instances ami-1a2b3c4d --tenancy dedicated -s subnet-1a2b3c4d

Document Conventions	« Previous Next »
Terms of Use	Did this page help you? Yes \| No \| Tell us about it...

Description

Syntax

Options

Common Options

Deprecated Options

Output

Examples

Example Request

Example Request

Example Request

Example Request

Related Topics

Download

Related Action

AWS Documentation » Amazon EC2 » Command Line Reference » Commands (CLI Tools) » ec2-run-instances	« Previous Next »
	Did this page help you? Yes \| No \| Tell us about it...

ec2-run-instances

Description

Syntax

Options

Common Options

Deprecated Options

Output

Examples

Example Request

Example Request

Example Request

Example Request

Related Topics

Download

Related Action

Related Commands