Amazon Elastic Compute Cloud
CLI Reference (API Version 2014-09-01)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Did this page help you?  Yes | No |  Tell us about it...

ec2-run-instances

Description

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

When you launch an instance, it enters the pending state. After the instance is ready for you, it enters the running state. To check the state of your instance, use the ec2-describe-instances command.

If you don't specify a security group when launching an instance, Amazon EC2 uses the default security group. For more information, see Security Groups in the Amazon EC2 User Guide for Linux Instances.

Linux instances have access to the public key of the key pair at boot. You can use this key to provide secure access to the instance. Amazon EC2 public images use this feature to provide secure access without passwords. For more information, see Key Pairs in the Amazon EC2 User Guide for Linux Instances.

You can provide optional user data when launching an instance. For more information, see Instance Metadata in the Amazon EC2 User Guide for Linux Instances.

Warning

If any of the AMIs have a product code attached for which the user has not subscribed, ec2-run-instances fails.

T2 instance types can only be launched into a VPC. If you do not have a default VPC, or if you do not specify a subnet ID in the request, RunInstances fails.

For more information about troubleshooting, see What To Do If An Instance Immediately Terminates, and Troubleshooting Connecting to Your Instance in the Amazon EC2 User Guide for Linux Instances.

The short version of this command is ec2run.

Tip

If you are using the AWS CLI, see run-instances instead.

Syntax

ec2-run-instances ami_id [-n instance_count] [-k keypair] [-g group [-g group ...]] [-d user_data | -f filename] [--instance-type instance_type] [--availability-zone zone] [--placement-group group_name] [--tenancy tenancy] [--kernel kernel_id] [--ramdisk ramdisk_id] [--block-device-mapping mapping] [--monitor] [--subnet subnet_id] [--disable-api-termination] [--instance-initiated-shutdown-behavior behavior] [--private-ip-address ip_address] [--client-token token] [--secondary-private-ip-address ip_address | --secondary-private-ip-address-count count] [--network-attachment attachment] [--iam-profile arn | name] [--ebs-optimized] [--associate-public-ip-address Boolean]

Options

NameDescription

ami_id

The ID of the AMI, which you can get by calling ec2-describe-images.

Type: String

Default: None

Required: Yes

Example: ami-5da964c3

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

The number of instances to launch. If you specify a minimum that is more instances than Amazon EC2 can launch in the target Availability Zone, Amazon EC2 launches no instances. If you specify a range (min-max), Amazon EC2 tries to launch the maximum number in the target Availability Zone, but launches no fewer than the minimum number.

Type: String

Default: 1

Constraints: Between 1 and the maximum number you're allowed for the specified instance type. For more information about the default limits, and how to request an increase, see How many instances can I run in Amazon EC2 in the Amazon EC2 General FAQ.

Required: No

Example: -n 5-10

-k, --key keypair

The name of the key pair. You can create a key pair using ec2-create-keypair or ec2-import-keypair.

Important

If you launch an instance without specifying a key pair, you can't connect to the instance.

Type: String

Default: None

Required: No

Example: -k my-key-pair

-g, --group group

One or more security groups. For a nondefault VPC, you must specify the security group by ID. For EC2-Classic or a default VPC, you can specify the security group by name or ID. You can create a security group using ec2-create-group.

Type: String

Default: Amazon EC2 uses the default security group

Required: No

Example: -g my-security-group

-d, --user-data user_data

The base64-encoded MIME user data for the instances.

Type: String

Default: None

Required: No

Example: -d s3-bucket:my-logs

-f, --user-data-file filename

The file name of the user data for the instances.

Type: String

Default: None

Required: No

Example: -f user-data.txt

-t, --instance-type instance_type

The instance type. For more information, see Instance Types in the Amazon EC2 User Guide for Linux Instances.

Type: String

Valid values: t2.micro | t2.small | t2.medium | m3.medium | m3.large | m3.xlarge | m3.2xlarge | m1.small | m1.medium | m1.large | m1.xlarge | c3.large | c3.xlarge | c3.2xlarge | c3.4xlarge | c3.8xlarge | c1.medium | c1.xlarge | cc2.8xlarge | r3.large | r3.xlarge | r3.2xlarge | r3.4xlarge | r3.8xlarge | m2.xlarge | m2.2xlarge | m2.4xlarge | cr1.8xlarge | i2.xlarge | i2.2xlarge | i2.4xlarge | i2.8xlarge | hs1.8xlarge | hi1.4xlarge | t1.micro | g2.2xlarge | cg1.4xlarge

Default: m1.small

Required: No

Example: -t m1.large

-z, --availability-zone zone

The Availability Zone for the instance.

Type: String

Default: Amazon EC2 selects the Availability Zone

Required: No

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

--placement-group group_name

The name of an existing placement group.

Type: String

Default: None

Required: No

Example: --placement-group my-placement-group

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

--kernel kernel_id

The ID of the kernel for the instance.

Important

We recommend that you use PV-GRUB instead of kernels and RAM disks. For more information, see PV-GRUB in the Amazon EC2 User Guide for Linux Instances.

Type: String

Default: None

Required: No

Example: --kernel aki-ba3adfd3

--ramdisk ramdisk_id

The ID of the RAM disk.

Important

We recommend that you use PV-GRUB instead of kernels and RAM disks. For more information, see PV-GRUB in the Amazon EC2 User Guide for Linux Instances.

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]:[delete-on-termination]:[volume-type[:iops]]:[encrypted] - An Amazon EBS volume to be mapped to the device. For example "/dev/sdh=snap-7eb96d16::false:io1:500:encrypted".

    [snapshot-id]

    To create a volume from a snapshot, specify the snapshot ID.

    [volume-size]

    To create an empty Amazon 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 istrue.

    [volume-type]

    The default volume type is standard. To create a General Purpose (SSD) volume, specify gp2. To create a Provisioned IOPS (SSD) volume, specify io1. If the volume type is io1, you must also specify the number of IOPS that the volume should support. For more information, see Amazon EBS Volume Types in the Amazon EC2 User Guide for Linux Instances.

    [iops]

    The number of provisioned IOPS that the volume supports (this option is only valid with io1 volume types).

    [encrypted]

    Indicates that the volume should be encrypted. Encrypted Amazon EBS volumes may only be attached to instances that support Amazon EBS encryption. Volumes that are created from encrypted snapshots are automatically encrypted. There is no way to create an encrypted volume from an unencrypted snapshot or vice versa. If your AMI uses encrypted volumes, you can only launch it on supported instance types. For more information, see Amazon EBS Encryption in the Amazon EC2 User Guide for Linux Instances.

You can specify multiple --block-device-mapping options in one call.

For more information, see Block Device Mapping in the Amazon EC2 User Guide for Linux Instances.

Type: String

Default: None

Required: No

Example: -b "/dev/sdc=snap-7eb96d16:100:false:io1:500"

Note

On Windows, the mapping argument must be enclosed in double quotes, as shown in the example.

Note

For M3 instances, you must specify instance store volumes in the block device mapping for the instance. When you launch an M3 instance, we ignore any instance store volumes specified in the block device mapping for the AMI.

-m, --monitor

Enables monitoring for the instance.

Type: Boolean

Default: Disabled

Required: No

Example: --monitor

-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

--disable-api-termination

If you enable this option, you can't terminate the instance using the Amazon EC2 console, CLI, or API; otherwise, you can. If you specify this option and then later want to be able to terminate the instance, you must first change the value of the disableApiTermination attribute to false using ec2-modify-instance-attribute. Alternatively, if you set --instance-initiated-shutdown-behavior to terminate, you can terminate the instance by running the shutdown command from the instance.

Type: Boolean

Default: Disabled

Required: No

Example: --disable-api-termination

--instance-initiated-shutdown-behavior behavior

Indicates whether an instance stops or terminates when you initiate shutdown from the instance (using the operating system command for system shutdown).

Type: String

Valid values: stop | terminate

Default: stop

Required: No

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

--private-ip-address ip_address

[EC2-VPC] The primary private IP address. You must specify a value from the IP address range of the subnet.

Type: String

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

Required: No

Example: --private-ip-address 10.0.0.25

--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 EC2 User Guide for Linux Instances.

Type: String

Default: None

Constraints: Maximum 64 ASCII characters

Required: No

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

--secondary-private-ip-address ip_address

[EC2-VPC] A secondary private IP address for the network interface or instance. You can specify this 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 can't 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 can't specify this parameter when also specifying --secondary-private-ip-address.

Type: Integer

Default: None

Required: No

Example: --secondary-private-ip-address-count 2

-a, --network-attachment attachment

The network attachment for the instance.

The format when creating a network interface is as follows:

:index[:subnet[:desc[:IP[:groups[:DOT[:count[:SIPs]]]]]]]

  • index - The device index.

  • subnet - The ID of the subnet.

  • desc - A description.

  • IP - The primary private IP address.

  • groups - A comma-separated list of security group IDs.

  • DOT - A Boolean value that indicates whether to delete the network interface on instance termination. You can specify true only when creating a network interface.

  • count - The count of secondary IP addresses. You can't specify both count and SIPs.

  • SIPs - A comma-separated list of secondary IP addresses.

The format when using an existing network interface is as follows: eni_id:index

Type: String

Default: None

Required: No

Examples:

Use an existing network interface for index 0:

-a eni-d2b24dbb:0

Use existing network interfaces for index 0 and index 1:

-a eni-d2b24dbb:0 -a eni-12345678:1

Create a network interface for index 0 and use an existing network interface for index 1:

-a :0:subnet-15ca247d:"My ENI" -a eni-12345678:1

Use an existing network interface for index 0 and create a network interface for index 1:

-a eni-12345678:0 -a :1:subnet-15ca247d:"My ENI":"10.0.0.10":sg-123456,sg-654321:false

Use an existing network interface for index 0 with specific secondary IP addresses:

-a eni-12345678:0 -a :1:subnet-15ca247d:"My ENI":::::"10.0.0.18,10.0.0.25"

-p, --iam-profile arn|name

The IAM instance profile to associate with the instances. This is either the Amazon Resource Name (ARN) of the instance profile or the name of the role.

Type: String

Default: None

Required: No

Example: arn:aws:iam::111111111111:instance-profile/s3access

Example: s3access

--ebs-optimized

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

Type: Boolean

Default: Disabled

Required: No

Example: --ebs-optimized

--associate-public-ip-address Boolean

[EC2-VPC] Indicates whether to assign a public IP address to an instance. The public IP address is assigned to a specific network interface. If set to true, the following rules apply:

  • Can only be assigned to a single network interface with the device index of 0. You can't assign a public IP address to a second network interface, and you can't assign a public IP address if you are launching with more than one network interface.

  • Can only be assigned to a new network interface, not an existing one.

Type: Boolean

Default: If launching into a default subnet, the default value is true. If launching into a nondefault subnet, the default value is false.

Required: No

Example: --associate-public-ip-address true

Common Options

OptionDescription

--region region

The region. Overrides the default region, the region specified by the EC2_URL environment variable, and the URL specified by the -U option.

Default: The region specified by the EC2_URL environment variable, or us-east-1 if EC2_URL isn't set.

-U, --url url

The uniform resource locator (URL) of the Amazon EC2 web service entry point.

Default: The endpoint specified by the EC2_URL environment variable, or https://ec2.amazonaws.com if EC2_URL isn't set.

-O, --aws-access-key aws_access_key_id

Your access key ID. 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

-W, --aws-secret-key aws_secret_access_key

Your secret access key.

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

-T, --security-token delegation_token

The delegation token to pass along to the AWS request. This is only required when you are using temporary security credentials. For more information, see Using Temporary Security Credentials.

Default: The value of the AWS_DELEGATION_TOKEN environment variable (if set).

Example: -t AQoDYXdzEJr...<remainder of security token>

--connection-timeout timeout

The connection timeout, in seconds.

Example: --connection-timeout 30

--request-timeout timeout

The request timeout, in seconds.

Example: --request-timeout 45

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

-D, --auth-dry-run

Checks whether you have the required permissions for the command, without actually running the command. If you have the required permissions, the command returns DryRunOperation; otherwise, it returns UnauthorizedOperation.

-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 the Query API.

-

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 -

-?, --help, -h

Displays usage information for the command.

Deprecated Options

We have deprecated the SOAP API for Amazon EC2. For more information, see SOAP Requests. From version 1.6.14.0 onwards of the Amazon EC2 CLI tools, the private key (-K, --private-key) and X.509 certificate (-C, --cert) options are not supported. Use your access key ID (-O, --aws-access-key) and secret access key (-W, --aws-secret-key) instead. For more information, see Setting Up the Amazon EC2 CLI and AMI Tools.

OptionDescription

-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. Some fields may be empty.

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

  2. 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 ID of the subnet

    • 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

  3. [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 ID of the network interface

      • The ID of the subnet

      • The ID of the VPC

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

This example command launches an Amazon EBS-backed instance with a Provisioned IOPS (SSD) root volume instead of the default Magnetic volume by specifying io1:iops. You can also choose a General Purpose (SSD) volume as your root volume by specifying gp2 in the block device mapping. You can change the root volume type by changing the default block device mapping of the AMI. To find the original block device mapping of an AMI, use the ec2-describe-images command with the image ID of the AMI you want to launch.

PROMPT> ec2-describe-images ami-978d91fe
IMAGE	ami-978d91fe	amazon/amzn-ami-hvm-2014.03.1.x86_64-ebs	amazon	available	public		x86_64	machine				ebs	hvm	xen
BLOCKDEVICEMAPPING	EBS	/dev/xvda		snap-b011716d	8	true	standard		Not Encrypted

In the above example, the root volume block device mapping is /dev/xvda=snap-b011716d:8:true:standard. To launch this AMI with a 100 GiB Provisioned IOPS (SSD) volume with 1,000 provisioned IOPS, use the following command.

PROMPT> ec2-run-instances ami-978d91fe -k my-key-pair --instance-type m3.large -b "/dev/xvda=snap-b011716d:100:true:io1:1000"

To launch this AMI with a 100 GiB General Purpose (SSD) volume, use the following command.

PROMPT> ec2-run-instances ami-978d91fe -k my-key-pair --instance-type m3.large -b "/dev/xvda=snap-b011716d:100:true:gp2"

Example 2

This example command launches three instances using the AMI with the ID ami-1a2b3c4d AMI.

PROMPT> ec2-run-instances ami-1a2b3c4d -n 3 -k my-key-pair --availability-zone us-east-1a
RESERVATION	r-1a2b3c4d	111122223333	
INSTANCE	i-1a2b3c4d	ami-1a2b3c4d			pending	my-key-pair	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	my-key-pair	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	my-key-pair	2		m1.small	YYYY-MM-DDTHH:MM:SS+0000	us-east-1a	aki-1a2b3c4d			monitoring-disabled					ebs					paravirtual	xen		sg-1a2b3c4d	default	false				

Example 3

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

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

Example 4

This example command 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 the subnet with the ID subnet-1a2b3c4d.

PROMPT> ec2-run-instances ami-1a2b3c4d -k my-key-pair -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	my-key-pair	0		c1.medium	YYYY-MM-DDTHH:MM:SS+0000	us-west-2a			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 5

This example command launches a Dedicated Instance into the specified subnet.

PROMPT> ec2-run-instances ami-1a2b3c4d -k my-key-pair --tenancy dedicated -s subnet-1a2b3c4d

Example 6

This example command launches an instance into a nondefault subnet, and requests a public IP address. The public IP address is assigned to the eth0 network interface.

PROMPT> ec2-run-instances ami-1a2b3c4d -k my-key-pair -s subnet-1a2b3c4d --associate-public-ip-address true

Example 7

This example command launches an m1.large instance with a block device mapping. There are two instance store volumes mapped to /dev/sdc and /dev/sdd, and a 100 GiB Amazon EBS volume mapped to /dev/sdf.

PROMPT> ec2-run-instances ami-1a2b3c4d -k my-key-pair --instance-type m1.large -b "/dev/sdc=ephemeral0" -b "/dev/sdd=ephemeral1" -b "/dev/sdf=:100:0"