Menu
Amazon Elastic Compute Cloud
CLI Reference (API Version 2015-10-01)

ec2-request-spot-instances

Description

Creates a Spot Instance request. Spot Instances are instances that Amazon EC2 launches when the bid price that you specify exceeds the current Spot Price. Amazon EC2 periodically sets the Spot Price based on available Spot Instance capacity and current Spot Instance requests. For more information, see Spot Instance Requests in the Amazon EC2 User Guide for Linux Instances.

Note

Although you can specify encrypted EBS volumes in the launch specification for your Spot Instances, these volumes are not encrypted.

The short version of this command is ec2rsi.

Tip

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

Syntax

ec2-request-spot-instances ami_id --price price [--instance-count count] [--type type] [--valid-from timestamp] [--valid-until timestamp] [--launch-group group] [--availability-zone-group group] [--user-data data | --user-data-file data-file] [--group group [--group group ...]] [--key key-pair] [--instance-type type] [--subnet subnet_id] [--availability-zone zone] [--kernel kernel] [--ramdisk ramdisk] [--block-device-mapping mapping] [--monitor] [--iam-profile arn | name] [--network-attachment attachment] [[--secondary-private-ip-address ip_address] | [--secondary-private-ip-address-count count]] [--ebs-optimized] [--associate-public-ip-address Boolean]

Options

NameDescription

ami_id

The ID of the AMI.

Type: String

Default: None

Required: Yes

Example: ami-2bb65342

-p, --price price

The maximum hourly price for any Spot Instance launched to fulfill the request.

Type: String

Default: None

Required: Yes

Example: -p .15

-n, --instance-count count

The maximum number of Spot Instances to launch.

Type: xs:integer

Default: 1

Required: No

Example: -n 10

-r, --type type

The Spot Instance request type.

Type: String

Valid values: one-time | persistent

Default: one-time

Required: No

Example: -r persistent

-s, --subnet subnet_id

The ID of the subnet in which to launch the Spot Instance.

Type: String

Default: None

Required: No

Example: -s subnet-bab943d3

--valid-from date

The start date of the request. If this is a one-time request, the request becomes active at this date and time and remains active until all instances launch, the request expires, or the request is canceled. If the request is persistent, the request becomes active at this date and time and remains active until it expires or is canceled.

Type: DateTime

Default: Request is effective immediately.

Required: No

Example: --valid-from 2009-12-31T11:51:50

--valid-until date

The end date of the request. If this is a one-time request, the request remains active until all instances launch, the request is canceled, or this date is reached. If the request is persistent, it remains active until it is canceled or this date and time is reached.

Type: DateTime

Default: Request is effective immediately.

Required: No

Example: --valid-until 2009-12-31T11:51:50

--launch-group group

The instance launch group. Launch groups are Spot Instances that launch together and terminate together.

Type: String

Default: Instances are launched and terminated individually.

Required: No

Example: --launch-group Skynet

--availability-zone-group group

The user-specified name for a logical grouping of bids.

When you specify --availability-zone-group in a Spot Instance request, all Spot Instances in the request are launched in the same Availability Zone. Instance proximity is maintained with this parameter, but choice of Availability Zone is not. --availability-zone-group applies only to bids for Spot Instances of the same instance type. Any additional Spot Instance requests that are specified with the same --availability-zone-group name will be launched in that same Availability Zone, as long as at least one instance from the group is still active.

If there is no active instance running in the Availability Zone group that you specify for a new Spot Instance request (for example, all instances are terminated, the bid is expired, or the bid falls below current market), then Amazon EC2 will launch the instance in any Availability Zone where the constraint can be met. Consequently, the subsequent set of Spot Instances could be placed in a different zone from the original request, even if the same --availability-zone-group name was specified.

To ensure that all Spot Instances across all bids are launched into a particular Availability Zone, specify LaunchSpecification.Placement.AvailabilityZone in the API or --availability-zone in the CLI.

Type: String

Default: Instances are launched in any available Availability Zone.

Required: No

Example: --availability-zone-group batchGroup01

--placement-group group_name

The name of an existing placement group you want to launch the instance into (for cluster instances).

Type: String

Default: Instances are launched in the default placement group.

Required: No

Example: --placement-group default

-d, --user-data user_data

The user data to make available to the instances.

Type: String

Default: None

Required: No

Example: -d "My user data"

-g, --group group

The ID of the security group. Note that you can't specify this option if you specify the --subnet option. Use the --network-attachment option to specify both a subnet and a security group.

Type: String

Default: User's default group.

Required: No

Example: -g sg-1a2b3c4d

-k, --key key_name

The name of the key pair.

Type: String

Default: None

Required: No

Example: -k my-key-pair

-t, --instance-type instance_type

The instance type.

Type: String

Valid values: t1.micro | m1.small | m1.medium | m1.large | m1.xlarge | m3.xlarge | m3.2xlarge | c1.medium | c1.xlarge | c3.4xlarge | c3.8xlarge | cc1.4xlarge | cc2.8xlarge | cg1.4xlarge | cr1.8xlarge | g2.2xlarge | m2.xlarge | m2.2xlarge | m2.4xlarge. For more information, see Instance Types in the Amazon EC2 User Guide for Linux Instances.

Required: No

Example: -t m1.large

-z, --availability-zone zone

The placement constraint (for example, a specific Availability Zone) for launching the instances.

Specify whether you want all of the Spot Instances in all of your bids to be launched in a particular Availability Zone. Specifying this option requires Amazon EC2 to find capacity in the specified Availability Zone instead of letting Amazon EC2 pick the best Availability Zone available; this can potentially delay the fulfillment of your bid, or require a higher bid price.

Type: String

Default: Amazon EC2 selects an Availability Zone in the current region.

Required: No

Example: -z us-east-1b

--kernel kernel

The ID of the kernel to select.

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

The ID of the RAM disk to select.

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

-b, --block-device-mapping mapping

An entry for the block device mapping for the instance. 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.

Each entry is passed in the form <devicename>=<blockdevice>. The devicename is the device name of the physical device on the instance to map, and 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".

  • ephemeraln – An instance store volume to be mapped to the device. Instance store volumes are numbered starting from 0. An instance type with 2 available instance store volumes can specify mappings for ephemeral0 and ephemeral1. For example: "/dev/sdc=ephemeral0".

  • [snapshot-id]:[volume-size]:[delete-on-termination]:[volume-type[:iops]]:[encrypted] – An Amazon EBS volume to map to the device.

    [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 deletion on instance termination, specify false. The default for the root volume is true and the default for other volumes is false. For more information, see Preserving Amazon EBS Volumes on Instance Termination in the Amazon EC2 User Guide for Linux Instances.

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

    To encrypt the volume, specify true. Volumes created from encrypted snapshots are automatically encrypted. An encrypted Amazon EBS volume must be attached to an instance that supports Amazon EBS encryption. If your AMI uses an encrypted volume, you must launch it using a supported instance type. For more information, see Amazon EBS Encryption 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.

--monitor

Enables monitoring for the instance.

Type: String

Default: Disabled

Required: No

Example: --monitor

--iam-profile arn|name

The IAM instance profile to associate with the launched instances. IAM instance profiles enable you to manage permissions for applications running on Amazon 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: --iam-profile arn:aws:iam::111111111111:instance-profile/s3access

-a, --network-attachment attachment

[EC2-VPC] The network attachment for the instance.

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

eni_id:index

The format when creating a network interface is as follows:

:index[:subnet[:desc[:private_ip[:groups[:DOT[:count[:secondary_ips]]]]]]]

Note that groups is a comma-separated list of security group IDs, DOT is either true or false, indicating whether to delete the interface on instance termination, count is the number of secondary IP addresses to assign, and secondary_ips is a list of secondary IP addresses. You can't specify both count and secondary_ips.

Type: String

Default: None

Required: No

Example 1: -a eni-d2b24dbb:0

Example 2: -a ":0:subnet-c9663da0:::sg-bab943d3"

--secondary-private-ip-address ip_address

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. This option is only available for instances running in a VPC. You can't specify this parameter when also specifying --secondary-private-ip-address-count.

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.

Note

On Windows clients, you must enclose IP addresses in quotes.

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

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. This option is only available for instances running in a VPC.

Type: Integer

Default: None

Required: No

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

--associate-public-ip-address Boolean

Indicates whether to assign an AWS public IP address to the instance that will be launched. Instances launched into a default subnet are assigned a public IP address by default. For information about instance IP addressing, see Amazon EC2 Instance IP Addressing.

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

--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 on all instance types. Additional usage charges apply when using this option.

Type: Boolean

Default: Disabled

Required: No

Example: --ebs-optimized

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 information for each Spot Instance request:

The Spot Instance request information

  • The SPOTINSTANCEREQUEST identifier

  • The ID of the Spot instance request

  • The Spot instance bid price

  • The Spot instance type (one-time or persistent)

  • The product description (Linux/UNIX or Windows)

  • The state of the Spot instance request (active, open, closed, cancelled, failed)

  • The date and time the request was created

  • The date and time that the request is valid until

  • The date and time the request will be held until

  • The launch group

  • The Availability Zone group

  • The ID of the instance

  • The ID of the image

  • The instance type

  • The key pair name

  • Any security groups the request belongs to

  • The Availability Zone the instance belongs to

  • The kernel ID of the instance

  • The RAM disk ID of the instance

  • The monitoring status

  • The ID of the subnet

  • The Availability Zone the instance was launched to

  • The IAM profile

Any Spot Instance faults

  • The SPOTINSTANCEFAULT identifier

  • The Spot instance fault code

  • The Spot instance fault message

The Spot Instance status information

  • The SPOTINSTANCESTATUS identifier

  • The Spot instance status

  • The date and time of the last update

  • The Spot Instance status message

Amazon EC2 command line tools display errors on stderr.

Examples

Example

This example command creates a Spot Instance request for three m1.small instances.

PROMPT>  ec2-request-spot-instances ami-1a2b3c4d -p 0.04 --key my-key-pair --group default --instance-type m1.small -n 3 --type one-time
SPOTINSTANCEREQUEST	sir-1a2b3c4d	0.040000	one-time	Linux/UNIX	open	YYYY-MM-DDTHH:MM:SS-0800						ami-1a2b3c4d	m1.small	my-key-pair	sg-1a2b3c4d				monitoring-disabled			
SPOTINSTANCESTATUS	pending-evaluation	YYYY-MM-DDTHH:MM:SS-0800	Your Spot request has been submitted for review, and is pending evaluation.
SPOTINSTANCEREQUEST	sir-2a2b3c4d	0.040000	one-time	Linux/UNIX	open	YYYY-MM-DDTHH:MM:SS-0800						ami-1a2b3c4d	m1.small	my-key-pair	sg-1a2b3c4d				monitoring-disabled			
SPOTINSTANCESTATUS	pending-evaluation	YYYY-MM-DDTHH:MM:SS-0800	Your Spot request has been submitted for review, and is pending evaluation.
SPOTINSTANCEREQUEST	sir-3a2b3c4d	0.040000	one-time	Linux/UNIX	open	YYYY-MM-DDTHH:MM:SS-0800						ami-1a2b3c4d	m1.small	my-key-pair	sg-1a2b3c4d				monitoring-disabled			
SPOTINSTANCESTATUS	pending-evaluation	YYYY-MM-DDTHH:MM:SS-0800	Your Spot request has been submitted for review, and is pending evaluation.

Related Topics

Setting Up

IAM Policies

You can create an IAM policy to grant users permission to use this command. For more information, see IAM Policies for Amazon EC2 in the Amazon EC2 User Guide for Linux Instances.

Related Action