Amazon Elastic Compute Cloud: User Guide For Linux Instances
Amazon Elastic Compute Cloud: User Guide For Linux Instances
Amazon Elastic Compute Cloud: User Guide For Linux Instances
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not
Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or
discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may
or may not be affiliated with, connected to, or sponsored by Amazon.
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Table of Contents
What Is Amazon EC2? ......................................................................................................................... 1
Features of Amazon EC2 ............................................................................................................. 1
How to Get Started with Amazon EC2 .......................................................................................... 1
Related Services ......................................................................................................................... 2
Accessing Amazon EC2 ............................................................................................................... 3
Pricing for Amazon EC2 .............................................................................................................. 3
PCI DSS Compliance ................................................................................................................... 4
Instances and AMIs ..................................................................................................................... 4
Instances ........................................................................................................................... 5
AMIs ................................................................................................................................. 6
Regions and Availability Zones ..................................................................................................... 6
Region and Availability Zone Concepts .................................................................................. 7
Available Regions ............................................................................................................... 8
Regions and Endpoints ....................................................................................................... 9
Describing Your Regions and Availability Zones ...................................................................... 9
Specifying the Region for a Resource .................................................................................. 11
Launching Instances in an Availability Zone ......................................................................... 13
Migrating an Instance to Another Availability Zone ............................................................... 13
Root Device Volume ................................................................................................................. 14
Root Device Storage Concepts ........................................................................................... 14
Choosing an AMI by Root Device Type ................................................................................ 15
Determining the Root Device Type of Your Instance .............................................................. 16
Changing the Root Device Volume to Persist ........................................................................ 16
Setting Up ....................................................................................................................................... 19
Sign Up for AWS ...................................................................................................................... 19
Create an IAM User .................................................................................................................. 19
Create a Key Pair ..................................................................................................................... 21
Create a Virtual Private Cloud (VPC) ........................................................................................... 24
Create a Security Group ............................................................................................................ 24
Getting Started ................................................................................................................................ 27
Overview ................................................................................................................................. 27
Prerequisites ............................................................................................................................ 28
Step 1: Launch an Instance ........................................................................................................ 28
Step 2: Connect to Your Instance ............................................................................................... 29
Step 3: Clean Up Your Instance .................................................................................................. 29
Next Steps ............................................................................................................................... 29
Best Practices .................................................................................................................................. 31
Tutorials .......................................................................................................................................... 33
Install a LAMP Server (Amazon Linux 2) ...................................................................................... 33
Step 1: Prepare the LAMP Server ....................................................................................... 33
Step 2: Test Your LAMP Server ........................................................................................... 37
Step 3: Secure the Database Server .................................................................................... 38
Step 4: (Optional) Install phpMyAdmin ................................................................................ 39
Troubleshooting ............................................................................................................... 41
Related Topics ................................................................................................................. 41
Install a LAMP Server (Amazon Linux AMI) .................................................................................. 42
Step 1: Prepare the LAMP Server ....................................................................................... 42
Step 2: Test Your Lamp Server ........................................................................................... 46
Step 3: Secure the Database Server .................................................................................... 47
Step 4: (Optional) Install phpMyAdmin ................................................................................ 48
Troubleshooting ............................................................................................................... 51
Related Topics ................................................................................................................. 52
Tutorial: Hosting a WordPress Blog ............................................................................................. 52
Prerequisites .................................................................................................................... 53
iii
Amazon Elastic Compute Cloud
User Guide for Linux Instances
iv
Amazon Elastic Compute Cloud
User Guide for Linux Instances
v
Amazon Elastic Compute Cloud
User Guide for Linux Instances
vi
Amazon Elastic Compute Cloud
User Guide for Linux Instances
vii
Amazon Elastic Compute Cloud
User Guide for Linux Instances
viii
Amazon Elastic Compute Cloud
User Guide for Linux Instances
ix
Amazon Elastic Compute Cloud
User Guide for Linux Instances
x
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Features of Amazon EC2
For more information about cloud computing, see What is Cloud Computing?
For more information about the features of Amazon EC2, see the Amazon EC2 product page.
For more information about running your website on AWS, see Web Hosting.
1
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Related Services
Basics
Storage
• AWS Systems Manager Run Command in the AWS Systems Manager User Guide
• Tutorial: Install a LAMP Web Server on Amazon Linux 2 (p. 33)
• Tutorial: Configure SSL/TLS on Amazon Linux 2 (p. 60)
• Getting Started with AWS: Hosting a Web App for Linux
If you have questions about whether AWS is right for you, contact AWS Sales. If you have technical
questions about Amazon EC2, use the Amazon EC2 forum.
Related Services
You can provision Amazon EC2 resources, such as instances and volumes, directly using Amazon EC2.
You can also provision Amazon EC2 resources using other services in AWS. For more information, see the
following documentation:
To automatically distribute incoming application traffic across multiple instances, use Elastic Load
Balancing. For more information, see Elastic Load Balancing User Guide.
To monitor basic statistics for your instances and Amazon EBS volumes, use Amazon CloudWatch. For
more information, see the Amazon CloudWatch User Guide.
2
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Accessing Amazon EC2
To automate actions, such as activating a Lambda function whenever a new Amazon EC2 instance starts,
or invoking AWS Systems Manager Run Command whenever an event in another AWS service happens,
use Amazon CloudWatch Events. For more information, see the Amazon CloudWatch Events User Guide.
To monitor the calls made to the Amazon EC2 API for your account, including calls made by the
AWS Management Console, command line tools, and other services, use AWS CloudTrail. For more
information, see the AWS CloudTrail User Guide.
To get a managed relational database in the cloud, use Amazon Relational Database Service (Amazon
RDS) to launch a database instance. Although you can set up a database on an EC2 instance, Amazon
RDS offers the advantage of handling your database management tasks, such as patching the software,
backing up, and storing the backups. For more information, see Amazon Relational Database Service
Developer Guide.
To import virtual machine (VM) images from your local environment into AWS and convert them into
ready-to-use AMIs or instances, use VM Import/Export. For more information, see the VM Import/Export
User Guide.
If you prefer to use a command line interface, you have the following options:
Provides commands for a broad set of AWS products, and is supported on Windows, Mac, and Linux.
To get started, see AWS Command Line Interface User Guide. For more information about the
commands for Amazon EC2, see ec2 in the AWS CLI Command Reference.
AWS Tools for Windows PowerShell
Provides commands for a broad set of AWS products for those who script in the PowerShell
environment. To get started, see the AWS Tools for Windows PowerShell User Guide. For more
information about the cmdlets for Amazon EC2, see the AWS Tools for PowerShell Cmdlet
Reference.
Amazon EC2 provides a Query API. These requests are HTTP or HTTPS requests that use the HTTP verbs
GET or POST and a Query parameter named Action. For more information about the API actions for
Amazon EC2, see Actions in the Amazon EC2 API Reference.
If you prefer to build applications using language-specific APIs instead of submitting a request over
HTTP or HTTPS, AWS provides libraries, sample code, tutorials, and other resources for software
developers. These libraries provide basic functions that automate tasks such as cryptographically signing
your requests, retrying requests, and handling error responses, making it is easier for you to get started.
For more information, see AWS SDKs and Tools.
3
Amazon Elastic Compute Cloud
User Guide for Linux Instances
PCI DSS Compliance
On-Demand Instances
Pay for the instances that you use by the second, with no long-term commitments or upfront
payments.
Reserved Instances
Make a low, one-time, up-front payment for an instance, reserve it for a one- or three-year term, and
pay a significantly lower hourly rate for these instances.
Spot Instances
Request unused EC2 instances, which can lower your costs significantly.
For a complete list of charges and specific prices for Amazon EC2, see Amazon EC2 Pricing.
To calculate the cost of a sample provisioned environment, see Cloud Economics Center.
To see your bill, go to the Billing and Cost Management Dashboard in the AWS Billing and Cost
Management console. Your bill contains links to usage reports that provide details about your bill. To
learn more about AWS account billing, see AWS Account Billing.
If you have questions concerning AWS billing, accounts, and events, contact AWS Support.
For an overview of Trusted Advisor, a service that helps you optimize the costs, security, and performance
of your AWS environment, see AWS Trusted Advisor.
4
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instances
Your instances keep running until you stop or terminate them, or until they fail. If an instance fails, you
can launch a new one from the AMI.
Instances
An instance is a virtual server in the cloud. Its configuration at launch is a copy of the AMI that you
specified when you launched the instance.
You can launch different types of instances from a single AMI. An instance type essentially determines
the hardware of the host computer used for your instance. Each instance type offers different compute
and memory capabilities. Select an instance type based on the amount of memory and computing power
that you need for the application or software that you plan to run on the instance. For more information
about the hardware specifications for each Amazon EC2 instance type, see Amazon EC2 Instance Types.
After you launch an instance, it looks like a traditional host, and you can interact with it as you would any
computer. You have complete control of your instances; you can use sudo to run commands that require
root privileges.
Your AWS account has a limit on the number of instances that you can have running. For more
information about this limit, and how to request an increase, see How many instances can I run in
Amazon EC2 in the Amazon EC2 General FAQ.
Your instance may include local storage volumes, known as instance store volumes, which you
can configure at launch time with block device mapping. For more information, see Block Device
Mapping (p. 977). After these volumes have been added to and mapped on your instance, they are
available for you to mount and use. If your instance fails, or if your instance is stopped or terminated,
the data on these volumes is lost; therefore, these volumes are best used for temporary data. To keep
important data safe, you should use a replication strategy across multiple instances, or store your
persistent data in Amazon S3 or Amazon EBS volumes. For more information, see Storage (p. 827).
5
Amazon Elastic Compute Cloud
User Guide for Linux Instances
AMIs
When an instance is stopped, the instance performs a normal shutdown, and then transitions to a
stopped state. All of its Amazon EBS volumes remain attached, and you can start the instance again at a
later time.
You are not charged for additional instance usage while the instance is in a stopped state. A minimum of
one minute is charged for every transition from a stopped state to a running state. If the instance type
was changed while the instance was stopped, you will be charged the rate for the new instance type
after the instance is started. All of the associated Amazon EBS usage of your instance, including root
device usage, is billed using typical Amazon EBS prices.
When an instance is in a stopped state, you can attach or detach Amazon EBS volumes. You can also
create an AMI from the instance, and you can change the kernel, RAM disk, and instance type.
Terminating an instance
When an instance is terminated, the instance performs a normal shutdown. The root device volume is
deleted by default, but any attached Amazon EBS volumes are preserved by default, determined by each
volume's deleteOnTermination attribute setting. The instance itself is also deleted, and you can't
start the instance again at a later time.
To prevent accidental termination, you can disable instance termination. If you do so, ensure that
the disableApiTermination attribute is set to true for the instance. To control the behavior
of an instance shutdown, such as shutdown -h in Linux or shutdown in Windows, set the
instanceInitiatedShutdownBehavior instance attribute to stop or terminate as desired.
Instances with Amazon EBS volumes for the root device default to stop, and instances with instance-
store root devices are always terminated as the result of an instance shutdown.
AMIs
Amazon Web Services (AWS) publishes many Amazon Machine Images (AMIs) that contain common
software configurations for public use. In addition, members of the AWS developer community have
published their own custom AMIs. You can also create your own custom AMI or AMIs; doing so enables
you to quickly and easily start new instances that have everything you need. For example, if your
application is a website or a web service, your AMI could include a web server, the associated static
content, and the code for the dynamic pages. As a result, after you launch an instance from this AMI,
your web server starts, and your application is ready to accept requests.
All AMIs are categorized as either backed by Amazon EBS, which means that the root device for an
instance launched from the AMI is an Amazon EBS volume, or backed by instance store, which means
that the root device for an instance launched from the AMI is an instance store volume created from a
template stored in Amazon S3.
The description of an AMI indicates the type of root device (either ebs or instance store). This is
important because there are significant differences in what you can do with each type of AMI. For more
information about these differences, see Storage for the Root Device (p. 97).
6
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Region and Availability Zone Concepts
Amazon operates state-of-the-art, highly-available data centers. Although rare, failures can occur that
affect the availability of instances that are in the same location. If you host all your instances in a single
location that is affected by such a failure, none of your instances would be available.
Contents
• Region and Availability Zone Concepts (p. 7)
• Available Regions (p. 8)
• Regions and Endpoints (p. 9)
• Describing Your Regions and Availability Zones (p. 9)
• Specifying the Region for a Resource (p. 11)
• Launching Instances in an Availability Zone (p. 13)
• Migrating an Instance to Another Availability Zone (p. 13)
Amazon EC2 resources are either global, tied to a Region, or tied to an Availability Zone. For more
information, see Resource Locations (p. 986).
Regions
Each Amazon EC2 Region is designed to be completely isolated from the other Amazon EC2 Regions.
This achieves the greatest possible fault tolerance and stability.
When you view your resources, you'll only see the resources tied to the Region you've specified. This
is because Regions are isolated from each other, and we don't replicate resources across Regions
automatically.
When you launch an instance, you must select an AMI that's in the same Region. If the AMI is in another
Region, you can copy the AMI to the Region you're using. For more information, see Copying an
AMI (p. 154).
Note that there is a charge for data transfer between Regions. For more information, see Amazon EC2
Pricing - Data Transfer.
Availability Zones
When you launch an instance, you can select an Availability Zone or let us choose one for you. If you
distribute your instances across multiple Availability Zones and one instance fails, you can design your
application so that an instance in another Availability Zone can handle requests.
7
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Available Regions
You can also use Elastic IP addresses to mask the failure of an instance in one Availability Zone by rapidly
remapping the address to an instance in another Availability Zone. For more information, see Elastic IP
Addresses (p. 724).
An Availability Zone is represented by a Region code followed by a letter identifier; for example,
us-east-1a. To ensure that resources are distributed across the Availability Zones for a Region, we
independently map Availability Zones to names for each AWS account. For example, the Availability Zone
us-east-1a for your AWS account might not be the same location as us-east-1a for another AWS
account.
To coordinate Availability Zones across accounts, you must use the AZ ID, which is a unique and
consistent identifier for an Availability Zone. For example, use1-az1 is an AZ ID for the us-east-1
Region and it has the same location in every AWS account.
Viewing AZ IDs enables you to determine the location of resources in one account relative to the
resources in another account. For example, if you share a subnet in the Availability Zone with the AZ ID
use-az2 with another account, this subnet is available to that account in the Availability Zone whose AZ
ID is also use-az2. The AZ ID for each VPC and subnet is displayed in the Amazon VPC console. For more
information, see Working with VPC Sharing in the Amazon VPC User Guide.
As Availability Zones grow over time, our ability to expand them can become constrained. If this
happens, we might restrict you from launching an instance in a constrained Availability Zone unless you
already have an instance in that Availability Zone. Eventually, we might also remove the constrained
Availability Zone from the list of Availability Zones for new accounts. Therefore, your account might have
a different number of available Availability Zones in a Region than another account.
You can list the Availability Zones that are available to your account. For more information, see
Describing Your Regions and Availability Zones (p. 9).
Available Regions
Your account determines the Regions that are available to you. For example:
• An AWS account provides multiple Regions so that you can launch Amazon EC2 instances in locations
that meet your requirements. For example, you might want to launch instances in Europe to be closer
to your European customers or to meet legal requirements.
• An AWS GovCloud (US-West) account provides access to the AWS GovCloud (US-West) Region only. For
more information, see AWS GovCloud (US-West) Region.
• An Amazon AWS (China) account provides access to the Beijing and Ningxia Regions only. For more
information, see AWS in China.
The following table lists the Regions provided by an AWS account. You can't describe or access additional
Regions from an AWS account, such as AWS GovCloud (US-West) or the China Regions.
Code Name
8
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Regions and Endpoints
Code Name
eu-central-1 EU (Frankfurt)
eu-west-1 EU (Ireland)
eu-west-2 EU (London)
eu-west-3 EU (Paris)
eu-north-1 EU (Stockholm)
The number and mapping of Availability Zones per Region may vary between AWS accounts. To get a
list of the Availability Zones that are available to your account, you can use the Amazon EC2 console
or the command line interface. For more information, see Describing Your Regions and Availability
Zones (p. 9).
For more information about endpoints and protocols in AWS GovCloud (US-West), see AWS GovCloud
(US-West) Endpoints in the AWS GovCloud (US) User Guide.
9
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Describing Your Regions and Availability Zones
To find your Regions and Availability Zones using the command line
1. [AWS CLI] Use the describe-regions command as follows to describe the Regions for your account.
2. [AWS CLI] Use the describe-availability-zones command as follows to describe the Availability Zones
within the specified Region.
10
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Specifying the Region for a Resource
3. [AWS Tools for Windows PowerShell] Use the Get-EC2Region command as follows to describe the
Regions for your account.
PS C:\> Get-EC2Region
4. [AWS Tools for Windows PowerShell] Use the Get-EC2AvailabilityZone command as follows to
describe the Availability Zones within the specified Region.
11
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Specifying the Region for a Resource
You can set the value of an environment variable to the desired regional endpoint (for example,
https://ec2.us-east-2.amazonaws.com):
Alternatively, you can use the --region (AWS CLI) or -Region (AWS Tools for Windows PowerShell)
command line option with each individual command. For example, --region us-east-2.
12
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launching Instances in an Availability Zone
For more information about the endpoints for Amazon EC2, see Amazon Elastic Compute Cloud
Endpoints.
When you launch an instance, you can optionally specify an Availability Zone in the Region that you
are using. If you do not specify an Availability Zone, we select one for you. When you launch your initial
instances, we recommend that you accept the default Availability Zone, because this enables us to select
the best Availability Zone for you based on system health and available capacity. If you launch additional
instances, only specify an Availability Zone if your new instances must be close to, or separated from,
your running instances.
The migration process involves creating an AMI from the original instance, launching an instance in the
new Availability Zone, and updating the configuration of the new instance, as shown in the following
procedure.
1. Create an AMI from the instance. The procedure depends on the operating system and the type of
root device volume for the instance. For more information, see the documentation that corresponds
to your operating system and root device volume:
13
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Root Device Volume
You can choose between AMIs backed by Amazon EC2 instance store and AMIs backed by Amazon EBS.
We recommend that you use AMIs backed by Amazon EBS, because they launch faster and use persistent
storage.
For more information about the device names Amazon EC2 uses for your root volumes, see Device
Naming on Linux Instances (p. 975).
Topics
• Root Device Storage Concepts (p. 14)
• Choosing an AMI by Root Device Type (p. 15)
• Determining the Root Device Type of Your Instance (p. 16)
• Changing the Root Device Volume to Persist (p. 16)
Instances that use instance stores for the root device automatically have one or more instance store
volumes available, with one volume serving as the root device volume. When an instance is launched, the
image that is used to boot the instance is copied to the root volume. Note that you can optionally use
additional instance store volumes, depending on the instance type.
Any data on the instance store volumes persists as long as the instance is running, but this data is
deleted when the instance is terminated (instance store-backed instances do not support the Stop
action) or if it fails (such as if an underlying drive has issues).
After an instance store-backed instance fails or terminates, it cannot be restored. If you plan to use
Amazon EC2 instance store-backed instances, we highly recommend that you distribute the data on
14
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Choosing an AMI by Root Device Type
your instance stores across multiple Availability Zones. You should also back up critical data from your
instance store volumes to persistent storage on a regular basis.
For more information, see Amazon EC2 Instance Store (p. 956).
Instances that use Amazon EBS for the root device automatically have an Amazon EBS volume attached.
When you launch an Amazon EBS-backed instance, we create an Amazon EBS volume for each Amazon
EBS snapshot referenced by the AMI you use. You can optionally use other Amazon EBS volumes or
instance store volumes, depending on the instance type.
An Amazon EBS-backed instance can be stopped and later restarted without affecting data stored in the
attached volumes. There are various instance– and volume-related tasks you can do when an Amazon
EBS-backed instance is in a stopped state. For example, you can modify the properties of the instance,
change its size, or update the kernel it is using, or you can attach your root volume to a different running
instance for debugging or any other purpose.
If an Amazon EBS-backed instance fails, you can restore your session by following one of these methods:
15
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Determining the Root Device Type of Your Instance
3. From the filter lists, select the image type (such as Public images). In the search bar choose
Platform to select the operating system (such as Amazon Linux), and Root Device Type to select
EBS images.
4. (Optional) To get additional information to help you make your choice, choose the Show/Hide
Columns icon, update the columns to display, and choose Close.
5. Choose an AMI and write down its AMI ID.
To verify the type of the root device volume of an AMI using the command line
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
To determine the root device type of an instance using the command line
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
16
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Changing the Root Device Volume to Persist
To change the root device volume of an instance to persist at launch using the console
You can verify the setting by viewing details for the root device volume on the instance's details pane.
Next to Block devices, choose the entry for the root device volume. By default, Delete on termination is
True. If you change the default behavior, Delete on termination is False.
Example at Launch
Use the run-instances command to preserve the root volume by including a block device mapping that
sets its DeleteOnTermination attribute to false.
[
{
"DeviceName": "/dev/sda1",
"Ebs": {
"DeleteOnTermination": false
}
}
]
You can confirm that DeleteOnTermination is false by using the describe-instances command and
looking for the BlockDeviceMappings entry for the device in the command output, as shown here.
...
"BlockDeviceMappings": [
{
"DeviceName": "/dev/sda1",
"Ebs": {
"Status": "attached",
"DeleteOnTermination": false,
"VolumeId": "vol-1234567890abcdef0",
"AttachTime": "2013-07-19T02:42:39.000Z"
}
17
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Changing the Root Device Volume to Persist
}
...
Use the modify-instance-attribute command to preserve the root volume by including a block device
mapping that sets its DeleteOnTermination attribute to false.
[
{
"DeviceName": "/dev/sda1",
"Ebs" : {
"DeleteOnTermination": false
}
}
]
18
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Sign Up for AWS
If you haven't signed up for AWS yet, or if you need assistance launching your first instance, complete the
following tasks to get set up to use Amazon EC2:
With Amazon EC2, you pay only for what you use. If you are a new AWS customer, you can get started
with Amazon EC2 for free. For more information, see AWS Free Tier.
If you have an AWS account already, skip to the next task. If you don't have an AWS account, use the
following procedure to create one.
1. Open https://portal.aws.amazon.com/billing/signup.
2. Follow the online instructions.
Part of the sign-up procedure involves receiving a phone call and entering a verification code on the
phone keypad.
Note your AWS account number, because you'll need it for the next task.
19
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Create an IAM User
If you signed up for AWS but have not created an IAM user for yourself, you can create one using the IAM
console. If you aren't familiar with using the console, see Working with the AWS Management Console
for an overview.
To create an administrator user for yourself and add the user to an administrators group
(console)
1. Use your AWS account email address and password to sign in as the AWS account root user to the
IAM console at https://console.aws.amazon.com/iam/.
Note
We strongly recommend that you adhere to the best practice of using the Administrator
IAM user below and securely lock away the root user credentials. Sign in as the root user
only to perform a few account and service management tasks.
2. In the navigation pane, choose Users and then choose Add user.
3. For User name, enter Administrator.
4. Select the check box next to AWS Management Console access. Then select Custom password, and
then enter your new password in the text box.
5. (Optional) By default, AWS requires the new user to create a new password when first signing in. You
can clear the check box next to User must create a new password at next sign-in to allow the new
user to reset their password after they sign in.
6. Choose Next: Permissions.
7. Under Set permissions, choose Add user to group.
8. Choose Create group.
9. In the Create group dialog box, for Group name enter Administrators.
10. Choose Filter policies, and then select AWS managed -job function to filter the table contents.
11. In the policy list, select the check box for AdministratorAccess. Then choose Create group.
Note
You must activate IAM user and role access to Billing before you can use the
AdministratorAccess permissions to access the AWS Billing and Cost Management
console. To do this, follow the instructions in step 1 of the tutorial about delegating access
to the billing console.
12. Back in the list of groups, select the check box for your new group. Choose Refresh if necessary to
see the group in the list.
13. Choose Next: Tags.
14. (Optional) Add metadata to the user by attaching tags as key-value pairs. For more information
about using tags in IAM, see Tagging IAM Entities in the IAM User Guide.
15. Choose Next: Review to see the list of group memberships to be added to the new user. When you
are ready to proceed, choose Create user.
You can use this same process to create more groups and users and to give your users access to your AWS
account resources. To learn about using policies that restrict user permissions to specific AWS resources,
see Access Management and Example Policies.
To sign in as this new IAM user, sign out of the AWS console, then use the following URL, where
your_aws_account_id is your AWS account number without the hyphens (for example, if your AWS
account number is 1234-5678-9012, your AWS account ID is 123456789012):
https://your_aws_account_id.signin.aws.amazon.com/console/
Enter the IAM user name (not your email address) and password that you just created. When you're
signed in, the navigation bar displays "your_user_name @ your_aws_account_id".
20
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Create a Key Pair
If you don't want the URL for your sign-in page to contain your AWS account ID, you can create an
account alias. From the IAM console, choose Dashboard in the navigation pane. From the dashboard,
choose Customize and enter an alias such as your company name. To sign in after you create an account
alias, use the following URL:
https://your_account_alias.signin.aws.amazon.com/console/
To verify the sign-in link for IAM users for your account, open the IAM console and check under IAM
users sign-in link on the dashboard.
For more information about IAM, see IAM and Amazon EC2 (p. 622).
If you haven't created a key pair already, you can create one using the Amazon EC2 console. Note that if
you plan to launch instances in multiple regions, you'll need to create a key pair in each region. For more
information about regions, see Regions and Availability Zones (p. 6).
1. Sign in to AWS using the URL that you created in the previous section.
2. From the AWS dashboard, choose EC2 to open the Amazon EC2 console.
3. From the navigation bar, select a region for the key pair. You can select any region that's available to
you, regardless of your location. However, key pairs are specific to a region; for example, if you plan
to launch an instance in the US East (Ohio) Region, you must create a key pair for the instance in the
US East (Ohio) Region.
21
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Create a Key Pair
4. In the navigation pane, under NETWORK & SECURITY, choose Key Pairs.
Tip
The navigation pane is on the left side of the console. If you do not see the pane, it might
be minimized; choose the arrow to expand the pane. You may have to scroll down to see the
Key Pairs link.
22
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Create a Key Pair
If you do not set these permissions, then you cannot connect to your instance using this key pair. For
more information, see Error: Unprotected Private Key File (p. 1025).
For more information, see Amazon EC2 Key Pairs (p. 598).
To connect to your Linux instance from a computer running Mac or Linux, you'll specify the .pem file to
your SSH client with the -i option and the path to your private key. To connect to your Linux instance
from a computer running Windows, you can use either MindTerm or PuTTY. If you plan to use PuTTY,
you'll need to install it and use the following procedure to convert the .pem file to a .ppk file.
4. Choose Load. By default, PuTTYgen displays only files with the extension .ppk. To locate your .pem
file, select the option to display files of all types.
23
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Create a Virtual Private Cloud (VPC)
5. Select the private key file that you created in the previous procedure and choose Open. Choose OK
to dismiss the confirmation dialog box.
6. Choose Save private key. PuTTYgen displays a warning about saving the key without a passphrase.
Choose Yes.
7. Specify the same name for the key that you used for the key pair. PuTTY automatically adds the
.ppk file extension.
For more information about VPCs, see the Amazon VPC User Guide.
Note that if you plan to launch instances in multiple regions, you'll need to create a security group in
each region. For more information about regions, see Regions and Availability Zones (p. 6).
Prerequisites
You'll need the public IPv4 address of your local computer. The security group editor in the Amazon
EC2 console can automatically detect the public IPv4 address for you. Alternatively, you can use the
search phrase "what is my IP address" in an Internet browser, or use the following service: Check IP. If
you are connecting through an Internet service provider (ISP) or from behind a firewall without a static IP
address, you need to find out the range of IP addresses used by client computers.
24
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Create a Security Group
25
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Create a Security Group
5. Enter a name for the new security group and a description. Use a name that is easy for you to
remember, such as your IAM user name, followed by _SG_, plus the region name. For example,
me_SG_uswest2.
6. In the VPC list, select your VPC. If you have a default VPC, it's the one that is marked with an asterisk
(*).
7. On the Inbound tab, create the following rules (choose Add Rule for each new rule), and then
choose Create:
• Choose HTTP from the Type list, and make sure that Source is set to Anywhere (0.0.0.0/0).
• Choose HTTPS from the Type list, and make sure that Source is set to Anywhere (0.0.0.0/0).
• Choose SSH from the Type list. In the Source box, choose My IP to automatically populate
the field with the public IPv4 address of your local computer. Alternatively, choose Custom
and specify the public IPv4 address of your computer or network in CIDR notation. To
specify an individual IP address in CIDR notation, add the routing suffix /32, for example,
203.0.113.25/32. If your company allocates addresses from a range, specify the entire range,
such as 203.0.113.0/24.
Warning
For security reasons, we don't recommend that you allow SSH access from all IPv4
addresses (0.0.0.0/0) to your instance, except for testing purposes and only for a short
time.
For more information, see Amazon EC2 Security Groups for Linux Instances (p. 607).
26
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Overview
When you sign up for AWS, you can get started with Amazon EC2 using the AWS Free Tier. If you created
your AWS account less than 12 months ago, and have not already exceeded the free tier benefits for
Amazon EC2, it will not cost you anything to complete this tutorial, because we help you select options
that are within the free tier benefits. Otherwise, you'll incur the standard Amazon EC2 usage fees from
the time that you launch the instance until you terminate the instance (which is the final task of this
tutorial), even if it remains idle.
Contents
• Overview (p. 27)
• Prerequisites (p. 28)
• Step 1: Launch an Instance (p. 28)
• Step 2: Connect to Your Instance (p. 29)
• Step 3: Clean Up Your Instance (p. 29)
• Next Steps (p. 29)
Overview
The instance is an Amazon EBS-backed instance (meaning that the root volume is an EBS volume).
You can either specify the Availability Zone in which your instance runs, or let Amazon EC2 select an
Availability Zone for you. When you launch your instance, you secure it by specifying a key pair and
security group. When you connect to your instance, you must specify the private key of the key pair that
you specified when launching your instance.
Tasks
To complete this tutorial, perform the following tasks:
27
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Prerequisites
Related Tutorials
• If you'd prefer to launch a Windows instance, see this tutorial in the Amazon EC2 User Guide for
Windows Instances: Getting Started with Amazon EC2 Windows Instances.
• If you'd prefer to use the command line, see this tutorial in the AWS Command Line Interface User
Guide: Using Amazon EC2 through the AWS CLI.
Prerequisites
Before you begin, be sure that you've completed the steps in Setting Up with Amazon EC2 (p. 19).
To launch an instance
Alternatively, you can create a new key pair. Select Create a new key pair, enter a name for the key
pair, and then choose Download Key Pair. This is the only chance for you to save the private key file,
so be sure to download it. Save the private key file in a safe place. You'll need to provide the name of
your key pair when you launch an instance and the corresponding private key each time you connect
to the instance.
Warning
Don't select the Proceed without a key pair option. If you launch your instance without a
key pair, then you can't connect to it.
28
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 2: Connect to Your Instance
When you are ready, select the acknowledgement check box, and then choose Launch Instances.
9. A confirmation page lets you know that your instance is launching. Choose View Instances to close
the confirmation page and return to the console.
10. On the Instances screen, you can view the status of the launch. It takes a short time for an instance
to launch. When you launch an instance, its initial state is pending. After the instance starts, its
state changes to running and it receives a public DNS name. (If the Public DNS (IPv4) column is
hidden, choose Show/Hide Columns (the gear-shaped icon) in the top right corner of the page and
then select Public DNS (IPv4).)
11. It can take a few minutes for the instance to be ready so that you can connect to it. Check that your
instance has passed its status checks; you can view this information in the Status Checks column.
If you launched an instance that is not within the AWS Free Tier, you'll stop incurring charges for that
instance as soon as the instance status changes to shutting down or terminated. If you'd like to keep
your instance for later, but not incur charges, you can stop the instance now and then start it again later.
For more information, see Stopping Instances.
1. In the navigation pane, choose Instances. In the list of instances, select the instance.
2. Choose Actions, Instance State, Terminate.
3. Choose Yes, Terminate when prompted for confirmation.
Amazon EC2 shuts down and terminates your instance. After your instance is terminated, it remains
visible on the console for a short while, and then the entry is deleted.
Next Steps
After you start your instance, you might want to try some of the following exercises:
29
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Next Steps
• Learn how to remotely manage your EC2 instance using Run Command. For more information, see
Tutorial: Remotely Manage Your Amazon EC2 Instances Using Systems Manager (p. 91) and AWS
Systems Manager Run Command in the AWS Systems Manager User Guide.
• Configure a CloudWatch alarm to notify you if your usage exceeds the Free Tier. For more information,
see Create a Billing Alarm in the AWS Billing and Cost Management User Guide.
• Add an EBS volume. For more information, see Creating an Amazon EBS Volume (p. 847) and
Attaching an Amazon EBS Volume to an Instance (p. 851).
• Install the LAMP stack. For more information, see Tutorial: Install a LAMP Web Server on Amazon Linux
2 (p. 33).
30
Amazon Elastic Compute Cloud
User Guide for Linux Instances
• Manage access to AWS resources and APIs using identity federation, IAM users, and IAM roles. Establish
credential management policies and procedures for creating, distributing, rotating, and revoking AWS
access credentials. For more information, see IAM Best Practices in the IAM User Guide.
• Implement the least permissive rules for your security group. For more information, see Security Group
Rules (p. 608).
• Regularly patch, update, and secure the operating system and applications on your instance. For more
information about updating Amazon Linux 2 or the Amazon Linux AMI, see Managing Software on
Your Linux Instance. For more information about updating your Windows instance, see Updating Your
Windows Instance in the Amazon EC2 User Guide for Windows Instances.
Storage
• Understand the implications of the root device type for data persistence, backup, and recovery. For
more information, see Storage for the Root Device (p. 97).
• Use separate Amazon EBS volumes for the operating system versus your data. Ensure that the volume
with your data persists after instance termination. For more information, see Preserving Amazon EBS
Volumes on Instance Termination (p. 483).
• Use the instance store available for your instance to store temporary data. Remember that the data
stored in instance store is deleted when you stop or terminate your instance. If you use instance
store for database storage, ensure that you have a cluster with a replication factor that ensures fault
tolerance.
Resource Management
• Use instance metadata and custom resource tags to track and identify your AWS resources. For
more information, see Instance Metadata and User Data (p. 526) and Tagging Your Amazon EC2
Resources (p. 995).
• View your current limits for Amazon EC2. Plan to request any limit increases in advance of the time
that you'll need them. For more information, see Amazon EC2 Service Limits (p. 1005).
• Regularly back up your EBS volumes using Amazon EBS snapshots (p. 866), and create an Amazon
Machine Image (AMI) (p. 95) from your instance to save the configuration as a template for
launching future instances.
• Deploy critical components of your application across multiple Availability Zones, and replicate your
data appropriately.
• Design your applications to handle dynamic IP addressing when your instance restarts. For more
information, see Amazon EC2 Instance IP Addressing (p. 706).
• Monitor and respond to events. For more information, see Monitoring Amazon EC2 (p. 544).
• Ensure that you are prepared to handle failover. For a basic solution, you can manually attach a
network interface or Elastic IP address to a replacement instance. For more information, see Elastic
Network Interfaces (p. 729). For an automated solution, you can use Amazon EC2 Auto Scaling. For
more information, see the Amazon EC2 Auto Scaling User Guide.
31
Amazon Elastic Compute Cloud
User Guide for Linux Instances
• Regularly test the process of recovering your instances and Amazon EBS volumes if they fail.
32
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Install a LAMP Server (Amazon Linux 2)
Tutorials
• Tutorial: Install a LAMP Web Server on Amazon Linux 2 (p. 33)
• Tutorial: Install a LAMP Web Server with the Amazon Linux AMI (p. 42)
• Tutorial: Hosting a WordPress Blog with Amazon Linux (p. 52)
• Tutorial: Configure SSL/TLS on Amazon Linux 2 (p. 60)
• Tutorial: Configure SSL/TLS on Amazon Linux (p. 75)
• Tutorial: Increase the Availability of Your Application on Amazon EC2 (p. 87)
• Tutorial: Remotely Manage Your Amazon EC2 Instances Using Systems Manager (p. 91)
This tutorial assumes that you have already launched a new instance using Amazon Linux 2, with a
public DNS name that is reachable from the internet. For more information, see Step 1: Launch an
Instance (p. 28). You must also have configured your security group to allow SSH (port 22), HTTP (port
80), and HTTPS (port 443) connections. For more information about these prerequisites, see Authorizing
Inbound Traffic for Your Linux Instances (p. 704).
Note
The following procedure installs the latest PHP version available on Amazon Linux 2, currently
PHP 7.2. If you plan to use PHP applications other than those described in this tutorial, you
should check their compatibility with PHP 7.2.
33
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 1: Prepare the LAMP Server
2. To ensure that all of your software packages are up to date, perform a quick software update on
your instance. This process may take a few minutes, but it is important to make sure that you have
the latest security updates and bug fixes.
The -y option installs the updates without asking for confirmation. If you would like to examine the
updates before installing, you can omit this option.
3. Install the lamp-mariadb10.2-php7.2 and php7.2 Amazon Linux Extras repositories to get the
latest versions of the LAMP MariaDB and PHP packages for Amazon Linux 2.
Note
If you receive an error stating sudo: amazon-linux-extras: command not found,
then your instance was not launched with an Amazon Linux 2 AMI (perhaps you are using
the Amazon Linux AMI instead). You can view your version of Amazon Linux with the
following command.
cat /etc/system-release
To set up a LAMP web server on Amazon Linux AMI , see Tutorial: Install a LAMP Web Server
with the Amazon Linux AMI (p. 42).
4. Now that your instance is current, you can install the Apache web server, MariaDB, and PHP software
packages.
Use the yum install command to install multiple software packages and all related dependencies at
the same time.
Note
You can view the current versions of these packages with the following command:
6. Use the systemctl command to configure the Apache web server to start at each system boot.
7. Add a security rule to allow inbound HTTP (port 80) connections to your instance if you have not
already done so. By default, a launch-wizard-N security group was set up for your instance during
initialization. This group contains a single rule to allow SSH connections.
34
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 1: Prepare the LAMP Server
Using the procedures in Adding Rules to a Security Group (p. 613), add a new inbound security
rule with the following values:
• Type: HTTP
• Protocol: TCP
• Port Range: 80
• Source: Custom
8. Test your web server. In a web browser, type the public DNS address (or the public IP address) of
your instance. If there is no content in /var/www/html, you should see the Apache test page. You
can get the public DNS for your instance using the Amazon EC2 console (check the Public DNS
column; if this column is hidden, choose Show/Hide Columns (the gear-shaped icon) and choose
Public DNS).
If you are unable to see the Apache test page, check that the security group you are using contains
a rule to allow HTTP (port 80) traffic. For information about adding an HTTP rule to your security
group, see Adding Rules to a Security Group (p. 613).
Important
If you are not using Amazon Linux, you may also need to configure the firewall on your
instance to allow these connections. For more information about how to configure the
firewall, see the documentation for your specific distribution.
35
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 1: Prepare the LAMP Server
Apache httpd serves files that are kept in a directory called the Apache document root. The Amazon
Linux Apache document root is /var/www/html, which by default is owned by root.
To allow the ec2-user account to manipulate files in this directory, you must modify the ownership and
permissions of the directory. There are many ways to accomplish this task. In this tutorial, you add ec2-
user to the apache group, to give the apache group ownership of the /var/www directory and assign
write permissions to the group.
1. Add your user (in this case, ec2-user) to the apache group.
2. Log out and then log back in again to pick up the new group, and then verify your membership.
a. Log out (use the exit command or close the terminal window):
b. To verify your membership in the apache group, reconnect to your instance, and then run the
following command:
3. Change the group ownership of /var/www and its contents to the apache group.
4. To add group write permissions and to set the group ID on future subdirectories, change the
directory permissions of /var/www and its subdirectories.
[ec2-user ~]$ sudo chmod 2775 /var/www && find /var/www -type d -exec sudo chmod 2775
{} \;
5. To add group write permissions, recursively change the file permissions of /var/www and its
subdirectories:
Now, ec2-user (and any future members of the apache group) can add, delete, and edit files in the
Apache document root, enabling you to add content, such as a static website or a PHP application.
A web server running the HTTP protocol provides no transport security for the data that it sends or
receives. When you connect to an HTTP server using a web browser, the URLs that you visit, the content
of webpages that you receive, and the contents (including passwords) of any HTML forms that you
submit are all visible to eavesdroppers anywhere along the network pathway. The best practice for
securing your web server is to install support for HTTPS (HTTP Secure), which protects your data with
SSL/TLS encryption.
For information about enabling HTTPS on your server, see Tutorial: Configure SSL/TLS on Amazon Linux
2 (p. 60).
36
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 2: Test Your LAMP Server
If you get a "Permission denied" error when trying to run this command, try logging out and
logging back in again to pick up the proper group permissions that you configured in To set file
permissions (p. 36).
2. In a web browser, type the URL of the file that you just created. This URL is the public DNS address
of your instance followed by a forward slash and the file name. For example:
http://my.public.dns.amazonaws.com/phpinfo.php
Note
If you do not see this page, verify that the /var/www/html/phpinfo.php file was created
properly in the previous step. You can also verify that all of the required packages were
installed with the following command.
37
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 3: Secure the Database Server
If any of the required packages are not listed in your output, install them with the sudo
yum install package command. Also verify that the php7.2 and lamp-mariadb10.2-
php7.2 extras are enabled in the out put of the amazon-linux-extras command.
3. Delete the phpinfo.php file. Although this can be useful information, it should not be broadcast to
the internet for security reasons.
You should now have a fully functional LAMP web server. If you add content to the Apache document
root at /var/www/html, you should be able to view that content at the public DNS address for your
instance.
2. Run mysql_secure_installation.
i. Type the current root password. By default, the root account does not have a password set.
Press Enter.
ii. Type Y to set a password, and type a secure password twice. For more information about
creating a secure password, see https://identitysafe.norton.com/password-generator/.
Make sure to store this password in a safe place.
Note
Setting a root password for MariaDB is only the most basic measure for securing
your database. When you build or install a database-driven application, you
typically create a database service user for that application and avoid using the
root account for anything but database administration.
b. Type Y to remove the anonymous user accounts.
c. Type Y to disable the remote root login.
d. Type Y to remove the test database.
e. Type Y to reload the privilege tables and save your changes.
3. (Optional) If you do not plan to use the MariaDB server right away, stop it. You can restart it when
you need it again.
4. (Optional) If you want the MariaDB server to start at every boot, type the following command.
38
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 4: (Optional) Install phpMyAdmin
To install phpMyAdmin
2. Restart Apache.
3. Restart php-fpm.
5. Select a source package for the latest phpMyAdmin release from https://www.phpmyadmin.net/
downloads. To download the file directly to your instance, copy the link and paste it into a wget
command, as in this example:
6. Create a phpMyAdmin folder and extract the package into it with the following command.
39
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 4: (Optional) Install phpMyAdmin
9. In a web browser, type the URL of your phpMyAdmin installation. This URL is the public DNS
address (or the public IP address) of your instance followed by a forward slash and the name of your
installation directory. For example:
http://my.public.dns.amazonaws.com/phpMyAdmin
40
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Troubleshooting
10. Log in to your phpMyAdmin installation with the root user name and the MySQL root password you
created earlier.
Your installation must still be configured before you put it into service. To configure phpMyAdmin,
you can manually create a configuration file, use the setup console, or combine both approaches.
For information about using phpMyAdmin, see the phpMyAdmin User Guide.
Troubleshooting
This section offers suggestions for resolving common problems you may encounter while setting up a
new LAMP server.
If the httpd process is not running, repeat the steps described in To prepare the LAMP
server (p. 33).
• Is the firewall correctly configured?
If you are unable to see the Apache test page, check that the security group you are using contains a
rule to allow HTTP (port 80) traffic. For information about adding an HTTP rule to your security group,
see Adding Rules to a Security Group (p. 613).
Related Topics
For more information about transferring files to your instance or installing a WordPress blog on your web
server, see the following documentation:
For more information about the commands and software used in this tutorial, see the following
webpages:
For more information about registering a domain name for your web server, or transferring an existing
domain name to this host, see Creating and Migrating Domains and Subdomains to Amazon Route 53 in
the Amazon Route 53 Developer Guide.
41
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Install a LAMP Server (Amazon Linux AMI)
This tutorial assumes that you have already launched a new instance using the Amazon Linux AMI, with
a public DNS name that is reachable from the internet. For more information, see Step 1: Launch an
Instance (p. 28). You must also have configured your security group to allow SSH (port 22), HTTP (port
80), and HTTPS (port 443) connections. For more information about these prerequisites, see Authorizing
Inbound Traffic for Your Linux Instances (p. 704).
To install and start the LAMP web server with the Amazon Linux AMI
The -y option installs the updates without asking for confirmation. If you would like to examine the
updates before installing, you can omit this option.
3. Now that your instance is current, you can install the Apache web server, MySQL, and PHP software
packages.
Note
Some applications may not be compatible with the following recommended software
environment. Before installing these packages, check whether your LAMP applications
are compatible with them. If there is a problem, you may need to install an alternative
environment. For more information, see The application software I want to run on my
server is incompatible with the installed PHP version or other software (p. 51)
Use the yum install command to install multiple software packages and all related dependencies at
the same time.
42
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 1: Prepare the LAMP Server
Note
If you receive the error No package package-name available, then your instance was
not launched with the Amazon Linux AMI (perhaps you are using Amazon Linux 2 instead).
You can view your version of Amazon Linux with the following command.
cat /etc/system-release
5. Use the chkconfig command to configure the Apache web server to start at each system boot.
The chkconfig command does not provide any confirmation message when you successfully use it to
enable a service.
Using the procedures in Adding Rules to a Security Group (p. 613), add a new inbound security
rule with the following values:
• Type: HTTP
• Protocol: TCP
• Port Range: 80
• Source: Custom
7. Test your web server. In a web browser, type the public DNS address (or the public IP address) of
your instance. If there is no content in /var/www/html, you should see the Apache test page. You
can get the public DNS for your instance using the Amazon EC2 console (check the Public DNS
column; if this column is hidden, choose Show/Hide Columns (the gear-shaped icon) and choose
Public DNS).
43
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 1: Prepare the LAMP Server
If you are unable to see the Apache test page, check that the security group you are using contains
a rule to allow HTTP (port 80) traffic. For information about adding an HTTP rule to your security
group, see Adding Rules to a Security Group (p. 613).
Important
If you are not using Amazon Linux, you may also need to configure the firewall on your
instance to allow these connections. For more information about how to configure the
firewall, see the documentation for your specific distribution.
Note
This test page appears only when there is no content in /var/www/html. When you add
content to the document root, your content appears at the public DNS address of your
instance instead of this test page.
Apache httpd serves files that are kept in a directory called the Apache document root. The Amazon
Linux Apache document root is /var/www/html, which by default is owned by root.
44
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 1: Prepare the LAMP Server
To allow the ec2-user account to manipulate files in this directory, you must modify the ownership and
permissions of the directory. There are many ways to accomplish this task. In this tutorial, you add ec2-
user to the apache group, to give the apache group ownership of the /var/www directory and assign
write permissions to the group.
1. Add your user (in this case, ec2-user) to the apache group.
2. Log out and then log back in again to pick up the new group, and then verify your membership.
a. Log out (use the exit command or close the terminal window):
b. To verify your membership in the apache group, reconnect to your instance, and then run the
following command:
3. Change the group ownership of /var/www and its contents to the apache group.
4. To add group write permissions and to set the group ID on future subdirectories, change the
directory permissions of /var/www and its subdirectories.
5. To add group write permissions, recursively change the file permissions of /var/www and its
subdirectories:
Now, ec2-user (and any future members of the apache group) can add, delete, and edit files in the
Apache document root, enabling you to add content, such as a static website or a PHP application.
A web server running the HTTP protocol provides no transport security for the data that it sends or
receives. When you connect to an HTTP server using a web browser, the URLs that you visit, the content
of webpages that you receive, and the contents (including passwords) of any HTML forms that you
submit are all visible to eavesdroppers anywhere along the network pathway. The best practice for
securing your web server is to install support for HTTPS (HTTP Secure), which protects your data with
SSL/TLS encryption.
For information about enabling HTTPS on your server, see Tutorial: Configure SSL/TLS on Amazon
Linux (p. 75).
45
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 2: Test Your Lamp Server
If you get a "Permission denied" error when trying to run this command, try logging out and logging
back in again to pick up the proper group permissions that you configured in Step 1: Prepare the
LAMP Server (p. 42).
2. In a web browser, type the URL of the file that you just created. This URL is the public DNS address
of your instance followed by a forward slash and the file name. For example:
http://my.public.dns.amazonaws.com/phpinfo.php
If you do not see this page, verify that the /var/www/html/phpinfo.php file was created properly
in the previous step. You can also verify that all of the required packages were installed with the
following command. The package versions in the second column do not need to match this example
output.
[ec2-user ~]$ sudo yum list installed httpd24 php70 mysql56-server php70-mysqlnd
Loaded plugins: priorities, update-motd, upgrade-helper
Installed Packages
httpd24.x86_64 2.4.25-1.68.amzn1 @amzn-
updates
46
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 3: Secure the Database Server
If any of the required packages are not listed in your output, install them using the sudo yum install
package command.
3. Delete the phpinfo.php file. Although this can be useful information, it should not be broadcast to
the internet for security reasons.
Starting mysqld: [ OK ]
2. Run mysql_secure_installation.
i. Type the current root password. By default, the root account does not have a password set.
Press Enter.
ii. Type Y to set a password, and type a secure password twice. For more information about
creating a secure password, see https://identitysafe.norton.com/password-generator/.
Make sure to store this password in a safe place.
Note
Setting a root password for MySQL is only the most basic measure for securing
your database. When you build or install a database-driven application, you
typically create a database service user for that application and avoid using the
root account for anything but database administration.
b. Type Y to remove the anonymous user accounts.
c. Type Y to disable the remote root login.
d. Type Y to remove the test database.
47
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 4: (Optional) Install phpMyAdmin
4. (Optional) If you want the MySQL server to start at every boot, type the following command.
You should now have a fully functional LAMP web server. If you add content to the Apache document
root at /var/www/html, you should be able to view that content at the public DNS address for your
instance.
3. Restart Apache.
5. Select a source package for the latest phpMyAdmin release from https://www.phpmyadmin.net/
downloads. To download the file directly to your instance, copy the link and paste it into a wget
command, as in this example:
48
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 4: (Optional) Install phpMyAdmin
6. Create a phpMyAdmin folder and extract the package into it using the following command.
9. In a web browser, type the URL of your phpMyAdmin installation. This URL is the public DNS
address (or the public IP address) of your instance followed by a forward slash and the name of your
installation directory. For example:
http://my.public.dns.amazonaws.com/phpMyAdmin
49
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 4: (Optional) Install phpMyAdmin
10. Log in to your phpMyAdmin installation with the root user name and the MySQL root password you
created earlier.
Your installation must still be configured before you put it into service. To configure phpMyAdmin,
you can manually create a configuration file, use the setup console, or combine both approaches.
For information about using phpMyAdmin, see the phpMyAdmin User Guide.
50
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Troubleshooting
Troubleshooting
This section offers suggestions for resolving common problems you may encounter while setting up a
new LAMP server.
If the httpd process is not running, repeat the steps described in Step 1: Prepare the LAMP
Server (p. 42).
• Is the firewall correctly configured?
If you are unable to see the Apache test page, check that the security group you are using contains a
rule to allow HTTP (port 80) traffic. For information about adding an HTTP rule to your security group,
see Adding Rules to a Security Group (p. 613).
How to downgrade
The well-tested previous version of this tutorial called for the following core LAMP packages:
• httpd24
• php56
• mysql55-server
• php56-mysqlnd
If you have already installed the latest packages as recommended at the start of this tutorial, you must
first uninstall these packages and other dependencies as follows:
[ec2-user ~]$ sudo yum remove -y httpd24 php70 mysql56-server php70-mysqlnd perl-DBD-
MySQL56
51
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Related Topics
If you decide later to upgrade to the recommended environment, you must first remove the customized
packages and dependencies:
[ec2-user ~]$ sudo yum remove -y httpd24 php56 mysql55-server php56-mysqlnd perl-DBD-
MySQL55
Related Topics
For more information about transferring files to your instance or installing a WordPress blog on your web
server, see the following documentation:
For more information about the commands and software used in this tutorial, see the following
webpages:
For more information about registering a domain name for your web server, or transferring an existing
domain name to this host, see Creating and Migrating Domains and Subdomains to Amazon Route 53 in
the Amazon Route 53 Developer Guide.
You are responsible for updating the software packages and maintaining security patches for your server.
For a more automated WordPress installation that does not require direct interaction with the web server
configuration, the AWS CloudFormation service provides a WordPress template that can also get you
started quickly. For more information, see Getting Started in the AWS CloudFormation User Guide. If
you'd prefer to host your WordPress blog on a Windows instance, see Deploying a WordPress Blog on
Your Amazon EC2 Windows Instance in the Amazon EC2 User Guide for Windows Instances. If you need
a high-availability solution with a decoupled database, see Deploying a High-Availability WordPress
Website in the AWS Elastic Beanstalk Developer Guide.
Important
These procedures are intended for use with Amazon Linux. For more information about other
distributions, see their specific documentation. Many steps in this tutorial do not work on
52
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Prerequisites
Ubuntu instances. For help installing WordPress on an Ubuntu instance, see WordPress in the
Ubuntu documentation.
Prerequisites
This tutorial assumes that you have launched an Amazon Linux instance with a functional web server
with PHP and database (either MySQL or MariaDB) support by following all of the steps in Tutorial:
Install a LAMP Web Server with the Amazon Linux AMI (p. 42) for Amazon Linux AMI or Tutorial:
Install a LAMP Web Server on Amazon Linux 2 (p. 33) for Amazon Linux 2. This tutorial also has steps
for configuring a security group to allow HTTP and HTTPS traffic, as well as several steps to ensure that
file permissions are set properly for your web server. For information about adding rules to your security
group, see Adding Rules to a Security Group (p. 613).
We strongly recommend that you associate an Elastic IP address (EIP) to the instance you are using
to host a WordPress blog. This prevents the public DNS address for your instance from changing and
breaking your installation. If you own a domain name and you want to use it for your blog, you can
update the DNS record for the domain name to point to your EIP address (for help with this, contact your
domain name registrar). You can have one EIP address associated with a running instance at no charge.
For more information, see Elastic IP Addresses (p. 724).
If you don't already have a domain name for your blog, you can register a domain name with Route 53
and associate your instance's EIP address with your domain name. For more information, see Registering
Domain Names Using Amazon Route 53 in the Amazon Route 53 Developer Guide.
Install WordPress
Connect to your instance, and download the WordPress installation package.
1. Download the latest WordPress installation package with the wget command. The following
command should always download the latest release.
2. Unzip and unarchive the installation package. The installation folder is unzipped to a folder called
wordpress.
Your WordPress installation needs to store information, such as blog posts and user comments, in a
database. This procedure helps you create your blog's database and a user that is authorized to read and
save information to it.
53
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Install WordPress
2. Log in to the database server as the root user. Enter your database root password when prompted;
this may be different than your root system password, or it may even be empty if you have not
secured your database server.
If you have not secured your database server yet, it is important that you do so. For more
information, see To secure the database server (p. 47).
3. Create a user and password for your MySQL database. Your WordPress installation uses these values
to communicate with your MySQL database. Enter the following command, substituting a unique
user name and password.
Make sure that you create a strong password for your user. Do not use the single quote character
( ' ) in your password, because this will break the preceding command. For more information about
creating a secure password, go to http://www.pctools.com/guides/password/. Do not reuse an
existing password, and make sure to store this password in a safe place.
4. Create your database. Give your database a descriptive, meaningful name, such as wordpress-db.
Note
The punctuation marks surrounding the database name in the command below are called
backticks. The backtick (`) key is usually located above the Tab key on a standard keyboard.
Backticks are not always required, but they allow you to use otherwise illegal characters,
such as hyphens, in database names.
5. Grant full privileges for your database to the WordPress user that you created earlier.
FLUSH PRIVILEGES;
exit
The WordPress installation folder contains a sample configuration file called wp-config-sample.php.
In this procedure, you copy this file and edit it to fit your specific configuration.
1. Copy the wp-config-sample.php file to a file called wp-config.php. This creates a new
configuration file and keeps the original sample file intact as a backup.
2. Edit the wp-config.php file with your favorite text editor (such as nano or vim) and enter values
for your installation. If you do not have a favorite text editor, nano is suitable for beginners.
54
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Install WordPress
a. Find the line that defines DB_NAME and change database_name_here to the database
name that you created in Step 4 (p. 54) of To create a database user and database for your
WordPress installation (p. 53).
define('DB_NAME', 'wordpress-db');
b. Find the line that defines DB_USER and change username_here to the database user that
you created in Step 3 (p. 54) of To create a database user and database for your WordPress
installation (p. 53).
define('DB_USER', 'wordpress-user');
c. Find the line that defines DB_PASSWORD and change password_here to the strong password
that you created in Step 3 (p. 54) of To create a database user and database for your
WordPress installation (p. 53).
define('DB_PASSWORD', 'your_strong_password');
d. Find the section called Authentication Unique Keys and Salts. These KEY and SALT
values provide a layer of encryption to the browser cookies that WordPress users store on their
local machines. Basically, adding long, random values here makes your site more secure. Visit
https://api.wordpress.org/secret-key/1.1/salt/ to randomly generate a set of key values that
you can copy and paste into your wp-config.php file. To paste text into a PuTTY terminal,
place the cursor where you want to paste the text and right-click your mouse inside the PuTTY
terminal.
1. Now that you've unzipped the installation folder, created a MySQL database and user, and
customized the WordPress configuration file, you are ready to copy your installation files to your
web server document root so you can run the installation script that completes your installation.
The location of these files depends on whether you want your WordPress blog to be available
55
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Install WordPress
3. If you want WordPress to run in an alternative directory under the document root, first create that
directory, and then copy the files to it. In this example, WordPress will run from the directory blog:
Important
For security purposes, if you are not moving on to the next procedure immediately, stop the
Apache web server (httpd) now. After you move your installation under the Apache document
root, the WordPress installation script is unprotected and an attacker could gain access to your
blog if the Apache web server were running. To stop the Apache web server, enter the command
sudo service httpd stop. If you are moving on to the next procedure, you do not need to stop
the Apache web server.
WordPress permalinks need to use Apache .htaccess files to work properly, but this is not enabled by
default on Amazon Linux. Use this procedure to allow all overrides in the Apache document root.
1. Open the httpd.conf file with your favorite text editor (such as nano or vim). If you do not have a
favorite text editor, nano is suitable for beginners.
<Directory "/var/www/html">
✔
✔ Possible values for the Options directive are "None", "All",
✔ or any combination of:
✔ Indexes Includes FollowSymLinks SymLinksifOwnerMatch ExecCGI MultiViews
✔
✔ Note that "MultiViews" must be named *explicitly* --- "Options All"
✔ doesn't give it to you.
✔
✔ The Options directive is both complicated and important. Please see
✔ http://httpd.apache.org/docs/2.4/mod/core.html✔options
✔ for more information.
✔
Options Indexes FollowSymLinks
✔
✔ AllowOverride controls what directives may be placed in .htaccess files.
✔ It can be "All", "None", or any combination of the keywords:
✔ Options FileInfo AuthConfig Limit
✔
AllowOverride None
✔
✔ Controls who can get stuff from this server.
✔
Require all granted
56
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Install WordPress
</Directory>
3. Change the AllowOverride None line in the above section to read AllowOverride All.
Note
There are multiple AllowOverride lines in this file; be sure you change the line in the
<Directory "/var/www/html"> section.
AllowOverride All
Some of the available features in WordPress require write access to the Apache document root (such
as uploading media though the Administration screens). If you have not already done so, apply the
following group memberships and permissions (as described in greater detail in the LAMP web server
tutorial (p. 42)).
1. Grant file ownership of /var/www and its contents to the apache user.
2. Grant group ownership of /var/www and its contents to the apache group.
3. Change the directory permissions of /var/www and its subdirectories to add group write
permissions and to set the group ID on future subdirectories.
4. Recursively change the file permissions of /var/www and its subdirectories to add group write
permissions.
5. Restart the Apache web server to pick up the new group and permissions.
• Amazon Linux 2
You are ready to install WordPress. The commands that you use depend on the operating system. The
commands in this procedure are for use with Amazon Linux 2. Use the procedure that follows this one
with Amazon Linux AMI.
1. Use the systemctl command to ensure that the httpd and database services start at every system
boot.
57
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Install WordPress
[ec2-user ~]$ sudo systemctl enable httpd && sudo systemctl enable mariadb
4. In a web browser, type the URL of your WordPress blog (either the public DNS address for your
instance, or that address followed by the blog folder). You should see the WordPress installation
script. Provide the information required by the WordPress installation. Choose Install WordPress to
complete the installation. For more information, see Run the Install Script on the WordPress website.
1. Use the chkconfig command to ensure that the httpd and database services start at every system
boot.
4. In a web browser, type the URL of your WordPress blog (either the public DNS address for your
instance, or that address followed by the blog folder). You should see the WordPress installation
script. Provide the information required by the WordPress installation. Choose Install WordPress to
complete the installation. For more information, see Run the Install Script on the WordPress website.
58
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Next Steps
Next Steps
After you have tested your WordPress blog, consider updating its configuration.
If you have a domain name associated with your EC2 instance's EIP address, you can configure your
blog to use that name instead of the EC2 public DNS address. For more information, see http://
codex.wordpress.org/Changing_The_Site_URL.
You can configure your blog to use different themes and plugins to offer a more personalized experience
for your readers. However, sometimes the installation process can backfire, causing you to lose your
entire blog. We strongly recommend that you create a backup Amazon Machine Image (AMI) of your
instance before attempting to install any themes or plugins so you can restore your blog if anything goes
wrong during installation. For more information, see Creating Your Own AMI (p. 95).
Increase Capacity
If your WordPress blog becomes popular and you need more compute power or storage, consider the
following steps:
• Expand the storage space on your instance. For more information, see Amazon EBS Elastic
Volumes (p. 892).
• Move your MySQL database to Amazon RDS to take advantage of the service's ability to scale easily.
• Migrate to a larger instance type. For more information, see Changing the Instance Type (p. 250).
• Add additional instances. For more information, see Tutorial: Increase the Availability of Your
Application on Amazon EC2 (p. 87).
For information about WordPress, see the WordPress Codex help documentation at http://
codex.wordpress.org/. For more information about troubleshooting your installation, go to http://
codex.wordpress.org/Installing_WordPress#Common_Installation_Problems. For information about
making your WordPress blog more secure, go to http://codex.wordpress.org/Hardening_WordPress.
For information about keeping your WordPress blog up-to-date, go to http://codex.wordpress.org/
Updating_WordPress.
If this has happened to your WordPress installation, you may be able to recover your blog with the
procedure below, which uses the wp-cli command line interface for WordPress.
59
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Tutorial: Configure SSL/TLS on Amazon Linux 2
public DNS name for your EC2 instance. If you are not sure of your old site URL, you can use curl to
find it with the following command.
You should see references to your old public DNS name in the output, which will look like this (old
site URL in red):
4. Search and replace the old site URL in your WordPress installation with the following command.
Substitute the old and new site URLs for your EC2 instance and the path to your WordPress
installation (usually /var/www/html or /var/www/html/blog).
5. In a web browser, enter the new site URL of your WordPress blog to verify that the site is working
properly again. If it is not, see http://codex.wordpress.org/Changing_The_Site_URL and http://
codex.wordpress.org/Installing_WordPress#Common_Installation_Problems for more information.
For historical reasons, web encryption is often referred to simply as SSL. While web browsers still
support SSL, its successor protocol TLS is less vulnerable to attack. Amazon Linux 2 disables server-
side support for all versions of SSL by default. Security standards bodies consider TLS 1.0 to be unsafe,
and both TLS 1.0 and TLS 1.1 are on track to be formally deprecated by the IETF. This tutorial contains
guidance based exclusively on enabling TLS 1.2. (A newer TLS 1.3 protocol exists in draft form, but is not
yet supported on Amazon Linux 2.) For more information about the updated encryption standards, see
RFC 7568 and RFC 8446.
Contents
• Prerequisites (p. 61)
60
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Prerequisites
Prerequisites
Before you begin this tutorial, complete the following steps:
• Launch an EBS-backed Amazon Linux 2 instance. For more information, see Step 1: Launch an
Instance (p. 28).
• Configure your security groups to allow your instance to accept connections on the following TCP
ports:
• SSH (port 22)
• HTTP (port 80)
• HTTPS (port 443)
For more information, see Authorizing Inbound Traffic for Your Linux Instances (p. 704).
• Install the Apache web server. For step-by-step instructions, see Tutorial: Install a LAMP Web Server on
Amazon Linux 2 (p. 33). Only the httpd package and its dependencies are needed, so you can ignore
the instructions involving PHP and MariaDB.
• To identify and authenticate websites, the TLS public key infrastructure (PKI) relies on the Domain
Name System (DNS). To use your EC2 instance to host a public website, you need to register a domain
name for your web server or transfer an existing domain name to your Amazon EC2 host. Numerous
third-party domain registration and DNS hosting services are available for this, or you can use Amazon
Route 53.
1. Connect to your instance (p. 29) and confirm that Apache is running.
If the returned value is not "enabled," start Apache and set it to start each time the system boots.
[ec2-user ~]$ sudo systemctl start httpd && sudo systemctl enable httpd
2. To ensure that all of your software packages are up-to-date, perform a quick software update on
your instance. This process may take a few minutes, but it is important to make sure that you have
the latest security updates and bug fixes.
61
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 1: Enable TLS on the Server
Note
The -y option installs the updates without asking for confirmation. If you would like to
examine the updates before installing, you can omit this option.
3. Now that your instance is current, add TLS support by installing the Apache module mod_ssl.
Your instance now has the following files that you use to configure your secure server and create a
certificate for testing:
• /etc/httpd/conf.d/ssl.conf
The configuration file for mod_ssl. It contains directives telling Apache where to find encryption
keys and certificates, the TLS protocol versions to allow, and the encryption ciphers to accept.
• /etc/pki/tls/certs/make-dummy-cert
A script to generate a self-signed X.509 certificate and private key for your server host. This
certificate is useful for testing that Apache is properly set up to use TLS. Because it offers no proof
of identity, it should not be used in production. If used in production, it triggers warnings in Web
browsers.
4. Run the script to generate a self-signed dummy certificate and key for testing.
This generates a new file localhost.crt in the /etc/pki/tls/certs/ directory. The specified
file name matches the default that is assigned in the SSLCertificateFile directive in /etc/httpd/
conf.d/ssl.conf.
This file contains both a self-signed certificate and the certificate's private key. Apache requires the
certificate and key to be in PEM format, which consists of Base64-encoded ASCII characters framed
by "BEGIN" and "END" lines, as in the following abbreviated example.
-----BEGIN CERTIFICATE-----
MIIEazCCA1OgAwIBAgICWxQwDQYJKoZIhvcNAQELBQAwgbExCzAJBgNVBAYTAi0t
MRIwEAYDVQQIDAlTb21lU3RhdGUxETAPBgNVBAcMCFNvbWVDaXR5MRkwFwYDVQQK
DBBTb21lT3JnYW5pemF0aW9uMR8wHQYDVQQLDBZTb21lT3JnYW5pemF0aW9uYWxV
bml0MRkwFwYDVQQDDBBpcC0xNzItMzEtMjAtMjM2MSQwIgYJKoZIhvcNAQkBFhVy
...
z5rRUE/XzxRLBZOoWZpNWTXJkQ3uFYH6s/sBwtHpKKZMzOvDedREjNKAvk4ws6F0
CuIjvubtUysVyQoMVPQ97ldeakHWeRMiEJFXg6kZZ0vrGvwnKoMh3DlK44D9dlU3
WanXWehT6FiSZvB4sTEXXJN2jdw8g+sHGnZ8zCOsclknYhHrCVD2vnBlZJKSZvak
3ZazhBxtQSukFMOnWPP2a0DMMFGYUHOd0BQE8sBJxg==
62
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 2: Obtain a CA-signed Certificate
-----END CERTIFICATE-----
The file names and extensions are a convenience and have no effect on function. For example, you
can call a certificate cert.crt, cert.pem, or any other file name, so long as the related directive in
the ssl.conf file uses the same name.
Note
When you replace the default TLS files with your own customized files, be sure that they are
in PEM format.
5. Open the /etc/httpd/conf.d/ssl.conf file and comment out the following line, because the
self-signed dummy certificate also contains the key. If you do not comment out this line before you
complete the next step, the Apache service fails to start.
SSLCertificateKeyFile /etc/pki/tls/private/localhost.key
6. Restart Apache.
Note
Make sure that TCP port 443 is accessible on your EC2 instance, as previously described.
7. Your Apache web server should now support HTTPS (secure HTTP) over port 443. Test it by entering
the IP address or fully qualified domain name of your EC2 instance into a browser URL bar with the
prefix https://.
Because you are connecting to a site with a self-signed, untrusted host certificate, your browser may
display a series of security warnings. Override the warnings and proceed to the site.
If the default Apache test page opens, it means that you have successfully configured TLS on your
server. All data passing between the browser and server is now encrypted.
Note
To prevent site visitors from encountering warning screens, you must obtain a trusted, CA-
signed certificate that not only encrypts, but also publicly authenticates you as the owner
of the site.
A self-signed TLS X.509 host certificate is cryptologically identical to a CA-signed certificate. The
difference is social, not mathematical. A CA promises, at a minimum, to validate a domain's ownership
before issuing a certificate to an applicant. Each web browser contains a list of CAs trusted by the
browser vendor to do this. An X.509 certificate consists primarily of a public key that corresponds to
your private server key, and a signature by the CA that is cryptographically tied to the public key. When a
browser connects to a web server over HTTPS, the server presents a certificate for the browser to check
against its list of trusted CAs. If the signer is on the list, or accessible through a chain of trust consisting
of other trusted signers, the browser negotiates a fast encrypted data channel with the server and loads
the page.
63
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 2: Obtain a CA-signed Certificate
Certificates generally cost money because of the labor involved in validating the requests, so it pays
to shop around. A list of well-known CAs can be found at dmoztools.net. A few CAs offer basic-level
certificates free of charge. The most notable of these CAs is the Let's Encrypt project, which also
supports the automation of the certificate creation and renewal process. For more information about
using Let's Encrypt as your CA, see Certificate Automation: Let's Encrypt with Certbot on Amazon Linux
2 (p. 71).
Underlying the host certificate is the key. As of 2019, government and industry groups recommend using
a minimum key (modulus) size of 2048 bits for RSA keys intended to protect documents, through 2030.
The default modulus size generated by OpenSSL in Amazon Linux 2 is 2048 bits, which is suitable for use
in a CA-signed certificate. In the following procedure, an optional step provided for those who want a
customized key, for example, one with a larger modulus or using a different encryption algorithm.
These instructions for acquiring a CA-signed host certificate do not work unless you own a registered and
hosted DNS domain.
1. Connect to your instance (p. 29) and navigate to /etc/pki/tls/private/. This is the directory where
you store the server's private key for TLS. If you prefer to use an existing host key to generate the
CSR, skip to Step 3.
2. (Optional) Generate a new private key. Here are some examples of key configurations. Any of the
resulting keys works with your web server, but they vary in the degree and type of security that they
implement.
• Example 1: Create a default RSA host key. The resulting file, custom.key, is a 2048-bit RSA
private key.
• Example 2: Create a stronger RSA key with a bigger modulus. The resulting file, custom.key, is a
4096-bit RSA private key.
• Example 3: Create a 4096-bit encrypted RSA key with password protection. The resulting file,
custom.key, is a 4096-bit RSA private key encrypted with the AES-128 cipher.
Important
Encrypting the key provides greater security, but because an encrypted key requires a
password, services depending on it cannot be auto-started. Each time you use this key,
you must supply the password (in the preceding example, "abcde12345") over an SSH
connection.
[ec2-user ~]$ sudo openssl genrsa -aes128 -passout pass:abcde12345 -out custom.key
4096
• Example 4: Create a key using a non-RSA cipher. RSA cryptography can be relatively slow because
of the size of its public keys, which are based on the product of two large prime numbers.
However, it is possible to create keys for TLS that use non-RSA ciphers. Keys based on the
mathematics of elliptic curves are smaller and computationally faster when delivering an
equivalent level of security.
[ec2-user ~]$ sudo openssl ecparam -name prime256v1 -out custom.key -genkey
The result is a 256-bit elliptic curve private key using prime256v1, a "named curve" that OpenSSL
supports. Its cryptographic strength is slightly greater than a 2048-bit RSA key, according to NIST.
64
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 2: Obtain a CA-signed Certificate
Note
Not all CAs provide the same level of support for elliptic-curve-based keys as for RSA
keys.
Make sure that the new private key has highly restrictive ownership and permissions (owner=root,
group=root, read/write for owner only). The commands would be as shown in the following
example.
After you have created and configured a satisfactory key, you can create a CSR.
3. Create a CSR using your preferred key. The following example uses custom.key.
[ec2-user ~]$ sudo openssl req -new -key custom.key -out csr.pem
OpenSSL opens a dialog and prompts you for the information shown in the following table. All of
the fields except Common Name are optional for a basic, domain-validated host certificate.
Country Name The two-letter ISO abbreviation for your US (=United States)
country.
Organization The full legal name of your organization. Do not Example Corporation
Name abbreviate your organization name.
65
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 2: Obtain a CA-signed Certificate
Finally, OpenSSL prompts you for an optional challenge password. This password applies only to the
CSR and to transactions between you and your CA, so follow the CA's recommendations about this
and the other optional field, optional company name. The CSR challenge password has no effect on
server operation.
The resulting file csr.pem contains your public key, your digital signature of your public key, and
the metadata that you entered.
4. Submit the CSR to a CA. This usually consists of opening your CSR file in a text editor and copying
the contents into a web form. At this time, you may be asked to supply one or more subject
alternate names (SANs) to be placed on the certificate. If www.example.com is the common name,
then example.com would be a good SAN, and vice versa. A visitor to your site entering either of
these names would see an error-free connection. If your CA web form allows it, include the common
name in the list of SANs. Some CAs include it automatically.
After your request has been approved, you receive a new host certificate signed by the CA. You
might also be instructed to download an intermediate certificate file that contains additional
certificates needed to complete the CA's chain of trust.
Note
Your CA might send you files in multiple formats intended for various purposes. For this
tutorial, you should only use a certificate file in PEM format, which is usually (but not
always) marked with a .pem or .crt file extension. If you are uncertain which file to use,
open the files with a text editor and find the one containing one or more blocks beginning
with the following line.
- - - - -BEGIN CERTIFICATE - - - - -
- - - -END CERTIFICATE - - - - -
You can also test the file at the command line as shown in the following.
Verify that these lines appear in the file. Do not use files ending with .p7b, .p7c, or similar
file extensions.
5. Place the new CA-signed certificate and any intermediate certificates in the /etc/pki/tls/certs
directory.
Note
There are several ways to upload your new certificate to your EC2 instance, but the most
straightforward and informative way is to open a text editor (for example, vi, nano,
or notepad) on both your local computer and your instance, and then copy and paste
the file contents between them. You need root [sudo] permissions when performing
these operations on the EC2 instance. This way, you can see immediately if there are any
permission or path problems. Be careful, however, not to add any additional lines while
copying the contents, or to change them in any way.
From inside the /etc/pki/tls/certs directory, check that the file ownership, group, and
permission settings match the highly restrictive Amazon Linux 2 defaults (owner=root, group=root,
read/write for owner only). The following example shows the commands to use.
66
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 2: Obtain a CA-signed Certificate
The permissions for the intermediate certificate file are less stringent (owner=root, group=root,
owner can write, group can read, world can read). The following example shows the commands to
use.
6. Place the private key that you used to create the CSR in the /etc/pki/tls/private/ directory.
Note
There are several ways to upload your custom key to your EC2 instance, but the most
straightforward and informative way is to open a text editor (for example, vi, nano,
or notepad) on both your local computer and your instance, and then copy and paste
the file contents between them. You need root [sudo] permissions when performing
these operations on the EC2 instance. This way, you can see immediately if there are any
permission or path problems. Be careful, however, not to add any additional lines while
copying the contents, or to change them in any way.
From inside the /etc/pki/tls/private directory, use the following commands to verify that the
file ownership, group, and permission settings match the highly restrictive Amazon Linux 2 defaults
(owner=root, group=root, read/write for owner only).
a. Provide the path and file name of the CA-signed host certificate in Apache's
SSLCertificateFile directive:
SSLCertificateFile /etc/pki/tls/certs/custom.crt
b. If you received an intermediate certificate file (intermediate.crt in this example), provide its
path and file name using Apache's SSLCACertificateFile directive:
SSLCACertificateFile /etc/pki/tls/certs/intermediate.crt
67
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 3: Test and Harden the Security Configuration
Note
Some CAs combine the host certificate and the intermediate certificates in a single file,
making the SSLCACertificateFile directive unnecessary. Consult the instructions
provided by your CA.
c. Provide the path and file name of the private key (custom.key in this example) in Apache's
SSLCertificateKeyFile directive:
SSLCertificateKeyFile /etc/pki/tls/private/custom.key
9. Test your server by entering your domain name into a browser URL bar with the prefix https://.
Your browser should load the test page over HTTPS without generating errors.
On the Qualys SSL Labs site, enter the fully qualified domain name of your server, in the form
www.example.com. After about two minutes, you receive a grade (from A to F) for your site and a
detailed breakdown of the findings. The following table summarizes the report for a domain with
settings identical to the default Apache configuration on Amazon Linux 2, and with a default Certbot
certificate.
Overall rating B
Certificate 100%
Though the overview shows that the configuration is mostly sound, the detailed report flags several
potential problems, listed here in order of severity:
✗ The RC4 cipher is supported for use by certain older browsers. A cipher is the mathematical core of
an encryption algorithm. RC4, a fast cipher used to encrypt TLS data-streams, is known to have several
serious weaknesses. Unless you have very good reasons to support legacy browsers, you should disable
this.
✗ Old TLS versions are supported. The configuration supports TLS 1.0 (already deprecated) and TLS 1.1
(on a path to deprecation). Only TLS 1.2 has been recommended since 2018.
68
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 3: Test and Harden the Security Configuration
✗ Forward secrecy is not fully supported. Forward secrecy is a feature of algorithms that encrypt using
temporary (ephemeral) session keys derived from the private key. This means in practice that attackers
cannot decrypt HTTPS data even if they possess a web server's long-term private key.
1. Open the configuration file /etc/httpd/conf.d/ssl.conf in a text editor and comment out the
following line by entering "#" at the beginning of the line.
This directive explicitly disables SSL versions 2 and 3, as well as TLS versions 1.0 and 1.1. The
server now refuses to accept encrypted connections with clients using anything except TLS 1.2.
The verbose wording in the directive conveys more clearly, to a human reader, what the server is
configured to do.
Note
Disabling TLS versions 1.0 and 1.1 in this manner blocks a small percentage of outdated
web browsers from accessing your site.
✔SSLCipherSuite HIGH:MEDIUM:!aNULL:!MD5
2. Specify explicit cipher suites and a cipher order that prioritizes forward secrecy and avoids insecure
ciphers. The SSLCipherSuite directive used here is based on output from the Mozilla SSL
Configuration Generator, which tailors a TLS configuration to the specific software running on
your server. (For more information, see Mozilla's useful resource Security/Server Side TLS.) First
determine your Apache and OpenSSL versions by using the output from the following commands.
For example, if the returned information is Apache 2.4.34 and OpenSSL 1.0.2, we enter this into the
generator. Then we choose the "modern" compatibility model, which creates an SSLCipherSuite
directive that aggressively enforces security but still works for most browsers.
SSLCipherSuite ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-
CHACHA20-POLY1305:
ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:
ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-
AES128-SHA256
The selected ciphers have ECDHE in their names, an abbreviation for Elliptic Curve Diffie-Hellman
Ephemeral . The term ephemeral indicates forward secrecy. As a by-product, these ciphers do not
support RC4.
69
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Troubleshooting
We recommend that you use an explicit list of ciphers instead of relying on defaults or terse
directives whose content isn't visible.
✔SSLHonorCipherOrder on
This directive forces the server to prefer high-ranking ciphers, including (in this case) those that
support forward secrecy. With this directive turned on, the server tries to establish a strong secure
connection before falling back to allowed ciphers with lesser security.
After completing both of these procedures, save the changes to /etc/httpd/conf.d/ssl.conf and
restart Apache.
If you test the domain again on Qualys SSL Labs, you should see that the RC4 vulnerability and other
warnings are gone and the summary looks something like the following.
Overall rating A
Certificate 100%
Important
Each update to OpenSSL introduces new ciphers and removes support for old ones. Keep your
EC2 Amazon Linux 2 instance up-to-date, watch for security announcements from OpenSSL,
and be alert to reports of new security exploits in the technical press. For more information,
see Predefined SSL Security Policies for Elastic Load Balancing in the User Guide for Classic Load
Balancers.
Troubleshooting
• My Apache webserver doesn't start unless I supply a password
This is expected behavior if you installed an encrypted, password-protected, private server key.
You can remove the encryption and password requirement from the key. Assuming that you have a
private encrypted RSA key called custom.key in the default directory, and that the password on it is
abcde12345, run the following commands on your EC2 instance to generate an unencrypted version
of the key.
70
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Certificate Automation: Let's Encrypt
with Certbot on Amazon Linux 2
[ec2-user private]$ sudo mv custom.key.nocrypt custom.key
[ec2-user private]$ sudo chown root:root custom.key
[ec2-user private]$ sudo chmod 600 custom.key
[ec2-user private]$ sudo systemctl restart httpd
When you are installing the required packages for SSL, you may see errors similar to the following.
This typically means that your EC2 instance is not running Amazon Linux 2. This tutorial only supports
instances freshly created from an official Amazon Linux 2 AMI.
Certbot is not officially supported on Amazon Linux 2, but is available for download and functions
correctly when installed. We recommend that you make the following backups to protect your data and
avoid inconvenience:
• Before you begin, take a snapshot of your Amazon EBS root volume. This allows you to restore the
original state of your EC2 instance. For information about creating EBS snapshots, see Creating
Amazon EBS Snapshots (p. 869).
• The procedure below requires you to edit your httpd.conf file, which controls Apache's operation.
Certbot makes its own automated changes to this and other configuration files. Make a backup copy of
your entire /etc/httpd directory in case you need to restore it.
Prepare to Install
Complete the following procedures before you install Certbot.
1. Download the Extra Packages for Enterprise Linux (EPEL) 7 repository packages. These are required
to supply dependencies needed by Certbot.
a. Navigate to your home directory (/home/ec2-user). Download EPEL with the following
command.
71
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Certificate Automation: Let's Encrypt
with Certbot on Amazon Linux 2
b. Install the repository packages as shown in the following command.
You can confirm that EPEL is enabled with the following command. It should return information
similar to the following.
...
epel/x86_64 Extra Packages for Enterprise Linux 7 - x86_64
enabled: 12949+175
epel-debuginfo/x86_64 Extra Packages for Enterprise Linux 7 - x86_64
- Debug enabled: 2890
epel-source/x86_64 Extra Packages for Enterprise Linux 7 - x86_64
- Source enabled: 0
epel-testing/x86_64 Extra Packages for Enterprise Linux 7 -
Testing - x86_64 enabled: 778+12
epel-testing-debuginfo/x86_64 Extra Packages for Enterprise Linux 7 -
Testing - x86_64 - Debug enabled: 107
epel-testing-source/x86_64 Extra Packages for Enterprise Linux 7 -
Testing - x86_64 - Source enabled: 0
...
2. Edit the main Apache configuration file, /etc/httpd/conf/httpd.conf. Locate the "listen 80"
directive and add the following lines after it, replacing the example domain names with the actual
Common Name and Subject Alternative Name (SAN).
<VirtualHost *:80>
DocumentRoot "/var/www/html"
ServerName "example.com"
ServerAlias "www.example.com"
</VirtualHost>
2. Run Certbot.
72
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Certificate Automation: Let's Encrypt
with Certbot on Amazon Linux 2
[ec2-user ~]$ sudo certbot
3. At the prompt "Enter email address (used for urgent renewal and security notices)," enter a contact
address and press Enter.
4. Agree to the Let's Encrypt Terms of Service at the prompt. Enter "A" and press Enter to proceed.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Please read the Terms of Service at
https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf. You must
agree in order to register with the ACME server at
https://acme-v02.api.letsencrypt.org/directory
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(A)gree/(C)ancel: A
5. At the authorization for EFF to put you on their mailing list, enter "Y" or "N" and press Enter.
6. Certbot displays the Common Name and Subject Alternative Name (SAN) that you provided in the
VirtualHost block.
Please choose whether or not to redirect HTTP traffic to HTTPS, removing HTTP access.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1: No redirect - Make no further changes to the webserver configuration.
2: Redirect - Make all requests redirect to secure HTTPS access. Choose this for
new sites, or if you're confident your site works on HTTPS. You can undo this
change by editing your web server's configuration.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Select the appropriate number [1-2] then [enter] (press 'c' to cancel):
To allow visitors to connect to your server via unencrypted HTTP, enter "1". If you want to accept
only encrypted connections via HTTPS, enter "2". Press Enter to submit your choice.
8. Certbot completes the configuration of Apache and reports success and other information.
73
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Certificate Automation: Let's Encrypt
with Certbot on Amazon Linux 2
You should test your configuration at:
https://www.ssllabs.com/ssltest/analyze.html?d=example.com
https://www.ssllabs.com/ssltest/analyze.html?d=www.example.com
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
IMPORTANT NOTES:
- Congratulations! Your certificate and chain have been saved at:
/etc/letsencrypt/live/certbot.oneeyedman.net/fullchain.pem
Your key file has been saved at:
/etc/letsencrypt/live/certbot.oneeyedman.net/privkey.pem
Your cert will expire on 2019-08-01. To obtain a new or tweaked
version of this certificate in the future, simply run certbot again
with the "certonly" option. To non-interactively renew *all* of
your certificates, run "certbot renew"
- Your account credentials have been saved in your Certbot
configuration directory at /etc/letsencrypt. You should make a
secure backup of this folder now. This configuration directory will
also contain certificates and private keys obtained by Certbot so
making regular backups of this folder is ideal.
9. After you complete the installation, test and optimize the security of your server as described in
Step 3: Test and Harden the Security Configuration (p. 68).
To automate Certbot
1. Open /etc/crontab in a text editor and add a line similar to the following.
Save the file when done. Here is an explanation of each component of the command.
39 1,13 * * *
Schedules a command to be run at 01:39 and 13:39 every day. The selected values are arbitrary,
but the Certbot developers suggest running the command at least twice daily. This guarantees
that any certificate found to be compromised is promptly revoked and replaced.
root
The command to be run. The renew subcommand causes Certbot to check any previously
obtained certificates and to renew those that are approaching expiration. The --no-self-
upgrade flag prevents Certbot from upgrading itself without your intervention.
2. Restart the cron daemon.
74
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Tutorial: Configure SSL/TLS on Amazon Linux
For historical reasons, web encryption is often referred to simply as SSL. While web browsers still
support SSL, its successor protocol TLS is less vulnerable to attack. The Amazon Linux AMI disables
server-side support all versions of SSL by default. Security standards bodies consider TLS 1.0 to be
unsafe, and both TLS 1.0 and TLS 1.1 are on track to be formally deprecated by the IETF. This tutorial
contains guidance based exclusively on enabling TLS 1.2. (A newer TLS 1.3 protocol exists in draft form,
but is not yet supported on Amazon Linux 2.) For more information about the updated encryption
standards, see RFC 7568 and RFC 8446.
Contents
• Prerequisites (p. 75)
• Step 1: Enable TLS on the Server (p. 76)
• Step 2: Obtain a CA-signed Certificate (p. 77)
• Step 3: Test and Harden the Security Configuration (p. 82)
• Troubleshooting (p. 84)
• Certificate Automation: Let's Encrypt with Certbot on Amazon Linux (p. 84)
Prerequisites
Before you begin this tutorial, complete the following steps:
• Launch an EBS-backed instance using the Amazon Linux AMI. For more information, see Step 1: Launch
an Instance (p. 28).
• Configure your security group to allow your instance to accept connections on the following TCP ports:
• SSH (port 22)
• HTTP (port 80)
• HTTPS (port 443)
For more information, see Authorizing Inbound Traffic for Your Linux Instances (p. 704).
• Install Apache web server. For step-by-step instructions, see Tutorial: Installing a LAMP Web Server on
Amazon Linux (p. 42). Only the http24 package and its dependencies are needed; you can ignore
the instructions involving PHP and MySQL.
• To identify and authenticate web sites, the TLS public key infrastructure (PKI) relies on the Domain
Name System (DNS). To use your EC2 instance to host a public web site, you need to register a domain
name for your web server or transfer an existing domain name to your Amazon EC2 host. Numerous
third-party domain registration and DNS hosting services are available for this, or you can use Amazon
Route 53.
75
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 1: Enable TLS on the Server
1. Connect to your instance (p. 29) and confirm that Apache is running.
2. To ensure that all of your software packages are up to date, perform a quick software update on
your instance. This process may take a few minutes, but it is important to make sure you have the
latest security updates and bug fixes.
Note
The -y option installs the updates without asking for confirmation. If you would like to
examine the updates before installing, you can omit this option.
3. Now that your instance is current, add TLS support by installing the Apache module mod_ssl:
Your instance now has the following files that you use to configure your secure server and create a
certificate for testing:
/etc/httpd/conf.d/ssl.conf
The configuration file for mod_ssl. It contains "directives" telling Apache where to find
encryption keys and certificates, the TLS protocol versions to allow, and the encryption ciphers
to accept.
/etc/pki/tls/private/localhost.key
An automatically generated, 2048-bit RSA private key for your Amazon EC2 host. During
installation, OpenSSL used this key to generate a self-signed host certificate, and you can also
use this key to generate a certificate signing request (CSR) to submit to a certificate authority
(CA).
/etc/pki/tls/certs/localhost.crt
An automatically generated, self-signed X.509 certificate for your server host. This certificate is
useful for testing that Apache is properly set up to use TLS.
The .key and .crt files are both in PEM format, which consists of Base64-encoded ASCII characters
framed by "BEGIN" and "END" lines, as in this abbreviated example of a certificate:
-----BEGIN CERTIFICATE-----
76
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 2: Obtain a CA-signed Certificate
MIIEazCCA1OgAwIBAgICWxQwDQYJKoZIhvcNAQELBQAwgbExCzAJBgNVBAYTAi0t
MRIwEAYDVQQIDAlTb21lU3RhdGUxETAPBgNVBAcMCFNvbWVDaXR5MRkwFwYDVQQK
DBBTb21lT3JnYW5pemF0aW9uMR8wHQYDVQQLDBZTb21lT3JnYW5pemF0aW9uYWxV
bml0MRkwFwYDVQQDDBBpcC0xNzItMzEtMjAtMjM2MSQwIgYJKoZIhvcNAQkBFhVy
...
z5rRUE/XzxRLBZOoWZpNWTXJkQ3uFYH6s/sBwtHpKKZMzOvDedREjNKAvk4ws6F0
WanXWehT6FiSZvB4sTEXXJN2jdw8g+sHGnZ8zCOsclknYhHrCVD2vnBlZJKSZvak
3ZazhBxtQSukFMOnWPP2a0DMMFGYUHOd0BQE8sBJxg==
-----END CERTIFICATE-----
The file names and extensions are a convenience and have no effect on function; you can call a
certificate cert.crt, cert.pem, or any other file name, so long as the related directive in the
ssl.conf file uses the same name.
Note
When you replace the default TLS files with your own customized files, be sure that they are
in PEM format.
4. Restart Apache.
5. Your Apache web server should now support HTTPS (secure HTTP) over port 443. Test it by typing
the IP address or fully qualified domain name of your EC2 instance into a browser URL bar with the
prefix https://. Because you are connecting to a site with a self-signed, untrusted host certificate,
your browser may display a series of security warnings.
Override the warnings and proceed to the site. If the default Apache test page opens, it means that
you have successfully configured TLS on your server. All data passing between the browser and
server is now safely encrypted.
To prevent site visitors from encountering warning screens, you need to obtain a certificate that not
only encrypts, but also publicly authenticates you as the owner of the site.
A self-signed TLS X.509 host certificate is cryptologically identical to a CA-signed certificate. The
difference is social, not mathematical; a CA promises to validate, at a minimum, a domain's ownership
before issuing a certificate to an applicant. Each web browser contains a list of CAs trusted by the
browser vendor to do this. An X.509 certificate consists primarily of a public key that corresponds to
your private server key, and a signature by the CA that is cryptographically tied to the public key. When a
browser connects to a web server over HTTPS, the server presents a certificate for the browser to check
against its list of trusted CAs. If the signer is on the list, or accessible through a chain of trust consisting
of other trusted signers, the browser negotiates a fast encrypted data channel with the server and loads
the page.
Certificates generally cost money because of the labor involved in validating the requests, so it pays
to shop around. A list of well-known CAs can be found at dmoztools.net. A few CAs offer basic-level
certificates free of charge. The most notable of these is the Let's Encrypt project, which also supports
77
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 2: Obtain a CA-signed Certificate
automation of the certificate creation and renewal process. For more information about using Let's
Encrypt as your CA, see Certificate Automation: Let's Encrypt with Certbot on Amazon Linux (p. 84).
Underlying the host certificate is the key. As of 2017, government and industry groups recommend using
a minimum key (modulus) size of 2048 bits for RSA keys intended to protect documents through 2030.
The default modulus size generated by OpenSSL in Amazon Linux is 2048 bits, which means that the
existing auto-generated key is suitable for use in a CA-signed certificate. An alternative procedure is
described below for those who desire a customized key, for instance, one with a larger modulus or using
a different encryption algorithm.
These instructions for acquiring a CA-signed host certificate do not work unless you own a registered and
hosted DNS domain.
1. Connect to your instance (p. 29) and navigate to /etc/pki/tls/private/. This is the directory where
the server's private key for TLS is stored. If you prefer to use your existing host key to generate the
CSR, skip to Step 3.
2. (Optional) Generate a new private key. Here are some examples of key configurations. Any of
the resulting keys work with your web server, but they vary in how (and how much) security they
implement.
• Example 1: Create a default RSA host key. The resulting file, custom.key, is a 2048-bit RSA
private key.
• Example 2: Create a stronger RSA key with a bigger modulus. The resulting file, custom.key, is a
4096-bit RSA private key.
• Example 3: Create a 4096-bit encrypted RSA key with password protection. The resulting file,
custom.key, is a 4096-bit RSA private key encrypted with the AES-128 cipher.
Important
Encrypting the key provides greater security, but because an encrypted key requires a
password, services depending on it cannot be auto-started. Each time you use this key,
you must supply the password (in the preceding example, "abcde12345") over an SSH
connection.
[ec2-user ~]$ sudo openssl genrsa -aes128 -passout pass:abcde12345 -out custom.key
4096
• Example 4: Create a key using a non-RSA cipher. RSA cryptography can be relatively slow because
of the size of its public keys, which are based on the product of two large prime numbers.
However, it is possible to create keys for TLS that use non-RSA ciphers. Keys based on the
mathematics of elliptic curves are smaller and computationally faster when delivering an
equivalent level of security.
[ec2-user ~]$ sudo openssl ecparam -name prime256v1 -out custom.key -genkey
The result is a 256-bit elliptic curve private key using prime256v1, a "named curve" that OpenSSL
supports. Its cryptographic strength is slightly greater than a 2048-bit RSA key, according to NIST.
Note
Not all CAs provide the same level of support for elliptic-curve-based keys as for RSA
keys.
78
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 2: Obtain a CA-signed Certificate
Make sure that the new private key has highly restrictive ownership and permissions (owner=root,
group=root, read/write for owner only). The commands would be as follows:
After you have created and configured a satisfactory key, you can create a CSR.
3. Create a CSR using your preferred key; the example below uses custom.key:
[ec2-user ~]$ sudo openssl req -new -key custom.key -out csr.pem
OpenSSL opens a dialog and prompts you for the information shown in the following table. All of
the fields except Common Name are optional for a basic, domain-validated host certificate.
Country Name The two-letter ISO abbreviation for your US (=United States)
country.
Organization The full legal name of your organization. Do not Example Corporation
Name abbreviate your organization name.
Common This value must exactly match the web address www.example.com
Name that you expect users to type into a browser.
Usually, this means a domain name with
a prefixed host name or alias in the form
www.example.com. In testing with a self-
signed certificate and no DNS resolution,
the common name may consist of the host
name alone. CAs also offer more expensive
certificates that accept wild-card names such as
*.example.com.
Finally, OpenSSL prompts you for an optional challenge password. This password applies only to the
CSR and to transactions between you and your CA, so follow the CA's recommendations about this
and the other optional field, optional company name. The CSR challenge password has no effect on
server operation.
79
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 2: Obtain a CA-signed Certificate
The resulting file csr.pem contains your public key, your digital signature of your public key, and
the metadata that you entered.
4. Submit the CSR to a CA. This usually consists of opening your CSR file in a text editor and copying
the contents into a web form. At this time, you may be asked to supply one or more subject
alternate names (SANs) to be placed on the certificate. If www.example.com is the common name,
then example.com would be a good SAN, and vice versa. A visitor to your site typing in either of
these names would see an error-free connection. If your CA web form allows it, include the common
name in the list of SANs. Some CAs include it automatically.
After your request has been approved, you receive a new host certificate signed by the CA. You
might also be instructed to download an intermediate certificate file that contains additional
certificates needed to complete the CA's chain of trust.
Note
Your CA may send you files in multiple formats intended for various purposes. For this
tutorial, you should only use a certificate file in PEM format, which is usually (but not
always) marked with a .pem or .crt extension. If you are uncertain which file to use, open
the files with a text editor and find the one containing one or more blocks beginning with
the following:
- - - - -BEGIN CERTIFICATE - - - - -
- - - -END CERTIFICATE - - - - -
Verify that these lines appear in the file. Do not use files ending with .p7b, .p7c, or similar
file extensions.
5. Place the new CA-signed certificate and any intermediate certificates in the /etc/pki/tls/certs
directory.
Note
There are several ways to upload your custom key to your EC2 instance, but the most
straightforward and informative way is to open a text editor (for example, vi, nano,
or notepad) on both your local computer and your instance, and then copy and paste
the file contents between them. You need root [sudo] permissions when performing
these operations on the EC2 instance. This way, you can see immediately if there are any
permission or path problems. Be careful, however, not to add any additional lines while
copying the contents, or to change them in any way.
From inside the /etc/pki/tls/certs directory, use the following commands to verify that the
file ownership, group, and permission settings match the highly restrictive Amazon Linux defaults
(owner=root, group=root, read/write for owner only).
80
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 2: Obtain a CA-signed Certificate
The permissions for the intermediate certificate file are less stringent (owner=root, group=root,
owner can write, group can read, world can read). The commands would be:
6. If you used a custom key to create your CSR and the resulting host certificate, remove or rename the
old key from the /etc/pki/tls/private/ directory, and then install the new key there.
Note
There are several ways to upload your custom key to your EC2 instance, but the most
straightforward and informative way is to open a text editor (vi, nano, notepad, etc.) on
both your local computer and your instance, and then copy and paste the file contents
between them. You need root [sudo] privileges when performing these operations on
the EC2 instance. This way, you can see immediately if there are any permission or path
problems. Be careful, however, not to add any additional lines while copying the contents,
or to change them in any way.
From inside the /etc/pki/tls/private directory, check that the file ownership, group, and
permission settings match the highly restrictive Amazon Linux defaults (owner=root, group=root,
read/write for owner only). The commands would be as follows:
a. Provide the path and file name of the CA-signed host certificate in Apache's
SSLCertificateFile directive:
SSLCertificateFile /etc/pki/tls/certs/custom.crt
b. If you received an intermediate certificate file (intermediate.crt in this example), provide its
path and file name using Apache's SSLCACertificateFile directive:
SSLCACertificateFile /etc/pki/tls/certs/intermediate.crt
Note
Some CAs combine the host certificate and the intermediate certificates in a single file,
making this directive unnecessary. Consult the instructions provided by your CA.
c. Provide the path and file name of the private key in Apache's SSLCertificateKeyFile
directive:
81
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 3: Test and Harden the Security Configuration
SSLCertificateKeyFile /etc/pki/tls/private/custom.key
9. Test your server by entering your domain name into a browser URL bar with the prefix https://.
Your browser should load the test page over HTTPS without generating errors.
On the Qualys SSL Labs site, type the fully qualified domain name of your server, in the form
www.example.com. After about two minutes, you receive a grade (from A to F) for your site and a
detailed breakdown of the findings. Though the overview shows that the configuration is mostly sound,
the detailed report flags several potential problems. For example:
✗ The RC4 cipher is supported for use by certain older browsers. A cipher is the mathematical core of
an encryption algorithm. RC4, a fast cipher used to encrypt TLS data-streams, is known to have several
serious weaknesses. Unless you have very good reasons to support legacy browsers, you should disable
this.
✗ Old TLS versions are supported. The configuration supports TLS 1.0 (already deprecated) and TLS 1.1
(on a path to deprecation). Only TLS 1.2 has been recommended since 2018.
1. Open the configuration file /etc/httpd/conf.d/ssl.conf in a text editor and comment out the
following lines by typing "#" at the beginning of each:
These directives explicitly disable SSL versions 2 and 3, as well as TLS versions 1.0 and 1.1. The
server now refuses to accept encrypted connections with clients using anything except TLS 1.2. The
verbose wording in the directive communicates more clearly, to a human reader, what the server is
configured to do.
Note
Disabling TLS versions 1.0 and 1.1 in this manner blocks a small percentage of outdated
web browsers from accessing your site.
82
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Step 3: Test and Harden the Security Configuration
1. Open the configuration file /etc/httpd/conf.d/ssl.conf and find the section with
commented-out examples for configuring SSLCipherSuite and SSLProxyCipherSuite.
✔SSLCipherSuite HIGH:MEDIUM:!aNULL:!MD5
✔SSLProxyCipherSuite HIGH:MEDIUM:!aNULL:!MD5
Leave these as they are, and below them add the following directives:
Note
Though shown here on several lines for readability, each of these two directives must be on
a single line without spaces between the cipher names.
SSLCipherSuite ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-
CHACHA20-POLY1305:
ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-
SHA256:ECDHE-ECDSA-AES256-SHA384:
ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:AES:!aNULL:!
eNULL:!EXPORT:!DES:
!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA
SSLProxyCipherSuite ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-
ECDSA-CHACHA20-POLY1305:
ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-
SHA256:ECDHE-ECDSA-AES256-SHA384:
ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:AES:!aNULL:!
eNULL:!EXPORT:!DES:
!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA
These ciphers are a subset of the much longer list of supported ciphers in OpenSSL. They were
selected and ordered according to the following criteria:
Note that the high-ranking ciphers have ECDHE in their names, for Elliptic Curve Diffie-Hellman
Ephemeral ; the ephemeral indicates forward secrecy. Also, RC4 is now among the forbidden ciphers
near the end.
We recommend that you use an explicit list of ciphers instead relying on defaults or terse directives
whose content isn't visible.
Important
The cipher list shown here is just one of many possible lists; for instance, you might want to
optimize a list for speed rather than forward secrecy.
If you anticipate a need to support older clients, you can allow the DES-CBC3-SHA cipher
suite.
Finally, each update to OpenSSL introduces new ciphers and deprecates old ones. Keep your
EC2 Amazon Linux instance up to date, watch for security announcements from OpenSSL,
and be alert to reports of new security exploits in the technical press. For more information,
see Predefined SSL Security Policies for Elastic Load Balancing in the User Guide for Classic
Load Balancers.
2. Uncomment the following line by removing the "#":
83
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Troubleshooting
✔SSLHonorCipherOrder on
This command forces the server to prefer high-ranking ciphers, including (in this case) those that
support forward secrecy. With this directive turned on, the server tries to establish a strongly secure
connection before falling back to allowed ciphers with lesser security.
3. Restart Apache. If you test the domain again on Qualys SSL Labs, you should see that the RC4
vulnerability is gone.
Troubleshooting
• My Apache webserver won't start unless I supply a password
This is expected behavior if you installed an encrypted, password-protected, private server key.
You can remove the encryption and password requirement from the key. Assuming that you have a
private encrypted RSA key called custom.key in the default directory, and that the password on it is
abcde12345, run the following commands on your EC2 instance to generate an unencrypted version
of the key.
Certbot is not officially supported on Amazon Linux AMI, but is available for download and functions
correctly when installed. We recommend that you make the following backups to protect your data and
avoid inconvenience:
• Before you begin, take a snapshot of your Amazon EBS root volume. This allows you to restore the
original state of your EC2 instance. For information about creating EBS snapshots, see Creating
Amazon EBS Snapshots (p. 869).
84
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Certificate Automation: Let's Encrypt
with Certbot on Amazon Linux
• The procedure below requires you to edit your httpd.conf file, which controls Apache's operation.
Certbot makes its own automated changes to this and other configuration files. Make a backup copy of
your entire /etc/httpd directory in case you need to restore it.
1. Enable the Extra Packages for Enterprise Linux (EPEL) repository from the Fedora project on your
instance. Packages from EPEL are required as dependencies when you run the Certbot installation
script.
2. Download the latest release of Certbot from EFF onto your EC2 instance using the following
command.
4. Run the file with root permissions and the --debug flag.
5. At the prompt "Is this ok [y/d/N]," type "y" and press Enter.
6. At the prompt "Enter email address (used for urgent renewal and security notices)," type a contact
address and press Enter.
7. Agree to the Let's Encrypt Terms of Service at the prompt. Type "A" and press Enter to proceed:
-------------------------------------------------------------------------------
Please read the Terms of Service at
https://letsencrypt.org/documents/LE-SA-v1.1.1-August-1-2016.pdf. You must agree
in order to register with the ACME server at
https://acme-v01.api.letsencrypt.org/directory
-------------------------------------------------------------------------------
(A)gree/(C)ancel: A
8. Click through the authorization for EFF put you on their mailing list by typing "Y" or "N" and press
Enter.
9. At the prompt shown below, type your Common Name (the name of your domain as described
above) and your Subject Alternative Name (SAN), separating the two names with a space or a
comma. Then press Enter. In this example, the names have been provided:
No names were found in your configuration files. Please enter in your domain
name(s) (comma and/or space separated) (Enter 'c' to cancel):example.com
www.example.com
10. On an Amazon Linux system with a default Apache configuration, you see output similar to the
example below, asking about the first name you provided. Type "1" and press Enter.
85
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Certificate Automation: Let's Encrypt
with Certbot on Amazon Linux
Which virtual host would you like to choose?
(note: conf files with multiple vhosts are not yet supported)
-------------------------------------------------------------------------------
1: ssl.conf | | HTTPS | Enabled
-------------------------------------------------------------------------------
Press 1 [enter] to confirm the selection (press 'c' to cancel): 1
11. Next, Certbot asks about the second name. Type "1" and press Enter.
12. Authorize Certbot to create and all needed host certificates. When prompted for each name, type
"1" and press Enter as shown in the example:
13. Choose whether to allow insecure connections to your web server. If you choose option 2 (as shown
in the example), all connections to your server will either be encrypted or rejected.
Certbot completes the configuration of Apache and reports success and other information:
86
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Tutorial: Increase the Availability of Your Application
https://www.ssllabs.com/ssltest/analyze.html?d=example.com
https://www.ssllabs.com/ssltest/analyze.html?d=www.example.com
-------------------------------------------------------------------------------
IMPORTANT NOTES:
- Congratulations! Your certificate and chain have been saved at
/etc/letsencrypt/live/example.com/fullchain.pem. Your cert will
expire on 2017-07-19. To obtain a new or tweaked version of this
certificate in the future, simply run certbot-auto again with the
"certonly" option. To non-interactively renew *all* of your
certificates, run "certbot-auto renew"
....
14. After you complete the installation, test and optimize the security of your server as described in
Step 3: Test and Harden the Security Configuration (p. 68).
Certbot is designed to become an invisible, error-resistant part of your server system. By default, it
generates host certificates with a short, 90-day expiration time. If you have not previously configured
your system to call the command automatically, you must re-run the certbot command manually. This
procedure shows how to automate Certbot by setting up a cron job.
1. After you have successfully run Certbot for the first time, open /etc/crontab in a text editor and
add a line similar to the following:
39 1,13 * * *
Schedules a command to be run at 01:39 and 13:39 every day. The selected values are arbitrary,
but the Certbot developers suggest running the command at least twice daily. This guarantees
that any certificate found to be compromised is promptly revoked and replaced.
root
The command to be run. The renew subcommand causes Certbot to check any previously
obtained certificates and to renew those that are approaching expiration. The --no-self-
upgrade flag prevents Certbot from upgrading itself without your intervention.
2. Restart the cron daemon:
87
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Prerequisites
for your application across these EC2 instances. This increases the availability of your application. Placing
your instances in multiple Availability Zones also improves the fault tolerance in your application. If one
Availability Zone experiences an outage, traffic is routed to the other Availability Zone.
You can use Amazon EC2 Auto Scaling to maintain a minimum number of running instances for your
application at all times. Amazon EC2 Auto Scaling can detect when your instance or application is
unhealthy and replace it automatically to maintain the availability of your application. You can also
use Amazon EC2 Auto Scaling to scale your Amazon EC2 capacity up or down automatically based on
demand, using criteria that you specify.
In this tutorial, we use Amazon EC2 Auto Scaling with Elastic Load Balancing to ensure that you maintain
a specified number of healthy EC2 instances behind your load balancer. Note that these instances do not
need public IP addresses, because traffic goes to the load balancer and is then routed to the instances.
For more information, see Amazon EC2 Auto Scaling and Elastic Load Balancing.
Contents
• Prerequisites (p. 88)
• Scale and Load Balance Your Application (p. 89)
• Test Your Load Balancer (p. 90)
Prerequisites
This tutorial assumes that you have already done the following:
1. Created a virtual private cloud (VPC) with one public subnet in two or more Availability Zones. If you
haven't done so, see Create a Virtual Private Cloud (VPC) (p. 24).
2. Launched an instance in the VPC.
3. Connected to the instance and customized it. For example, installing software and applications,
copying data, and attaching additional EBS volumes. For information about setting up a web server
on your instance, see Tutorial: Install a LAMP Web Server with the Amazon Linux AMI (p. 42).
4. Tested your application on your instance to ensure that your instance is configured correctly.
5. Created a custom Amazon Machine Image (AMI) from your instance. For more information, see
Creating an Amazon EBS-Backed Linux AMI (p. 116) or Creating an Instance Store-Backed Linux
AMI (p. 119).
6. (Optional) Terminated the instance if you no longer need it.
7. Created an IAM role that grants your application the access to AWS it needs. For more information,
see To create an IAM role using the IAM console (p. 698).
88
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Scale and Load Balance Your Application
a. For Name, type a name for your load balancer. For example, my-lb.
b. For Scheme, keep the default value, internet-facing.
c. For Listeners, keep the default, which is a listener that accepts HTTP traffic on port 80.
d. For Availability Zones, select the VPC that you used for your instances. Select an Availability
Zone and then select the public subnet for that Availability Zone. Repeat for a second
Availability Zone.
e. Choose Next: Configure Security Settings.
6. For this tutorial, you are not using a secure listener. Choose Next: Configure Security Groups.
7. On the Configure Security Groups page, do the following:
a. For Name, type a name for your launch configuration (for example, my-launch-config).
89
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Test Your Load Balancer
b. For IAM role, select the IAM role that you created in Prerequisites (p. 88).
c. (Optional) If you need to run a startup script, expand Advanced Details and type the script in
User data.
d. Choose Skip to review.
15. On the Review page, choose Edit security groups. You can select an existing security group or
create a new one. This security group must allow HTTP traffic and health checks from the load
balancer. If your instances will have public IP addresses, you can optionally allow SSH traffic if you
need to connect to the instances. When you are finished, choose Review.
16. On the Review page, choose Create launch configuration.
17. When prompted, select an existing key pair, create a new key pair, or proceed without a key pair.
Select the acknowledgment check box, and then choose Create launch configuration.
18. After the launch configuration is created, you must create an Auto Scaling group.
• If you are new to Amazon EC2 Auto Scaling and you are using the Create Auto Scaling group
wizard, you are taken to the next step automatically.
• Otherwise, choose Create an Auto Scaling group using this launch configuration.
19. On the Configure Auto Scaling group details page, do the following:
a. For Group name, type a name for the Auto Scaling group. For example, my-asg.
b. For Group size, type the number of instances (for example, 2). Note that we recommend that
you maintain approximately the same number of instances in each Availability Zone.
c. Select your VPC from Network and your two public subnets from Subnet.
d. Under Advanced Details, select Receive traffic from one or more load balancers. Select your
target group from Target Groups.
e. Choose Next: Configure scaling policies.
20. On the Configure scaling policies page, choose Review, as we will let Amazon EC2 Auto Scaling
maintain the group at the specified size. Note that later on, you can manually scale this Auto Scaling
group, configure the group to scale on a schedule, or configure the group to scale based on demand.
21. On the Review page, choose Create Auto Scaling group.
22. After the group is created, choose Close.
1. Verify that your instances are ready. From the Auto Scaling Groups page, select your Auto Scaling
group, and then choose the Instances tab. Initially, your instances are in the Pending state. When
their states are InService, they are ready for use.
2. Verify that your instances are registered with the load balancer. From the Target Groups page, select
your target group, and then choose the Targets tab. If the state of your instances is initial, it's
possible that they are still registering. When the state of your instances is healthy, they are ready
for use. After your instances are ready, you can test your load balancer as follows.
3. From the Load Balancers page, select your load balancer.
4. On the Description tab, locate the DNS name. This name has the following form:
my-lb-xxxxxxxxxx.us-west-2.elb.amazonaws.com
5. In a web browser, paste the DNS name for the load balancer into the address bar and press Enter.
You'll see your website displayed.
90
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Tutorial: Remotely Manage Your EC2 Instances
You must configure an AWS Identity and Access Management (IAM) instance profile for Systems Manager.
In order for your instance to communicate with the Systems Manager API, the AWS managed policy
AmazonSSMManagedInstanceCore must be attached to the instance profile. The permissions in this
policy enable the instance to communicate with the Systems Manager API and provides the minimum
permissions necessary to use the Systems Manager service.
For information about creating an IAM instance profile for Systems Manager with these permissions, and
for information about other permissions and policies you can assign to your instance profile, see Create
an IAM Instance Profile for Systems Manager in the AWS Systems Manager User Guide.
You must also configure your IAM user account for Systems Manager, as described in the next section.
To install SSM Agent on Linux, see Installing and Configuring SSM Agent on Amazon EC2 Linux Instances
in the AWS Systems Manager User Guide.
91
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Send a Command Using the Systems Manager Console
To install SSM Agent on Windows, see Installing and Configuring SSM Agent on Windows Instances in the
AWS Systems Manager User Guide.
If you don't see the instance, verify that you are currently in the same AWS Region as the instance
you created. Also verify that you configured the IAM role and trust policies as described earlier.
6. For Execute on, enter 1.
7. For Stop after, enter 1.
8. For Commands, type Get-Service for Windows, or ps aux for Linux.
9. (Optional) For Working Directory, specify a path to the folder on your EC2 instances where you
want to run the command.
10. (Optional) For Execution Timeout, specify the number of seconds the EC2Config service or SSM
Agent will attempt to run the command before it times out and fails.
Note
Windows AMIs published before November 2016 use the EC2Config service to process
requests and configure instances. Unless you have a specific reason for using the EC2Config
service or an earlier version of SSM Agent to process Systems Manager requests, we
recommend that you download and install the latest version of the SSM Agent to each of
your Amazon EC2 instances and managed instances in your hybrid environment. For more
information, see Working with SSM Agent in the AWS Systems Manager User Guide
11. For Comment, we recommend providing information that will help you identify this command in
your list of commands.
12. For Timeout (seconds), type the number of seconds that Run Command should attempt to reach an
instance before the instance is considered unreachable and the command execution fails.
13. Choose Run to execute the command. Run Command displays a status screen. Choose View result.
14. To view the output, choose the command invocation for the command, choose the Output tab.
92
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Send a Command Using AWS
Tools for Windows PowerShell
For more examples of how to execute commands using Run Command, see Running Commands Using
Systems Manager Run Command in the AWS Systems Manager User Guide.
To run a command
1. On your local computer, download the latest version of AWS Tools for Windows PowerShell.
2. Open AWS Tools for Windows PowerShell on your local computer and run the following command
to specify your credentials.
3. Run the following command to set the Region for your PowerShell session. Specify the AWS Region
where you created the instance in the previous procedure. This example uses the us-west-2 region.
4. Run the following command to retrieve the services running on the instance.
The command returns a command ID, which you will use to view the results.
93
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Send a Command Using the AWS CLI
5. The following command returns the output of the original Send-SSMCommand. The output is
truncated after 2500 characters. To view the full list of services, specify an Amazon S3 bucket in the
command using the -OutputS3BucketName bucket_name parameter.
For more examples of how to execute commands using Run Command with Tools for Windows
PowerShell, see Systems Manager Run Command Walkthough Using the AWS Tools for Windows
PowerShell.
To execute a command
Install and configure the AWS CLI, if you have not already.
For information, see Install or Upgrade and then Configure the AWS CLI in the AWS Systems Manager
User Guide.
1. Run the following command to retrieve the services running on the instance.
The command returns a command ID, which you will use to view the results.
2. The following command returns the output of the original Send-SSMCommand. The output is
truncated after 2500 characters. To view the full list of services, you specify an Amazon S3 bucket in
the command using the --output-s3-bucket-name bucket_name parameter.
For more examples of how to run commands using Run Command using the AWS CLI, see Walkthrough:
Use the AWS CLI with Run Command in the AWS Systems Manager User Guide.
Related Content
For more information about Run Command and Systems Manager, see the following references.
94
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Using an AMI
• One or more EBS snapshots, or, for instance-store-backed AMIs, a template for the root volume of the
instance (for example, an operating system, an application server, and applications).
• Launch permissions that control which AWS accounts can use the AMI to launch instances.
• A block device mapping that specifies the volumes to attach to the instance when it's launched.
Using an AMI
The following diagram summarizes the AMI lifecycle. After you create and register an AMI, you can use it
to launch new instances. (You can also launch instances from an AMI if the AMI owner grants you launch
permissions.) You can copy an AMI within the same region or to different regions. When you no longer
require an AMI, you can deregister it.
You can search for an AMI that meets the criteria for your instance. You can search for AMIs provided by
AWS or AMIs provided by the community. For more information, see AMI Types (p. 96) and Finding a
Linux AMI (p. 100).
After you launch an instance from an AMI, you can connect to it. When you are connected to an instance,
you can use it just like you use any other server. For information about launching, connecting, and using
your instance, see Amazon EC2 Instances (p. 178).
The root storage device of the instance determines the process you follow to create an AMI. The root
volume of an instance is either an Amazon EBS volume or an instance store volume. For information, see
Amazon EC2 Root Device Volume (p. 14).
To create an Amazon EBS-backed AMI, see Creating an Amazon EBS-Backed Linux AMI (p. 116). To
create an instance store-backed AMI, see Creating an Instance Store-Backed Linux AMI (p. 119).
95
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Buying, Sharing, and Selling AMIs
To help categorize and manage your AMIs, you can assign custom tags to them. For more information,
see Tagging Your Amazon EC2 Resources (p. 995).
You can purchase AMIs from a third party, including AMIs that come with service contracts from
organizations such as Red Hat. You can also create an AMI and sell it to other Amazon EC2 users. For
more information about buying or selling AMIs, see Paid AMIs (p. 112).
• A stable, secure, and high-performance execution environment for applications running on Amazon
EC2.
• Provided at no additional charge to Amazon EC2 users.
• Repository access to multiple versions of MySQL, PostgreSQL, Python, Ruby, Tomcat, and many more
common packages.
• Updated on a regular basis to include the latest components, and these updates are also made
available in the yum repositories for installation on running instances.
• Includes packages that enable easy integration with AWS services, such as the AWS CLI, Amazon EC2
API and AMI tools, the Boto library for Python, and the Elastic Load Balancing tools.
AMI Types
You can select an AMI to use based on the following characteristics:
96
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch Permissions
Launch Permissions
The owner of an AMI determines its availability by specifying launch permissions. Launch permissions fall
into the following categories.
Launch Description
Permission
Amazon and the Amazon EC2 community provide a large selection of public AMIs. For more information,
see Shared AMIs (p. 103). Developers can charge for their AMIs. For more information, see Paid
AMIs (p. 112).
The following table summarizes the important differences when using the two types of AMIs.
Boot time for an Usually less than 1 minute Usually less than 5 minutes
instance
Data persistence By default, the root volume Data on any instance store volumes
is deleted when the instance persists only during the life of the
terminates.* Data on any other instance.
Amazon EBS volumes persists after
instance termination by default.
Modifications The instance type, kernel, RAM disk, Instance attributes are fixed for the
and user data can be changed while life of an instance.
the instance is stopped.
Charges You're charged for instance usage, You're charged for instance usage
Amazon EBS volume usage, and and storing your AMI in Amazon S3.
storing your AMI as an Amazon EBS
snapshot.
97
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Storage for the Root Device
AMI creation/bundling Uses a single command/call Requires installation and use of AMI
tools
* By default, Amazon EBS-backed instance root volumes have the DeleteOnTermination flag set to
true. For information about how to change this flag so that the volume persists after termination, see
Changing the Root Device Volume to Persist (p. 16).
To determine the root device type of an AMI using the command line
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
Stopped State
You can stop an Amazon EBS-backed instance, but not an Amazon EC2 instance store-backed instance.
Stopping causes the instance to stop running (its status goes from running to stopping to stopped).
A stopped instance persists in Amazon EBS, which allows it to be restarted. Stopping is different from
terminating; you can't restart a terminated instance. Because Amazon EC2 instance store-backed
instances can't be stopped, they're either running or terminated. For more information about what
happens and what you can do while an instance is stopped, see Stop and Start Your Instance (p. 468).
Instances that use Amazon EBS for the root device automatically have an Amazon EBS volume attached.
The volume appears in your list of volumes like any other. With most instance types, Amazon EBS-
backed instances don't have instance store volumes by default. You can add instance store volumes or
98
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Virtualization Types
additional Amazon EBS volumes using a block device mapping. For more information, see Block Device
Mapping (p. 977).
Boot Times
Instances launched from an Amazon EBS-backed AMI launch faster than instances launched from an
instance store-backed AMI. When you launch an instance from an instance store-backed AMI, all the
parts have to be retrieved from Amazon S3 before the instance is available. With an Amazon EBS-backed
AMI, only the parts required to boot the instance need to be retrieved from the snapshot before the
instance is available. However, the performance of an instance that uses an Amazon EBS volume for
its root device is slower for a short time while the remaining parts are retrieved from the snapshot and
loaded into the volume. When you stop and restart the instance, it launches quickly, because the state is
stored in an Amazon EBS volume.
AMI Creation
To create Linux AMIs backed by instance store, you must create an AMI from your instance on the
instance itself using the Amazon EC2 AMI tools.
AMI creation is much easier for AMIs backed by Amazon EBS. The CreateImage API action creates your
Amazon EBS-backed AMI and registers it. There's also a button in the AWS Management Console that
lets you create an AMI from a running instance. For more information, see Creating an Amazon EBS-
Backed Linux AMI (p. 116).
With Amazon EC2 instance store-backed AMIs, each time you customize an AMI and create a new one, all
of the parts are stored in Amazon S3 for each AMI. So, the storage footprint for each customized AMI is
the full size of the AMI. For Amazon EBS-backed AMIs, each time you customize an AMI and create a new
one, only the changes are stored. So the storage footprint for subsequent AMIs you customize after the
first is much smaller, resulting in lower AMI storage charges.
When an Amazon EBS-backed instance is stopped, you're not charged for instance usage; however, you're
still charged for volume storage. As soon as you start your instance, we charge a minimum of one minute
for usage. After one minute, we charge only for the seconds used. For example, if you run an instance for
20 seconds and then stop it, we charge for a full one minute. If you run an instance for 3 minutes and 40
seconds, we charge for exactly 3 minutes and 40 seconds of usage. We charge you for each second, with
a one-minute minimum, that you keep the instance running, even if the instance remains idle and you
don't connect to it.
For the best performance, we recommend that you use current generation instance types and HVM
AMIs when you launch your instances. For more information about current generation instance types,
see Amazon EC2 Instance Types. If you are using previous generation instance types and would like to
upgrade, see Upgrade Paths.
HVM AMIs
99
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Finding a Linux AMI
HVM AMIs are presented with a fully virtualized set of hardware and boot by executing the master boot
record of the root block device of your image. This virtualization type provides the ability to run an
operating system directly on top of a virtual machine without any modification, as if it were run on the
bare-metal hardware. The Amazon EC2 host system emulates some or all of the underlying hardware
that is presented to the guest.
Unlike PV guests, HVM guests can take advantage of hardware extensions that provide fast access to
the underlying hardware on the host system. For more information on CPU virtualization extensions
available in Amazon EC2, see Intel Virtualization Technology on the Intel website. HVM AMIs are required
to take advantage of enhanced networking and GPU processing. In order to pass through instructions
to specialized network and GPU devices, the OS needs to be able to have access to the native hardware
platform; HVM virtualization provides this access. For more information, see Enhanced Networking on
Linux (p. 750) and Linux Accelerated Computing Instances (p. 241).
To find an HVM AMI, verify that the virtualization type of the AMI is set to hvm, using the console or the
describe-images command.
PV AMIs
PV AMIs boot with a special boot loader called PV-GRUB, which starts the boot cycle and then chain
loads the kernel specified in the menu.lst file on your image. Paravirtual guests can run on host
hardware that does not have explicit support for virtualization, but they cannot take advantage of
special hardware extensions such as enhanced networking or GPU processing. Historically, PV guests had
better performance than HVM guests in many cases, but because of enhancements in HVM virtualization
and the availability of PV drivers for HVM AMIs, this is no longer true. For more information about PV-
GRUB and its use in Amazon EC2, see Enabling Your Own Linux Kernels (p. 172).
The following previous generation instance types support PV AMIs: C1, C3, HS1, M1, M3, M2, and T1.
Current generation instance types do not support PV AMIs.
The following AWS regions support PV instances: Asia Pacific (Tokyo), Asia Pacific (Singapore), Asia
Pacific (Sydney), EU (Frankfurt), EU (Ireland), South America (São Paulo), US East (N. Virginia), US West
(N. California), and US West (Oregon).
To find a PV AMI, verify that the virtualization type of the AMI is set to paravirtual, using the console
or the describe-images command.
PV on HVM
Paravirtual guests traditionally performed better with storage and network operations than HVM guests
because they could leverage special drivers for I/O that avoided the overhead of emulating network
and disk hardware, whereas HVM guests had to translate these instructions to emulated hardware.
Now PV drivers are available for HVM guests, so operating systems that cannot be ported to run in
a paravirtualized environment can still see performance advantages in storage and network I/O by
using them. With these PV on HVM drivers, HVM guests can get the same, or better, performance than
paravirtual guests.
• The Region
• The operating system
• The architecture: 32-bit (i386) or 64-bit (x86_64)
• The root device type: Amazon EBS or instance store
100
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Finding a Linux AMI Using the Amazon EC2 Console
If you need to find a Windows AMI, see Finding a Windows AMI in the Amazon EC2 User Guide for
Windows Instances.
Contents
• Finding a Linux AMI Using the Amazon EC2 Console (p. 101)
• Finding an AMI Using the AWS CLI (p. 101)
• Finding a Quick Start AMI (p. 102)
101
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Finding a Quick Start AMI
more information, see Launching an Instance Using the AWS CLI in the AWS Command Line Interface User
Guide.
The describe-images command supports filtering parameters. For example, use the --owners parameter
to display public AMIs owned by Amazon.
You can add the following filter to the previous command to display only AMIs backed by Amazon EBS:
--filters "Name=root-device-type,Values=ebs"
Important
Omitting the --owners flag from the describe-images command will return all images for
which you have launch permissions, regardless of ownership.
To locate the current version of a quick start AMI, you can enumerate all AMIs with its AMI name, and
then find the one with the most recent creation date.
Example Example: Find the current Ubuntu Server 16.04 LTS AMI
Example Example: Find the current Red Hat Enterprise Linux 7.5 AMI
Example Example: Find the current SUSE Linux Enterprise Server 15 AMI
102
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Shared AMIs
Shared AMIs
A shared AMI is an AMI that a developer created and made available for other developers to use. One of
the easiest ways to get started with Amazon EC2 is to use a shared AMI that has the components you
need and then add custom content. You can also create your own AMIs and share them with others.
You use a shared AMI at your own risk. Amazon can't vouch for the integrity or security of AMIs shared
by other Amazon EC2 users. Therefore, you should treat shared AMIs as you would any foreign code that
you might consider deploying in your own data center and perform the appropriate due diligence. We
recommend that you get an AMI from a trusted source. If you have questions or observations about a
shared AMI, use the AWS forums.
Amazon's public images have an aliased owner, which appears as amazon in the account field. This
enables you to find AMIs from Amazon easily. Other users can't alias their AMIs.
For information about creating an AMI, see Creating an Instance Store-Backed Linux AMI or Creating an
Amazon EBS-Backed Linux AMI . For more information about building, delivering, and maintaining your
applications on the AWS Marketplace, see the AWS Marketplace User Guide and AWS Marketplace Seller
Guide.
Contents
• Finding Shared AMIs (p. 103)
• Making an AMI Public (p. 105)
• Sharing an AMI with Specific AWS Accounts (p. 106)
• Using Bookmarks (p. 108)
• Guidelines for Shared Linux AMIs (p. 108)
103
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Finding Shared AMIs
4. Use filters to list only the types of AMIs that interest you. For example, choose Owner : and then
choose Amazon images to display only Amazon's public images.
The following command lists all public AMIs, including any public AMIs that you own.
The following command lists the AMIs for which you have explicit launch permissions. This list does not
include any AMIs that you own.
The following command lists the AMIs owned by Amazon. Amazon's public AMIs have an aliased owner,
which appears as amazon in the account field. This enables you to find AMIs from Amazon easily. Other
users can't alias their AMIs.
The following command lists the AMIs owned by the specified AWS account.
To reduce the number of displayed AMIs, use a filter to list only the types of AMIs that interest you. For
example, use the following filter to display only EBS-backed AMIs.
--filters "Name=root-device-type,Values=ebs"
To ensure that you don't accidentally lose access to your instance, we recommend that you initiate
two SSH sessions and keep the second session open until you've removed credentials that you don't
recognize and confirmed that you can still log into your instance using SSH.
1. Identify and disable any unauthorized public SSH keys. The only key in the file should be the key you
used to launch the AMI. The following command locates authorized_keys files:
104
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Making an AMI Public
2. Disable password-based authentication for the root user. Open the sshd_config file and edit the
PermitRootLogin line as follows:
PermitRootLogin without-password
Alternatively, you can disable the ability to log into the instance as the root user:
PermitRootLogin No
If you discover a public AMI that you feel presents a security risk, contact the AWS security team. For
more information, see the AWS Security Center.
AMIs are a regional resource. Therefore, sharing an AMI makes it available in that region. To make an AMI
available in a different region, copy the AMI to the region and then share it. For more information, see
Copying an AMI (p. 154).
To avoid exposing sensitive data when you share an AMI, read the security considerations in Guidelines
for Shared Linux AMIs (p. 108) and follow the recommended actions.
Note
If an AMI has a product code, or contains a snapshot of an encrypted volume, you can't make it
public. You can share the AMI only with specific AWS accounts.
105
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Sharing an AMI with Specific AWS Accounts
You can add or remove account IDs from the list of accounts that have launch permissions for an AMI. To
make the AMI public, specify the all group. You can specify both public and explicit launch permissions.
1. Use the modify-image-attribute command as follows to add the all group to the
launchPermission list for the specified AMI.
2. To verify the launch permissions of the AMI, use the following describe-image-attribute command.
3. (Optional) To make the AMI private again, remove the all group from its launch permissions.
Note that the owner of the AMI always has launch permissions and is therefore unaffected by this
command.
AMIs are a regional resource. Therefore, sharing an AMI makes it available in that region. To make an AMI
available in a different region, copy the AMI to the region and then share it. For more information, see
Copying an AMI (p. 154).
There is no limit to the number of AWS accounts with which an AMI can be shared.
106
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Sharing an AMI with Specific AWS Accounts
To share this AMI with multiple users, repeat this step until you have added all the required users.
5. To allow create volume permissions for snapshots, select Add "create volume" permissions to the
following associated snapshots when creating permissions.
Note
You do not need to share the Amazon EBS snapshots that an AMI references in order to
share the AMI. Only the AMI itself needs to be shared; the system automatically provides
the instance access to the referenced Amazon EBS snapshots for the launch. However, you
do need to share any CMKs used to encrypt snapshots that the AMI references. For more
information, see Sharing an Amazon EBS Snapshot (p. 878).
6. Choose Save when you are done.
7. (Optional) To view the AWS account IDs with which you have shared the AMI, select the AMI in the
list, and choose the Permissions tab. To find AMIs that are shared with you, see Finding Shared
AMIs (p. 103).
The following command grants launch permissions for the specified AMI to the specified AWS account.
Note
You do not need to share the Amazon EBS snapshots that an AMI references in order to share
the AMI. Only the AMI itself needs to be shared; the system automatically provides the instance
access to the referenced Amazon EBS snapshots for the launch. However, you do need to share
any CMKs used to encrypt snapshots that the AMI references. For more information, see Sharing
an Amazon EBS Snapshot (p. 878).
The following command removes launch permissions for the specified AMI from the specified AWS
account:
107
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Using Bookmarks
The following command removes all public and explicit launch permissions from the specified AMI. Note
that the owner of the AMI always has launch permissions and is therefore unaffected by this command.
Using Bookmarks
If you have created a public AMI, or shared an AMI with another AWS user, you can create a bookmark
that allows a user to access your AMI and launch an instance in their own account immediately. This is an
easy way to share AMI references, so users don't have to spend time finding your AMI in order to use it.
Note that your AMI must be public, or you must have shared it with the user to whom you want to send
the bookmark.
1. Type a URL with the following information, where region is the region in which your AMI resides:
https://console.aws.amazon.com/ec2/v2/home?
region=region✔LaunchInstanceWizard:ami=ami_id
For example, this URL launches an instance from the ami-0abcdef1234567890 AMI in the us-east-1
region:
https://console.aws.amazon.com/ec2/v2/home?region=us-
east-1✔LaunchInstanceWizard:ami=ami-0abcdef1234567890
Topics
• Update the AMI Tools Before Using Them (p. 109)
• Disable Password-Based Remote Logins for Root (p. 109)
• Disable Local Root Access (p. 109)
• Remove SSH Host Key Pairs (p. 110)
• Install Public Key Credentials (p. 110)
• Disabling sshd DNS Checks (Optional) (p. 111)
• Identify Yourself (p. 111)
108
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Guidelines for Shared Linux AMIs
If you are building AMIs for AWS Marketplace, see Building AMIs for AWS Marketplace for guidelines,
policies and best practices.
For additional information about sharing AMIs safely, see the following articles:
For Amazon Linux 2, install the aws-amitools-ec2 package and add the AMI tools to your PATH with
the following command. For the Amazon Linux AMI, aws-amitools-ec2 package is already installed by
default.
[ec2-user ~]$ sudo yum install -y aws-amitools-ec2 && export PATH=$PATH:/opt/aws/bin > /
etc/profile.d/aws-amitools-ec2.sh && . /etc/profile.d/aws-amitools-ec2.sh
For other distributions, make sure you have the latest AMI tools.
To solve this problem, disable password-based remote logins for the root user.
1. Open the /etc/ssh/sshd_config file with a text editor and locate the following line:
✔PermitRootLogin yes
PermitRootLogin without-password
The location of this configuration file might differ for your distribution, or if you are not running
OpenSSH. If this is the case, consult the relevant documentation.
109
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Guidelines for Shared Linux AMIs
Note
This command does not impact the use of sudo.
Remove all of the following key files that are present on your system.
• ssh_host_dsa_key
• ssh_host_dsa_key.pub
• ssh_host_key
• ssh_host_key.pub
• ssh_host_rsa_key
• ssh_host_rsa_key.pub
• ssh_host_ecdsa_key
• ssh_host_ecdsa_key.pub
• ssh_host_ed25519_key
• ssh_host_ed25519_key.pub
You can securely remove all of these files with the following command.
Warning
Secure deletion utilities such as shred may not remove all copies of a file from your storage
media. Hidden copies of files may be created by journalling file systems (including Amazon Linux
default ext4), snapshots, backups, RAID, and temporary caching. For more information see the
shred documentation.
Important
If you forget to remove the existing SSH host key pairs from your public AMI, our routine
auditing process notifies you and all customers running instances of your AMI of the potential
security risk. After a short grace period, we mark the AMI private.
Amazon EC2 allows users to specify a public-private key pair name when launching an instance. When
a valid key pair name is provided to the RunInstances API call (or through the command line API
tools), the public key (the portion of the key pair that Amazon EC2 retains on the server after a call to
CreateKeyPair or ImportKeyPair) is made available to the instance through an HTTP query against
the instance metadata.
To log in through SSH, your AMI must retrieve the key value at boot and append it to /root/.ssh/
authorized_keys (or the equivalent for any other user account on the AMI). Users can launch instances
of your AMI with a key pair and log in without requiring a root password.
110
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Guidelines for Shared Linux AMIs
Many distributions, including Amazon Linux and Ubuntu, use the cloud-init package to inject public
key credentials for a configured user. If your distribution does not support cloud-init, you can add
the following code to a system start-up script (such as /etc/rc.local) to pull in the public key you
specified at launch for the root user.
if [ ! -d /root/.ssh ] ; then
mkdir -p /root/.ssh
chmod 700 /root/.ssh
fi
✔ Fetch public key using HTTP
curl http://169.254.169.254/latest/meta-data/public-keys/0/openssh-key > /tmp/my-key
if [ $? -eq 0 ] ; then
cat /tmp/my-key >> /root/.ssh/authorized_keys
chmod 700 /root/.ssh/authorized_keys
rm /tmp/my-key
fi
This can be applied to any user account; you do not need to restrict it to root.
Note
Rebundling an instance based on this AMI includes the key with which it was launched. To
prevent the key's inclusion, you must clear out (or delete) the authorized_keys file or exclude
this file from rebundling.
1. Open the /etc/ssh/sshd_config file with a text editor and locate the following line:
✔UseDNS yes
UseDNS no
Note
The location of this configuration file can differ for your distribution or if you are not running
OpenSSH. If this is the case, consult the relevant documentation.
Identify Yourself
Currently, there is no easy way to know who provided a shared AMI, because each AMI is represented by
an account ID.
We recommend that you post a description of your AMI, and the AMI ID, in the Amazon EC2 forum. This
provides a convenient central location for users who are interested in trying new shared AMIs.
Protect Yourself
We recommend against storing sensitive data or software on any AMI that you share. Users who launch a
shared AMI might be able to rebundle it and register it as their own. Follow these guidelines to help you
to avoid some easily overlooked security risks:
111
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Paid AMIs
Warning
The limitations of shred described in the warning above apply here as well.
Be aware that bash writes the history of the current session to the disk on exit. If you log out
of your instance after deleting ~/.bash_history, and then log back in, you will find that
~/.bash_history has been re-created and contains all of the commands executed during
your previous session.
Other programs besides bash also write histories to disk, Use caution and remove or exclude
unnecessary dot-files and dot-directories.
• Bundling a running instance requires your private key and X.509 certificate. Put these and other
credentials in a location that is not bundled (such as the instance store).
Paid AMIs
A paid AMI is an AMI that you can purchase from a developer.
Amazon EC2 integrates with AWS Marketplace, enabling developers to charge other Amazon EC2 users
for the use of their AMIs or to provide support for instances.
The AWS Marketplace is an online store where you can buy software that runs on AWS, including AMIs
that you can use to launch your EC2 instance. The AWS Marketplace AMIs are organized into categories,
such as Developer Tools, to enable you to find products to suit your requirements. For more information
about AWS Marketplace, see the AWS Marketplace site.
Launching an instance from a paid AMI is the same as launching an instance from any other AMI. No
additional parameters are required. The instance is charged according to the rates set by the owner of
the AMI, as well as the standard usage fees for the related web services, for example, the hourly rate for
running an m1.small instance type in Amazon EC2. Additional taxes might also apply. The owner of the
paid AMI can confirm whether a specific instance was launched using that paid AMI.
Important
Amazon DevPay is no longer accepting new sellers or products. AWS Marketplace is now
the single, unified e-commerce platform for selling software and services through AWS. For
information about how to deploy and sell software from AWS Marketplace, see Selling on AWS
Marketplace. AWS Marketplace supports AMIs backed by Amazon EBS.
Contents
• Selling Your AMI (p. 113)
• Finding a Paid AMI (p. 113)
• Purchasing a Paid AMI (p. 114)
• Getting the Product Code for Your Instance (p. 114)
• Using Paid Support (p. 114)
112
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Selling Your AMI
For information about how to sell your AMI on AWS Marketplace, see Selling on AWS Marketplace.
This command returns numerous details that describe each AMI, including the product code for a paid
AMI. The output from describe-images includes an entry for the product code like the following:
"ProductCodes": [
{
"ProductCodeId": "product_code",
"ProductCodeType": "marketplace"
}
113
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Purchasing a Paid AMI
],
If you know the product code, you can filter the results by product code. This example returns the most
recent AMI with the specified product code.
Typically a seller of a paid AMI presents you with information about the AMI, including its price and a
link where you can buy it. When you click the link, you're first asked to log into AWS, and then you can
purchase the AMI.
• AWS Marketplace website: You can launch preconfigured software quickly with the 1-Click
deployment feature.
• Amazon EC2 launch wizard: You can search for an AMI and launch an instance directly from the
wizard. For more information, see Launching an AWS Marketplace Instance (p. 417).
If your instance supports it, you can use the GET command:
114
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Bills for Paid and Supported AMIs
developer gives you a product code, which you must then associate with your own AMI. This enables
the developer to confirm that your instance is eligible for support. It also ensures that when you run
instances of the product, you are charged according to the terms for the product specified by the
developer.
Important
You can't use a support product with Reserved Instances. You always pay the price that's
specified by the seller of the support product.
To associate a product code with your AMI, use one of the following commands, where ami_id is the ID of
the AMI and product_code is the product code:
After you set the product code attribute, it cannot be changed or removed.
1. Ensure that you have terminated any instances running from the subscription.
115
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Creating an Amazon EBS-Backed Linux AMI
Note
After you've canceled your subscription, you are no longer able to launch any instances
from that AMI. To use that AMI again, you need to resubscribe to it, either on the AWS
Marketplace website, or through the launch wizard in the Amazon EC2 console.
The procedures described below work for Amazon EC2 instances backed by encrypted Amazon EBS
volumes (including the root volume) as well as for unencrypted volumes.
The AMI creation process is different for instance store-backed AMIs. For more information about the
differences between Amazon EBS-backed and instance store-backed instances, and how to determine
the root device type for your instance, see Storage for the Root Device (p. 97). For more information
about creating an instance store-backed Linux AMI, see Creating an Instance Store-Backed Linux
AMI (p. 119).
For more information about creating an Amazon EBS-backed Windows AMI, see Creating an Amazon
EBS-Backed Windows AMI in the Amazon EC2 User Guide for Windows Instances.
Amazon EC2 powers down the instance before creating the AMI to ensure that everything on the
instance is stopped and in a consistent state during the creation process. If you're confident that your
instance is in a consistent state appropriate for AMI creation, you can tell Amazon EC2 not to power
down and reboot the instance. Some file systems, such as XFS, can freeze and unfreeze activity, making it
safe to create the image without rebooting the instance.
During the AMI-creation process, Amazon EC2 creates snapshots of your instance's root volume and any
other EBS volumes attached to your instance. You're charged for the snapshots until you deregister the
AMI and delete the snapshots. For more information, see Deregistering Your Linux AMI (p. 159). If any
volumes attached to the instance are encrypted, the new AMI only launches successfully on instances
that support Amazon EBS encryption. For more information, see Amazon EBS Encryption (p. 903).
Depending on the size of the volumes, it can take several minutes for the AMI-creation process to
complete (sometimes up to 24 hours). You may find it more efficient to create snapshots of your volumes
before creating your AMI. This way, only small, incremental snapshots need to be created when the AMI
is created, and the process completes more quickly (the total time for snapshot creation remains the
same). For more information, see Creating Amazon EBS Snapshots (p. 869).
After the process completes, you have a new AMI and snapshot created from the root volume of the
instance. When you launch an instance using the new AMI, we create a new EBS volume for its root
volume using the snapshot.
If you add instance-store volumes or EBS volumes to your instance in addition to the root device volume,
the block device mapping for the new AMI contains information for these volumes, and the block device
116
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Creating a Linux AMI from an Instance
mappings for instances that you launch from the new AMI automatically contain information for these
volumes. The instance-store volumes specified in the block device mapping for the new instance are new
and don't contain any data from the instance store volumes of the instance you used to create the AMI.
The data on EBS volumes persists. For more information, see Block Device Mapping (p. 977).
Note
When you create a new instance from an EBS-backed AMI, you should initialize both its root
volume and any additional EBS storage before putting it into production. For more information,
see Initializing Amazon EBS Volumes.
1. Select an appropriate EBS-backed AMI to serve as a starting point for your new AMI, and configure
it as needed before launch. For more information, see Launching an Instance Using the Launch
Instance Wizard (p. 395).
2. Choose Launch to launch an instance of the EBS-backed AMI that you've selected. Accept the default
values as you step through the wizard. For more information, see Launching an Instance Using the
Launch Instance Wizard (p. 395).
3. While the instance is running, connect to it. You can perform any of the following actions on your
instance to customize it for your needs:
117
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Creating a Linux AMI from a Snapshot
Warning
If you select No reboot, we can't guarantee the file system integrity of the created image.
• Instance Volumes – The fields in this section enable you to modify the root volume, and add
additional Amazon EBS and instance store volumes. For information about each field, pause on
the i icon next to each field to display field tooltips. Some important points are listed below.
• To change the size of the root volume, locate Root in the Volume Type column, and for Size
(GiB), type the required value.
• If you select Delete on Termination, when you terminate the instance created from this
AMI, the EBS volume is deleted. If you clear Delete on Termination, when you terminate the
instance, the EBS volume is not deleted.
Note
Delete on Termination determines if the EBS volume is deleted or not; it does not
affect the instance or the AMI.
• To add an Amazon EBS volume, choose Add New Volume (which adds a new row). For Volume
Type, choose EBS, and fill in the fields in the row. When you launch an instance from your new
AMI, additional volumes are automatically attached to the instance. Empty volumes must be
formatted and mounted. Volumes based on a snapshot must be mounted.
• To add an instance store volume, see Adding Instance Store Volumes to an AMI (p. 962). When
you launch an instance from your new AMI, additional volumes are automatically initialized and
mounted. These volumes do not contain data from the instance store volumes of the running
instance on which you based your AMI.
7. To view the status of your AMI while it is being created, in the navigation pane, choose AMIs.
Initially, the status is pending but should change to available after a few minutes.
(Optional) To view the snapshot that was created for the new AMI, choose Snapshots. When you
launch an instance from this AMI, we use this snapshot to create its root device volume.
8. Launch an instance from your new AMI. For more information, see Launching an Instance Using the
Launch Instance Wizard (p. 395).
9. The new running instance contains all of the customizations that you applied in previous steps.
118
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Creating an Instance Store-Backed Linux AMI
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
The AMI creation process is different for Amazon EBS-backed AMIs. For more information about the
differences between Amazon EBS-backed and instance store-backed instances, and how to determine
the root device type for your instance, see Storage for the Root Device (p. 97). If you need to create an
Amazon EBS-backed Linux AMI, see Creating an Amazon EBS-Backed Linux AMI (p. 116).
119
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Prerequisites
First, launch an instance from an AMI that's similar to the AMI that you'd like to create. You can connect
to your instance and customize it. When the instance is set up the way you want it, you can bundle it.
It takes several minutes for the bundling process to complete. After the process completes, you have a
bundle, which consists of an image manifest (image.manifest.xml) and files (image.part.xx) that
contain a template for the root volume. Next you upload the bundle to your Amazon S3 bucket and then
register your AMI.
When you launch an instance using the new AMI, we create the root volume for the instance using
the bundle that you uploaded to Amazon S3. The storage space used by the bundle in Amazon S3
incurs charges to your account until you delete it. For more information, see Deregistering Your Linux
AMI (p. 159).
If you add instance store volumes to your instance in addition to the root device volume, the block device
mapping for the new AMI contains information for these volumes, and the block device mappings for
instances that you launch from the new AMI automatically contain information for these volumes. For
more information, see Block Device Mapping (p. 977).
Prerequisites
Before you can create an AMI, you must complete the following tasks:
• Install the AMI tools. For more information, see Setting Up the AMI Tools (p. 120).
• Install the AWS CLI. For more information, see Getting Set Up with the AWS Command Line Interface.
• Ensure that you have an Amazon S3 bucket for the bundle. To create an Amazon S3 bucket, open the
Amazon S3 console and click Create Bucket. Alternatively, you can use the AWS CLI mb command.
• Ensure that you have your AWS account ID. For more information, see AWS Account Identifiers in the
AWS General Reference.
• Ensure that you have your access key ID and secret access key. For more information, see Access Keys in
the AWS General Reference.
• Ensure that you have an X.509 certificate and corresponding private key.
• If you need to create an X.509 certificate, see Managing Signing Certificates (p. 122). The X.509
certificate and private key are used to encrypt and decrypt your AMI.
• [China (Beijing)] Use the $EC2_AMITOOL_HOME/etc/ec2/amitools/cert-ec2-cn-
north-1.pem certificate.
• [AWS GovCloud (US-West)] Use the $EC2_AMITOOL_HOME/etc/ec2/amitools/cert-ec2-
gov.pem certificate.
• Connect to your instance and customize it. For example, you can install software and applications,
copy data, delete temporary files, and modify the Linux configuration.
Tasks
120
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Setting Up the AMI Tools
1. Install Ruby using the package manager for your Linux distribution, such as yum. For example:
2. Download the RPM file using a tool such as wget or curl. For example:
The command above should indicate that the file's SHA1 and MD5 hashes are OK. If the command
indicates that the hashes are NOT OK, use the following command to view the file's Header SHA1
and MD5 hashes:
Then, compare your file's Header SHA1 and MD5 hashes with the following verified AMI tools hashes
to confirm the file's authenticity:
If your file's Header SHA1 and MD5 hashes match the verified AMI tools hashes, continue to the next
step.
4. Install the RPM using the following command:
5. Verify your AMI tools installation using the ec2-ami-tools-version (p. 133) command.
Note
If you receive a load error such as "cannot load such file -- ec2/amitools/version
(LoadError)", complete the next step to add the location of your AMI tools installation to
your RUBYLIB path.
6. (Optional) If you received an error in the previous step, add the location of your AMI tools
installation to your RUBYLIB path.
In the above example, the missing file from the previous load error is located at /usr/lib/
ruby/site_ruby and /usr/lib64/ruby/site_ruby.
b. Add the locations from the previous step to your RUBYLIB path.
121
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Setting Up the AMI Tools
c. Verify your AMI tools installation using the ec2-ami-tools-version (p. 133) command.
1. Install Ruby and unzip using the package manager for your Linux distribution, such as apt-get. For
example:
[ec2-user ~]$ sudo apt-get update -y && sudo apt-get install -y ruby unzip
2. Download the .zip file using a tool such as wget or curl. For example:
Notice that the .zip file contains a folder ec2-ami-tools-x.x.x, where x.x.x is the version number of
the tools (for example, ec2-ami-tools-1.5.7).
4. Set the EC2_AMITOOL_HOME environment variable to the installation directory for the tools. For
example:
6. You can verify your AMI tools installation using the ec2-ami-tools-version (p. 133) command.
122
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Creating an AMI from an Instance Store-Backed Instance
openssl req -new -x509 -nodes -sha256 -days 365 -key private-key.pem -outform PEM -
out certificate.pem
To disable or re-enable a signing certificate for a user, use the update-signing-certificate command. The
following command disables the certificate:
Topics
• Creating an AMI from an Instance Store-Backed Amazon Linux Instance (p. 123)
• Creating an AMI from an Instance Store-Backed Ubuntu Instance (p. 126)
1. The AMI tools require GRUB Legacy to boot properly. Use the following command to install GRUB:
123
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Creating an AMI from an Instance Store-Backed Instance
This procedure assumes that you have satisfied the prerequisites in Prerequisites (p. 120).
1. Upload your credentials to your instance. We use these credentials to ensure that only you and
Amazon EC2 can access your AMI.
This enables you to exclude your credentials from the created image.
b. Copy your X.509 certificate and corresponding private key from your computer to the /tmp/
cert directory on your instance using a secure copy tool such as scp (p. 449). The -i my-
private-key.pem option in the following scp command is the private key you use to connect
to your instance with SSH, not the X.509 private key. For example:
Alternatively, because these are plain text files, you can open the certificate and key in a text editor
and copy their contents into new files in /tmp/cert.
2. Prepare the bundle to upload to Amazon S3 by running the ec2-bundle-vol (p. 136) command
from inside your instance. Be sure to specify the -e option to exclude the directory where your
credentials are stored. By default, the bundle process excludes files that might contain sensitive
information. These files include *.sw, *.swo, *.swp, *.pem, *.priv, *id_rsa*, *id_dsa*
*.gpg, *.jks, */.ssh/authorized_keys, and */.bash_history. To include all of these files,
use the --no-filter option. To include some of these files, use the --include option.
Important
By default, the AMI bundling process creates a compressed, encrypted collection of files
in the /tmp directory that represents your root volume. If you do not have enough free
disk space in /tmp to store the bundle, you need to specify a different location for the
bundle to be stored with the -d /path/to/bundle/storage option. Some instances
have ephemeral storage mounted at /mnt or /media/ephemeral0 that you can use, or
you can also create (p. 847), attach (p. 851), and mount (p. 852) a new Amazon EBS
volume to store the bundle.
a. You must run the ec2-bundle-vol command as root. For most commands, you can use sudo to
gain elevated permissions, but in this case, you should run sudo -E su to keep your environment
variables.
Note that bash prompt now identifies you as the root user, and that the dollar sign has been
replaced by a hash tag, signalling that you are in a root shell:
124
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Creating an AMI from an Instance Store-Backed Instance
[root ec2-user]✔
b. To create the AMI bundle, run the ec2-bundle-vol (p. 136) command as follows:
Note
For the China (Beijing) and AWS GovCloud (US-West) regions, use the --ec2cert
parameter and specify the certificates as per the prerequisites (p. 120).
It can take a few minutes to create the image. When this command completes, your /tmp
(or non-default) directory contains the bundle (image.manifest.xml, plus multiple
image.part.xx files).
c. Exit from the root shell.
3. (Optional) To add more instance store volumes, edit the block device mappings in the
image.manifest.xml file for your AMI. For more information, see Block Device Mapping (p. 977).
c. Edit the block device mappings in image.manifest.xml with a text editor. The example below
shows a new entry for the ephemeral1 instance store volume.
Note
For a list of excluded files, see ec2-bundle-vol (p. 136).
<block_device_mapping>
<mapping>
<virtual>ami</virtual>
<device>sda</device>
</mapping>
<mapping>
<virtual>ephemeral0</virtual>
<device>sdb</device>
</mapping>
<mapping>
<virtual>ephemeral1</virtual>
<device>sdc</device>
</mapping>
<mapping>
<virtual>root</virtual>
<device>/dev/sda1</device>
</mapping>
</block_device_mapping>
125
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Creating an AMI from an Instance Store-Backed Instance
4. To upload your bundle to Amazon S3, run the ec2-upload-bundle (p. 146) command as follows.
Important
To register your AMI in a region other than US East (N. Virginia), you must specify both the
target region with the --region option and a bucket path that already exists in the target
region or a unique bucket path that can be created in the target region.
5. (Optional) After the bundle is uploaded to Amazon S3, you can remove the bundle from the /tmp
directory on the instance using the following rm command:
Important
If you specified a path with the -d /path/to/bundle/storage option in Step
2 (p. 124), use that path instead of /tmp.
6. To register your AMI, run the register-image command as follows.
Important
If you previously specified a region for the ec2-upload-bundle (p. 146) command, specify
that region again for this command.
HVM instances also require partitioning tools to be installed for the AMI tools to work properly.
1. GRUB Legacy (version 0.9x or less) must be installed on your instance. Check to see if GRUB Legacy
is present and install it if necessary.
In this example, the GRUB version is greater than 0.9x, so GRUB Legacy must be installed.
Proceed to Step 1.b (p. 126). If GRUB Legacy is already present, you can skip to Step
2 (p. 127).
b. Install the grub package using the following command.
126
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Creating an AMI from an Instance Store-Backed Instance
2. Install the following partition management packages using the package manager for your
distribution.
Note the options following the kernel and root device parameters: ro, console=ttyS0, and
xen_emul_unplug=unnecessary. Your options may differ.
4. Check the kernel entries in /boot/grub/menu.lst.
Note that the console parameter is pointing to hvc0 instead of ttyS0 and that the
xen_emul_unplug=unnecessary parameter is missing. Again, your options may differ.
5. Edit the /boot/grub/menu.lst file with your favorite text editor (such as vim or nano) to change
the console and add the parameters you identified earlier to the boot entries.
6. Verify that your kernel entries now contain the correct parameters.
127
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Creating an AMI from an Instance Store-Backed Instance
7. [For Ubuntu 14.04 and later only] Starting with Ubuntu 14.04, instance store backed Ubuntu AMIs
use a GPT partition table and a separate EFI partition mounted at /boot/efi. The ec2-bundle-vol
command will not bundle this boot partition, so you need to comment out the /etc/fstab entry
for the EFI partition as shown in the following example.
This procedure assumes that you have satisfied the prerequisites in Prerequisites (p. 120).
1. Upload your credentials to your instance. We use these credentials to ensure that only you and
Amazon EC2 can access your AMI.
This enables you to exclude your credentials from the created image.
b. Copy your X.509 certificate and private key from your computer to the /tmp/cert directory on
your instance, using a secure copy tool such as scp (p. 449). The -i my-private-key.pem
option in the following scp command is the private key you use to connect to your instance with
SSH, not the X.509 private key. For example:
Alternatively, because these are plain text files, you can open the certificate and key in a text editor
and copy their contents into new files in /tmp/cert.
2. Prepare the bundle to upload to Amazon S3 by running the ec2-bundle-vol (p. 136) command
from your instance. Be sure to specify the -e option to exclude the directory where your credentials
are stored. By default, the bundle process excludes files that might contain sensitive information.
These files include *.sw, *.swo, *.swp, *.pem, *.priv, *id_rsa*, *id_dsa* *.gpg, *.jks,
*/.ssh/authorized_keys, and */.bash_history. To include all of these files, use the --no-
filter option. To include some of these files, use the --include option.
Important
By default, the AMI bundling process creates a compressed, encrypted collection of files
in the /tmp directory that represents your root volume. If you do not have enough free
disk space in /tmp to store the bundle, you need to specify a different location for the
bundle to be stored with the -d /path/to/bundle/storage option. Some instances
have ephemeral storage mounted at /mnt or /media/ephemeral0 that you can use, or
you can also create (p. 847), attach (p. 851), and mount (p. 852) a new Amazon EBS
volume to store the bundle.
128
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Creating an AMI from an Instance Store-Backed Instance
a. You must run the ec2-bundle-vol command needs as root. For most commands, you can use
sudo to gain elevated permissions, but in this case, you should run sudo -E su to keep your
environment variables.
ubuntu:~$ sudo -E su
Note that bash prompt now identifies you as the root user, and that the dollar sign has been
replaced by a hash tag, signalling that you are in a root shell:
root@ubuntu:✔
b. To create the AMI bundle, run the ec2-bundle-vol (p. 136) command as follows.
Important
For Ubuntu 14.04 and later HVM instances, add the --partition mbr flag to bundle
the boot instructions properly; otherwise, your newly-created AMI will not boot.
It can take a few minutes to create the image. When this command completes, your tmp
directory contains the bundle (image.manifest.xml, plus multiple image.part.xx files).
c. Exit from the root shell.
root@ubuntu:✔ exit
3. (Optional) To add more instance store volumes, edit the block device mappings in the
image.manifest.xml file for your AMI. For more information, see Block Device Mapping (p. 977).
c. Edit the block device mappings in image.manifest.xml with a text editor. The example below
shows a new entry for the ephemeral1 instance store volume.
<block_device_mapping>
<mapping>
<virtual>ami</virtual>
<device>sda</device>
</mapping>
<mapping>
<virtual>ephemeral0</virtual>
<device>sdb</device>
</mapping>
<mapping>
<virtual>ephemeral1</virtual>
<device>sdc</device>
</mapping>
<mapping>
<virtual>root</virtual>
129
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Converting to an Amazon EBS-Backed AMI
<device>/dev/sda1</device>
</mapping>
</block_device_mapping>
Important
If you intend to register your AMI in a region other than US East (N. Virginia), you must
specify both the target region with the --region option and a bucket path that already
exists in the target region or a unique bucket path that can be created in the target region.
5. (Optional) After the bundle is uploaded to Amazon S3, you can remove the bundle from the /tmp
directory on the instance using the following rm command:
Important
If you specified a path with the -d /path/to/bundle/storage option in Step
2 (p. 128), use that same path below, instead of /tmp.
6. To register your AMI, run the register-image AWS CLI command as follows.
Important
If you previously specified a region for the ec2-upload-bundle (p. 146) command, specify
that region again for this command.
7. [Ubuntu 14.04 and later] Uncomment the EFI entry in /etc/fstab; otherwise, your running
instance will not be able to reboot.
1. Launch an Amazon Linux instance from an Amazon EBS-backed AMI. For more information, see
Launching an Instance Using the Launch Instance Wizard (p. 395). Amazon Linux instances have
the AWS CLI and AMI tools pre-installed.
2. Upload the X.509 private key that you used to bundle your instance store-backed AMI to your
instance. We use this key to ensure that only you and Amazon EC2 can access your AMI.
a. Create a temporary directory on your instance for your X.509 private key as follows:
130
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Converting to an Amazon EBS-Backed AMI
b. Copy your X.509 private key from your computer to the /tmp/cert directory on your instance,
using a secure copy tool such as scp (p. 449). The my-private-key parameter in the
following command is the private key you use to connect to your instance with SSH. For
example:
3. Set environment variables for your AWS access key and secret key.
a. Create an empty Amazon EBS volume in the same Availability Zone as your instance using the
create-volume command. Note the volume ID in the command output.
Important
This Amazon EBS volume must be the same size or larger than the original instance
store root volume.
b. Attach the volume to your Amazon EBS-backed instance using the attach-volume command.
6. Download the bundle for your instance store-based AMI to /tmp/bundle using the ec2-download-
bundle (p. 142) command.
7. Reconstitute the image file from the bundle using the ec2-unbundle (p. 145) command.
8. Copy the files from the unbundled image to the new Amazon EBS volume.
131
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Converting to an Amazon EBS-Backed AMI
9. Probe the volume for any new partitions that were unbundled.
10. List the block devices to find the device name to mount.
In this example, the partition to mount is /dev/sdb1, but your device name will likely be different.
If your volume is not partitioned, then the device to mount will be similar to /dev/sdb (without a
device partition trailing digit).
11. Create a mount point for the new Amazon EBS volume and mount the volume.
12. Open the /etc/fstab file on the EBS volume with your favorite text editor (such as vim or nano)
and remove any entries for instance store (ephemeral) volumes. Because the Amazon EBS volume is
mounted on /mnt/ebs, the fstab file is located at /mnt/ebs/etc/fstab.
14. Create an AMI from the new Amazon EBS volume as follows.
132
Amazon Elastic Compute Cloud
User Guide for Linux Instances
AMI Tools Reference
c. Identify the processor architecture, virtualization type, and the kernel image (aki) used on the
original AMI with the describe-images command. You need the AMI ID of the original instance
store-backed AMI for this step.
In this example, the architecture is x86_64 and the kernel image ID is aki-fc8f11cc. Use
these values in the following step. If the output of the above command also lists an ari ID, take
note of that as well.
d. Register your new AMI with the snapshot ID of your new Amazon EBS volume and the values
from the previous step. If the previous command output listed an ari ID, include that in the
following command with --ramdisk-id ari_id.
15. (Optional) After you have tested that you can launch an instance from your new AMI, you can delete
the Amazon EBS volume that you created for this procedure.
For information about your access keys, see Best Practices for Managing AWS Access Keys.
Commands
• ec2-ami-tools-version (p. 133)
• ec2-bundle-image (p. 134)
• ec2-bundle-vol (p. 136)
• ec2-delete-bundle (p. 140)
• ec2-download-bundle (p. 142)
• ec2-migrate-manifest (p. 144)
• ec2-unbundle (p. 145)
• ec2-upload-bundle (p. 146)
• Common Options for AMI Tools (p. 149)
ec2-ami-tools-version
Description
Describes the version of the AMI tools.
133
Amazon Elastic Compute Cloud
User Guide for Linux Instances
AMI Tools Reference
Syntax
ec2-ami-tools-version
Output
The version information.
Example
This example command displays the version information for the AMI tools that you're using.
ec2-bundle-image
Description
Creates an instance store-backed Linux AMI from an operating system image created in a loopback file.
Syntax
ec2-bundle-image -c path -k path -u account -i path [-d path] [--ec2cert path]
[-r architecture] [--productcodes code1,code2,...] [-B mapping] [-p prefix]
Options
-c, --cert path
Required: Yes
-k, --privatekey path
The path to a PEM-encoded RSA key file. You'll need to specify this key to unbundle this bundle, so
keep it in a safe place. Note that the key doesn't have to be registered to your AWS account.
Required: Yes
-u, --user account
Required: Yes
-i, --image path
Required: Yes
-d, --destination path
Default: /tmp
Required: No
--ec2cert path
The path to the Amazon EC2 X.509 public key certificate used to encrypt the image manifest.
134
Amazon Elastic Compute Cloud
User Guide for Linux Instances
AMI Tools Reference
The us-gov-west-1 and cn-north-1 regions use a non-default public key certificate and the path
to that certificate must be specified with this option. The path to the certificate varies based on the
installation method of the AMI tools. For Amazon Linux, the certificates are located at /opt/aws/
amitools/ec2/etc/ec2/amitools/. If you installed the AMI tools from the RPM or ZIP file in
Setting Up the AMI Tools (p. 120), the certificates are located at $EC2_AMITOOL_HOME/etc/ec2/
amitools/.
Image architecture. If you don't provide the architecture on the command line, you'll be prompted
for it when bundling starts.
Required: No
--productcodes code1,code2,...
Required: No
-B, --block-device-mapping mapping
Defines how block devices are exposed to an instance of this AMI if its instance type supports the
specified device.
Specify a comma-separated list of key-value pairs, where each key is a virtual name and each value is
the corresponding device name. Virtual names include the following:
• 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 instance store volume
Required: No
-p, --prefix prefix
Default: The name of the image file. For example, if the image path is /var/spool/my-image/
version-2/debian.img, then the default prefix is debian.img.
Required: No
--kernel kernel_id
Required: No
--ramdisk ramdisk_id
Required: No
Output
Status messages describing the stages and status of the bundling process.
135
Amazon Elastic Compute Cloud
User Guide for Linux Instances
AMI Tools Reference
Example
This example creates a bundled AMI from an operating system image that was created in a loopback file.
ec2-bundle-vol
Description
Creates an instance store-backed Linux AMI by compressing, encrypting, and signing a copy of the root
device volume for the instance.
Amazon EC2 attempts to inherit product codes, kernel settings, RAM disk settings, and block device
mappings from the instance.
By default, the bundle process excludes files that might contain sensitive information. These files
include *.sw, *.swo, *.swp, *.pem, *.priv, *id_rsa*, *id_dsa* *.gpg, *.jks, */.ssh/
authorized_keys, and */.bash_history. To include all of these files, use the --no-filter option.
To include some of these files, use the --include option.
For more information, see Creating an Instance Store-Backed Linux AMI (p. 119).
Syntax
ec2-bundle-vol -c path -k path -u account [-d path] [--ec2cert path] [-
r architecture] [--productcodes code1,code2,...] [-B mapping] [--all] [-e
directory1,directory2,...] [-i file1,file2,...] [--no-filter] [-p prefix] [-
s size] [--[no-]inherit] [-v volume] [-P type] [-S script] [--fstab path] [--
generate-fstab] [--grub-config path]
Options
-c, --cert path
136
Amazon Elastic Compute Cloud
User Guide for Linux Instances
AMI Tools Reference
Required: Yes
-k, --privatekey path
Required: Yes
-u, --user account
Required: Yes
-d, --destination destination
Default: /tmp
Required: No
--ec2cert path
The path to the Amazon EC2 X.509 public key certificate used to encrypt the image manifest.
The us-gov-west-1 and cn-north-1 regions use a non-default public key certificate and the path
to that certificate must be specified with this option. The path to the certificate varies based on the
installation method of the AMI tools. For Amazon Linux, the certificates are located at /opt/aws/
amitools/ec2/etc/ec2/amitools/. If you installed the AMI tools from the RPM or ZIP file in
Setting Up the AMI Tools (p. 120), the certificates are located at $EC2_AMITOOL_HOME/etc/ec2/
amitools/.
The image architecture. If you don't provide this on the command line, you'll be prompted to provide
it when the bundling starts.
Required: No
--productcodes code1,code2,...
Required: No
-B, --block-device-mapping mapping
Defines how block devices are exposed to an instance of this AMI if its instance type supports the
specified device.
Specify a comma-separated list of key-value pairs, where each key is a virtual name and each value is
the corresponding device name. Virtual names include the following:
• 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 instance store volume
Required: No
-a, --all
137
Amazon Elastic Compute Cloud
User Guide for Linux Instances
AMI Tools Reference
Required: No
-e, --exclude directory1,directory2,...
A list of absolute directory paths and files to exclude from the bundle operation. This parameter
overrides the --all option. When exclude is specified, the directories and subdirectories listed with
the parameter will not be bundled with the volume.
Required: No
-i, --include file1,file2,...
A list of files to include in the bundle operation. The specified files would otherwise be excluded
from the AMI because they might contain sensitive information.
Required: No
--no-filter
If specified, we won't exclude files from the AMI because they might contain sensitive information.
Required: No
-p, --prefix prefix
Default: image
Required: No
-s, --size size
The size, in MB (1024 * 1024 bytes), of the image file to create. The maximum size is 10240 MB.
Default: 10240
Required: No
--[no-]inherit
Indicates whether the image should inherit the instance's metadata (the default is to inherit).
Bundling fails if you enable --inherit but the instance metadata is not accessible.
Required: No
-v, --volume volume
The absolute path to the mounted volume from which to create the bundle.
Required: No
-P, --partition type
Indicates whether the disk image should use a partition table. If you don't specify a partition table
type, the default is the type used on the parent block device of the volume, if applicable, otherwise
the default is gpt.
Required: No
-S, --script script
A customization script to be run right before bundling. The script must expect a single argument, the
mount point of the volume.
Required: No
138
Amazon Elastic Compute Cloud
User Guide for Linux Instances
AMI Tools Reference
--fstab path
The path to the fstab to bundle into the image. If this is not specified, Amazon EC2 bundles /etc/
fstab.
Required: No
--generate-fstab
Required: No
--grub-config
The path to an alternate grub configuration file to bundle into the image. By default, ec2-bundle-
vol expects either /boot/grub/menu.lst or /boot/grub/grub.conf to exist on the cloned
image. This option allows you to specify a path to an alternative grub configuration file, which will
then be copied over the defaults (if present).
Required: No
--kernel kernel_id
Required: No
--ramdiskramdisk_id
Required: No
Output
Status messages describing the stages and status of the bundling.
Example
This example creates a bundled AMI by compressing, encrypting and signing a snapshot of the local
machine's root file system.
Splitting /mnt/image.gz.crypt...
139
Amazon Elastic Compute Cloud
User Guide for Linux Instances
AMI Tools Reference
Created image.part.00
Created image.part.01
Created image.part.02
Created image.part.03
...
Created image.part.22
Created image.part.23
Generating digests for each part...
Digests generated.
Creating bundle manifest...
Bundle Volume complete.
ec2-delete-bundle
Description
Deletes the specified bundle from Amazon S3 storage. After you delete a bundle, you can't launch
instances from the corresponding AMI.
Syntax
ec2-delete-bundle -b bucket -a access_key_id -s secret_access_key [-t token]
[--url url] [--region region] [--sigv version] [-m path] [-p prefix] [--clear]
[--retry] [-y]
Options
-b, --bucket bucket
The name of the Amazon S3 bucket containing the bundled AMI, followed by an optional '/'-
delimited path prefix
Required: Yes
-a, --access-key access_key_id
Required: Yes
-s, --secret-key secret_access_key
Required: Yes
-t, --delegation-token token
The delegation token to pass along to the AWS request. For more information, see the Using
Temporary Security Credentials.
Default: us-east-1
140
Amazon Elastic Compute Cloud
User Guide for Linux Instances
AMI Tools Reference
Valid values: 2 | 4
Default: 4
Required: No
-m, --manifestpath
The bundled AMI filename prefix. Provide the entire prefix. For example, if the prefix is image.img,
use -p image.img and not -p image.
Deletes the Amazon S3 bucket if it's empty after deleting the specified bundle.
Required: No
--retry
Required: No
-y, --yes
Required: No
Output
Amazon EC2 displays status messages indicating the stages and status of the delete process.
Example
This example deletes a bundle from Amazon S3.
141
Amazon Elastic Compute Cloud
User Guide for Linux Instances
AMI Tools Reference
ec2-delete-bundle complete.
ec2-download-bundle
Description
Downloads the specified instance store-backed Linux AMIs from Amazon S3 storage.
Syntax
ec2-download-bundle -b bucket -a access_key_id -s secret_access_key -k path
[--url url] [--region region] [--sigv version] [-m file] [-p prefix] [-d
directory] [--retry]
Options
-b, --bucket bucket
The name of the Amazon S3 bucket where the bundle is located, followed by an optional '/'-
delimited path prefix.
Required: Yes
-a, --access-key access_key_id
Required: Yes
-s, --secret-key secret_access_key
Required: Yes
-k, --privatekey path
Required: Yes
--url url
Default: https://s3.amazonaws.com/
Required: No
--region region
Default: us-east-1
Valid values: 2 | 4
Default: 4
Required: No
142
Amazon Elastic Compute Cloud
User Guide for Linux Instances
AMI Tools Reference
The name of the manifest file (without the path). We recommend that you specify either the
manifest (-m) or a prefix (-p).
Required: No
-p, --prefix prefix
Default: image
Required: No
-d, --directory directory
The directory where the downloaded bundle is saved. The directory must exist.
Required: No
--retry
Required: No
Output
Status messages indicating the various stages of the download process are displayed.
Example
This example creates the bundled directory (using the Linux mkdir command) and downloads the
bundle from the myawsbucket Amazon S3 bucket.
143
Amazon Elastic Compute Cloud
User Guide for Linux Instances
AMI Tools Reference
ec2-migrate-manifest
Description
Modifies an instance store-backed Linux AMI (for example, its certificate, kernel, and RAM disk) so that it
supports a different region.
Syntax
ec2-migrate-manifest -c path -k path -m path {(-a access_key_id -s
secret_access_key --region region) | (--no-mapping)} [--ec2cert ec2_cert_path]
[--kernel kernel-id] [--ramdisk ramdisk_id]
Options
-c, --cert path
Required: Yes
-k, --privatekey path
Required: Yes
--manifest path
Required: Yes
-a, --access-key access_key_id
During migration, Amazon EC2 replaces the kernel and RAM disk in the manifest file with a kernel
and RAM disk designed for the destination region. Unless the --no-mapping parameter is given,
ec2-migrate-bundle might use the DescribeRegions and DescribeImages operations to
perform automated mappings.
Required: Required if you're not providing the -a, -s, and --region options used for automatic
mapping.
--ec2cert path
The path to the Amazon EC2 X.509 public key certificate used to encrypt the image manifest.
144
Amazon Elastic Compute Cloud
User Guide for Linux Instances
AMI Tools Reference
The us-gov-west-1 and cn-north-1 regions use a non-default public key certificate and the
path to that certificate must be specified with this option. The path to the certificate varies based
on the installation method of the AMI tools. For Amazon Linux, the certificates are located at /
opt/aws/amitools/ec2/etc/ec2/amitools/. If you installed the AMI tools from the ZIP file in
Setting Up the AMI Tools (p. 120), the certificates are located at $EC2_AMITOOL_HOME/etc/ec2/
amitools/.
Required: No
--ramdisk ramdisk_id
Required: No
Output
Status messages describing the stages and status of the bundling process.
Example
This example copies the AMI specified in the my-ami.manifest.xml manifest from the US to the EU.
Backing up manifest...
Successfully migrated my-ami.manifest.xml It is now suitable for use in eu-west-1.
ec2-unbundle
Description
Re-creates the bundle from an instance store-backed Linux AMI.
Syntax
ec2-unbundle -k path -m path [-s source_directory] [-d destination_directory]
Options
-k, --privatekey path
145
Amazon Elastic Compute Cloud
User Guide for Linux Instances
AMI Tools Reference
Required: Yes
-m, --manifest path
Required: Yes
-s, --source source_directory
Required: No
-d, --destination destination_directory
The directory in which to unbundle the AMI. The destination directory must exist.
Required: No
Example
This Linux and UNIX example unbundles the AMI specified in the image.manifest.xml file.
Output
Status messages indicating the various stages of the unbundling process are displayed.
ec2-upload-bundle
Description
Uploads the bundle for an instance store-backed Linux AMI to Amazon S3 and sets the appropriate
ACLs on the uploaded objects. For more information, see Creating an Instance Store-Backed Linux
AMI (p. 119).
Syntax
ec2-upload-bundle -b bucket -a access_key_id -s secret_access_key [-t token] -m
path [--url url] [--region region] [--sigv version] [--acl acl] [-d directory]
[--part part] [--retry] [--skipmanifest]
Options
-b, --bucket bucket
The name of the Amazon S3 bucket in which to store the bundle, followed by an optional '/'-
delimited path prefix. If the bucket doesn't exist, it's created if the bucket name is available.
Required: Yes
146
Amazon Elastic Compute Cloud
User Guide for Linux Instances
AMI Tools Reference
Required: Yes
-s, --secret-key secret_access_key
Required: Yes
-t, --delegation-token token
The delegation token to pass along to the AWS request. For more information, see the Using
Temporary Security Credentials.
The path to the manifest file. The manifest file is created during the bundling process and can be
found in the directory containing the bundle.
Required: Yes
--url url
Deprecated. Use the --region option instead unless your bucket is constrained to the EU location
(and not eu-west-1). The --location flag is the only way to target that specific location restraint.
Default: https://s3.amazonaws.com/
Required: No
--region region
The region to use in the request signature for the destination S3 bucket.
• If the bucket doesn't exist and you don't specify a region, the tool creates the bucket without a
location constraint (in us-east-1).
• If the bucket doesn't exist and you specify a region, the tool creates the bucket in the specified
region.
• If the bucket exists and you don't specify a region, the tool uses the bucket's location.
• If the bucket exists and you specify us-east-1 as the region, the tool uses the bucket's actual
location without any error message, any existing matching files are over-written.
• If the bucket exists and you specify a region (other than us-east-1) that doesn't match the
bucket's actual location, the tool exits with an error.
If your bucket is constrained to the EU location (and not eu-west-1), use the --location flag
instead. The --location flag is the only way to target that specific location restraint.
Default: us-east-1
Valid values: 2 | 4
147
Amazon Elastic Compute Cloud
User Guide for Linux Instances
AMI Tools Reference
Default: 4
Required: No
--acl acl
Default: aws-exec-read
Required: No
-d, --directory directory
Default: The directory containing the manifest file (see the -m option).
Required: No
--part part
Starts uploading the specified part and all subsequent parts. For example, --part 04.
Required: No
--retry
Required: No
--skipmanifest
Required: No
--location location
Deprecated. Use the --region option instead, unless your bucket is constrained to the EU location
(and not eu-west-1). The --location flag is the only way to target that specific location restraint.
The location constraint of the destination Amazon S3 bucket. If the bucket exists and you specify a
location that doesn't match the bucket's actual location, the tool exits with an error. If the bucket
exists and you don't specify a location, the tool uses the bucket's location. If the bucket doesn't exist
and you specify a location, the tool creates the bucket in the specified location. If the bucket doesn't
exist and you don't specify a location, the tool creates the bucket without a location constraint (in
us-east-1).
Default: If --region is specified, the location is set to that specified region. If --region is not
specified, the location defaults to us-east-1.
Required: No
Output
Amazon EC2 displays status messages that indicate the stages and status of the upload process.
Example
This example uploads the bundle specified by the image.manifest.xml manifest.
148
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Using Encryption with EBS-Backed AMIs
--help, -h
EC2 instances with encrypted EBS volumes are launched from AMIs in the same way as other instances.
In addition, when you launch an instance from an AMI backed by unencrypted EBS snapshots, you can
encrypt some or all of the volumes during launch.
Like EBS volumes, snapshots in AMIs can be encrypted by either your default AWS Key Management
Service customer master key (CMK), or to a customer managed key that you specify. You must in all cases
have permission to use the selected key.
149
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance-Launching Scenarios
AMIs with encrypted snapshots can be shared across AWS accounts. For more information, see Shared
AMIs.
Instance-Launching Scenarios
Amazon EC2 instances are launched from AMIs using the RunInstances action with parameters
supplied through block device mapping, either by means of the AWS Management Console or directly
using the Amazon EC2 API or CLI. For more information about block device mapping, see Block Device
Mapping. For examples of controlling block device mapping from the AWS CLI, see Launch, List, and
Terminate EC2 Instances.
By default, without explicit encryption parameters, a RunInstances action maintains the existing
encryption state of an AMI's source snapshots while restoring EBS volumes from them. If encryption
by default is enabled, all volumes created from the AMI (whether from encrypted or unencrypted
snapshots) will be encrypted. If encryption by default is not enabled, then the instance maintains the
encryption state of the AMI.
You can also launch an instance and simultaneously apply a new encryption state to the resulting
volumes by supplying encryption parameters. Consequently, the following behaviors are observed:
The default behaviors can be overridden by supplying encryption parameters. The available parameters
are Encrypted and KmsKeyId. Setting only the Encrypted parameter results in the following:
• An unencrypted snapshot is restored to an EBS volume that is encrypted by your AWS account's
default CMK.
• An encrypted snapshot that you own is restored to an EBS volume encrypted by the same CMK. (In
other words, the Encrypted parameter has no effect.)
• An encrypted snapshot that you do not own (i.e., the AMI is shared with you) is restored to a volume
that is encrypted by your AWS account's default CMK. (In other words, the Encrypted parameter has
no effect.)
Setting both the Encrypted and KmsKeyId parameters allows you to specify a non-default CMK for an
encryption operation. The following behaviors result:
Submitting a KmsKeyId without also setting the Encrypted parameter results in an error.
The following sections provide examples of launching instances from AMIs using non-default encryption
parameters. In each of these scenarios, parameters supplied to the RunInstances action result in a
change of encryption state during restoration of a volume from a snapshot.
150
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance-Launching Scenarios
Note
For detailed console procedures to launch an instance from an AMI, see Launch Your Instance.
For documentation of the RunInstances API, see RunInstances.
For documentation of the run-instances command in the AWS Command Line Interface, see
run-instances.
The Encrypted parameter alone results in the volume for this instance being encrypted. Providing
a KmsKeyId parameter is optional. If no key ID is specified, the AWS account's default CMK is used to
encrypt the volume. To encrypt the volume to a different CMK that you own, supply the KmsKeyId
parameter.
If you own the AMI and supply no encryption parameters, the resulting instance has a volume encrypted
by the same key as the snapshot. If the AMI is shared rather than owned by you, and you supply no
encryption parameters, the volume is encrypted by your default CMK. With encryption parameters
supplied as shown, the volume is encrypted by the specified CMK.
151
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Image-Copying Scenarios
In this scenario, the RunInstances action is supplied with encryption parameters for each of the source
snapshots. When all possible encryption parameters are specified, the resulting instance is the same
regardless of whether you own the AMI.
Image-Copying Scenarios
Amazon EC2 AMIs are copied using the CopyImage action, either through the AWS Management Console
or directly using the Amazon EC2 API or CLI.
By default, without explicit encryption parameters, a CopyImage action maintains the existing
encryption state of an AMI's source snapshots during copy. You can also copy an AMI and simultaneously
apply a new encryption state to its associated EBS snapshots by supplying encryption parameters.
Consequently, the following behaviors are observed:
All of these default behaviors can be overridden by supplying encryption parameters. The available
parameters are Encrypted and KmsKeyId. Setting only the Encrypted parameter results in the
following:
152
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Image-Copying Scenarios
• An unencrypted snapshot is copied to a snapshot encrypted by the AWS account's default CMK.
• An encrypted snapshot is copied to a snapshot encrypted by the same CMK. (In other words, the
Encrypted parameter has no effect.)
• An encrypted snapshot that you do not own (i.e., the AMI is shared with you) is copied to a volume that
is encrypted by your AWS account's default CMK. (In other words, the Encrypted parameter has no
effect.)
Setting both the Encrypted and KmsKeyId parameters allows you to specify a customer managed CMK
for an encryption operation. The following behaviors result:
Submitting a KmsKeyId without also setting the Encrypted parameter results in an error.
The following section provides an example of copying an AMI using non-default encryption parameters,
resulting in a change of encryption state.
Note
For detailed console procedures to copy an AMI, see Copying an AMI.
For documentation of the CopyImage API, see CopyImage.
For documentation of the command copy-image in the AWS Command Line Interface, see
copy-image.
153
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Copying an AMI
Setting the Encrypted parameter encrypts the single snapshot for this instance. If you do not specify
the KmsKeyId parameter, the default CMK is used to encrypt the snapshot copy.
Note
You can also copy an image with multiple snapshots and configure the encryption state of each
individually.
Copying an AMI
You can copy an Amazon Machine Image (AMI) within or across AWS Regions using the AWS
Management Console, the AWS Command Line Interface or SDKs, or the Amazon EC2 API, all of which
support the CopyImage action. You can copy both Amazon EBS-backed AMIs and instance-store-backed
AMIs. You can copy AMIs with encrypted snapshots and also change encryption status during the copy
process.
Copying a source AMI results in an identical but distinct target AMI with its own unique identifier. In the
case of an Amazon EBS-backed AMI, each of its backing snapshots is, by default, copied to an identical
but distinct target snapshot. (The sole exceptions are when you choose to encrypt or re-encrypt the
snapshot.) You can change or deregister the source AMI with no effect on the target AMI. The reverse is
also true.
There are no charges for copying an AMI. However, standard storage and data transfer rates apply.
AWS does not copy launch permissions, user-defined tags, or Amazon S3 bucket permissions from the
source AMI to the new AMI. After the copy operation is complete, you can apply launch permissions,
user-defined tags, and Amazon S3 bucket permissions to the new AMI.
The following example policy allows the user to copy the AMI source in the specified bucket to the
specified Region.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:ListAllMyBuckets",
"Resource": [
"arn:aws:s3:::*"
]
},
{
"Effect": "Allow",
"Action": "s3:GetObject",
"Resource": [
"arn:aws:s3:::ami-source-bucket/*"
]
},
{
"Effect": "Allow",
"Action": [
"s3:CreateBucket",
154
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Cross-Region Copying
"s3:GetBucketAcl",
"s3:PutObjectAcl",
"s3:PutObject"
],
"Resource": [
"arn:aws:s3:::amis-for-123456789012-in-us-east-1*"
]
}
]
}
To find the Amazon Resource Name (ARN) of the AMI source bucket, open the Amazon EC2 console at
https://console.aws.amazon.com/ec2/, in the navigation pane choose AMIs, and locate the bucket name
in the Source column.
Cross-Region Copying
Copying an AMI across geographically diverse Regions provides the following benefits:
• Consistent global deployment: Copying an AMI from one Region to another enables you to launch
consistent instances in different Regions based on the same AMI.
• Scalability: You can more easily design and build global applications that meet the needs of your users,
regardless of their location.
• Performance: You can increase performance by distributing your application, as well as locating critical
components of your application in closer proximity to your users. You can also take advantage of
Region-specific features, such as instance types or other AWS services.
• High availability: You can design and deploy applications across AWS regions, to increase availability.
The following diagram shows the relations among a source AMI and two copied AMIs in different
Regions, as well as the EC2 instances launched from each. When you launch an instance from an AMI, it
resides in the same Region where the AMI resides. If you make changes to the source AMI and want those
changes to be reflected in the AMIs in the target Regions, you must recopy the source AMI to the target
Regions.
When you first copy an instance store-backed AMI to a Region, we create an Amazon S3 bucket for the
AMIs copied to that Region. All instance store-backed AMIs that you copy to that Region are stored in this
bucket. The bucket names have the following format: amis-for-account-in-region-hash. For example:
amis-for-123456789012-in-us-east-2-yhjmxvp6.
Prerequisite
Prior to copying an AMI, you must ensure that the contents of the source AMI are updated to support
running in a different Region. For example, you should update any database connection strings or similar
application configuration data to point to the appropriate resources. Otherwise, instances launched from
155
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Cross-Account Copying
the new AMI in the destination Region may still use the resources from the source Region, which can
impact performance and cost.
Limits
Cross-Account Copying
You can share an AMI with another AWS account. Sharing an AMI does not affect the ownership of the
AMI. The owning account is charged for the storage in the Region. For more information, see Sharing an
AMI with Specific AWS Accounts (p. 106).
If you copy an AMI that has been shared with your account, you are the owner of the target AMI in your
account. The owner of the source AMI is charged standard Amazon EBS or Amazon S3 transfer fees, and
you are charged for the storage of the target AMI in the destination Region.
Resource Permissions
To copy an AMI that was shared with you from another account, the owner of the source AMI must grant
you read permissions for the storage that backs the AMI, either the associated EBS snapshot (for an
Amazon EBS-backed AMI) or an associated S3 bucket (for an instance store-backed AMI). If the shared
AMI has encrypted snapshots, the owner must share the key or keys with you as well.
Note
You can't copy an AMI with an associated billingProduct code that was shared with you from
another account. This includes Windows AMIs and AMIs from the AWS Marketplace. To copy a
shared AMI with a billingProduct code, launch an EC2 instance in your account using the
shared AMI and then create an AMI from the instance. For more information, see Creating an
Amazon EBS-Backed Linux AMI (p. 116).
1 Unencrypted-to-unencrypted Yes
2 Encrypted-to-encrypted Yes
3 Unencrypted-to-encrypted Yes
4 Encrypted-to-unencrypted No
Note
Encrypting during the CopyImage action applies only to Amazon EBS-backed AMIs. Because
an instance store-backed AMI does not rely on snapshots, you cannot use copying to change its
encryption status.
By default (i.e., without specifying encryption parameters), the backing snapshot of an AMI is copied
with its original encryption status. Copying an AMI backed by an unencrypted snapshot results in an
156
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Copying an AMI
identical target snapshot that is also unencrypted. If the source AMI is backed by an encrypted snapshot,
copying it results in an identical target snapshot that is encrypted by the same customer master key
(CMK). Copying an AMI backed by multiple snapshots preserves, by default, the source encryption status
in each target snapshot.
If you specify encryption parameters while copying an AMI, you can encrypt or re-encrypt its backing
snapshots. The following example shows a non-default case that supplies encryption parameters to the
CopyImage action in order to change the target AMI's encryption state.
In this scenario, an AMI backed by an unencrypted root snapshot is copied to an AMI with an encrypted
root snapshot. The CopyImage action is invoked with two encryption parameters, including a CMK. As
a result, the encryption status of the root snapshot changes, so that the target AMI is backed by a root
snapshot containing the same data as the source snapshot, but encrypted using the specified key. You
incur storage costs for the snapshots in both AMIs, as well as charges for any instances you launch from
either AMI.
Note
Enabling encryption by default (p. 904) has the same effect as setting the Encrypted
parameter to true for all snapshots in the AMI.
Setting the Encrypted parameter encrypts the single snapshot for this instance. If you do not specify
the KmsKeyId parameter, the default CMK is used to encrypt the snapshot copy.
For more information about copying AMIs with encrypted snapshots, see Using Encryption with EBS-
Backed AMIs (p. 149).
Copying an AMI
You can copy an AMI as follows.
Prerequisite
Create or obtain an AMI backed by an Amazon EBS snapshot. Note that you can use the Amazon EC2
console to search a wide variety of AMIs provided by AWS. For more information, see Creating an
Amazon EBS-Backed Linux AMI (p. 116) and Finding a Linux AMI (p. 100).
157
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Stopping a Pending AMI Copy Operation
2. From the console navigation bar, select the Region that contains the AMI. In the navigation pane,
choose Images, AMIs to display the list of AMIs available to you in the Region.
3. Select the AMI to copy and choose Actions, Copy AMI.
4. In the Copy AMI dialog box, specify the following information and then choose Copy AMI:
To check on the progress of the copy operation immediately, follow the provided link. To check on
the progress later, choose Done, and then when you are ready, use the navigation bar to switch to
the target region (if applicable) and locate your AMI in the list of AMIs.
The initial status of the target AMI is pending and the operation is complete when the status is
available.
You can copy an AMI using the copy-image command. You must specify both the source and destination
Regions. You specify the source Region using the --source-region parameter. You can specify
the destination Region using either the --region parameter or an environment variable. For more
information, see Configuring the AWS Command Line Interface.
When you encrypt a target snapshot during copying, you must specify these additional parameters: --
encrypted and --kms-key-id.
You can copy an AMI using the Copy-EC2Image command. You must specify both the source and
destination Regions. You specify the source Region using the -SourceRegion parameter. You can
specify the destination Region using either the -Region parameter or the Set-AWSDefaultRegion
command. For more information, see Specifying AWS Regions.
When you encrypt a target snapshot during copying, you must specify these additional parameters: -
Encrypted and -KmsKeyId.
158
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Deregistering Your Linux AMI
When you deregister an AMI, it doesn't affect any instances that you've already launched from the
AMI. You'll continue to incur usage costs for these instances. Therefore, if you are finished with these
instances, you should terminate them.
The procedure that you'll use to clean up your AMI depends on whether it is backed by Amazon EBS or
instance store. For more information, see Determining the Root Device Type of Your AMI (p. 98).
Contents
• Cleaning Up Your Amazon EBS-Backed AMI (p. 159)
• Cleaning Up Your Instance Store-Backed AMI (p. 160)
The following diagram illustrates the process for cleaning up your Amazon EBS-backed AMI.
159
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Cleaning Up Your Instance Store-Backed AMI
2. In the navigation pane, choose AMIs. Select the AMI, and take note of its ID — this can help you find
the correct snapshot in the next step. Choose Actions, and then Deregister. When prompted for
confirmation, choose Continue.
Note
It may take a few minutes before the console removes the AMI from the list. Choose
Refresh to refresh the status.
3. In the navigation pane, choose Snapshots, and select the snapshot (look for the AMI ID in the
Description column). Choose Actions, and then choose Delete Snapshot. When prompted for
confirmation, choose Yes, Delete.
4. (Optional) If you are finished with an instance that you launched from the AMI, terminate it. In the
navigation pane, choose Instances. Select the instance, choose Actions, then Instance State, and
then Terminate. When prompted for confirmation, choose Yes, Terminate.
The following diagram illustrates the process for cleaning up your instance store-backed AMI.
2. Delete the bundle in Amazon S3 using the ec2-delete-bundle (p. 140) (AMI tools) command as
follows.
3. (Optional) If you are finished with an instance that you launched from the AMI, you can terminate it
using the terminate-instances command as follows.
160
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Amazon Linux
4. (Optional) If you are finished with the Amazon S3 bucket that you uploaded the bundle to, you can
delete the bucket. To delete an Amazon S3 bucket, open the Amazon S3 console, select the bucket,
choose Actions, and then choose Delete.
Amazon Linux
Amazon Linux is provided by Amazon Web Services (AWS). It is designed to provide a stable, secure,
and high-performance execution environment for applications running on Amazon EC2. It also includes
packages that enable easy integration with AWS, including launch configuration tools and many popular
AWS libraries and tools. AWS provides ongoing security and maintenance updates for all instances
running Amazon Linux. Many applications developed on CentOS (and similar distributions) run on
Amazon Linux.
AWS provides two versions of Amazon Linux: Amazon Linux 2 and the Amazon Linux AMI. For more
information, including the complete list of AMIs, see Amazon Linux 2 and Amazon Linux AMI. For
Amazon Linux Docker container images, see amazonlinux on Docker Hub.
If you are migrating from another Linux distribution to Amazon Linux, we recommend that you migrate
to Amazon Linux 2. If you are currently using the Amazon Linux AMI, we recommend that you migrate
to Amazon Linux 2. To migrate to Amazon Linux 2, launch an instance or create a virtual machine using
the current image. Install your application on Amazon Linux 2, plus any packages required by your
application. Test your application, and make any changes required for it to run on Amazon Linux 2. For
more information about running Amazon Linux outside AWS, see Running Amazon Linux 2 as a Virtual
Machine On-Premises (p. 168).
Contents
• Connecting to an Amazon Linux Instance (p. 161)
• Identifying Amazon Linux Images (p. 161)
• AWS Command Line Tools (p. 163)
• Package Repository (p. 163)
• Extras Library (Amazon Linux 2) (p. 165)
• Accessing Source Packages for Reference (p. 166)
• cloud-init (p. 166)
• Subscribing to Amazon Linux Notifications (p. 168)
• Running Amazon Linux 2 as a Virtual Machine On-Premises (p. 168)
161
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Identifying Amazon Linux Images
• image_name, image_version, image_arch — Values from the build recipe that Amazon used to
construct the image.
• image_stamp — A unique, random hex value generated during image creation.
• image_date — The UTC time of image creation, in YYYYMMDDhhmmss format
• recipe_name, recipe_id — The name and ID of the build recipe Amazon used to construct the
image.
Amazon Linux contains an /etc/system-release file that specifies the current release that is
installed. This file is updated using yum and is part of the system-release RPM.
Amazon Linux also contains a machine-readable version of /etc/system-release that follows the
CPE specification; see /etc/system-release-cpe.
Amazon Linux 2
The following is an example of /etc/image-id for the current version of Amazon Linux 2:
The following is an example of /etc/system-release for the current version of Amazon Linux 2:
162
Amazon Elastic Compute Cloud
User Guide for Linux Instances
AWS Command Line Tools
recipe_id="5b283820-dc60-a7ea-d436-39fa-439f-02ea-5c802dbd"
The following is an example of /etc/system-release for the current Amazon Linux AMI:
• aws-amitools-ec2
• aws-apitools-as
• aws-apitools-cfn
• aws-apitools-ec2
• aws-apitools-elb
• aws-apitools-mon
• aws-cfn-bootstrap
• aws-cli
Amazon Linux 2 and the minimal versions of Amazon Linux (amzn-ami-minimal-* and amzn2-ami-
minimal-*) do not always contain all of these packages; however, you can install them from the default
repositories using the following command:
For instances launched using IAM roles, a simple script has been included to prepare
AWS_CREDENTIAL_FILE, JAVA_HOME, AWS_PATH, PATH, and product-specific environment variables
after a credential file has been installed to simplify the configuration of these tools.
Also, to allow the installation of multiple versions of the API and AMI tools, we have placed symbolic
links to the desired versions of these tools in /opt/aws, as described here:
/opt/aws/bin
Products are installed in directories of the form name-version and a symbolic link name that is
attached to the most recently installed version.
/opt/aws/{apitools|amitools}/name/environment.sh
Package Repository
Amazon Linux 2 and the Amazon Linux AMI are designed to be used with online package repositories
hosted in each Amazon EC2 region. These repositories provide ongoing updates to packages in Amazon
Linux 2 and the Amazon Linux AMI, as well as access to hundreds of additional common open-source
server applications. The repositories are available in all regions and are accessed using yum update tools.
163
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Package Repository
Hosting repositories in each region enables us to deploy updates quickly and without any data transfer
charges.
Amazon Linux 2 and the Amazon Linux AMI are updated regularly with security and feature
enhancements. If you do not need to preserve data or customizations for your instances, you can simply
launch new instances using the current AMI. If you need to preserve data or customizations for your
instances, you can maintain those instances through the Amazon Linux package repositories. These
repositories contain all the updated packages. You can choose to apply these updates to your running
instances. Older versions of the AMI and update packages continue to be available for use, even as new
versions are released.
Important
Your instance must have access to the internet in order to access the repository.
For the Amazon Linux AMI, access to the Extra Packages for Enterprise Linux (EPEL) repository is
configured, but it is not enabled by default. Amazon Linux 2 is not configured to use the EPEL repository.
EPEL provides third-party packages in addition to those that are in the repositories. The third-party
packages are not supported by AWS. You can enable the EPEL repository with the following commands:
If you find that Amazon Linux does not contain an application you need, you can simply install the
application directly on your Amazon Linux instance. Amazon Linux uses RPMs and yum for package
management, and that is likely the simplest way to install new applications. You should always check to
see if an application is available in our central Amazon Linux repository first, because many applications
are available there. These applications can easily be added to your Amazon Linux instance.
To upload your applications onto a running Amazon Linux instance, use scp or sftp and then configure
the application by logging on to your instance. Your applications can also be uploaded during the
instance launch by using the PACKAGE_SETUP action from the built-in cloud-init package. For more
information, see cloud-init (p. 166).
Security Updates
Security updates are provided using the package repositories as well as updated AMIs Security alerts are
published in the Amazon Linux Security Center. For more information about AWS security policies or to
report a security problem, go to the AWS Security Center.
Amazon Linux is configured to download and install security updates at launch time. This is controlled
using the following cloud-init setting: repo_upgrade. The following snippet of cloud-init configuration
shows how you can change the settings in the user data text you pass to your instance initialization:
✔cloud-config
repo_upgrade: security
164
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Extras Library (Amazon Linux 2)
security
Apply updates that Amazon marks as bug fixes. Bug fixes are a larger set of updates, which include
security updates and fixes for various other minor bugs.
all
The default setting for repo_upgrade is security. That is, if you don't specify a different value in your
user data, by default, Amazon Linux performs the security upgrades at launch for any packages installed
at that time. Amazon Linux also notifies you of any updates to the installed packages by listing the
number of available updates upon login using the /etc/motd file. To install these updates, you need to
run sudo yum upgrade on the instance.
Repository Configuration
With Amazon Linux, AMIs are treated as snapshots in time, with a repository and update structure that
always gives you the latest packages when you run yum update -y.
The repository structure is configured to deliver a continuous flow of updates that enable you to roll
from one version of Amazon Linux to the next. For example, if you launch an instance from an older
version of the Amazon Linux AMI (such as 2017.09 or earlier) and run yum update -y, you end up with
the latest packages.
You can disable rolling updates by enabling the lock-on-launch feature. The lock-on-launch feature locks
your instance to receive updates only from the specified release of the AMI. For example, you can launch
a 2017.09 AMI and have it receive only the updates that were released prior to the 2018.03 AMI, until
you are ready to migrate to the 2018.03 AMI.
Important
If you lock to a version of the repositories that is not the latest, you do not receive further
updates. To receive a continuous flow of updates, you must use the latest AMI, or consistently
update your AMI with the repositories pointed to latest.
To enable lock-on-launch in new instances, launch it with the following user data passed to cloud-init:
✔cloud-config
repo_releasever: 2017.09
1. Edit /etc/yum.conf.
2. Comment out releasever=latest.
3. To clear the cache, run yum clean all .
165
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Accessing Source Packages for Reference
To enable a topic and install the latest version of its package to ensure freshness, use the following
command:
To enable topics and install specific versions of their packages to ensure stability, use the following
command:
The source RPM can be unpacked, and, for reference, you can view the source tree using standard RPM
tools. After you finish debugging, the package is available for use.
cloud-init
The cloud-init package is an open-source application built by Canonical that is used to bootstrap Linux
images in a cloud computing environment, such as Amazon EC2. Amazon Linux contains a customized
version of cloud-init. It enables you to specify actions that should happen to your instance at boot time.
You can pass desired actions to cloud-init through the user data fields when launching an instance.
This means you can use common AMIs for many use cases and configure them dynamically at startup.
Amazon Linux also uses cloud-init to perform initial configuration of the ec2-user account.
Amazon Linux uses the cloud-init actions found in /etc/cloud/cloud.cfg.d and /etc/cloud/
cloud.cfg. You can create your own cloud-init action files in /etc/cloud/cloud.cfg.d. All files
in this directory are read by cloud-init. They are read in lexical order, and later files overwrite values in
earlier files.
The cloud-init package performs these (and other) common configuration tasks for instances at boot:
166
Amazon Elastic Compute Cloud
User Guide for Linux Instances
cloud-init
✔cloud-config
mounts:
- [ ephemeral0 ]
For more control over mounts, see Mounts in the cloud-init documentation.
• Instance store volumes that support TRIM are not formatted when an instance launches, so you
must partition and format them before you can mount them. For more information, see Instance
Store Volume TRIM Support (p. 965). You can use the disk_setup module to partition and
format your instance store volumes at boot. For more information, see Disk Setup in the cloud-init
documentation.
• Gzip
• If user-data is gzip compressed, cloud-init decompresses the data and handles it appropriately.
• MIME multipart
• Using a MIME multipart file, you can specify more than one type of data. For example, you could
specify both a user-data script and a cloud-config type. Each part of the multipart file can be
handled by cloud-init if it is one of the supported formats.
• Base64 decoding
• If user-data is base64-encoded, cloud-init determines if it can understand the decoded data as
one of the supported types. If it understands the decoded data, it decodes the data and handles it
appropriately. If not, it returns the base64 data intact.
• User-Data script
• Begins with ✔! or Content-Type: text/x-shellscript.
• The script is executed by /etc/init.d/cloud-init-user-scripts during the first boot cycle.
This occurs late in the boot process (after the initial configuration actions are performed).
• Include file
• Begins with ✔include or Content-Type: text/x-include-url.
• This content is an include file. The file contains a list of URLs, one per line. Each of the URLs is read,
and their content passed through this same set of rules. The content read from the URL can be
gzipped, MIME-multi-part, or plaintext.
• Cloud Config Data
• Begins with ✔cloud-config or Content-Type: text/cloud-config.
• This content is cloud-config data. For a commented example of supported configuration formats,
see the examples .
• Upstart job
• Begins with ✔upstart-job or Content-Type: text/upstart-job.
• This content is stored in a file in /etc/init, and upstart consumes the content as per other upstart
jobs.
167
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Subscribing to Amazon Linux Notifications
• Cloud Boothook
• Begins with ✔cloud-boothook or Content-Type: text/cloud-boothook.
• This content is boothook data. It is stored in a file under /var/lib/cloud and then executed
immediately.
• This is the earliest "hook" available. There is no mechanism provided for running it only one time.
The boothook must take care of this itself. It is provided with the instance ID in the environment
variable INSTANCE_ID. Use this variable to provide a once-per-instance set of boothook data.
a. [Amazon Linux 2] For Topic ARN, copy and paste the following Amazon Resource Name (ARN):
arn:aws:sns:us-east-1:137112412989:amazon-linux-2-ami-updates.
b. [Amazon Linux] For Topic ARN, copy and paste the following Amazon Resource Name (ARN):
arn:aws:sns:us-east-1:137112412989:amazon-linux-ami-updates.
c. For Protocol, choose Email.
d. For Endpoint, type an email address that you can use to receive the notifications.
e. Choose Create subscription.
5. You receive a confirmation email with the subject line "AWS Notification - Subscription
Confirmation". Open the email and choose Confirm subscription to complete your subscription.
Whenever AMIs are released, we send notifications to the subscribers of the corresponding topic. To stop
receiving these notifications, use the following procedure to unsubscribe.
• VMWare
• KVM
168
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Running Amazon Linux 2 as a Virtual Machine On-Premises
To use the Amazon Linux 2 virtual machine images with one of the supported virtualization platforms,
you need to do the following:
To generate the seed.iso boot image, you need two configuration files:
• meta-data—This file includes the hostname and static network settings for the VM.
• user-data—This file configures user accounts, and specifies their passwords, key pairs, and access
mechanisms. By default, the Amazon Linux 2 VM image creates a ec2-user user account. You use the
user-data configuration file to set the password for the default user account.
1. Create a new folder named seedconfig to store your meta-data and user-data configuration
files.
2. Create the meta-data configuration file.
local-hostname: vm_hostname
b. Specify any custom network settings, such as the network interface name.
✔network-interfaces: |
✔ iface interface_name inet static
For example, the following code block shows the contents of a meta-data configuration file that
specifies the VM hostname (amazonlinux.onprem), configures the default network interface
(eth0), and specifies static IP addresses for the necessary network devices.
local-hostname: amazonlinux.onprem
✔ eth0 is the default network interface enabled in the image. You can configure static
network settings with an entry like the following.
network-interfaces: |
auto eth0
iface eth0 inet static
address 192.168.1.10
network 192.168.1.0
netmask 255.255.255.0
169
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Running Amazon Linux 2 as a Virtual Machine On-Premises
broadcast 192.168.1.255
gateway 192.168.1.254
a. Specify a custom password, in plaintext format, for the default ec2-user user account:
✔cloud-config
✔vim:syntax=yaml
users:
✔ A user by the name `ec2-user` is created in the image by default.
- default
chpasswd:
list: |
ec2-user:plain_text_password
✔ In the above line, do not add any spaces after 'ec2-user:'.
Note
Be sure to replace the plain_text_password placeholder with a plaintext password
of your choice.
b. (Optional) Create additional user accounts and specify their access mechanisms, passwords, and
key pairs. For more information about the supported directives, see Modules.
c. (Optional) By default, cloud-init applies network settings each time the VM boots. Add the
following code to the user-data configuration file to prevent cloud-init from applying
network settings at each boot, and to retain the network settings applied during the first boot.
For example, the following code block shows the contents of a user-data configuration file that
creates three additional users, specifies a custom password for the default ec2-user user account,
and prevents cloud-init from applying network settings at each boot.
✔cloud-config
✔ vim:syntax=yaml
users:
✔ A user by the name ec2-user is created in the image by default.
- default
✔ The following entry creates user1 and assigns a plain text password.
✔ Please note that the use of a plain text password is not recommended from security
best practices standpoint.
- name: user1
groups: sudo
sudo: ['ALL=(ALL) NOPASSWD:ALL']
plain_text_passwd: myp@ssw0rd
lock_passwd: false
✔ The following entry creates user2 and attaches a hashed password to the user.
✔ Hashed passwords can be generated with the following command on Amazon Linux 2:
✔ python -c 'import crypt,getpass; print(crypt.crypt(getpass.getpass()))'
- name: user2
passwd: hashed-password
170
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Running Amazon Linux 2 as a Virtual Machine On-Premises
lock_passwd: false
✔ The following entry creates user3, disables password-based login and enables an SSH
public key.
- name: user3
ssh-authorized-keys:
- ssh-public-key-information
lock_passwd: true
chpasswd:
list: |
ec2-user:myp@ssw0rd
✔ In the above line, do not add any spaces after 'ec2-user:'.
✔ NOTE: Cloud-init applies network settings on every boot by default. To retain network
settings from first
boot, uncomment the following ‘write_files’ section:
✔write_files:
- path: /etc/cloud/cloud.cfg.d/80_disable_network_after_firstboot.cfg
content: |
✔ Disable network configuration after first boot
network:
config: disabled
4. Place your meta-data and user-data configuration files in the seedconfig folder created in
Step 1.
5. Create the seed.iso boot image using the meta-data and user-data configuration files.
For Linux, use a tool such as genisoimage. Navigate into the seedconfig folder and execute the
following command:
For macOS, use a tool such as hdiutil. Navigate one level up from the seedconfig folder and
execute the following command:
• VMWare
• KVM
• Oracle VirtualBox
• Microsoft Hyper-V
171
Amazon Elastic Compute Cloud
User Guide for Linux Instances
User Provided Kernels
After the VM has booted, log in using one of the user accounts defined in the user-data configuration
file. You can disconnect the boot image from the VM after you have logged in for the first time.
Contents
• HVM AMIs (GRUB) (p. 172)
• Paravirtual AMIs (PV-GRUB) (p. 173)
By default, GRUB does not send its output to the instance console because it creates an extra boot delay.
For more information, see Instance Console Output (p. 1052). If you are installing a custom kernel,
you should consider enabling GRUB output by deleting the hiddenmenu line and adding serial and
terminal lines to /boot/grub/menu.lst as shown in the example below.
Important
Avoid printing large amounts of debug information during the boot process; the serial console
does not support high rate data transfer.
default=0
fallback=1
timeout=5
serial --unit=0 --speed=9600
terminal --dumb --timeout=5 serial console
172
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Paravirtual AMIs (PV-GRUB)
initrd /boot/initramfs-4.14.26-46.32.amzn1.x86_64.img
You don't need to specify a fallback kernel in your menu.lst file, but we recommend that you have a
fallback when you test a new kernel. GRUB can fall back to another kernel in the event that the new
kernel fails. Having a fallback kernel allows the instance to boot even if the new kernel isn't found.
If your new Vanilla Linux kernel fails, the output will be similar to the example below.
PV-GRUB understands standard grub.conf or menu.lst commands, which allows it to work with all
currently supported Linux distributions. Older distributions such as Ubuntu 10.04 LTS, Oracle Enterprise
Linux or CentOS 5.x require a special "ec2" or "xen" kernel package, while newer distributions include the
required drivers in the default kernel package.
Most modern paravirtual AMIs use a PV-GRUB AKI by default (including all of the paravirtual Linux AMIs
available in the Amazon EC2 Launch Wizard Quick Start menu), so there are no additional steps that
you need to take to use a different kernel on your instance, provided that the kernel you want to use
is compatible with your distribution. The best way to run a custom kernel on your instance is to start
with an AMI that is close to what you want and then to compile the custom kernel on your instance and
modify the menu.lst file as shown in Configuring GRUB (p. 174) to boot with that kernel.
You can verify that the kernel image for an AMI is a PV-GRUB AKI by executing the following describe-
images command with the Amazon EC2 command line tools (substituting the kernel image ID you want
to check:
Topics
• Limitations of PV-GRUB (p. 173)
• Configuring GRUB for Paravirtual AMIs (p. 174)
• Amazon PV-GRUB Kernel Image IDs (p. 175)
• Updating PV-GRUB (p. 176)
Limitations of PV-GRUB
PV-GRUB has the following limitations:
• You can't use the 64-bit version of PV-GRUB to start a 32-bit kernel or vice versa.
• You can't specify an Amazon ramdisk image (ARI) when using a PV-GRUB AKI.
173
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Paravirtual AMIs (PV-GRUB)
• AWS has tested and verified that PV-GRUB works with these file system formats: EXT2, EXT3, EXT4,
JFS, XFS, and ReiserFS. Other file system formats might not work.
• PV-GRUB can boot kernels compressed using the gzip, bzip2, lzo, and xz compression formats.
• Cluster AMIs don't support or need PV-GRUB, because they use full hardware virtualization (HVM).
While paravirtual instances use PV-GRUB to boot, HVM instance volumes are treated like actual disks,
and the boot process is similar to the boot process of a bare metal operating system with a partitioned
disk and bootloader.
• PV-GRUB versions 1.03 and earlier don't support GPT partitioning; they support MBR partitioning only.
• If you plan to use a logical volume manager (LVM) with Amazon EBS volumes, you need a separate
boot partition outside of the LVM. Then you can create logical volumes with the LVM.
The following is an example of a menu.lst configuration file for booting an AMI with a PV-GRUB
AKI. In this example, there are two kernel entries to choose from: Amazon Linux 2018.03 (the original
kernel for this AMI), and Vanilla Linux 4.16.4 (a newer version of the Vanilla Linux kernel from https://
www.kernel.org/). The Vanilla entry was copied from the original entry for this AMI, and the kernel
and initrd paths were updated to the new locations. The default 0 parameter points the bootloader
to the first entry it sees (in this case, the Vanilla entry), and the fallback 1 parameter points the
bootloader to the next entry if there is a problem booting the first.
default 0
fallback 1
timeout 0
hiddenmenu
You don't need to specify a fallback kernel in your menu.lst file, but we recommend that you have a
fallback when you test a new kernel. PV-GRUB can fall back to another kernel in the event that the new
kernel fails. Having a fallback kernel allows the instance to boot even if the new kernel isn't found.
PV-GRUB checks the following locations for menu.lst, using the first one it finds:
• (hd0)/boot/grub
• (hd0,0)/boot/grub
• (hd0,0)/grub
• (hd0,1)/boot/grub
• (hd0,1)/grub
• (hd0,2)/boot/grub
• (hd0,2)/grub
• (hd0,3)/boot/grub
174
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Paravirtual AMIs (PV-GRUB)
• (hd0,3)/grub
Note that PV-GRUB 1.03 and earlier only check one of the first two locations in this list.
We recommend that you always use the latest version of the PV-GRUB AKI, as not all versions of the PV-
GRUB AKI are compatible with all instance types. Use the following describe-images command to get a
list of the PV-GRUB AKIs for the current region:
Note that PV-GRUB is the only AKI available in the ap-southeast-2 region. You should verify that any
AMI you want to copy to this region is using a version of PV-GRUB that is available in this region.
The following are the current AKI IDs for each region. Register new AMIs using an hd0 AKI.
Note
We continue to provide hd00 AKIs for backward compatibility in regions where they were
previously available.
aki-f975a998 pv-grub-hd0_1.05-i386.gz
aki-7077ab11 pv-grub-hd0_1.05-x86_64.gz
aki-17a40074 pv-grub-hd0_1.05-i386.gz
aki-73a50110 pv-grub-hd0_1.05-x86_64.gz
aki-ba5665d9 pv-grub-hd0_1.05-i386.gz
aki-66506305 pv-grub-hd0_1.05-x86_64.gz
eu-central-1, EU (Frankfurt)
aki-1419e57b pv-grub-hd0_1.05-i386.gz
aki-931fe3fc pv-grub-hd0_1.05-x86_64.gz
175
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Paravirtual AMIs (PV-GRUB)
eu-west-1, EU (Ireland)
aki-1c9fd86f pv-grub-hd0_1.05-i386.gz
aki-dc9ed9af pv-grub-hd0_1.05-x86_64.gz
aki-7cd34110 pv-grub-hd0_1.05-i386.gz
aki-912fbcfd pv-grub-hd0_1.05-x86_64.gz
aki-04206613 pv-grub-hd0_1.05-i386.gz
aki-5c21674b pv-grub-hd0_1.05-x86_64.gz
aki-5ee9573f pv-grub-hd0_1.05-i386.gz
aki-9ee55bff pv-grub-hd0_1.05-x86_64.gz
aki-43cf8123 pv-grub-hd0_1.05-i386.gz
aki-59cc8239 pv-grub-hd0_1.05-x86_64.gz
aki-7a69931a pv-grub-hd0_1.05-i386.gz
aki-70cb0e10 pv-grub-hd0_1.05-x86_64.gz
Updating PV-GRUB
We recommend that you always use the latest version of the PV-GRUB AKI, as not all versions of the PV-
GRUB AKI are compatible with all instance types. Also, older versions of PV-GRUB are not available in all
regions, so if you copy an AMI that uses an older version to a region that does not support that version,
176
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Paravirtual AMIs (PV-GRUB)
you will be unable to boot instances launched from that AMI until you update the kernel image. Use the
following procedures to check your instance's version of PV-GRUB and update it if necessary.
{
"InstanceId": "instance_id",
"KernelId": "aki-70cb0e10"
}
{
"Images": [
{
"VirtualizationType": "paravirtual",
"Name": "pv-grub-hd0_1.05-x86_64.gz",
...
"Description": "PV-GRUB release 1.05, 64-bit"
}
]
}
This kernel image is PV-GRUB 1.05. If your PV-GRUB version is not the newest version (as shown in
Amazon PV-GRUB Kernel Image IDs (p. 175)), you should update it using the following procedure.
If your instance is using an older version of PV-GRUB, you should update it to the latest version.
1. Identify the latest PV-GRUB AKI for your region and processor architecture from Amazon PV-GRUB
Kernel Image IDs (p. 175).
2. Stop your instance. Your instance must be stopped to modify the kernel image used.
177
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Types
Before you launch a production environment, you need to answer the following questions.
Amazon EC2 provides different instance types to enable you to choose the CPU, memory, storage,
and networking capacity that you need to run your applications. For more information, see Instance
Types (p. 178).
Q. What purchasing option best meets my needs?
Amazon EC2 supports On-Demand instances (the default), Spot instances, and Reserved Instances.
For more information, see Instance Purchasing Options (p. 254).
Q. Which type of root volume meets my needs?
Each instance is backed by Amazon EBS or backed by instance store. Select an AMI based on which
type of root volume you need. For more information, see Storage for the Root Device (p. 97).
Q. Can I remotely manage a fleet of EC2 instances and machines in my hybrid environment?
AWS Systems Manager lets you remotely and securely manage the configuration of your Amazon
EC2 instances, and your on-premises instances and virtual machines (VMs) in hybrid environments,
including VMs from other cloud providers. For more information, see the AWS Systems Manager User
Guide.
Instance Types
When you launch an instance, the instance type that you specify determines the hardware of the host
computer used for your instance. Each instance type offers different compute, memory, and storage
capabilities and are grouped in instance families based on these capabilities. Select an instance type
based on the requirements of the application or software that you plan to run on your instance.
Amazon EC2 provides each instance with a consistent and predictable amount of CPU capacity,
regardless of its underlying hardware.
Amazon EC2 dedicates some resources of the host computer, such as CPU, memory, and instance
storage, to a particular instance. Amazon EC2 shares other resources of the host computer, such as the
network and the disk subsystem, among instances. If each instance on a host computer tries to use
as much of one of these shared resources as possible, each receives an equal share of that resource.
However, when a resource is underused, an instance can consume a higher share of that resource while
it's available.
178
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Available Instance Types
Each instance type provides higher or lower minimum performance from a shared resource. For example,
instance types with high I/O performance have a larger allocation of shared resources. Allocating a larger
share of shared resources also reduces the variance of I/O performance. For most applications, moderate
I/O performance is more than enough. However, for applications that require greater or more consistent
I/O performance, consider an instance type with higher I/O performance.
Contents
• Available Instance Types (p. 179)
• Hardware Specifications (p. 181)
• AMI Virtualization Types (p. 181)
• Nitro-based Instances (p. 181)
• Networking and Storage Features (p. 182)
• Instance Limits (p. 184)
• General Purpose Instances (p. 185)
• Compute Optimized Instances (p. 222)
• Memory Optimized Instances (p. 226)
• Storage Optimized Instances (p. 234)
• Linux Accelerated Computing Instances (p. 241)
• Changing the Instance Type (p. 250)
For more information about the current generation instance types, see Amazon EC2 Instance Types.
179
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Available Instance Types
180
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Hardware Specifications
Hardware Specifications
For more information about the hardware specifications for each Amazon EC2 instance type, see Amazon
EC2 Instance Types.
To determine which instance type best meets your needs, we recommend that you launch an instance
and use your own benchmark application. Because you pay by the instance second, it's convenient and
inexpensive to test multiple instance types before making a decision.
If your needs change, even after you make a decision, you can resize your instance later. For more
information, see Changing the Instance Type (p. 250).
Note
Amazon EC2 instances run on 64-bit virtual Intel processors as specified in the instance type
product pages. For more information about the hardware specifications for each Amazon
EC2 instance type, see Amazon EC2 Instance Types. However, confusion may result from
industry naming conventions for 64-bit CPUs. Chip manufacturer Advanced Micro Devices
(AMD) introduced the first commercially successful 64-bit architecture based on the Intel x86
instruction set. Consequently, the architecture is widely referred to as AMD64 regardless of the
chip manufacturer. Windows and several Linux distributions follow this practice. This explains
why the internal system information on an Ubuntu or Windows EC2 instance displays the CPU
architecture as AMD64 even though the instances are running on Intel hardware.
For best performance, we recommend that you use an HVM AMI. In addition, HVM AMIs are required to
take advantage of enhanced networking. HVM virtualization uses hardware-assist technology provided
by the AWS platform. With HVM virtualization, the guest VM runs as if it were on a native hardware
platform, except that it still uses PV network and storage drivers for improved performance.
Nitro-based Instances
The Nitro system is a collection of AWS-built hardware and software components that enable high
performance, high availability, and high security. In addition, the Nitro system provides bare metal
capabilities that eliminate virtualization overhead and support workloads that require full access to host
hardware.
Nitro Components
The following components are part of the Nitro system:
• Nitro hypervisor - A lightweight hypervisor that manages memory and CPU allocation and delivers
performance that is indistinguishable from bare metal for most workloads.
• Nitro card
181
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Networking and Storage Features
Instance Types
• A1, C5, C5d, C5n, I3en, M5, M5a, M5ad, M5d, p3dn.24xlarge, R5, R5a, R5ad, R5d, T3, T3a, and z1d
• Bare metal: c5.metal, i3.metal, m5.metal, m5d.metal, r5.metal, r5d.metal, u-6tb1.metal,
u-9tb1.metal, u-12tb1.metal, and z1d.metal
Resources
Networking features
• IPv6 is supported on all current generation instance types and the C3, R3, and I2 previous generation
instance types.
• To maximize the networking and bandwidth performance of your instance type, you can do the
following:
• Launch supported instance types into a cluster placement group to optimize your instances for
high performance computing (HPC) applications. Instances in a common cluster placement group
can benefit from high-bandwidth, low-latency networking. For more information, see Placement
Groups (p. 784).
• Enable enhanced networking for supported current generation instance types to get significantly
higher packet per second (PPS) performance, lower network jitter, and lower latencies. For more
information, see Enhanced Networking on Linux (p. 750).
• Current generation instance types that are enabled for enhanced networking have the following
networking performance attributes:
• Traffic within the same region over private IPv4 or IPv6 can support 5 Gbps for single-flow traffic
and up to 25 Gbps for multi-flow traffic (depending on the instance type).
• Traffic to and from Amazon S3 buckets within the same region over the public IP address space or
through a VPC endpoint can use all available instance aggregate bandwidth.
• The maximum supported MTU varies across instance types. All Amazon EC2 instance types support
standard Ethernet V2 1500 MTU frames. All current generation instances support 9001 MTU, or jumbo
frames, and some previous generation instances support them as well. For more information, see
Network Maximum Transmission Unit (MTU) for Your EC2 Instance (p. 793).
182
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Networking and Storage Features
Storage features
• Some instance types support EBS volumes and instance store volumes, while other instance types
support only EBS volumes. Some instance types that support instance store volumes use solid state
drives (SSD) to deliver very high random I/O performance. Some instance types support NVMe
instance store volumes. Some instance types support NVMe EBS volumes. For more information, see
Amazon EBS and NVMe on Linux Instances (p. 912) and NVMe SSD Volumes (p. 964).
• To obtain additional, dedicated capacity for Amazon EBS I/O, you can launch some instance types as
EBS–optimized instances. Some instance types are EBS–optimized by default. For more information,
see Amazon EBS–Optimized Instances (p. 915).
P3 p3dn.24xlarge:p3dn.24xlarge:p3dn.24xlarge:Yes ENA
No Yes NVMe *
183
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Limits
T2 Yes No No No No
The following table summarizes the networking and storage features supported by previous generation
instance types.
G2 SSD Yes No
M3 SSD No No
Instance Limits
There is a limit on the total number of instances that you can launch in a region, and there are additional
limits on some instance types.
For more information about the default limits, see How many instances can I run in Amazon EC2?
For more information about viewing your current limits or requesting an increase in your current limits,
see Amazon EC2 Service Limits (p. 1005).
184
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
A1 Instances
A1 instances are ideally suited for scale-out workloads that are supported by the Arm ecosystem. These
instances are well-suited for the following applications:
• Web servers
• Containerized microservices
• Caching fleets
• Distributed data stores
• Applications that require the Arm instruction set
m5.metal and m5d.metal instances provide your applications with direct access to physical resources of
the host server, such as processors and memory. These instances are well suited for the following:
• Workloads that require access to low-level hardware features (for example, Intel VT) that are not
available or fully supported in virtualized environments
• Applications that require a non-virtualized environment for licensing or support
For more information, see Amazon EC2 T2 Instances and Amazon EC2 T3 Instances.
185
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
Contents
• Hardware Specifications (p. 186)
• Instance Performance (p. 188)
• Network Performance (p. 188)
• SSD I/O Performance (p. 189)
• Instance Features (p. 190)
• Release Notes (p. 191)
• Burstable Performance Instances (p. 192)
Hardware Specifications
The following is a summary of the hardware specifications for general purpose instances.
a1.medium 1 2
a1.large 2 4
a1.xlarge 4 8
a1.2xlarge 8 16
a1.4xlarge 16 32
m4.large 2 8
m4.xlarge 4 16
m4.2xlarge 8 32
m4.4xlarge 16 64
m4.10xlarge 40 160
m4.16xlarge 64 256
m5.large 2 8
m5.xlarge 4 16
m5.2xlarge 8 32
m5.4xlarge 16 64
m5.8xlarge 32 128
m5.12xlarge 48 192
m5.16xlarge 64 256
m5.24xlarge 96 384
m5.metal 96 384
m5a.large 2 8
m5a.xlarge 4 16
186
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
m5a.2xlarge 8 32
m5a.4xlarge 16 64
m5a.8xlarge 32 128
m5a.12xlarge 48 192
m5a.16xlarge 64 256
m5a.24xlarge 96 384
m5ad.large 2 8
m5ad.xlarge 4 16
m5ad.2xlarge 8 32
m5ad.4xlarge 16 64
m5ad.12xlarge 48 192
m5ad.24xlarge 96 384
m5d.large 2 8
m5d.xlarge 4 16
m5d.2xlarge 8 32
m5d.4xlarge 16 64
m5d.8xlarge 32 128
m5d.12xlarge 48 192
m5d.16xlarge 64 256
m5d.24xlarge 96 384
m5d.metal 96 384
t2.nano 1 0.5
t2.micro 1 1
t2.small 1 2
t2.medium 2 4
t2.large 2 8
t2.xlarge 4 16
t2.2xlarge 8 32
t3.nano 2 0.5
t3.micro 2 1
t3.small 2 2
187
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
t3.medium 2 4
t3.large 2 8
t3.xlarge 4 16
t3.2xlarge 8 32
t3a.nano 2 0.5
t3a.micro 2 1
t3a.small 2 2
t3a.medium 2 4
t3a.large 2 8
t3a.xlarge 4 16
t3a.2xlarge 8 32
For more information about the hardware specifications for each Amazon EC2 instance type, see Amazon
EC2 Instance Types.
For more information about specifying CPU options, see Optimizing CPU Options (p. 504).
Instance Performance
EBS-optimized instances enable you to get consistently high performance for your EBS volumes by
eliminating contention between Amazon EBS I/O and other network traffic from your instance. Some
general purpose instances are EBS-optimized by default at no additional cost. For more information, see
Amazon EBS–Optimized Instances (p. 915).
Some general purpose instance types provide the ability to control processor C-states and P-states on
Linux. C-states control the sleep levels that a core can enter when it is inactive, while P-states control the
desired performance (in CPU frequency) from a core. For more information, see Processor State Control
for Your EC2 Instance (p. 494).
Network Performance
You can enable enhanced networking capabilities on supported instance types. Enhanced networking
provides significantly higher packet-per-second (PPS) performance, lower network jitter, and lower
latencies. For more information, see Enhanced Networking on Linux (p. 750).
Instance types that use the Elastic Network Adapter (ENA) for enhanced networking deliver high packet
per second performance with consistently low latencies. Most applications do not consistently need
a high level of network performance, but can benefit from having access to increased bandwidth
when they send or receive data. Instance sizes that use the ENA and are documented with network
performance of "Up to 10 Gbps" or "Up to 25 Gbps" use a network I/O credit mechanism to allocate
network bandwidth to instances based on average bandwidth utilization. These instances accrue credits
when their network bandwidth is below their baseline limits, and can use these credits when they
perform network data transfers.
The following is a summary of network performance for general purpose instances that support
enhanced networking.
188
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
189
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
As you fill the SSD-based instance store volumes for your instance, the number of write IOPS that
you can achieve decreases. This is due to the extra work the SSD controller must do to find available
space, rewrite existing data, and erase unused space so that it can be rewritten. This process of
garbage collection results in internal write amplification to the SSD, expressed as the ratio of SSD write
operations to user write operations. This decrease in performance is even larger if the write operations
are not in multiples of 4,096 bytes or not aligned to a 4,096-byte boundary. If you write a smaller
amount of bytes or bytes that are not aligned, the SSD controller must read the surrounding data and
store the result in a new location. This pattern results in significantly increased write amplification,
increased latency, and dramatically reduced I/O performance.
SSD controllers can use several strategies to reduce the impact of write amplification. One such strategy
is to reserve space in the SSD instance storage so that the controller can more efficiently manage the
space available for write operations. This is called over-provisioning. The SSD-based instance store
volumes provided to an instance don't have any space reserved for over-provisioning. To reduce write
amplification, we recommend that you leave 10% of the volume unpartitioned so that the SSD controller
can use it for over-provisioning. This decreases the storage that you can use, but increases performance
even if the disk is close to full capacity.
For instance store volumes that support TRIM, you can use the TRIM command to notify the SSD
controller whenever you no longer need data that you've written. This provides the controller with more
free space, which can reduce write amplification and increase performance. For more information, see
Instance Store Volume TRIM Support (p. 965).
Instance Features
The following is a summary of features for general purpose instances:
190
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
M4 Yes No No Yes
T2 Yes No No No
T3 Yes Yes No No
Release Notes
• M5, M5d, and T3 instances feature a 3.1 GHz Intel Xeon Platinum 8000 series processor.
• M5a, M5ad, and T3a instances feature a 2.5 GHz AMD EPYC 7000 series processor.
• A1 instances feature a 2.3 GHz AWS Graviton processor based on 64-bit Arm architecture.
• M4, M5, M5a, M5ad, M5d, t2.large and larger, and t3.large and larger, and t3a.large and larger
instance types require 64-bit HVM AMIs. They have high-memory, and require a 64-bit operating
system to take advantage of that capacity. HVM AMIs provide superior performance in comparison to
paravirtual (PV) AMIs on high-memory instance types. In addition, you must use an HVM AMI to take
advantage of enhanced networking.
• A1 instances have the following requirements:
• Must have the NVMe drivers installed. EBS volumes are exposed as NVMe block devices (p. 912).
• Must have the Elastic Network Adapter (ENA (p. 751)) drivers installed.
• Must use an AMI for the 64-bit Arm architecture.
• Must support booting through UEFI with ACPI tables and support ACPI hot-plug of PCI devices.
191
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
CONFIG_HOTPLUG_PCI_PCIE=y
CONFIG_PCIEASPM=y
• Bare metal instances use a PCI-based serial device rather than an I/O port-based serial device. The
upstream Linux kernel and the latest Amazon Linux AMIs support this device. Bare metal instances also
provide an ACPI SPCR table to enable the system to automatically use the PCI-based serial device. The
latest Windows AMIs automatically use the PCI-based serial device.
• A1, M5, M5a, M5ad, M5d, T3, and T3a instances should have system-logind or acpid installed to
support clean shutdown through API requests.
• There is a limit on the total number of instances that you can launch in a region, and there are
additional limits on some instance types. For more information, see How many instances can I run in
Amazon EC2?. To request a limit increase, use the Amazon EC2 Instance Request Form.
Burstable performance instances are the only instance types that use credits for CPU usage. For more
information about instance pricing and additional hardware details, see Amazon EC2 Pricing and Amazon
EC2 Instance Types.
If your account is less than 12 months old, you can use a t2.micro instance for free within certain usage
limits. For more information, see AWS Free Tier.
Contents
• Burstable Performance Instance Requirements (p. 193)
• Best Practices (p. 193)
192
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
• CPU Credits and Baseline Performance for Burstable Performance Instances (p. 193)
• Unlimited Mode for Burstable Performance Instances (p. 196)
• Standard Mode for Burstable Performance Instances (p. 203)
• Working with Burstable Performance Instances (p. 214)
• Monitoring Your CPU Credits (p. 218)
• These instances are available as On-Demand Instances, Reserved Instances, and Spot Instances, but
not as Scheduled Instances or Dedicated Instances. They are also not supported on a Dedicated Host.
For more information, see Instance Purchasing Options (p. 254).
• Ensure that the instance size you choose passes the minimum memory requirements of your operating
system and applications. Operating systems with graphical user interfaces that consume significant
memory and CPU resources (for example, Windows) might require a t2.micro or larger instance size
for many use cases. As the memory and CPU requirements of your workload grow over time, you can
scale to larger instance sizes of the same instance type, or another instance type.
• For additional requirements, see General Purpose Instances Release Notes (p. 191).
Best Practices
Follow these best practices to get the maximum benefit from burstable performance instances.
• Use a recommended AMI – Use an AMI that provides the required drivers. For more information, see
Release Notes (p. 191).
• Turn on instance recovery – Create a CloudWatch alarm that monitors an EC2 instance and
automatically recovers it if it becomes impaired for any reason. For more information, see Adding
Recover Actions to Amazon CloudWatch Alarms (p. 581).
Contents
• CPU Credits (p. 193)
• Baseline Performance (p. 196)
CPU Credits
One CPU credit is equal to one vCPU running at 100% utilization for one minute. Other combinations of
number of vCPUs, utilization, and time can also equate to one CPU credit. For example, one CPU credit is
equal to one vCPU running at 50% utilization for two minutes, or two vCPUs running at 25% utilization
for two minutes.
Each burstable performance instance continuously earns (at a millisecond-level resolution) a set rate
of CPU credits per hour, depending on the instance size. The accounting process for whether credits
193
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
are accrued or spent also happens at a millisecond-level resolution, so you don't have to worry about
overspending CPU credits; a short burst of CPU uses a small fraction of a CPU credit.
If a burstable performance instance uses fewer CPU resources than is required for baseline performance
(such as when it is idle), the unspent CPU credits are accrued in the CPU credit balance. If a burstable
performance instance needs to burst above the baseline performance level, it spends the accrued credits.
The more credits that a burstable performance instance has accrued, the more time it can burst beyond
its baseline when more performance is needed.
The following table lists the burstable performance instance types, the rate at which CPU credits are
earned per hour, the maximum number of earned CPU credits that an instance can accrue, the number of
vCPUs per instance, and the baseline performance level as a percentage of a full core performance (using
a single vCPU).
t2.nano 3 72 1 5%
194
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
* The number of credits that can be accrued is equivalent to the number of credits that can be earned
in a 24-hour period.
** The baseline performance in the table is per vCPU. For instance sizes that have more than one vCPU,
to calculate the baseline CPU utilization for the instance, multiply the vCPU percentage by the number
of vCPUs. For example, a t3.large instance has two vCPUs, which provide a baseline CPU utilization
for the instance of 60% (2 vCPUs x 30% baseline performance of one vCPU). In CloudWatch, CPU
utilization is shown per vCPU. Therefore, the CPU utilization for a t3.large instance operating at the
baseline performance is shown as 30% in CloudWatch CPU metrics.
The number of CPU credits earned per hour is determined by the instance size. For example, a t3.nano
earns six credits per hour, while a t3.small earns 24 credits per hour. The preceding table lists the
credit earn rate for all instances.
While earned credits never expire on a running instance, there is a limit to the number of earned credits
that an instance can accrue. The limit is determined by the CPU credit balance limit. After the limit is
reached, any new credits that are earned are discarded, as indicated by the following image. The full
bucket indicates the CPU credit balance limit, and the spillover indicates the newly earned credits that
exceed the limit.
The CPU credit balance limit differs for each instance size. For example, a t3.micro instance can accrue
a maximum of 288 earned CPU credits in the CPU credit balance. The preceding table lists the maximum
number of earned credits that each instance can accrue.
Note
T2 Standard instances also earn launch credits. Launch credits do not count towards the CPU
credit balance limit. If a T2 instance has not spent its launch credits, and remains idle over a 24-
hour period while accruing earned credits, its CPU credit balance appears as over the limit. For
more information, see Launch Credits (p. 204).
T3 and T3a instances do not earn launch credits. These instances launch as unlimited by
default, and therefore can burst immediately upon start without any launch credits.
For T3 and T3a, the CPU credit balance persists for seven days after an instance stops and the credits are
lost thereafter. If you start the instance within seven days, no credits are lost.
For T2, the CPU credit balance does not persist between instance stops and starts. If you stop a T2
instance, the instance loses all its accrued credits.
For more information, see CPUCreditBalance in the CloudWatch metrics table (p. 219).
195
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
Baseline Performance
The number of credits that an instance earns per hour can be expressed as a percentage of CPU
utilization. It is known as the baseline performance, and sometimes just as the baseline. For example, a
t3.nano instance, with two vCPUs, earns six credits per hour, resulting in a baseline performance of 5%
(3/60 minutes) per vCPU. A t3.xlarge instance, with four vCPUs, earns 96 credits per hour, resulting in
a baseline performance of 40% (24/60 minutes) per vCPU.
For the vast majority of general-purpose workloads, instances configured as unlimited provide
ample performance without any additional charges. If the instance runs at higher CPU utilization for a
prolonged period, it can do so for a flat additional rate per vCPU-hour. For information about instance
pricing, see Amazon EC2 Pricing and the section for Unlimited pricing in Amazon EC2 On-Demand
Pricing.
Important
If you use a t2.micro instance under the AWS Free Tier offer and configure it as unlimited,
charges may apply if your average utilization over a rolling 24-hour period exceeds the baseline
of the instance.
Contents
• Unlimited Mode Concepts (p. 196)
• Examples: Unlimited Mode (p. 200)
The unlimited mode is a credit configuration option for burstable performance instances. It can be
enabled or disabled at any time for a running or stopped instance.
Note
T3 and T3a instances are launched as unlimited by default. T2 instances are launched as
standard by default.
If a burstable performance instance configured as unlimited depletes its CPU credit balance, it can
spend surplus credits to burst beyond the baseline. When its CPU utilization falls below the baseline,
it uses the CPU credits that it earns to pay down the surplus credits that it spent earlier. The ability to
earn CPU credits to pay down surplus credits enables Amazon EC2 to average the CPU utilization of an
instance over a 24-hour period. If the average CPU usage over a 24-hour period exceeds the baseline, the
instance is billed for the additional usage at a flat additional rate per vCPU-hour.
The following graph shows the CPU usage of a t3.large. The baseline CPU utilization for a t3.large
is 30%. If the instance runs at 30% CPU utilization or less on average over a 24-hour period, there is
no additional charge because the cost is already covered by the instance hourly price. However, if the
instance runs at 40% CPU utilization on average over a 24-hour period, as shown in the graph, the
instance is billed for the additional 10% CPU usage at a flat additional rate per vCPU-hour.
196
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
For more information about the baseline performance per vCPU for each instance type and how many
credits each instance type earns, see the credit table (p. 194).
When determining whether you should use a burstable performance instance in unlimited mode,
such as a T3, or a fixed performance instance, such as an M5, you need to determine the breakeven CPU
usage. The breakeven CPU usage for a burstable performance instance is the point at which a burstable
performance instance costs the same as a fixed performance instance. The breakeven CPU usage helps
you determine the following:
• If the average CPU usage over a 24-hour period is at or below the breakeven CPU usage, use a
burstable performance instance in unlimited mode so that you can benefit from the lower price of a
burstable performance instance while getting the same performance as a fixed performance instance.
• If the average CPU usage over a 24-hour period is above the breakeven CPU usage, the burstable
performance instance will cost more than the equivalently-sized fixed performance instance. If a T3
instance continuously bursts at 100% CPU, you end up paying approximately 1.5 times the price of an
equivalently-sized M5 instance.
The following graph shows the breakeven CPU usage point where a t3.large costs the same as an
m5.large. The breakeven CPU usage point for a t3.large is 42.5%. If the average CPU usage is at
42.5%, the cost of running the t3.large is the same as an m5.large, and is more expensive if the
average CPU usage is above 42.5%. If the workload needs less than 42.5% average CPU usage, you can
benefit from the lower price of the t3.large while getting the same performance as an m5.large.
197
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
The following table shows how to calculate the breakeven CPU usage threshold so that you can
determine when it's less expensive to use a burstable performance instance in unlimited mode or a
fixed performance instance. The columns in the table are labeled A through K.
A B C D E= F G H= I= J = (I / K=
D-C G / 60 E/H 60) / B F+J
198
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
• Column I shows the number of additional minutes that the t3.large can burst per hour at 100% CPU
while paying the same price per hour as an m5.large.
• Column J shows the additional CPU usage (in %) over baseline that the instance can burst while paying
the same price per hour as an m5.large.
• Column K shows the breakeven CPU usage (in %) that the t3.large can burst without paying more
than the m5.large. Anything above this, and the t3.large costs more than the m5.large.
The following table shows the breakeven CPU usage (in %) for T3 instance types compared to the
similarly-sized M5 instance types.
t3.large 42.5%
t3.xlarge 52.5%
t3.2xlarge 52.5%
If the average CPU utilization of an instance is at or below the baseline, the instance incurs no additional
charges. Because an instance earns a maximum number of credits (p. 194) in a 24-hour period (for
example, a t3.micro instance can earn a maximum of 288 credits in a 24-hour period), it can spend
surplus credits up to that maximum without being charged.
However, if CPU utilization stays above the baseline, the instance cannot earn enough credits to pay
down the surplus credits that it has spent. The surplus credits that are not paid down are charged at a
flat additional rate per vCPU-hour.
Surplus credits that were spent earlier are charged when any of the following occurs:
• The spent surplus credits exceed the maximum number of credits (p. 194) the instance can earn in a
24-hour period. Spent surplus credits above the maximum are charged at the end of the hour.
• The instance is stopped or terminated.
• The instance is switched from unlimited to standard.
Spent surplus credits are tracked by the CloudWatch metric CPUSurplusCreditBalance. Surplus
credits that are charged are tracked by the CloudWatch metric CPUSurplusCreditsCharged. For more
information, see Additional CloudWatch Metrics for Burstable Performance Instances (p. 218).
T2 Standard instances receive launch credits (p. 204), but T2 Unlimited instances do not. A T2
Unlimited instance can burst beyond the baseline at any time with no additional charge, as long as
its average CPU utilization is at or below the baseline over a rolling 24-hour window or its lifetime,
whichever is shorter. As such, T2 Unlimited instances do not require launch credits to achieve high
performance immediately after launch.
If a T2 instance is switched from standard to unlimited, any accrued launch credits are removed from
the CPUCreditBalance before the remaining CPUCreditBalance is carried over.
Note
T3 and T3a instances never receive launch credits.
199
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
T3 and T3a instances launch as unlimited by default. T2 instances launch as standard by default, but
you can enable unlimited at launch.
You can switch from unlimited to standard, and from standard to unlimited, at any time on a
running or stopped instance. For more information, see Launching a Burstable Performance Instance
as Unlimited or Standard (p. 215) and Modifying the Credit Specification of a Burstable Performance
Instance (p. 217).
You can check whether your burstable performance instance is configured as unlimited or standard
using the Amazon EC2 console or the AWS CLI. For more information, see Viewing the Credit
Specification of a Burstable Performance Instance (p. 217).
CPUCreditBalance is a CloudWatch metric that tracks the number of credits accrued by an instance.
CPUSurplusCreditBalance is a CloudWatch metric that tracks the number of surplus credits spent by
an instance.
When you change an instance configured as unlimited to standard, the following occurs:
To see if your instance is spending more credits than the baseline provides, you can use CloudWatch
metrics to track usage, and you can set up hourly alarms to be notified of credit usage. For more
information, see Monitoring Your CPU Credits (p. 218).
The following examples explain credit use for instances that are configured as unlimited.
Examples
• Example 1: Explaining Credit Use with T3 Unlimited (p. 200)
• Example 2: Explaining Credit Use with T2 Unlimited (p. 202)
In this example, you see the CPU utilization of a t3.nano instance launched as unlimited, and how it
spends earned and surplus credits to sustain CPU performance.
A t3.nano instance earns 144 CPU credits over a rolling 24-hour period, which it can redeem for 144
minutes of vCPU use. When it depletes its CPU credit balance (represented by the CloudWatch metric
CPUCreditBalance), it can spend surplus CPU credits—that it has not yet earned—to burst for as long
as it needs. Because a t3.nano instance earns a maximum of 144 credits in a 24-hour period, it can
spend surplus credits up to that maximum without being charged immediately. If it spends more than
144 CPU credits, it is charged for the difference at the end of the hour.
200
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
The intent of the example, illustrated by the following graph, is to show how an instance can burst using
surplus credits even after it depletes its CPUCreditBalance. The following workflow references the
numbered points on the graph:
P1 – At 0 hours on the graph, the instance is launched as unlimited and immediately begins to earn
credits. The instance remains idle from the time it is launched—CPU utilization is 0%—and no credits are
spent. All unspent credits are accrued in the credit balance. For the first 24 hours, CPUCreditUsage is at
0, and the CPUCreditBalance value reaches its maximum of 144.
P2 – For the next 12 hours, CPU utilization is at 2.5%, which is below the 5% baseline. The instance
earns more credits than it spends, but the CPUCreditBalance value cannot exceed its maximum of 144
credits.
P3 – For the next 24 hours, CPU utilization is at 7% (above the baseline), which requires a spend of 57.6
credits. The instance spends more credits than it earns, and the CPUCreditBalance value reduces to
86.4 credits.
P4 – For the next 12 hours, CPU utilization decreases to 2.5% (below the baseline), which requires a
spend of 36 credits. In the same time, the instance earns 72 credits. The instance earns more credits than
it spends, and the CPUCreditBalance value increases to 122 credits.
P5 – For the next 5 hours, the instance bursts at 100% CPU utilization, and spends a total of 570 credits
to sustain the burst. About an hour into this period, the instance depletes its entire CPUCreditBalance
of 122 credits, and starts to spend surplus credits to sustain the high CPU performance, totaling 448
surplus credits in this period (570-122=448). When the CPUSurplusCreditBalance value reaches
144 CPU credits (the maximum a t3.nano instance can earn in a 24-hour period), any surplus credits
spent thereafter cannot be offset by earned credits. The surplus credits spent thereafter amounts to 304
credits (448-144=304), which results in a small additional charge at the end of the hour for 304 credits.
P6 – For the next 13 hours, CPU utilization is at 5% (the baseline). The instance earns as
many credits as it spends, with no excess to pay down the CPUSurplusCreditBalance. The
CPUSurplusCreditBalance value remains at 144 credits.
P7 – For the last 24 hours in this example, the instance is idle and CPU utilization is 0%. During this time,
the instance earns 144 credits, which it uses to pay down the CPUSurplusCreditBalance.
201
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
In this example, you see the CPU utilization of a t2.nano instance launched as unlimited, and how it
spends earned and surplus credits to sustain CPU performance.
A t2.nano instance earns 72 CPU credits over a rolling 24-hour period, which it can redeem for 72
minutes of vCPU use. When it depletes its CPU credit balance (represented by the CloudWatch metric
CPUCreditBalance), it can spend surplus CPU credits—that it has not yet earned—to burst for as long
as it needs. Because a t2.nano instance earns a maximum of 72 credits in a 24-hour period, it can spend
surplus credits up to that maximum without being charged immediately. If it spends more than 72 CPU
credits, it is charged for the difference at the end of the hour.
The intent of the example, illustrated by the following graph, is to show how an instance can burst using
surplus credits even after it depletes its CPUCreditBalance. You can assume that, at the start of the
time line in the graph, the instance has an accrued credit balance equal to the maximum number of
credits it can earn in 24 hours. The following workflow references the numbered points on the graph:
1 – In the first 10 minutes, CPUCreditUsage is at 0, and the CPUCreditBalance value remains at its
maximum of 72.
2 – At 23:40, as CPU utilization increases, the instance spends CPU credits and the CPUCreditBalance
value decreases.
3 – At around 00:47, the instance depletes its entire CPUCreditBalance, and starts to spend surplus
credits to sustain high CPU performance.
4 – Surplus credits are spent until 01:55, when the CPUSurplusCreditBalance value reaches 72 CPU
credits. This is equal to the maximum a t2.nano instance can earn in a 24-hour period. Any surplus
202
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
credits spent thereafter cannot be offset by earned credits within the 24-hour period, which results in a
small additional charge at the end of the hour.
5 – The instance continues to spend surplus credits until around 02:20. At this time, CPU utilization
falls below the baseline, and the instance starts to earn credits at 3 credits per hour (or 0.25
credits every 5 minutes), which it uses to pay down the CPUSurplusCreditBalance. After the
CPUSurplusCreditBalance value reduces to 0, the instance starts to accrue earned credits in its
CPUCreditBalance at 0.25 credits every 5 minutes.
Surplus credits cost $0.05 per vCPU-hour. The instance spent approximately 25 surplus credits between
01:55 and 02:20, which is equivalent to 0.42 vCPU-hours.
Additional charges for this instance are 0.42 vCPU-hours x $0.05/vCPU-hour = $0.021, rounded to $0.02.
You can set billing alerts to be notified every hour of any accruing charges, and take action if required.
203
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
that the instance does not experience a sharp performance drop-off when its accrued CPU credit balance
is depleted. For more information, see CPU Credits and Baseline Performance for Burstable Performance
Instances (p. 193).
Contents
• Standard Mode Concepts (p. 204)
• Examples: Standard Mode (p. 206)
The standard mode is a configuration option for burstable performance instances. It can be enabled or
disabled at any time for a running or stopped instance.
Note
T3 and T3a instances are launched as unlimited by default. T2 instances are launched as
standard by default.
A T2 Standard instance receives two types of CPU credits: earned credits and launch credits. When a T2
Standard instance is in a running state, it continuously earns (at a millisecond-level resolution) a set rate
of earned credits per hour. At start, it has not yet earned credits for a good startup experience; therefore,
to provide a good startup experience, it receives launch credits at start, which it spends first while it
accrues earned credits.
Launch Credits
T2 Standard instances get 30 launch credits per vCPU at launch or start. For example, a t2.micro
instance has one vCPU and gets 30 launch credits, while a t2.xlarge instance has four vCPUs and gets
120 launch credits. Launch credits are designed to provide a good startup experience to allow instances
to burst immediately after launch before they have accrued earned credits.
Launch credits are spent first, before earned credits. Unspent launch credits are accrued in the CPU
credit balance, but do not count towards the CPU credit balance limit. For example, a t2.micro instance
has a CPU credit balance limit of 144 earned credits. If it is launched and remains idle for 24 hours,
its CPU credit balance reaches 174 (30 launch credits + 144 earned credits), which is over the limit.
However, after the instance spends the 30 launch credits, the credit balance cannot exceed 144. For more
information about the CPU credit balance limit for each instance size, see the credit table (p. 194).
The following table lists the initial CPU credit allocation received at launch or start, and the number of
vCPUs.
t1.micro 15 1
t2.nano 30 1
204
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
t2.micro 30 1
t2.small 30 1
t2.medium 60 2
t2.large 60 2
t2.xlarge 120 4
t2.2xlarge 240 8
There is a limit to the number of times T2 Standard instances can receive launch credits. The default limit
is 100 launches or starts of all T2 Standard instances combined per account, per Region, per rolling 24-
hour period. For example, the limit is reached when one instance is stopped and started 100 times within
a 24-hour period, or when 100 instances are launched within a 24-hour period, or other combinations
that equate to 100 starts. New accounts may have a lower limit, which increases over time based on your
usage.
Tip
To ensure that your workloads always get the performance they need, switch to Unlimited Mode
for Burstable Performance Instances (p. 196) or consider using a larger instance size.
The following table lists the differences between launch credits and earned credits.
Credit earn T2 Standard instances get 30 launch Each T2 instance continuously earns (at
rate credits per vCPU at launch or start. a millisecond-level resolution) a set rate
of CPU credits per hour, depending on
If a T2 instance is switched from the instance size. For more information
unlimited to standard, it does not get about the number of CPU credits
launch credits at the time of switching. earned per instance size, see the credit
table (p. 194).
Credit earn The limit for receiving launch credits is A T2 instance cannot accrue more credits
limit 100 launches or starts of all T2 Standard than the CPU credit balance limit. If the
instances combined per account, per CPU credit balance has reached its limit,
Region, per rolling 24-hour period. New any credits that are earned after the limit
accounts may have a lower limit, which is reached are discarded. Launch credits
increases over time based on your usage. do not count towards the limit. For more
information about the CPU credit balance
limit for each T2 instance size, see the
credit table (p. 194).
Credit use Launch credits are spent first, before Earned credits are spent only after all
earned credits. launch credits are spent.
205
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
The number of accrued launch credits and accrued earned credits is tracked by the CloudWatch metric
CPUCreditBalance. For more information, see CPUCreditBalance in the CloudWatch metrics
table (p. 219).
The following examples explain credit use when instances are configured as standard.
Examples
• Example 1: Explaining Credit Use with T3 Standard (p. 206)
• Example 2: Explaining Credit Use with T2 Standard (p. 207)
In this example, you see how a t3.nano instance launched as standard earns, accrues, and spends
earned credits. You see how the credit balance reflects the accrued earned credits.
Note
T3 and T3a instances configured as standard do not receive launch credits.
A running t3.nano instance earns 144 credits every 24 hours. Its credit balance limit is 144 earned
credits. After the limit is reached, new credits that are earned are discarded. For more information about
the number of credits that can be earned and accrued, see the credit table (p. 194).
You might launch a T3 Standard instance and use it immediately. Or, you might launch a T3 Standard
instance and leave it idle for a few days before running applications on it. Whether an instance is used or
remains idle determines if credits are spent or accrued. If an instance remains idle for 24 hours from the
time it is launched, the credit balance reaches it limit, which is the maximum number of earned credits
that can be accrued.
This example describes an instance that remains idle for 24 hours from the time it is launched, and walks
you through seven periods of time over a 96-hour period, showing the rate at which credits are earned,
accrued, spent, and discarded, and the value of the credit balance at the end of each period.
P1 – At 0 hours on the graph, the instance is launched as standard and immediately begins to earn
credits. The instance remains idle from the time it is launched—CPU utilization is 0%—and no credits are
spent. All unspent credits are accrued in the credit balance. For the first 24 hours, CPUCreditUsage is at
0, and the CPUCreditBalance value reaches its maximum of 144.
P2 – For the next 12 hours, CPU utilization is at 2.5%, which is below the 5% baseline. The instance
earns more credits than it spends, but the CPUCreditBalance value cannot exceed its maximum of 144
credits. Any credits that are earned in excess of the limit are discarded.
P3 – For the next 24 hours, CPU utilization is at 7% (above the baseline), which requires a spend of 57.6
credits. The instance spends more credits than it earns, and the CPUCreditBalance value reduces to
86.4 credits.
P4 – For the next 12 hours, CPU utilization decreases to 2.5% (below the baseline), which requires a
spend of 36 credits. In the same time, the instance earns 72 credits. The instance earns more credits than
it spends, and the CPUCreditBalance value increases to 122 credits.
P5 – For the next two hours, the instance bursts at 100% CPU utilization, and depletes its entire
CPUCreditBalance value of 122 credits. At the end of this period, with the CPUCreditBalance at
zero, CPU utilization is forced to drop to the baseline performance level of 5%. At the baseline, the
instance earns as many credits as it spends.
206
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
P6 – For the next 14 hours, CPU utilization is at 5% (the baseline). The instance earns as many credits as
it spends. The CPUCreditBalance value remains at 0.
P7 – For the last 24 hours in this example, the instance is idle and CPU utilization is 0%. During this time,
the instance earns 144 credits, which it accrues in its CPUCreditBalance.
In this example, you see how a t2.nano instance launched as standard earns, accrues, and spends
launch and earned credits. You see how the credit balance reflects not only accrued earned credits, but
also accrued launch credits.
A t2.nano instance gets 30 launch credits when it is launched, and earns 72 credits every 24 hours. Its
credit balance limit is 72 earned credits; launch credits do not count towards the limit. After the limit is
reached, new credits that are earned are discarded. For more information about the number of credits
that can be earned and accrued, see the credit table (p. 194). For more information about limits, see
Launch Credit Limits (p. 205).
You might launch a T2 Standard instance and use it immediately. Or, you might launch a T2 Standard
instance and leave it idle for a few days before running applications on it. Whether an instance is used
or remains idle determines if credits are spent or accrued. If an instance remains idle for 24 hours from
the time it is launched, the credit balance appears to exceed its limit because the balance reflects both
accrued earned credits and accrued launch credits. However, after CPU is used, the launch credits are
spent first. Thereafter, the limit always reflects the maximum number of earned credits that can be
accrued.
This example describes an instance that remains idle for 24 hours from the time it is launched, and walks
you through seven periods of time over a 96-hour period, showing the rate at which credits are earned,
accrued, spent, and discarded, and the value of the credit balance at the end of each period.
Period 1: 1 – 24 hours
At 0 hours on the graph, the T2 instance is launched as standard and immediately gets 30 launch
credits. It earns credits while in the running state. The instance remains idle from the time it is launched
—CPU utilization is 0%—and no credits are spent. All unspent credits are accrued in the credit balance.
At approximately 14 hours after launch, the credit balance is 72 (30 launch credits + 42 earned credits),
which is equivalent to what the instance can earn in 24 hours. At 24 hours after launch, the credit
balance exceeds 72 credits because the unspent launch credits are accrued in the credit balance—the
credit balance is 102 credits: 30 launch credits + 72 earned credits.
207
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
Conclusion
If there is no CPU utilization after launch, the instance accrues more credits than what it can earn in 24
hours (30 launch credits + 72 earned credits = 102 credits).
In a real-world scenario, an EC2 instance consumes a small number of credits while launching and
running, which prevents the balance from reaching the maximum theoretical value in this example.
Period 2: 25 – 36 hours
For the next 12 hours, the instance continues to remain idle and earn credits, but the credit balance does
not increase. It plateaus at 102 credits (30 launch credits + 72 earned credits). The credit balance has
reached its limit of 72 accrued earned credits, so newly earned credits are discarded.
208
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
Credit Discard Rate 72 credits per 24 hours (100% of credit earn rate)
Conclusion
An instance constantly earns credits, but it cannot accrue more earned credits if the credit balance
has reached its limit. After the limit is reached, newly earned credits are discarded. Launch credits do
not count towards the credit balance limit. If the balance includes accrued launch credits, the balance
appears to be over the limit.
Period 3: 37 – 61 hours
For the next 25 hours, the instance uses 2% CPU, which requires 30 credits. In the same period, it earns
75 credits, but the credit balance decreases. The balance decreases because the accrued launch credits
are spent first, while newly earned credits are discarded because the credit balance is already at its limit
of 72 earned credits.
209
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
Credit Spend Rate 28.8 credits per 24 hours (1.2 credits per hour,
2% CPU utilization, 40% of credit earn rate)—30
credits over 25 hours
Credit Discard Rate 72 credits per 24 hours (100% of credit earn rate)
Conclusion
An instance spends launch credits first, before spending earned credits. Launch credits do not count
towards the credit limit. After the launch credits are spent, the balance can never go higher than what
can be earned in 24 hours. Furthermore, while an instance is running, it cannot get more launch credits.
Period 4: 62 – 72 hours
For the next 11 hours, the instance uses 2% CPU, which requires 13.2 credits. This is the same CPU
utilization as in the previous period, but the balance does not decrease. It stays at 72 credits.
The balance does not decrease because the credit earn rate is higher than the credit spend rate. In the
time that the instance spends 13.2 credits, it also earns 33 credits. However, the balance limit is 72
credits, so any earned credits that exceed the limit are discarded. The balance plateaus at 72 credits,
which is different from the plateau of 102 credits during Period 2, because there are no accrued launch
credits.
210
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
Credit Spend Rate 28.8 credits per 24 hours (1.2 credits per hour, 2%
CPU utilization, 40% of credit earn rate)—13.2
credits over 11 hours
Credit Discard Rate 43.2 credits per 24 hours (60% of credit earn rate)
Conclusion
After launch credits are spent, the credit balance limit is determined by the number of credits that an
instance can earn in 24 hours. If the instance earns more credits than it spends, newly earned credits over
the limit are discarded.
Period 5: 73 – 75 hours
For the next three hours, the instance bursts at 20% CPU utilization, which requires 36 credits. The
instance earns nine credits in the same three hours, which results in a net balance decrease of 27 credits.
At the end of three hours, the credit balance is 45 accrued earned credits.
211
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
Credit Spend Rate 288 credits per 24 hours (12 credits per hour, 20%
CPU utilization, 400% of credit earn rate)—36
credits over 3 hours
Conclusion
If an instance spends more credits than it earns, its credit balance decreases.
Period 6: 76 – 90 hours
For the next 15 hours, the instance uses 2% CPU, which requires 18 credits. This is the same CPU
utilization as in Periods 3 and 4. However, the balance increases in this period, whereas it decreased in
Period 3 and plateaued in Period 4.
In Period 3, the accrued launch credits were spent, and any earned credits that exceeded the credit limit
were discarded, resulting in a decrease in the credit balance. In Period 4, the instance spent fewer credits
than it earned. Any earned credits that exceeded the limit were discarded, so the balance plateaued at its
maximum of 72 credits.
212
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
In this period, there are no accrued launch credits, and the number of accrued earned credits in the
balance is below the limit. No earned credits are discarded. Furthermore, the instance earns more credits
than it spends, resulting in an increase in the credit balance.
Credit Spend Rate 28.8 credits per 24 hours (1.2 credits per hour,
2% CPU utilization, 40% of credit earn rate)—18
credits over 15 hours
Credit Earn Rate 72 credits per 24 hours (45 credits over 15 hours)
Conclusion
If an instance spends fewer credits than it earns, its credit balance increases.
Period 7: 91 – 96 hours
For the next six hours, the instance remains idle—CPU utilization is 0%—and no credits are spent. This is
the same CPU utilization as in Period 2, but the balance does not plateau at 102 credits—it plateaus at
72 credits, which is the credit balance limit for the instance.
In Period 2, the credit balance included 30 accrued launch credits. The launch credits were spent in
Period 3. A running instance cannot get more launch credits. After its credit balance limit is reached, any
earned credits that exceed the limit are discarded.
213
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
Credit Discard Rate 72 credits per 24 hours (100% of credit earn rate)
Conclusion
An instance constantly earns credits, but cannot accrue more earned credits if the credit balance limit has
been reached. After the limit is reached, newly earned credits are discarded. The credit balance limit is
determined by the number of credits that an instance can earn in 24 hours. For more information about
credit balance limits, see the credit table (p. 194).
Contents
• Launching a Burstable Performance Instance as Unlimited or Standard (p. 215)
• Using an Auto Scaling Group to Launch a Burstable Performance Instance as Unlimited (p. 215)
214
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
T3 and T3a instances launch as unlimited by default. T2 instances launch as standard by default.
For more information about AMI and driver requirements for these instances, see Release
Notes (p. 191).
You must launch your instances using an Amazon EBS volume as the root device. For more information,
see Amazon EC2 Root Device Volume (p. 14).
You can launch your instances as unlimited or standard using the Amazon EC2 console, an AWS SDK,
a command line tool, or with an Auto Scaling group. For more information, see Using an Auto Scaling
Group to Launch a Burstable Performance Instance as Unlimited (p. 215).
1. Follow the Launching an Instance Using the Launch Instance Wizard (p. 395) procedure.
2. On the Choose an Instance Type page, select an instance type, and choose Next: Configure
Instance Details.
3. Choose a credit specification. The default for T3 and T3a is unlimited, and for T2 it is standard.
a. To launch a T3 or T3a instance as standard, on the Configure Instance Details page, for T2/T3
Unlimited, clear Enable.
b. To launch a T2 instance as unlimited, on the Configure Instance Details page, for T2/T3
Unlimited, select Enable.
4. Continue as prompted by the wizard. When you've finished reviewing your options on the Review
Instance Launch page, choose Launch. For more information, see Launching an Instance Using the
Launch Instance Wizard (p. 395).
Use the run-instances command to launch your instances. Specify the credit specification using the --
credit-specification CpuCredits= parameter. Valid credit specifications are unlimited and
standard.
• For T3 and T3a, if you do not include the --credit-specification parameter, the instance
launches as unlimited by default.
• For T2, if you do not include the --credit-specification parameter, the instance launches as
standard by default.
When burstable performance instances are launched or started, they require CPU credits for a good
bootstrapping experience. If you use an Auto Scaling group to launch your instances, we recommend
that you configure your instances as unlimited. If you do, the instances use surplus credits when
they are automatically launched or restarted by the Auto Scaling group. Using surplus credits prevents
performance restrictions.
215
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
You must use a launch template for launching instances as unlimited in an Auto Scaling group. A
launch configuration does not support launching instances as unlimited.
1. Follow the Creating a Launch Template for an Auto Scaling Group procedure.
2. In Launch template contents, for Instance type, choose a T3, T3a, or T2 instance size.
3. To launch instances as unlimited in an Auto Scaling group, in Advanced details, for T2/T3
Unlimited, choose Enable.
4. When you've finished defining the launch template parameters, choose Create launch template.
For more information, see Creating a Launch Template for an Auto Scaling Group in the Amazon EC2
Auto Scaling User Guide.
Use the create-launch-template command and specify unlimited as the credit specification.
To associate the launch template with an Auto Scaling group, create the Auto Scaling group using the
launch template, or add the launch template to an existing Auto Scaling group.
Use the create-auto-scaling-group AWS CLI command and specify the --launch-template parameter.
216
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
Use the update-auto-scaling-group AWS CLI command and specify the --launch-template parameter.
You can view the credit specification (unlimited or standard) of a running or stopped instance.
Use the describe-instance-credit-specifications command. If you do not specify one or more instance
IDs, all instances with the credit specification of unlimited are returned, as well as instances that were
previously configured with the unlimited credit specification. For example, if you resize a T3 instance
to an M4 instance, while it is configured as unlimited, Amazon EC2 returns the M4 instance.
Example
{
"InstanceCreditSpecifications": [
{
"InstanceId": "i-1234567890abcdef0",
"CpuCredits": "unlimited"
}
]
}
You can switch the credit specification of a running or stopped instance at any time between unlimited
and standard.
217
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
Note
The Change T2/T3 Unlimited option is enabled only if you select a T3, T3a, or T2 instance.
4. To change the credit specification to unlimited, choose Enable. To change the credit specification
to standard, choose Disable. The current credit specification for the instance appears in
parentheses after the instance ID.
Use the modify-instance-credit-specification command. Specify the instance and its credit specification
using the --instance-credit-specification parameter. Valid credit specifications are unlimited
and standard.
Example
{
"SuccessfulInstanceCreditSpecifications": [
{
"InstanceId": "i- 1234567890abcdef0"
}
],
"UnsuccessfulInstanceCreditSpecifications": []
}
Topics
• Additional CloudWatch Metrics for Burstable Performance Instances (p. 218)
• Calculating CPU Credit Usage (p. 220)
T3, T3a, and T2 instances have these additional CloudWatch metrics, which are updated every five
minutes:
• CPUCreditUsage – The number of CPU credits spent during the measurement period.
• CPUCreditBalance – The number of CPU credits that an instance has accrued. This balance is
depleted when the CPU bursts and CPU credits are spent more quickly than they are earned.
• CPUSurplusCreditBalance – The number of surplus CPU credits spent to sustain CPU performance
when the CPUCreditBalance value is zero.
• CPUSurplusCreditsCharged – The number of surplus CPU credits exceeding the maximum number
of CPU credits (p. 194) that can be earned in a 24-hour period, and thus attracting an additional
charge.
218
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
The following table describes the CloudWatch metrics for burstable performance instances. For more
information, see List the Available CloudWatch Metrics for Your Instances (p. 560).
Metric Description
CPUCreditUsage The number of CPU credits spent by the instance for CPU
utilization. One CPU credit equals one vCPU running at 100%
utilization for one minute or an equivalent combination of vCPUs,
utilization, and time (for example, one vCPU running at 50%
utilization for two minutes or two vCPUs running at 25% utilization
for two minutes).
Credits are accrued in the credit balance after they are earned,
and removed from the credit balance when they are spent. The
credit balance has a maximum limit, determined by the instance
size. After the limit is reached, any new credits that are earned are
discarded. For T2 Standard, launch credits do not count towards the
limit.
CPUSurplusCreditsCharged The number of spent surplus credits that are not paid down by
earned CPU credits, and which thus incur an additional charge.
Spent surplus credits are charged when any of the following occurs:
219
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
Metric Description
• The spent surplus credits exceed the maximum number of credits
that the instance can earn in a 24-hour period. Spent surplus
credits above the maximum are charged at the end of the hour.
• The instance is stopped or terminated.
• The instance is switched from unlimited to standard.
The CPU credit usage of instances is calculated using the instance CloudWatch metrics described in the
preceding table.
Amazon EC2 sends the metrics to CloudWatch every five minutes. A reference to the prior value of a
metric at any point in time implies the previous value of the metric, sent five minutes ago.
• The CPU credit balance increases if CPU utilization is below the baseline, when the credits spent are
less than the credits earned in the prior five-minute interval.
• The CPU credit balance decreases if CPU utilization is above the baseline, when the credits spent are
more than the credits earned in the prior five-minute interval.
Example
The size of the instance determines the number of credits that the instance can earn per hour and the
number of earned credits that it can accrue in the credit balance. For information about the number of
credits earned per hour, and the credit balance limit for each instance size, see the credit table (p. 194).
Example
This example uses a t3.nano instance. To calculate the CPUCreditBalance value of the instance, use
the preceding equation as follows:
220
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General Purpose Instances
Example
When a T3, T3a, or T2 instance needs to burst above the baseline, it always spends accrued credits before
spending surplus credits. When it depletes its accrued CPU credit balance, it can spend surplus credits
to burst for as long as it needs. When CPU utilization falls below the baseline, surplus credits are always
paid down before the instance accrues earned credits.
We use the term Adjusted balance in the following equations to reflect the activity that occurs in
this five-minute interval. We use this value to arrive at the values for the CPUCreditBalance and
CPUSurplusCreditBalance CloudWatch metrics.
Example
A value of 0 for Adjusted balance indicates that the instance spent all its earned credits
for bursting, and no surplus credits were spent. As a result, both CPUCreditBalance and
CPUSurplusCreditBalance are set to 0.
A positive Adjusted balance value indicates that the instance accrued earned credits, and previous
surplus credits, if any, were paid down. As a result, the Adjusted balance value is assigned to
CPUCreditBalance, and the CPUSurplusCreditBalance is set to 0. The instance size determines the
maximum number of credits (p. 194) that it can accrue.
Example
A negative Adjusted balance value indicates that the instance spent all its earned credits that it
accrued and, in addition, also spent surplus credits for bursting. As a result, the Adjusted balance
value is assigned to CPUSurplusCreditBalance and CPUCreditBalance is set to 0. Again, the
instance size determines the maximum number of credits (p. 194) that it can accrue.
Example
If the surplus credits spent exceed the maximum credits that the instance can accrue, the surplus credit
balance is set to the maximum, as shown in the preceding equation. The remaining surplus credits are
charged as represented by the CPUSurplusCreditsCharged metric.
Example
Finally, when the instance terminates, any surplus credits tracked by the CPUSurplusCreditBalance
are charged. If the instance is switched from unlimited to standard, any remaining
CPUSurplusCreditBalance is also charged.
221
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Compute Optimized Instances
Contents
• Hardware Specifications (p. 222)
• Instance Performance (p. 223)
• Network Performance (p. 223)
• SSD I/O Performance (p. 224)
• Instance Features (p. 225)
• Release Notes (p. 225)
Hardware Specifications
The following is a summary of the hardware specifications for compute optimized instances.
c4.large 2 3.75
c4.xlarge 4 7.5
c4.2xlarge 8 15
c4.4xlarge 16 30
c4.8xlarge 36 60
c5.large 2 4
c5.xlarge 4 8
c5.2xlarge 8 16
c5.4xlarge 16 32
c5.9xlarge 36 72
c5.12xlarge 48 96
c5.18xlarge 72 144
c5.24large 96 192
222
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Compute Optimized Instances
c5.metal 96 192
c5d.large 2 4
c5d.xlarge 4 8
c5d.2xlarge 8 16
c5d.4xlarge 16 32
c5d.9xlarge 36 72
c5d.18xlarge 72 144
c5n.large 2 5.25
c5n.xlarge 4 10.5
c5n.2xlarge 8 21
c5n.4xlarge 16 42
c5n.9xlarge 36 96
c5n.18xlarge 72 192
For more information about the hardware specifications for each Amazon EC2 instance type, see Amazon
EC2 Instance Types.
For more information about specifying CPU options, see Optimizing CPU Options (p. 504).
Instance Performance
EBS-optimized instances enable you to get consistently high performance for your EBS volumes by
eliminating contention between Amazon EBS I/O and other network traffic from your instance. Some
compute optimized instances are EBS-optimized by default at no additional cost. For more information,
see Amazon EBS–Optimized Instances (p. 915).
Some compute optimized instance types provide the ability to control processor C-states and P-states on
Linux. C-states control the sleep levels that a core can enter when it is inactive, while P-states control the
desired performance (in CPU frequency) from a core. For more information, see Processor State Control
for Your EC2 Instance (p. 494).
Network Performance
You can enable enhanced networking capabilities on supported instance types. Enhanced networking
provides significantly higher packet-per-second (PPS) performance, lower network jitter, and lower
latencies. For more information, see Enhanced Networking on Linux (p. 750).
Instance types that use the Elastic Network Adapter (ENA) for enhanced networking deliver high packet
per second performance with consistently low latencies. Most applications do not consistently need
a high level of network performance, but can benefit from having access to increased bandwidth
when they send or receive data. Instance sizes that use the ENA and are documented with network
performance of "Up to 10 Gbps" or "Up to 25 Gbps" use a network I/O credit mechanism to allocate
network bandwidth to instances based on average bandwidth utilization. These instances accrue credits
when their network bandwidth is below their baseline limits, and can use these credits when they
perform network data transfers.
223
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Compute Optimized Instances
The following is a summary of network performance for compute optimized instances that support
enhanced networking.
As you fill the SSD-based instance store volumes for your instance, the number of write IOPS that
you can achieve decreases. This is due to the extra work the SSD controller must do to find available
space, rewrite existing data, and erase unused space so that it can be rewritten. This process of
garbage collection results in internal write amplification to the SSD, expressed as the ratio of SSD write
operations to user write operations. This decrease in performance is even larger if the write operations
are not in multiples of 4,096 bytes or not aligned to a 4,096-byte boundary. If you write a smaller
amount of bytes or bytes that are not aligned, the SSD controller must read the surrounding data and
224
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Compute Optimized Instances
store the result in a new location. This pattern results in significantly increased write amplification,
increased latency, and dramatically reduced I/O performance.
SSD controllers can use several strategies to reduce the impact of write amplification. One such strategy
is to reserve space in the SSD instance storage so that the controller can more efficiently manage the
space available for write operations. This is called over-provisioning. The SSD-based instance store
volumes provided to an instance don't have any space reserved for over-provisioning. To reduce write
amplification, we recommend that you leave 10% of the volume unpartitioned so that the SSD controller
can use it for over-provisioning. This decreases the storage that you can use, but increases performance
even if the disk is close to full capacity.
For instance store volumes that support TRIM, you can use the TRIM command to notify the SSD
controller whenever you no longer need data that you've written. This provides the controller with more
free space, which can reduce write amplification and increase performance. For more information, see
Instance Store Volume TRIM Support (p. 965).
Instance Features
The following is a summary of features for compute optimized instances:
C4 Yes No No Yes
Release Notes
• C4, C5, C5d, and C5n instances require 64-bit EBS-backed HVM AMIs. They have high-memory and
require a 64-bit operating system to take advantage of that capacity. HVM AMIs provide superior
performance in comparison to paravirtual (PV) AMIs on high-memory instance types. In addition, you
must use an HVM AMI to take advantage of enhanced networking.
• C5, C5d, and C5n instances have the following requirements:
• NVMe drivers must be installed. EBS volumes are exposed as NVMe block devices (p. 912).
• Elastic Network Adapter (ENA (p. 751)) drivers must be installed.
225
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Memory Optimized Instances
• CentOS 7 or later
• FreeBSD 11.1 or later
• C5, C5d, and C5n instances support a maximum of 28 attachments, including network interfaces,
EBS volumes, and NVMe instance store volumes. Every instance has at least one network interface
attachment.
• Launching a bare metal instance boots the underlying server, which includes verifying all hardware and
firmware components. This means that it can take 20 minutes from the time the instance enters the
running state until it becomes available over the network.
• To attach or detach EBS volumes or secondary network interfaces from a bare metal instance requires
PCIe native hotplug support. Amazon Linux 2 and the latest versions of the Amazon Linux AMI
support PCIe native hotplug, but earlier versions do not. You must enable the following Linux kernel
configuration options:
CONFIG_HOTPLUG_PCI_PCIE=y
CONFIG_PCIEASPM=y
• Bare metal instances use a PCI-based serial device rather than an I/O port-based serial device. The
upstream Linux kernel and the latest Amazon Linux AMIs support this device. Bare metal instances also
provide an ACPI SPCR table to enable the system to automatically use the PCI-based serial device. The
latest Windows AMIs automatically use the PCI-based serial device.
• C5, C5d, and C5n instances should have acpid installed to support clean shutdown through API
requests.
• There is a limit on the total number of instances that you can launch in a region, and there are
additional limits on some instance types. For more information, see How many instances can I run in
Amazon EC2?. To request a limit increase, use the Amazon EC2 Instance Request Form.
r5.metal and r5d.metal instances provide your applications with direct access to physical resources of
the host server, such as processors and memory. These instances are well suited for the following:
• Workloads that require access to low-level hardware features (for example, Intel VT) that are not
available or fully supported in virtualized environments
• Applications that require a non-virtualized environment for licensing or support
226
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Memory Optimized Instances
High memory instances (u-6tb1.metal, u-9tb1.metal, and u-12tb1.metal) offer 6 TiB, 9 TiB,
and 12 TiB of memory per instance. These instances are designed to run large in-memory databases,
including production installations of SAP HANA. They offer bare metal performance with direct access to
host hardware.
X1 Instances
These instances are well suited for the following applications:
• In-memory databases such as SAP HANA, including SAP-certified support for Business Suite S/4HANA,
Business Suite on HANA (SoH), Business Warehouse on HANA (BW), and Data Mart Solutions on HANA.
For more information, see SAP HANA on the AWS Cloud.
• Big-data processing engines such as Apache Spark or Presto.
• High-performance computing (HPC) applications.
X1e Instances
These instances are well suited for the following applications:
• High-performance databases.
• In-memory databases such as SAP HANA. For more information, see SAP HANA on the AWS Cloud.
• Memory-intensive enterprise applications.
z1d Instances
These instances deliver both high compute and high memory and are well-suited for the following
applications:
z1d.metal instances provide your applications with direct access to physical resources of the host
server, such as processors and memory. These instances are well suited for the following:
• Workloads that require access to low-level hardware features (for example, Intel VT) that are not
available or fully supported in virtualized environments
• Applications that require a non-virtualized environment for licensing or support
Contents
• Hardware Specifications (p. 228)
• Memory Performance (p. 230)
• Instance Performance (p. 230)
• Network Performance (p. 230)
• SSD I/O Performance (p. 231)
• Instance Features (p. 232)
• Support for vCPUs (p. 233)
227
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Memory Optimized Instances
Hardware Specifications
The following is a summary of the hardware specifications for memory optimized instances.
r4.large 2 15.25
r4.xlarge 4 30.5
r4.2xlarge 8 61
r4.4xlarge 16 122
r4.8xlarge 32 244
r4.16xlarge 64 488
r5.large 2 16
r5.xlarge 4 32
r5.2xlarge 8 64
r5.4xlarge 16 128
r5.8xlarge 32 256
r5.12xlarge 48 384
r5.16xlarge 64 512
r5.24xlarge 96 768
r5.metal 96 768
r5a.large 2 16
r5a.xlarge 4 32
r5a.2xlarge 8 64
r5a.4xlarge 16 128
r5a.8xlarge 32 256
r5a.12xlarge 48 384
r5a.16xlarge 64 512
r5a.24xlarge 96 768
r5ad.large 2 16
r5ad.xlarge 4 32
r5ad.2xlarge 8 64
r5ad.4xlarge 16 128
228
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Memory Optimized Instances
r5ad.12xlarge 48 384
r5ad.24xlarge 96 768
r5d.large 2 16
r5d.xlarge 4 32
r5d.2xlarge 8 64
r5d.4xlarge 16 128
r5d.8xlarge 32 256
r5d.12xlarge 48 384
r5d.16xlarge 64 512
r5d.24xlarge 96 768
r5d.metal 96 768
x1.16xlarge 64 976
x1e.xlarge 4 122
x1e.2xlarge 8 244
x1e.4xlarge 16 488
x1e.8xlarge 32 976
x1e.16xlarge 64 1,952
z1d.large 2 16
z1d.xlarge 4 32
z1d.2xlarge 8 64
z1d.3xlarge 12 96
z1d.6xlarge 24 192
z1d.12xlarge 48 384
z1d.metal 48 384
229
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Memory Optimized Instances
For more information about the hardware specifications for each Amazon EC2 instance type, see Amazon
EC2 Instance Types.
For more information about specifying CPU options, see Optimizing CPU Options (p. 504).
Memory Performance
X1 instances include Intel Scalable Memory Buffers, providing 300 GiB/s of sustainable memory-read
bandwidth and 140 GiB/s of sustainable memory-write bandwidth.
For more information about how much RAM can be enabled for memory optimized instances, see
Hardware Specifications (p. 228).
Memory optimized instances have high memory and require 64-bit HVM AMIs to take advantage of that
capacity. HVM AMIs provide superior performance in comparison to paravirtual (PV) AMIs on memory
optimized instances. For more information, see Linux AMI Virtualization Types (p. 99).
Instance Performance
R4 instances feature up to 64 vCPUs and are powered by two AWS-customized Intel XEON processors
based on E5-2686v4 that feature high-memory bandwidth and larger L3 caches to boost the
performance of in-memory applications.
X1e and X1 instances feature up to 128 vCPUs and are powered by four Intel Xeon E7-8880 v3
processors that feature high-memory bandwidth and larger L3 caches to boost the performance of in-
memory applications.
High memory instances (u-6tb1.metal, u-9tb1.metal, and u-12tb1.metal) are the first instances
to be powered by an eight-socket platform with the latest generation Intel Xeon Platinum 8176M
(Skylake) processors that are optimized for mission-critical enterprise workloads.
Memory optimized instances enable increased cryptographic performance through the latest Intel AES-
NI feature, support Intel Transactional Synchronization Extensions (TSX) to boost the performance of in-
memory transactional data processing, and support Advanced Vector Extensions 2 (Intel AVX2) processor
instructions to expand most integer commands to 256 bits.
Some memory optimized instances provide the ability to control processor C-states and P-states on
Linux. C-states control the sleep levels that a core can enter when it is inactive, while P-states control
the desired performance (measured by CPU frequency) from a core. For more information, see Processor
State Control for Your EC2 Instance (p. 494).
Network Performance
You can enable enhanced networking capabilities on supported instance types. Enhanced networking
provides significantly higher packet-per-second (PPS) performance, lower network jitter, and lower
latencies. For more information, see Enhanced Networking on Linux (p. 750).
Instance types that use the Elastic Network Adapter (ENA) for enhanced networking deliver high packet
per second performance with consistently low latencies. Most applications do not consistently need
a high level of network performance, but can benefit from having access to increased bandwidth
when they send or receive data. Instance sizes that use the ENA and are documented with network
performance of "Up to 10 Gbps" or "Up to 25 Gbps" use a network I/O credit mechanism to allocate
network bandwidth to instances based on average bandwidth utilization. These instances accrue credits
when their network bandwidth is below their baseline limits, and can use these credits when they
perform network data transfers.
The following is a summary of network performance for memory optimized instances that support
enhanced networking.
230
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Memory Optimized Instances
231
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Memory Optimized Instances
As you fill the SSD-based instance store volumes for your instance, the number of write IOPS that
you can achieve decreases. This is due to the extra work the SSD controller must do to find available
space, rewrite existing data, and erase unused space so that it can be rewritten. This process of
garbage collection results in internal write amplification to the SSD, expressed as the ratio of SSD write
operations to user write operations. This decrease in performance is even larger if the write operations
are not in multiples of 4,096 bytes or not aligned to a 4,096-byte boundary. If you write a smaller
amount of bytes or bytes that are not aligned, the SSD controller must read the surrounding data and
store the result in a new location. This pattern results in significantly increased write amplification,
increased latency, and dramatically reduced I/O performance.
SSD controllers can use several strategies to reduce the impact of write amplification. One such strategy
is to reserve space in the SSD instance storage so that the controller can more efficiently manage the
space available for write operations. This is called over-provisioning. The SSD-based instance store
volumes provided to an instance don't have any space reserved for over-provisioning. To reduce write
amplification, we recommend that you leave 10% of the volume unpartitioned so that the SSD controller
can use it for over-provisioning. This decreases the storage that you can use, but increases performance
even if the disk is close to full capacity.
For instance store volumes that support TRIM, you can use the TRIM command to notify the SSD
controller whenever you no longer need data that you've written. This provides the controller with more
free space, which can reduce write amplification and increase performance. For more information, see
Instance Store Volume TRIM Support (p. 965).
Instance Features
The following is a summary of features for memory optimized instances.
R4 Yes No No Yes
232
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Memory Optimized Instances
Yes
u-6tb1.metal Yes No No
Yes
u-9tb1.metal Yes No No
Yes
u-12tb1.metal Yes No No
X1 No No SSD Yes
Release Notes
• R5 and R5d instances feature a 3.1 GHz Intel Xeon Platinum 8000 series processor.
• R5a and R5ad instances feature a 2.5 GHz AMD EPYC 7000 series processor.
• The following are requirements for high memory, R5, R5a, R5ad, R5d, and z1d instances:
• NVMe drivers must be installed. EBS volumes are exposed as NVMe block devices (p. 912).
233
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Storage Optimized Instances
CONFIG_HOTPLUG_PCI_PCIE=y
CONFIG_PCIEASPM=y
• Bare metal instances use a PCI-based serial device rather than an I/O port-based serial device. The
upstream Linux kernel and the latest Amazon Linux AMIs support this device. Bare metal instances also
provide an ACPI SPCR table to enable the system to automatically use the PCI-based serial device. The
latest Windows AMIs automatically use the PCI-based serial device.
• You can't launch X1 instances using a Windows Server 2008 SP2 64-bit AMI, except for x1.16xlarge
instances.
• You can't launch X1e instances using a Windows Server 2008 SP2 64-bit AMI.
• With earlier versions of the Windows Server 2008 R2 64-bit AMI, you can't launch r4.large and
r4.4xlarge instances. If you experience this issue, update to the latest version of this AMI.
• There is a limit on the total number of instances that you can launch in a region, and there are
additional limits on some instance types. For more information, see How many instances can I run in
Amazon EC2?. To request a limit increase, use the Amazon EC2 Instance Request Form.
D2 Instances
234
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Storage Optimized Instances
H1 Instances
i3.metal instances provide your applications with direct access to physical resources of the host server,
such as processors and memory. These instances are well suited for the following:
• Workloads that require access to low-level hardware features (for example, Intel VT) that are not
available or fully supported in virtualized environments
• Applications that require a non-virtualized environment for licensing or support
Contents
• Hardware Specifications (p. 235)
• Instance Performance (p. 236)
• Network Performance (p. 237)
• SSD I/O Performance (p. 238)
• Instance Features (p. 239)
• Support for vCPUs (p. 239)
• Release Notes (p. 240)
Hardware Specifications
The primary data storage for D2 instances is HDD instance store volumes. The primary data storage for
I3 instances is non-volatile memory express (NVMe) SSD instance store volumes.
Instance store volumes persist only for the life of the instance. When you stop or terminate an instance,
the applications and data in its instance store volumes are erased. We recommend that you regularly
back up or replicate important data in your instance store volumes. For more information, see Amazon
EC2 Instance Store (p. 956) and SSD Instance Store Volumes (p. 964).
The following is a summary of the hardware specifications for storage optimized instances.
235
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Storage Optimized Instances
d2.xlarge 4 30.5
d2.2xlarge 8 61
d2.4xlarge 16 122
d2.8xlarge 36 244
h1.2xlarge 8 32
h1.4xlarge 16 64
h1.8xlarge 32 128
h1.16xlarge 64 256
i3.large 2 15.25
i3.xlarge 4 30.5
i3.2xlarge 8 61
i3.4xlarge 16 122
i3.8xlarge 32 244
i3.16xlarge 64 488
i3.metal 72 512
i3en.large 2 16
i3en.xlarge 4 32
i3en.2xlarge 8 64
i3en.3xlarge 12 96
i3en.6xlarge 24 192
i3en.12xlarge 48 384
i3en.24xlarge 96 768
For more information about the hardware specifications for each Amazon EC2 instance type, see Amazon
EC2 Instance Types.
For more information about specifying CPU options, see Optimizing CPU Options (p. 504).
Instance Performance
To ensure the best disk throughput performance from your instance on Linux, we recommend that you
use the most recent version of Amazon Linux 2 or the Amazon Linux AMI.
For instances with NVMe instance store volumes, you must use a Linux AMI with kernel version 4.4 or
later. Otherwise, your instance will not achieve the maximum IOPS performance available.
236
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Storage Optimized Instances
D2 instances provide the best disk performance when you use a Linux kernel that supports persistent
grants, an extension to the Xen block ring protocol that significantly improves disk throughput and
scalability. For more information about persistent grants, see this article in the Xen Project Blog.
EBS-optimized instances enable you to get consistently high performance for your EBS volumes by
eliminating contention between Amazon EBS I/O and other network traffic from your instance. Some
storage optimized instances are EBS-optimized by default at no additional cost. For more information,
see Amazon EBS–Optimized Instances (p. 915).
Some storage optimized instance types provide the ability to control processor C-states and P-states on
Linux. C-states control the sleep levels that a core can enter when it is inactive, while P-states control the
desired performance (in CPU frequency) from a core. For more information, see Processor State Control
for Your EC2 Instance (p. 494).
Network Performance
You can enable enhanced networking capabilities on supported instance types. Enhanced networking
provides significantly higher packet-per-second (PPS) performance, lower network jitter, and lower
latencies. For more information, see Enhanced Networking on Linux (p. 750).
Instance types that use the Elastic Network Adapter (ENA) for enhanced networking deliver high packet
per second performance with consistently low latencies. Most applications do not consistently need
a high level of network performance, but can benefit from having access to increased bandwidth
when they send or receive data. Instance sizes that use the ENA and are documented with network
performance of "Up to 10 Gbps" or "Up to 25 Gbps" use a network I/O credit mechanism to allocate
network bandwidth to instances based on average bandwidth utilization. These instances accrue credits
when their network bandwidth is below their baseline limits, and can use these credits when they
perform network data transfers.
The following is a summary of network performance for storage optimized instances that support
enhanced networking.
i3.4xlarge and smaller Up to 10 Gbps, use network I/O ENA (p. 751)
credit mechanism
i3en.3xlarge and smaller Up to 25 Gbps, use network I/O ENA (p. 751)
credit mechanism
237
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Storage Optimized Instances
As you fill your SSD-based instance store volumes, the I/O performance that you get decreases. This is
due to the extra work that the SSD controller must do to find available space, rewrite existing data, and
erase unused space so that it can be rewritten. This process of garbage collection results in internal write
amplification to the SSD, expressed as the ratio of SSD write operations to user write operations. This
decrease in performance is even larger if the write operations are not in multiples of 4,096 bytes or not
aligned to a 4,096-byte boundary. If you write a smaller amount of bytes or bytes that are not aligned,
the SSD controller must read the surrounding data and store the result in a new location. This pattern
results in significantly increased write amplification, increased latency, and dramatically reduced I/O
performance.
SSD controllers can use several strategies to reduce the impact of write amplification. One such strategy
is to reserve space in the SSD instance storage so that the controller can more efficiently manage the
space available for write operations. This is called over-provisioning. The SSD-based instance store
volumes provided to an instance don't have any space reserved for over-provisioning. To reduce write
amplification, we recommend that you leave 10% of the volume unpartitioned so that the SSD controller
can use it for over-provisioning. This decreases the storage that you can use, but increases performance
even if the disk is close to full capacity.
For instance store volumes that support TRIM, you can use the TRIM command to notify the SSD
controller whenever you no longer need data that you've written. This provides the controller with more
free space, which can reduce write amplification and increase performance. For more information, see
Instance Store Volume TRIM Support (p. 965).
238
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Storage Optimized Instances
Instance Features
The following is a summary of features for storage optimized instances:
D2 No HDD Yes
H1 No HDD * Yes
I3 No NVMe * Yes
The following Linux AMIs support launching d2.8xlarge instances with 36 vCPUs:
If you must use a different AMI for your application, and your d2.8xlarge instance launch does not
complete successfully (for example, if your instance status changes to stopped during launch with a
Client.InstanceInitiatedShutdown state transition reason), modify your instance as described in
the following procedure to support more than 32 vCPUs so that you can use the d2.8xlarge instance
type.
1. Launch a D2 instance using your AMI, choosing any D2 instance type other than d2.8xlarge.
2. Update the kernel to the latest version by following your operating system-specific instructions. For
example, for RHEL 6, use the following command:
239
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Storage Optimized Instances
5. Change the instance type of your stopped instance to d2.8xlarge (choose Actions, Instance
Settings, Change Instance Type, and then follow the directions).
6. Start the instance. If the instance launches properly, you are done. If the instance still does not boot
properly, proceed to the next step.
7. (Optional) If the instance still does not boot properly, the kernel on your instance may not support
more than 32 vCPUs. However, you may be able to boot the instance if you limit the vCPUs.
a. Change the instance type of your stopped instance to any D2 instance type other than
d2.8xlarge (choose Actions, Instance Settings, Change Instance Type, and then follow the
directions).
b. Add the maxcpus=32 option to your boot kernel parameters by following your operating
system-specific instructions. For example, for RHEL 6, edit the /boot/grub/menu.lst file and
add the following option to the most recent and active kernel entry:
default=0
timeout=1
splashimage=(hd0,0)/boot/grub/splash.xpm.gz
hiddenmenu
title Red Hat Enterprise Linux Server (2.6.32-504.3.3.el6.x86_64)
root (hd0,0)
kernel /boot/vmlinuz-2.6.32-504.3.3.el6.x86_64 maxcpus=32 console=ttyS0 ro
root=UUID=9996863e-b964-47d3-a33b-3920974fdbd9 rd_NO_LUKS KEYBOARDTYPE=pc
KEYTABLE=us LANG=en_US.UTF-8 xen_blkfront.sda_is_xvda=1 console=ttyS0,115200n8
console=tty0 rd_NO_MD SYSFONT=latarcyrheb-sun16 crashkernel=auto rd_NO_LVM
rd_NO_DM
initrd /boot/initramfs-2.6.32-504.3.3.el6.x86_64.img
Release Notes
• You must launch storage optimized instances using an HVM AMI. For more information, see Linux AMI
Virtualization Types (p. 99).
• The following are requirements for I3en and i3.metal instances:
• NVMe drivers must be installed. EBS volumes are exposed as NVMe block devices (p. 912).
• Elastic Network Adapter (ENA (p. 751)) drivers must be installed.
• To attach or detach EBS volumes or secondary network interfaces from a bare metal instance requires
PCIe native hotplug support. Amazon Linux 2 and the latest versions of the Amazon Linux AMI
support PCIe native hotplug, but earlier versions do not. You must enable the following Linux kernel
configuration options:
CONFIG_HOTPLUG_PCI_PCIE=y
CONFIG_PCIEASPM=y
• Bare metal instances use a PCI-based serial device rather than an I/O port-based serial device. The
upstream Linux kernel and the latest Amazon Linux AMIs support this device. Bare metal instances also
provide an ACPI SPCR table to enable the system to automatically use the PCI-based serial device. The
latest Windows AMIs automatically use the PCI-based serial device.
• With FreeBSD AMIs, bare metal instances take nearly an hour to boot and I/O to the local NVMe
storage does not complete. As a workaround, add the following line to /boot/loader.conf and
reboot:
hw.nvme.per_cpu_io_queues="0"
• The d2.8xlarge instance type has 36 vCPUs, which might cause launch issues in some
Linux operating systems that have a vCPU limit of 32. For more information, see Support for
vCPUs (p. 239).
• There is a limit on the total number of instances that you can launch in a region, and there are
additional limits on some instance types. For more information, see How many instances can I run in
Amazon EC2?. To request a limit increase, use the Amazon EC2 Instance Request Form.
GPU-based instances provide access to NVIDIA GPUs with thousands of compute cores. You can use GPU-
based accelerated computing instances to accelerate scientific, engineering, and rendering applications
by leveraging the CUDA or Open Computing Language (OpenCL) parallel computing frameworks. You
can also use them for graphics applications, including game streaming, 3-D application streaming, and
other graphics workloads.
FPGA-based instances provide access to large FPGAs with millions of parallel system logic cells. You can
use FPGA-based accelerated computing instances to accelerate workloads such as genomics, financial
analysis, real-time video processing, big data analysis, and security workloads by leveraging custom
hardware accelerations. You can develop these accelerations using hardware description languages such
as Verilog or VHDL, or by using higher-level languages such as OpenCL parallel computing frameworks.
You can either develop your own hardware acceleration code or purchase hardware accelerations through
the AWS Marketplace.
Important
FPGA-based instances do not support Microsoft Windows.
You can cluster accelerated computing instances into a cluster placement group. Cluster placement
groups provide low latency and high-bandwidth connectivity between the instances within a single
Availability Zone. For more information, see Placement Groups (p. 784).
Contents
• Accelerated Computing Instance Families (p. 242)
• Hardware Specifications (p. 243)
241
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Accelerated Computing Instances
For information about Windows accelerated computing instances, see Windows Accelerated Computing
Instances in the Amazon EC2 User Guide for Windows Instances.
F1 Instances
F1 instances use Xilinx UltraScale+ VU9P FPGAs and are designed to accelerate computationally
intensive algorithms, such as data-flow or highly parallel operations not suited to general purpose
CPUs. Each FPGA in an F1 instance contains approximately 2.5 million logic elements and approximately
6,800 Digital Signal Processing (DSP) engines, along with 64 GiB of local DDR ECC protected memory,
connected to the instance by a dedicated PCIe Gen3 x16 connection. F1 instances provide local NVMe
SSD volumes.
Developers can use the FPGA Developer AMI and AWS Hardware Developer Kit to create custom
hardware accelerations for use on F1 instances. The FPGA Developer AMI includes development tools for
full-cycle FPGA development in the cloud. Using these tools, developers can create and share Amazon
FPGA Images (AFIs) that can be loaded onto the FPGA of an F1 instance.
P3 Instances
P3 instances use NVIDIA Tesla V100 GPUs and are designed for general purpose GPU computing
using the CUDA or OpenCL programming models or through a machine learning framework. P3
instances provide high-bandwidth networking, powerful half, single, and double-precision floating-
point capabilities, and up to 32 GiB of memory per GPU, which makes them ideal for deep learning,
computational fluid dynamics, computational finance, seismic analysis, molecular modeling, genomics,
rendering, and other server-side GPU compute workloads. Tesla V100 GPUs do not support graphics
mode. For more information, see Amazon EC2 P3 Instances.
To view topology information about the system, run the following command:
nvidia-smi topo -m
P2 Instances
242
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Accelerated Computing Instances
P2 instances use NVIDIA Tesla K80 GPUs and are designed for general purpose GPU computing using
the CUDA or OpenCL programming models. P2 instances provide high-bandwidth networking, powerful
single and double precision floating-point capabilities, and 12 GiB of memory per GPU, which makes
them ideal for deep learning, graph databases, high-performance databases, computational fluid
dynamics, computational finance, seismic analysis, molecular modeling, genomics, rendering, and other
server-side GPU compute workloads.
To view topology information about the system, run the following command:
nvidia-smi topo -m
G3 Instances
G3 instances use NVIDIA Tesla M60 GPUs and provide a cost-effective, high-performance platform
for graphics applications using DirectX or OpenGL. G3 instances also provide NVIDIA GRID Virtual
Workstation features, such as support for four monitors with resolutions up to 4096x2160, and NVIDIA
GRID Virtual Applications. G3 instances are well-suited for applications such as 3D visualizations,
graphics-intensive remote workstations, 3D rendering, video encoding, virtual reality, and other server-
side graphics workloads requiring massively parallel processing power.
G3 instances support NVIDIA GRID Virtual Workstation and NVIDIA GRID Virtual Applications. To activate
either of these features, see Activate NVIDIA GRID Virtual Applications (G3 Instances Only) (p. 249).
G2 Instances
G2 instances use NVIDIA GRID K520 GPUs and provide a cost-effective, high-performance platform for
graphics applications using DirectX or OpenGL. NVIDIA GRID GPUs also support NVIDIA’s fast capture and
encode API operations. Example applications include video creation services, 3D visualizations, streaming
graphics-intensive applications, and other server-side graphics workloads.
Hardware Specifications
The following is a summary of the hardware specifications for accelerated computing instances.
p2.xlarge 4 61 1
p2.8xlarge 32 488 8
p2.16xlarge 64 732 16
p3.2xlarge 8 61 1
p3.8xlarge 32 244 4
p3.16xlarge 64 488 8
p3dn.24xlarge 96 768 8
g2.2xlarge 8 15 1
g2.8xlarge 32 60 4
g3s.xlarge 4 30.5 1
243
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Accelerated Computing Instances
g3.4xlarge 16 122 1
g3.8xlarge 32 244 2
g3.16xlarge 64 488 4
f1.2xlarge 8 122 1
f1.4xlarge 16 244 2
f1.16xlarge 64 976 8
For more information about the hardware specifications for each Amazon EC2 instance type, see Amazon
EC2 Instance Types.
For more information about specifying CPU options, see Optimizing CPU Options (p. 504).
Instance Performance
There are several GPU setting optimizations that you can perform to achieve the best performance on
your instances. For more information, see Optimizing GPU Settings (p. 250).
EBS-optimized instances enable you to get consistently high performance for your EBS volumes
by eliminating contention between Amazon EBS I/O and other network traffic from your instance.
Some accelerated computing instances are EBS-optimized by default at no additional cost. For more
information, see Amazon EBS–Optimized Instances (p. 915).
Some accelerated computing instance types provide the ability to control processor C-states and P-states
on Linux. C-states control the sleep levels that a core can enter when it is inactive, while P-states control
the desired performance (in CPU frequency) from a core. For more information, see Processor State
Control for Your EC2 Instance (p. 494).
Network Performance
You can enable enhanced networking capabilities on supported instance types. Enhanced networking
provides significantly higher packet-per-second (PPS) performance, lower network jitter, and lower
latencies. For more information, see Enhanced Networking on Linux (p. 750).
Instance types that use the Elastic Network Adapter (ENA) for enhanced networking deliver high packet
per second performance with consistently low latencies. Most applications do not consistently need
a high level of network performance, but can benefit from having access to increased bandwidth
when they send or receive data. Instance sizes that use the ENA and are documented with network
performance of "Up to 10 Gbps" or "Up to 25 Gbps" use a network I/O credit mechanism to allocate
network bandwidth to instances based on average bandwidth utilization. These instances accrue credits
when their network bandwidth is below their baseline limits, and can use these credits when they
perform network data transfers.
The following is a summary of network performance for accelerated computing instances that support
enhanced networking.
244
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Accelerated Computing Instances
Instance Features
The following is a summary of features for accelerated computing instances.
G2 No No SSD Yes
G3 Yes No No Yes
P2 Yes No No Yes
F1 No No NVMe * Yes
Release Notes
• You must launch the instance using an HVM AMI.
• GPU-based instances can't access the GPU unless the NVIDIA drivers are installed.
• There is a limit of 100 AFIs per region.
• There is a limit on the number of instances that you can run. For more information, see How many
instances can I run in Amazon EC2? in the Amazon EC2 FAQ. To request an increase in these limits, use
the following form: Request to Increase Amazon EC2 Instance Limit.
245
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Accelerated Computing Instances
For a list of AMIs with the NVIDIA driver, search AWS Marketplace as follows:
• NVIDIA P3 AMIs
• NVIDIA P2 AMIs
• NVIDIA GRID G3 AMIs
• NVIDIA GRID G2 AMIs
You can launch accelerated computing instances using any HVM AMI.
Important
These AMIs include drivers, software, or toolkits that are developed, owned, or provided by
NVIDIA Corporation. By using these AMIs, you agree to use these NVIDIA drivers, software, or
toolkits only on Amazon EC2 instances that include NVIDIA hardware.
You can also install the NVIDIA driver manually. For more information, see Installing the NVIDIA Driver on
Linux Instances (p. 246).
Amazon provides AMIs with updated and compatible builds of the NVIDIA kernel drivers for each official
kernel upgrade in the AWS Marketplace. If you decide to use a different NVIDIA driver version than
the one that Amazon provides, or decide to use a kernel that's not an official Amazon build, you must
uninstall the Amazon-provided NVIDIA packages from your system to avoid conflicts with the versions of
the drivers that you are trying to install.
The Amazon-provided CUDA toolkit package has dependencies on the NVIDIA drivers. Uninstalling the
NVIDIA packages erases the CUDA toolkit. You must reinstall the CUDA toolkit after installing the NVIDIA
driver.
Use the following AWS CLI command to download the latest driver:
Multiple versions of the NVIDIA GRID driver are stored in this bucket. You can see all of the available
versions with the following command:
246
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Accelerated Computing Instances
Download the 64-bit NVIDIA driver appropriate for your instance type from http://www.nvidia.com/
Download/Find.aspx.
For more information about installing and configuring the driver, choose the ADDITIONAL
INFORMATION tab on the download page for the driver on the NVIDIA website and choose the README
link.
1. Update your package cache and get necessary package updates for your instance.
2. (Ubuntu 16.04 and later, with the linux-aws package) Upgrade the linux-aws package to receive
the latest version.
247
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Accelerated Computing Instances
6. Disable the nouveau open source driver for NVIDIA graphics cards.
GRUB_CMDLINE_LINUX="rdblacklist=nouveau"
• For P2 and P3 instances, the following command downloads the NVIDIA driver, where xxx.xxx
represents the version of the NVIDIA driver.
• For G2 instances, the following command downloads the NVIDIA driver, where xxx.xxx represents
the version of the NVIDIA driver.
• For G3 instances, you can download the driver from Amazon S3 using the AWS CLI or SDKs. To
install the AWS CLI, see Installing the AWS Command Line Interface in the AWS Command Line
Interface User Guide. Use the following AWS CLI command to download the latest driver:
Important
This download is available to AWS customers only. By downloading, you agree to use the
downloaded software only to develop AMIs for use with the NVIDIA Tesla M60 hardware.
Upon installation of the software, you are bound by the terms of the NVIDIA GRID Cloud
End User License Agreement.
Multiple versions of the NVIDIA GRID driver are stored in this bucket. You can see all of the
available versions with the following command:
248
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Accelerated Computing Instances
8. Run the self-install script to install the NVIDIA driver that you downloaded in the previous step. For
example:
When prompted, accept the license agreement and specify the installation options as required (you
can accept the default options).
9. Reboot the instance.
10. Confirm that the driver is functional. The response for the following command lists the installed
NVIDIA driver version and details about the GPUs.
Note
This command may take several minutes to run.
11. [G3 instances only] To enable NVIDIA GRID Virtual Applications on a G3 instance, complete the GRID
activation steps in Activate NVIDIA GRID Virtual Applications (G3 Instances Only) (p. 249) (NVIDIA
GRID Virtual Workstation is enabled by default).
12. [P2, P3, and G3 instances] Complete the optimization steps in Optimizing GPU Settings (p. 250) to
achieve the best performance from your GPU.
FeatureType=0
IgnoreSP=TRUE
249
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Changing the Instance Type
1. Configure the GPU settings to be persistent. This command can take several minutes to run.
Note
GPUs on P3 instances do not support autoboost.
3. Set all GPU clock speeds to their maximum frequency. Use the memory and graphics clock speeds
specified in the following commands.
Note
Some versions of the NVIDIA driver do not allow setting application clock speed and throw
a "Setting applications clocks is not supported for GPU …" error, which
you can ignore.
• G3 instances:
• P2 instances:
• P3 instances:
For more information, see the documentation for the AWS FPGA Hardware Development Kit.
250
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Changing the Instance Type
You might also want to migrate from a previous generation instance type to a current generation
instance type to take advantage of some features; for example, support for IPv6.
If the root device for your instance is an EBS volume, you can change the size of the instance simply by
changing its instance type, which is known as resizing it. If the root device for your instance is an instance
store volume, you must migrate your application to a new instance with the instance type that you need.
For more information about root device volumes, see Storage for the Root Device (p. 97).
When you resize an instance, you must select an instance type that is compatible with the configuration
of the instance. If the instance type that you want is not compatible with the instance configuration you
have, then you must migrate your application to a new instance with the instance type that you need.
Important
When you resize an instance, the resized instance usually has the same number of instance store
volumes that you specified when you launched the original instance. With instance types that
support NVMe instance store volumes (which are available by default), the resized instance
might have additional instance store volumes, depending on the AMI. Otherwise, you can
migrate your application to an instance with a new instance type manually, specifying the
number of instance store volumes that you need when you launch the new instance.
Contents
• Compatibility for Resizing Instances (p. 251)
• Resizing an Amazon EBS–backed Instance (p. 252)
• Migrating an Instance Store-backed Instance (p. 253)
• Migrating to a New Instance Configuration (p. 254)
• Virtualization type: Linux AMIs use one of two types of virtualization: paravirtual (PV) or hardware
virtual machine (HVM). You can't resize an instance that was launched from a PV AMI to an instance
type that is HVM only. For more information, see Linux AMI Virtualization Types (p. 99). To check the
virtualization type of your instance, see the Virtualization field on the details pane of the Instances
screen in the Amazon EC2 console.
• Architecture: AMIs are specific to the architecture of the processor, so you must select an instance type
with the same processor architecture as the current instance type. For example:
• A1 instances are the only instances that support processors based on the Arm architecture. If you
are resizing an instance type with a processor based on the Arm architecture, you are limited to the
instance types that support a processor based on the Arm architecture.
• The following instance types are the only instance types that support 32-bit AMIs: t2.nano,
t2.micro, t2.small, t2.medium, c3.large, t1.micro, m1.small, m1.medium, and
c1.medium. If you are resizing a 32-bit instance, you are limited to these instance types.
• Network: Newer instance types must be launched in a VPC. Therefore, you can't resize an instance in
the EC2-Classic platform to a instance type that is available only in a VPC unless you have a nondefault
VPC. To check whether your instance is in a VPC, check the VPC ID value on the details pane of the
Instances screen in the Amazon EC2 console. For more information, see Migrating from a Linux
Instance in EC2-Classic to a Linux Instance in a VPC (p. 816).
• Enhanced networking: Instance types that support enhanced networking (p. 750) require
the necessary drivers installed. For example, the A1, C5, C5d, C5n, I3en, M5, M5a, M5ad, M5d,
p3dn.24xlarge, R5, R5a, R5ad, R5d, T3, T3a, and z1d instance types require EBS-backed AMIs with
the Elastic Network Adapter (ENA) drivers installed. To resize an existing instance to an instance
type that supports enhanced networking, you must first install the ENA drivers (p. 751) or ixgbevf
drivers (p. 763) on your instance, as appropriate.
251
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Changing the Instance Type
• NVMe: EBS volumes are exposed as NVMe block devices on Nitro-based instances (p. 181). If you
resize an instance from an instance type that does not support NVMe to an instance type that supports
NVMe, you must first install the NVMe drivers (p. 912) on your instance. Also, the device names for
devices that you specify in the block device mapping are renamed using NVMe device names (/dev/
nvme[0-26]n1). Therefore, to mount file systems at boot time using /etc/fstab, you must use
UUID/Label instead of device names.
• AMI: For information about the AMIs required by instance types that support enhanced networking
and NVMe, see the Release Notes in the following documentation:
• General Purpose Instances (p. 185)
• Compute Optimized Instances (p. 222)
• Memory Optimized Instances (p. 226)
• Storage Optimized Instances (p. 234)
• We move the instance to new hardware; however, the instance ID does not change.
• If your instance has a public IPv4 address, we release the address and give it a new public IPv4 address.
The instance retains its private IPv4 addresses, any Elastic IP addresses, and any IPv6 addresses.
• If your instance is in an Auto Scaling group, the Amazon EC2 Auto Scaling service marks the stopped
instance as unhealthy, and may terminate it and launch a replacement instance. To prevent this,
you can suspend the scaling processes for the group while you're resizing your instance. For more
information, see Suspending and Resuming Scaling Processes in the Amazon EC2 Auto Scaling User
Guide.
• If your instance is in a cluster placement group (p. 785) and, after changing the instance type, the
instance start fails, try the following: stop all the instances in the cluster placement group, change
the instance type for the affected instance, and then restart all the instances in the cluster placement
group.
• Ensure that you plan for downtime while your instance is stopped. Stopping and resizing an instance
may take a few minutes, and restarting your instance may take a variable amount of time depending
on your application's startup scripts.
For more information, see Stop and Start Your Instance (p. 468).
Use the following procedure to resize an Amazon EBS–backed instance using the AWS Management
Console.
1. (Optional) If the new instance type requires drivers that are not installed on the existing instance,
you must connect to your instance and install the drivers first. For more information, see
Compatibility for Resizing Instances (p. 251).
2. Open the Amazon EC2 console.
3. In the navigation pane, choose Instances.
4. Select the instance and choose Actions, Instance State, Stop.
5. In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.
6. With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This
action is disabled if the instance state is not stopped.
7. In the Change Instance Type dialog box, do the following:
252
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Changing the Instance Type
a. From Instance Type, select the instance type that you want. If the instance type that you want
does not appear in the list, then it is not compatible with the configuration of your instance (for
example, because of virtualization type). For more information, see Compatibility for Resizing
Instances (p. 251).
b. (Optional) If the instance type that you selected supports EBS–optimization, select EBS-
optimized to enable EBS–optimization or deselect EBS-optimized to disable EBS–optimization.
If the instance type that you selected is EBS–optimized by default, EBS-optimized is selected
and you can't deselect it.
c. Choose Apply to accept the new settings.
8. To restart the stopped instance, select the instance and choose Actions, Instance State, Start.
9. In the confirmation dialog box, choose Yes, Start. It can take a few minutes for the instance to enter
the running state.
10. (Troubleshooting) If your instance won't boot, it is possible that one of the requirements for the new
instance type was not met. For more information, see Why is my Linux instance not booting after I
changed its type?
1. Back up any data on your instance store volumes that you need to keep to persistent storage.
To migrate data on your EBS volumes that you need to keep, take a snapshot of the volumes
(see Creating Amazon EBS Snapshots (p. 869)) or detach the volume from the instance so
that you can attach it to the new instance later (see Detaching an Amazon EBS Volume from an
Instance (p. 864)).
2. Create an AMI from your instance store-backed instance by satisfying the prerequisites and following
the procedures in Creating an Instance Store-Backed Linux AMI (p. 119). When you are finished
creating an AMI from your instance, return to this procedure.
3. Open the Amazon EC2 console and in the navigation pane, choose AMIs. From the filter lists, choose
Owned by me, and choose the image that you created in the previous step. Notice that AMI Name is
the name that you specified when you registered the image and Source is your Amazon S3 bucket.
Note
If you do not see the AMI that you created in the previous step, make sure that you have
selected the Region in which you created your AMI.
4. Choose Launch. When you specify options for the instance, be sure to select the new instance type
that you want. If the instance type that you want can't be selected, then it is not compatible with
configuration of the AMI that you created (for example, because of virtualization type). You can also
specify any EBS volumes that you detached from the original instance.
It can take a few minutes for the instance to enter the running state.
5. (Optional) You can terminate the instance that you started with, if it's no longer needed. Select the
instance and verify that you are about to terminate the original instance, not the new instance (for
example, check the name or launch time). Choose Actions, Instance State, Terminate.
253
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Purchasing Options
If you want to move from an instance launched from a PV AMI to an instance type that is HVM only, the
general process is as follows:
1. Back up any data on your instance store volumes that you need to keep to persistent storage.
To migrate data on your EBS volumes that you need to keep, create a snapshot of the volumes
(see Creating Amazon EBS Snapshots (p. 869)) or detach the volume from the instance so
that you can attach it to the new instance later (see Detaching an Amazon EBS Volume from an
Instance (p. 864)).
2. Launch a new instance, selecting the following:
• An HVM AMI.
• The HVM only instance type.
• If you are using an Elastic IP address, select the VPC that the original instance is currently running
in.
• Any EBS volumes that you detached from the original instance and want to attach to the new
instance, or new EBS volumes based on the snapshots that you created.
• If you want to allow the same traffic to reach the new instance, select the security group that is
associated with the original instance.
3. Install your application and any required software on the instance.
4. Restore any data that you backed up from the instance store volumes of the original instance.
5. If you are using an Elastic IP address, assign it to the newly launched instance as follows:
• On-Demand Instances – Pay, by the second, for the instances that you launch.
• Reserved Instances – Purchase, at a significant discount, instances that are always available, for a term
from one to three years.
• Scheduled Instances – Purchase instances that are always available on the specified recurring
schedule, for a one-year term.
• Spot Instances – Request unused EC2 instances, which can lower your Amazon EC2 costs significantly.
• Dedicated Hosts – Pay for a physical host that is fully dedicated to running your instances, and bring
your existing per-socket, per-core, or per-VM software licenses to reduce costs.
254
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Determining the Instance Lifecycle
• Dedicated Instances – Pay, by the hour, for instances that run on single-tenant hardware.
• Capacity Reservations – Reserve capacity for your EC2 instances in a specific Availability Zone for any
duration.
If you require a capacity reservation, purchase Reserved Instances or Capacity Reservations for a specific
Availability Zone, or purchase Scheduled Instances. Spot Instances are a cost-effective choice if you
can be flexible about when your applications run and if they can be interrupted. Dedicated Hosts or
Dedicated Instances can help you address compliance requirements and reduce costs by using your
existing server-bound software licenses. For more information, see Amazon EC2 Pricing.
Contents
• Determining the Instance Lifecycle (p. 255)
• Reserved Instances (p. 256)
• Scheduled Reserved Instances (p. 293)
• Spot Instances (p. 297)
• Dedicated Hosts (p. 359)
• Dedicated Instances (p. 377)
• On-Demand Capacity Reservations (p. 382)
If the instance is running on a Dedicated Host, the output contains the following information:
255
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
"Tenancy": "host"
If the instance is a Dedicated Instance, the output contains the following information:
"Tenancy": "dedicated"
If the instance is a Spot Instance, the output contains the following information:
"InstanceLifecycle": "spot"
If the instance is a Scheduled Instance, the output contains the following information:
"InstanceLifecycle": "scheduled"
Reserved Instances
Reserved Instances provide you with a significant discount compared to On-Demand Instance pricing.
Reserved Instances are not physical instances, but rather a billing discount applied to the use of On-
Demand Instances in your account. These On-Demand Instances must match certain attributes in order
to benefit from the billing discount.
The following diagram shows a basic overview of purchasing and using Reserved Instances.
In this scenario, you have a running On-Demand Instance (T2) in your account, for which you're currently
paying On-Demand rates. You purchase a Reserved Instance that matches the attributes of your running
instance, and the billing benefit is immediately applied. Next, you purchase a Reserved Instance for
a C4 instance. You do not have any running instances in your account that match the attributes of
this Reserved Instance. In the final step, you launch an instance that matches the attributes of the C4
Reserved Instance, and the billing benefit is immediately applied.
256
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
Instance Attributes
A Reserved Instance has four instance attributes that determine its price. The attributes also determine
how the Reserved Instance is applied to a running instance in your account.
• Instance type: For example, m4.large. This is composed of the instance family (m4) and the instance
size (large).
• Scope: Whether the Reserved Instance applies to a Region (regional Reserved Instance) or specific
Availability Zone (zonal Reserved Instance). For more information, see Regional and Zonal Reserved
Instances (Scope) (p. 258).
• Tenancy: Whether your instance runs on shared (default) or single-tenant (dedicated) hardware. For
more information, see Dedicated Instances (p. 377).
• Platform: The operating system; for example, Windows or Linux/Unix. For more information, see
Choosing a Platform (p. 269).
Reserved Instances do not renew automatically; when they expire, you can continue using the EC2
instance without interruption, but you are charged On-Demand rates. In the above example, when the
Reserved Instances that cover the T2 and C4 instances expire, you go back to paying the On-Demand
rates until you terminate the instances or purchase new Reserved Instances that match the instance
attributes.
Term Commitment
You can purchase a Reserved Instance for a one-year or three-year commitment, with the three-year
commitment offering a bigger discount.
Payment Options
The following payment options are available for Reserved Instances:
• All Upfront: Full payment is made at the start of the term, with no other costs or additional hourly
charges incurred for the remainder of the term, regardless of hours used.
• Partial Upfront: A portion of the cost must be paid upfront and the remaining hours in the term are
billed at a discounted hourly rate, regardless of whether the Reserved Instance is being used.
• No Upfront: You are billed a discounted hourly rate for every hour within the term, regardless of
whether the Reserved Instance is being used. No upfront payment is required.
Note
No Upfront Reserved Instances are based on a contractual obligation to pay monthly for the
entire term of the reservation. For this reason, a successful billing history is required before
you can purchase No Upfront Reserved Instances.
Generally speaking, you can save more money making a higher upfront payment for Reserved
Instances. You can also find Reserved Instances offered by third-party sellers at lower prices and shorter
term lengths on the Reserved Instance Marketplace. For more information, see Reserved Instance
Marketplace (p. 275).
257
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
Offering Class
If your computing needs change, you may be able to modify or exchange your Reserved Instance,
depending on the offering class.
• Standard: These provide the most significant discount, but can only be modified.
• Convertible: These provide a lower discount than Standard Reserved Instances, but can be exchanged
for another Convertible Reserved Instance with different instance attributes. Convertible Reserved
Instances can also be modified.
For more information, see Types of Reserved Instances (Offering Classes) (p. 259).
After you purchase a Reserved Instance, you cannot cancel your purchase. However, you may be able to
modify (p. 281), exchange (p. 289), or sell (p. 275) your Reserved Instance if your needs change.
For more information about pricing, see Amazon EC2 Reserved Instances Pricing.
For example, in a Region with three Availability Zones, the limit is 80 Reserved Instances per month:
20 regional Reserved Instances for the Region plus 20 zonal Reserved Instances for each of the three
Availability Zones (20x3=60).
A regional Reserved Instance applies a discount to a running On-Demand Instance. The default On-
Demand Instance limit is 20. You cannot exceed your running On-Demand Instance limit by purchasing
regional Reserved Instances. For example, if you already have 20 running On-Demand Instances, and you
purchase 20 regional Reserved Instances, the 20 regional Reserved Instances are used to apply a discount
to the 20 running On-Demand Instances. If you purchase more regional Reserved Instances, you will not
be able to launch more instances because you have reached your On-Demand Instance limit.
Note
Before purchasing regional Reserved Instances, make sure your On-Demand Instance limit
matches or exceeds the number of regional Reserved Instances you intend to own. If required,
make sure you request an increase to your On-Demand Instance limit before purchasing more
regional Reserved Instances.
A zonal Reserved Instance—a Reserved Instance that is purchased for a specific Availability Zone—
provides capacity reservation as well as a discount. You can exceed your running On-Demand Instance
limit by purchasing zonal Reserved Instances. For example, if you already have 20 running On-Demand
Instances, and you purchase 20 zonal Reserved Instances, you can launch a further 20 On-Demand
Instances that match the specifications of your zonal Reserved Instances, giving you a total of 40 running
instances.
The Amazon EC2 console provides limit information. For more information, see Viewing Your Current
Limits (p. 1005).
• Regional: When you purchase a Reserved Instance for a Region, it's referred to as a regional Reserved
Instance.
258
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
• Zonal: When you purchase a Reserved Instance for a specific Availability Zone, it's referred to as a
zonal Reserved Instance.
Availability Zone flexibility The Reserved Instance discount No Availability Zone flexibility—
applies to instance usage in any the Reserved Instance discount
Availability Zone in the specified applies to instance usage in the
Region. specified Availability Zone only.
Instance size flexibility The Reserved Instance discount No instance size flexibility—
applies to instance usage within the Reserved Instance discount
the instance family, regardless of applies to instance usage for the
size. Only supported on Amazon specified instance type and size
Linux/Unix Reserved Instances only.
with default tenancy. For more
information, see Instance
Size Flexibility Determined by
Normalization Factor (p. 260).
For more information and examples, see How Reserved Instances Are Applied (p. 260).
The following are the differences between Standard and Convertible offering classes.
Some attributes, such as instance size, can be Can be exchanged during the term for another
modified during the term; however, the instance Convertible Reserved Instance with new
family cannot be modified. You cannot exchange attributes including instance family, instance
a Standard Reserved Instance, only modify it. type, platform, scope, or tenancy. For more
For more information, see Modifying Reserved information, see Exchanging Convertible Reserved
Instances (p. 281). Instances (p. 289). You can also modify some
attributes of a Convertible Reserved Instance.
For more information, see Modifying Reserved
Instances (p. 281).
Can be sold in the Reserved Instance Marketplace. Cannot be sold in the Reserved Instance
Marketplace.
259
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
Standard and Convertible Reserved Instances can be purchased to apply to instances in a specific
Availability Zone (zonal Reserved Instances), or to instances in a Region (regional Reserved Instances). For
more information and examples, see How Reserved Instances Are Applied (p. 260).
If you want to purchase capacity reservations that recur on a daily, weekly, or monthly basis, a
Scheduled Reserved Instance may meet your needs. For more information, see Scheduled Reserved
Instances (p. 293).
Reserved Instances apply to usage in the same manner, irrespective of the offering type (Standard or
Convertible), and are automatically applied to running On-Demand Instances with matching attributes.
Regional Reserved Instances also provide instance size flexibility where the Reserved Instance discount
applies to instance usage within the instance family, regardless of size.
Instance size flexibility only applies to Reserved Instances that use the Amazon Linux/Unix platform with
default tenancy.
Instance size flexibility does not apply to the following Reserved Instances:
• Reserved Instances that are purchased for a specific Availability Zone (zonal Reserved Instances)
• Reserved Instances with dedicated tenancy
• Reserved Instances for Windows, Windows with SQL Standard, Windows with SQL Server Enterprise,
Windows with SQL Server Web, RHEL, and SLES
Instance size flexibility is determined by the normalization factor of the instance size. The discount
applies either fully or partially to running instances of the same instance family, depending on the
instance size of the reservation, in any Availability Zone in the Region. The only attributes that must be
matched are the instance family, tenancy, and platform.
Instance size flexibility is applied from the smallest to the largest instance size within the instance family
based on the normalization factor.
260
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
The following table lists the different sizes within an instance family, and the corresponding
normalization factor per hour. This scale is used to apply the discounted rate of Reserved Instances to
the normalized usage of the instance family.
nano 0.25
micro 0.5
small 1
medium 2
large 4
xlarge 8
2xlarge 16
3xlarge 24
4xlarge 32
6xlarge 48
8xlarge 64
9xlarge 72
10xlarge 80
12xlarge 96
16xlarge 128
18xlarge 144
24xlarge 192
32xlarge 256
For example, a t2.medium instance has a normalization factor of 2. If you purchase a t2.medium
default tenancy Amazon Linux/Unix Reserved Instance in the US East (N. Virginia) and you have two
running t2.small instances in your account in that Region, the billing benefit is applied in full to both
instances.
261
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
Or, if you have one t2.large instance running in your account in the US East (N. Virginia) Region, the
billing benefit is applied to 50% of the usage of the instance.
Note
The normalization factor is also applied when modifying Reserved Instances. For more
information, see Modifying Reserved Instances (p. 281).
Instance size flexibility also applies to bare metal instances within the instance family. If you have
regional Amazon Linux/Unix Reserved Instances with shared tenancy on bare metal instances, you can
benefit from the Reserved Instance savings within the same instance family. The opposite is also true: if
you have regional Amazon Linux/Unix Reserved Instances with shared tenancy on instances in the same
family as a bare metal instance, you can benefit from the Reserved Instance savings on the bare metal
instance.
A bare metal instance is the same size as the largest instance within the same instance family. For
example, an i3.metal is the same size as an i3.16xlarge, so they have the same normalization factor.
Note
The .metal instance sizes do not have a single normalization factor. They vary based on the
specific instance family.
262
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
c5.metal 192
i3.metal 128
r5.metal 192
r5d.metal 192
z1d.metal 96
m5.metal 192
m5d.metal 192
For example, an i3.metal instance has a normalization factor of 128. If you purchase an i3.metal
default tenancy Amazon Linux/Unix Reserved Instance in the US East (N. Virginia), the billing benefit can
apply as follows:
• If you have one running i3.16xlarge in your account in that Region, the billing benefit is applied in
full to the i3.16xlarge instance (i3.16xlarge normalization factor = 128).
• Or, if you have two running i3.8xlarge instances in your account in that Region, the billing benefit is
applied in full to both i3.8xlarge instances (i3.8xlarge normalization factor = 64).
• Or, if you have four running i3.4xlarge instances in your account in that Region, the billing benefit
is applied in full to all four i3.4xlarge instances (i3.4xlarge normalization factor = 32).
The opposite is also true. For example, if you purchase two i3.8xlarge default tenancy Amazon Linux/
Unix Reserved Instances in the US East (N. Virginia), and you have one running i3.metal instance in
that Region, the billing benefit is applied in full to the i3.metal instance.
• 4 x m3.large Linux, default tenancy Reserved Instances in Availability Zone us-east-1a (capacity is
reserved)
• 4 x m4.large Amazon Linux, default tenancy Reserved Instances in Region us-east-1
• 1 x c4.large Amazon Linux, default tenancy Reserved Instances in Region us-east-1
• The discount and capacity reservation of the four m3.large zonal Reserved Instances is used by the
four m3.large instances because the attributes (instance size, Region, platform, tenancy) between
them match.
263
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
• The m4.large regional Reserved Instances provide Availability Zone and instance size flexibility,
because they are regional Amazon Linux Reserved Instances with default tenancy.
You've purchased four m4.large regional Reserved Instances, and in total, they are equal to 16
normalized units/hour (4x4). Account A has two m4.xlarge instances running, which is equivalent to
16 normalized units/hour (2x8). In this case, the four m4.large regional Reserved Instances provide
the billing benefit to an entire hour of usage of the two m4.xlarge instances.
• The c4.large regional Reserved Instance in us-east-1 provides Availability Zone and instance size
flexibility, because it is a regional Amazon Linux Reserved Instance with default tenancy, and applies
to the c4.xlarge instance. A c4.large instance is equivalent to 4 normalized units/hour and a
c4.xlarge is equivalent to 8 normalized units/hour.
In this case, the c4.large regional Reserved Instance provides partial benefit to c4.xlarge usage.
This is because the c4.large Reserved Instance is equivalent to 4 normalized units/hour of usage,
but the c4.xlarge instance requires 8 normalized units/hour. Therefore, the c4.large Reserved
Instance billing discount applies to 50% of c4.xlarge usage. The remaining c4.xlarge usage is
charged at the On-Demand rate.
Reserved Instances are first applied to usage within the purchasing account, followed by qualifying usage
in any other account in the organization. For more information, see Reserved Instances and Consolidated
Billing (p. 267). For regional Reserved Instances that offer instance size flexibility, the benefit is applied
from the smallest to the largest instance size within the instance family.
You're running the following On-Demand Instances in account A (the purchasing account):
Another customer is running the following On-Demand Instances in account B—a linked account:
The regional Reserved Instance benefits are applied in the following way:
• The discount of the four m4.xlarge Reserved Instances is used by the two m4.xlarge instances
and the single m4.2xlarge instance in account A (purchasing account). All three instances match
the attributes (instance family, Region, platform, tenancy). The discount is applied to instances in the
purchasing account (account A) first, even though account B (linked account) has two m4.xlarge that
also match the Reserved Instances. There is no capacity reservation because the Reserved Instances are
regional Reserved Instances.
• The discount of the two c4.xlarge Reserved Instances applies to the two c4.xlarge instances,
because they are a smaller instance size than the c4.2xlarge instance. There is no capacity
reservation because the Reserved Instances are regional Reserved Instances.
264
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
In general, Reserved Instances that are owned by an account are applied first to usage in that account.
However, if there are qualifying, unused Reserved Instances for a specific Availability Zone (zonal
Reserved Instances) in other accounts in the organization, they are applied to the account before regional
Reserved Instances owned by the account. This is done to ensure maximum Reserved Instance utilization
and a lower bill. For billing purposes, all the accounts in the organization are treated as one account. The
following example may help explain this.
You're running the following On-Demand Instance in account A (the purchasing account):
A customer also purchases the following zonal Reserved Instances in linked account C:
• The discount of the m4.xlarge zonal Reserved Instance owned by account C is applied to the
m4.xlarge usage in account A.
• The discount of the m4.xlarge regional Reserved Instance owned by account A is applied to the
m4.xlarge usage in account B.
• If the regional Reserved Instance owned by account A was first applied to the usage in account A, the
zonal Reserved Instance owned by account C remains unused and usage in account B is charged at On-
Demand rates.
For more information, see Reserved Instances in the Billing and Cost Management Report.
When Reserved Instances expire, you are charged On-Demand rates for EC2 instance usage. You can set
up a billing alert to warn you when your bill exceeds a threshold you define. For more information, see
Monitoring Charges with Alerts and Notifications in the AWS Billing and Cost Management User Guide.
Note
The AWS Free Tier is available for new AWS accounts. If you are using the AWS Free Tier to run
Amazon EC2 instances, and you purchase a Reserved Instance, you are charged under standard
pricing guidelines. For information, see AWS Free Tier.
Contents
• Usage Billing (p. 266)
265
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
Usage Billing
Reserved Instances are billed for every clock-hour during the term that you select, regardless of whether
an instance is running. Each clock-hour starts on the hour (zero minutes and zero seconds past the hour)
of a standard 24-hour clock. For example, 1:00:00 to 1:59:59 is one clock-hour. For more information
about instance states, see Instance Lifecycle (p. 390).
A Reserved Instance billing benefit is applied to a running instance on a per-second basis. A Reserved
Instance billing benefit can apply to a maximum of 3600 seconds (one hour) of instance usage per clock-
hour. You can run multiple instances concurrently, but can only receive the benefit of the Reserved
Instance discount for a total of 3600 seconds per clock-hour; instance usage that exceeds 3600 seconds
in a clock-hour is billed at the On-Demand rate.
For example, if you purchase one m4.xlarge Reserved Instance and run four m4.xlarge instances
concurrently for one hour, one instance is charged at one hour of Reserved Instance usage and the other
three instances are charged at three hours of On-Demand usage.
However, if you purchase one m4.xlarge Reserved Instance and run four m4.xlarge instances for 15
minutes (900 seconds) each within the same hour, the total running time for the instances is one hour,
which results in one hour of Reserved Instance usage and 0 hours of On-Demand usage.
If multiple eligible instances are running concurrently, the Reserved Instance billing benefit is applied
to all the instances at the same time up to a maximum of 3600 seconds in a clock-hour; thereafter, On-
Demand rates apply.
Cost Explorer on the Billing and Cost Management console enables you to analyze the savings against
running On-Demand Instances. The Reserved Instances FAQ includes an example of a list value
calculation.
If you close your AWS account, On-Demand billing for your resources stops. However, if you have any
Reserved Instances in your account, you continue to receive a bill for these until they expire.
266
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
You can view the charges online, or you can download a CSV file.
You can also track your Reserved Instance utilization using the AWS Cost and Usage Report. For
more information, see Reserved Instances under Cost and Usage Report in the AWS Billing and Cost
Management User Guide.
If you close the payer account, any member accounts that benefit from Reserved Instances billing
discounts continue to benefit from the discount until the Reserved Instances expire, or until the member
account is removed.
• Pricing tiers and related discounts apply only to purchases of Amazon EC2 Standard Reserved
Instances.
• Pricing tiers do not apply to Reserved Instances for Windows with SQL Server Standard, SQL Server
Web, and SQL Server Enterprise.
• Pricing tiers do not apply to Reserved Instances for Linux with SQL Server Standard, SQL Server Web,
and SQL Server Enterprise.
• Pricing tier discounts only apply to purchases made from AWS. They do not apply to purchases of
third-party Reserved Instances.
• Discount pricing tiers are currently not applicable to Convertible Reserved Instance purchases.
Topics
• Calculating Reserved Instance Pricing Discounts (p. 267)
• Buying with a Discount Tier (p. 268)
• Crossing Pricing Tiers (p. 269)
• Consolidated Billing for Pricing Tiers (p. 269)
You can determine the pricing tier for your account by calculating the list value for all of your Reserved
Instances in a Region. Multiply the hourly recurring price for each reservation by the total number of
hours for the term and add the undiscounted upfront price (also known as the fixed price) listed on the
267
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
Reserved Instances pricing page at the time of purchase. Because the list value is based on undiscounted
(public) pricing, it is not affected if you qualify for a volume discount or if the price drops after you buy
your Reserved Instances.
List value = fixed price + (undiscounted recurring hourly price * hours in term)
For example, for a 1-year Partial Upfront t2.small Reserved Instance, assume the upfront price is
$60.00 and the hourly rate is $0.007. This provides a list value of $121.32.
To view the fixed price values for Reserved Instances using the Amazon EC2 console
To view the fixed price values for Reserved Instances using the command line
When you buy Reserved Instances, Amazon EC2 automatically applies any discounts to the part of your
purchase that falls within a discount pricing tier. You don't need to do anything differently, and you can
buy Reserved Instances using any of the Amazon EC2 tools. For more information, see Buying Reserved
Instances (p. 269).
After the list value of your active Reserved Instances in a Region crosses into a discount pricing tier,
any future purchase of Reserved Instances in that Region are charged at a discounted rate. If a single
purchase of Reserved Instances in a Region takes you over the threshold of a discount tier, then the
portion of the purchase that is above the price threshold is charged at the discounted rate. For more
information about the temporary Reserved Instance IDs that are created during the purchase process,
see Crossing Pricing Tiers (p. 269).
If your list value falls below the price point for that discount pricing tier—for example, if some of your
Reserved Instances expire—future purchases of Reserved Instances in the Region are not discounted.
However, you continue to get the discount applied against any Reserved Instances that were originally
purchased within the discount pricing tier.
When you buy Reserved Instances, one of four possible scenarios occurs:
268
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
If your purchase crosses into a discounted pricing tier, you see multiple entries for that purchase: one for
that part of the purchase charged at the regular price, and another for that part of the purchase charged
at the applicable discounted rate.
The Reserved Instance service generates several Reserved Instance IDs because your purchase crossed
from an undiscounted tier, or from one discounted tier to another. There is an ID for each set of
reservations in a tier. Consequently, the ID returned by your purchase CLI command or API action is
different from the actual ID of the new Reserved Instances.
A consolidated billing account aggregates the list value of member accounts within a Region. When
the list value of all active Reserved Instances for the consolidated billing account reaches a discount
pricing tier, any Reserved Instances purchased after this point by any member of the consolidated
billing account are charged at the discounted rate (as long as the list value for that consolidated account
stays above the discount pricing tier threshold). For more information, see Reserved Instances and
Consolidated Billing (p. 267).
When you search for Reserved Instances to buy, you receive a quote on the cost of the returned offerings.
When you proceed with the purchase, AWS automatically places a limit price on the purchase price. The
total cost of your Reserved Instances won't exceed the amount that you were quoted.
If the price rises or changes for any reason, the purchase is not completed. If, at the time of purchase,
there are offerings similar to your choice but at a lower price, AWS sells you the offerings at the lower
price.
Before you confirm your purchase, review the details of the Reserved Instance that you plan to buy, and
make sure that all the parameters are accurate. After you purchase a Reserved Instance (either from a
third-party seller in the Reserved Instance Marketplace or from AWS), you cannot cancel your purchase.
Note
To purchase and modify Reserved Instances, ensure that your IAM user account has the
appropriate permissions, such as the ability to describe Availability Zones. For information,
see Example Policies for Working With the AWS CLI or an AWS SDK and Example Policies for
Working in the Amazon EC2 Console.
Tasks
• Choosing a Platform (p. 269)
• Buying Standard Reserved Instances (p. 270)
• Buying Convertible Reserved Instances (p. 272)
• Viewing Your Reserved Instances (p. 274)
• Using Your Reserved Instances (p. 275)
Choosing a Platform
When you purchase a Reserved Instance, you must choose an offering for a platform that represents the
operating system for your instance.
For SUSE Linux and RHEL distributions, you must choose offerings for those specific platforms. For all
other Linux distributions (including Ubuntu), choose an offering for the Linux/UNIX platform.
269
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
Note
If the status goes to retired, AWS may not have received your payment.
{
"ReservedInstancesOfferings": [
{
"OfferingClass": "standard",
"OfferingType": "No Upfront",
"ProductDescription": "Linux/UNIX",
"InstanceTenancy": "default",
"PricingDetails": [],
"UsagePrice": 0.0,
"RecurringCharges": [
270
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
{
"Amount": 0.0672,
"Frequency": "Hourly"
}
],
"Marketplace": false,
"CurrencyCode": "USD",
"FixedPrice": 0.0,
"Duration": 31536000,
"Scope": "Region",
"ReservedInstancesOfferingId": "bec624df-a8cc-4aad-a72f-4f8abc34caf2",
"InstanceType": "t2.large"
},
{
"OfferingClass": "standard",
"OfferingType": "Partial Upfront",
"ProductDescription": "Linux/UNIX",
"InstanceTenancy": "default",
"PricingDetails": [],
"UsagePrice": 0.0,
"RecurringCharges": [
{
"Amount": 0.032,
"Frequency": "Hourly"
}
],
"Marketplace": false,
"CurrencyCode": "USD",
"FixedPrice": 280.0,
"Duration": 31536000,
"Scope": "Region",
"ReservedInstancesOfferingId": "6b15a842-3acb-4320-bd55-fa43a79f3fe3",
"InstanceType": "t2.large"
},
{
"OfferingClass": "standard",
"OfferingType": "All Upfront",
"ProductDescription": "Linux/UNIX",
"InstanceTenancy": "default",
"PricingDetails": [],
"UsagePrice": 0.0,
"RecurringCharges": [],
"Marketplace": false,
"CurrencyCode": "USD",
"FixedPrice": 549.0,
"Duration": 31536000,
"Scope": "Region",
"ReservedInstancesOfferingId": "5062dc97-d284-417b-b09e-8abed1e5a183",
"InstanceType": "t2.large"
}
]
}
To find Reserved Instances on the Reserved Instance Marketplace only, use the marketplace filter
and do not specify a duration in the request, as the term may be shorter than a 1– or 3-year term.
When you find a Reserved Instance that meets your needs, take note of the
ReservedInstancesOfferingId.
271
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
2. Use the purchase-reserved-instances-offering command to buy your Reserved Instance. You must
specify the Reserved Instance offering ID you obtained the previous step and you must specify the
number of instances for the reservation.
3. Use the describe-reserved-instances command to get the status of your Reserved Instance.
Alternatively, use the following AWS Tools for Windows PowerShell commands:
• Get-EC2ReservedInstancesOffering
• New-EC2ReservedInstance
• Get-EC2ReservedInstance
If you already have a running instance that matches the specifications of the Reserved Instance, the
billing benefit is immediately applied. You do not have to restart your instances. If you do not have
a suitable running instance, launch an instance and ensure that you match the same criteria that you
specified for your Reserved Instance. For more information, see Using Your Reserved Instances (p. 275).
For examples of how Reserved Instances are applied to your running instances, see How Reserved
Instances Are Applied (p. 260).
Note
If the status goes to retired, AWS may not have received your payment.
272
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
{
"ReservedInstancesOfferings": [
{
"OfferingClass": "convertible",
"OfferingType": "No Upfront",
"ProductDescription": "Linux/UNIX",
"InstanceTenancy": "default",
"PricingDetails": [],
"UsagePrice": 0.0,
"RecurringCharges": [
{
"Amount": 0.0556,
"Frequency": "Hourly"
}
],
"Marketplace": false,
"CurrencyCode": "USD",
"FixedPrice": 0.0,
"Duration": 94608000,
"Scope": "Region",
"ReservedInstancesOfferingId": "e242e87b-b75c-4079-8e87-02d53f145204",
"InstanceType": "t2.large"
},
{
"OfferingClass": "convertible",
"OfferingType": "Partial Upfront",
"ProductDescription": "Linux/UNIX",
"InstanceTenancy": "default",
"PricingDetails": [],
"UsagePrice": 0.0,
"RecurringCharges": [
{
"Amount": 0.0258,
"Frequency": "Hourly"
}
],
"Marketplace": false,
"CurrencyCode": "USD",
"FixedPrice": 677.0,
"Duration": 94608000,
"Scope": "Region",
"ReservedInstancesOfferingId": "13486b92-bdd6-4b68-894c-509bcf239ccd",
"InstanceType": "t2.large"
},
{
"OfferingClass": "convertible",
"OfferingType": "All Upfront",
"ProductDescription": "Linux/UNIX",
"InstanceTenancy": "default",
"PricingDetails": [],
"UsagePrice": 0.0,
"RecurringCharges": [],
273
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
"Marketplace": false,
"CurrencyCode": "USD",
"FixedPrice": 1327.0,
"Duration": 94608000,
"Scope": "Region",
"ReservedInstancesOfferingId": "e00ec34b-4674-4fb9-a0a9-213296ab93aa",
"InstanceType": "t2.large"
}
]
}
When you find a Reserved Instance that meets your needs, take note of the
ReservedInstancesOfferingId.
2. Use the purchase-reserved-instances-offering command to buy your Reserved Instance. You must
specify the Reserved Instance offering ID you obtained the previous step and you must specify the
number of instances for the reservation.
3. Use the describe-reserved-instances command to get the status of your Reserved Instance.
Alternatively, use the following AWS Tools for Windows PowerShell commands:
• Get-EC2ReservedInstancesOffering
• New-EC2ReservedInstance
• Get-EC2ReservedInstance
If you already have a running instance that matches the specifications of the Reserved Instance, the
billing benefit is immediately applied. You do not have to restart your instances. If you do not have
a suitable running instance, launch an instance and ensure that you match the same criteria that you
specified for your Reserved Instance. For more information, see Using Your Reserved Instances (p. 275).
For examples of how Reserved Instances are applied to your running instances, see How Reserved
Instances Are Applied (p. 260).
274
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
If you're launching an instance to take advantage of the billing benefit of a Reserved Instance, ensure
that you specify the following information during launch:
• Platform: You must choose an Amazon Machine Image (AMI) that matches the platform (product
description) of your Reserved Instance. For example, if you specified Linux/UNIX, you can launch an
instance from an Amazon Linux AMI or an Ubuntu AMI.
• Instance type: Specify the same instance type as your Reserved Instance; for example, t2.large.
• Availability Zone: If you purchased a Reserved Instance for a specific Availability Zone, you must launch
the instance into the same Availability Zone. If you purchased a regional Reserved Instance, you can
launch your instance into any Availability Zone.
• Tenancy: The tenancy of your instance must match the tenancy of the Reserved Instance; for example,
dedicated or shared. For more information, see Dedicated Instances (p. 377).
For more information, see Launching an Instance Using the Launch Instance Wizard (p. 395). For
examples of how Reserved Instances are applied to your running instances, see How Reserved Instances
Are Applied (p. 260).
You can use Amazon EC2 Auto Scaling or other AWS services to launch the On-Demand Instances that
use your Reserved Instance benefits. For more information, see the Amazon EC2 Auto Scaling User Guide.
If you want to sell your unused Reserved Instances on the Reserved Instance Marketplace, you must meet
certain eligibility criteria.
Contents
• Selling on the Reserved Instance Marketplace (p. 275)
• Buying from the Reserved Instance Marketplace (p. 281)
To fulfill a buyer's request, AWS first sells the Reserved Instance with the lowest upfront price in the
specified grouping. Then, we sell the Reserved Instance with the next lowest price, until the buyer's
entire order is fulfilled. AWS then processes the transactions and transfers ownership of the Reserved
Instances to the buyer.
275
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
You own your Reserved Instance until it's sold. After the sale, you've given up the capacity reservation
and the discounted recurring fees. If you continue to use your instance, AWS charges you the On-
Demand price starting from the time that your Reserved Instance was sold.
Contents
• Restrictions and Limitations (p. 276)
• Registering as a Seller (p. 276)
• Bank Account for Disbursement (p. 277)
• Tax Information (p. 277)
• Pricing Your Reserved Instances (p. 278)
• Listing Your Reserved Instances (p. 278)
• Reserved Instance Listing States (p. 279)
• Lifecycle of a Listing (p. 279)
• After Your Reserved Instance Is Sold (p. 280)
• Getting Paid (p. 280)
• Information Shared with the Buyer (p. 280)
The following limitations and restrictions apply when selling Reserved Instances:
• Only Amazon EC2 Standard Reserved Instances can be sold in the Reserved Instance Marketplace.
Convertible Reserved Instances cannot be sold. There must be at least one month remaining in the
term of the Standard Reserved Instance.
• The minimum price allowed in the Reserved Instance Marketplace is $0.00.
• You can sell No Upfront, Partial Upfront, or All Upfront Reserved Instances in the Reserved Instance
Marketplace. If there is an upfront payment on a Reserved Instance, it can be sold only after AWS has
received the upfront payment and the reservation has been active (you've owned it) for at least 30
days.
• You cannot modify your listing in the Reserved Instance Marketplace directly. However, you can
change your listing by first canceling it and then creating another listing with new parameters. For
information, see Pricing Your Reserved Instances (p. 278). You can also modify your Reserved
Instances before listing them. For information, see Modifying Reserved Instances (p. 281).
• AWS charges a service fee of 12 percent of the total upfront price of each Standard Reserved Instance
you sell in the Reserved Instance Marketplace. The upfront price is the price the seller is charging for
the Standard Reserved Instance.
• Only Amazon EC2 Standard Reserved Instances can be sold in the Reserved Instance Marketplace.
Other AWS Reserved Instances, such as Amazon RDS and Amazon ElastiCache Reserved Instances
cannot be sold in the Reserved Instance Marketplace.
Registering as a Seller
To sell in the Reserved Instance Marketplace, you must first register as a seller. During registration, you
provide the following information:
• Bank information—AWS must have your bank information in order to disburse funds collected when
you sell your reservations. The bank you specify must have a US address. For more information, see
Bank Account for Disbursement (p. 277).
• Tax information—All sellers are required to complete a tax information interview to determine any
necessary tax reporting obligations. For more information, see Tax Information (p. 277).
276
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
After AWS receives your completed seller registration, you receive an email confirming your registration
and informing you that you can get started selling in the Reserved Instance Marketplace.
1. Open the Reserved Instance Marketplace Seller Registration page and sign in using your AWS
credentials.
2. On the Manage Bank Account page, provide the following information about the bank through to
receive payment:
Note
If you are using a corporate bank account, you are prompted to send the information about
the bank account via fax (1-206-765-3424).
After registration, the bank account provided is set as the default, pending verification with the
bank. It can take up to two weeks to verify a new bank account, during which time you can't receive
disbursements. For an established account, it usually takes about two days for disbursements to
complete.
1. On the Reserved Instance Marketplace Seller Registration page, sign in with the account that you
used when you registered.
2. On the Manage Bank Account page, add a new bank account or modify the default bank account as
needed.
Tax Information
Your sale of Reserved Instances might be subject to a transaction-based tax, such as sales tax or value-
added tax. You should check with your business's tax, legal, finance, or accounting department to
determine if transaction-based taxes are applicable. You are responsible for collecting and sending the
transaction-based taxes to the appropriate tax authority.
As part of the seller registration process, you must complete a tax interview in the Seller Registration
Portal. The interview collects your tax information and populates an IRS form W-9, W-8BEN, or W-8BEN-
E, which is used to determine any necessary tax reporting obligations.
The tax information you enter as part of the tax interview might differ depending on whether you
operate as an individual or business, and whether you or your business are a US or non-US person or
entity. As you fill out the tax interview, keep in mind the following:
• Information provided by AWS, including the information in this topic, does not constitute tax, legal, or
other professional advice. To find out how the IRS reporting requirements might affect your business,
or if you have other questions, contact your tax, legal, or other professional advisor.
• To fulfill the IRS reporting requirements as efficiently as possible, answer all questions and enter all
information requested during the interview.
277
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
• Check your answers. Avoid misspellings or entering incorrect tax identification numbers. They can
result in an invalidated tax form.
Based on your tax interview responses and IRS reporting thresholds, Amazon may file Form 1099-K.
Amazon mails a copy of your Form 1099-K on or before January 31 in the year following the year that
your tax account reaches the threshold levels. For example, if your account reaches the threshold in
2018, your Form 1099-K is mailed on or before January 31, 2019.
For more information about IRS requirements and Form 1099-K, see the IRS website.
The upfront fee is the only fee that you can specify for the Reserved Instance that you're selling. The
upfront fee is the one-time fee that the buyer pays when they purchase a Reserved Instance. You cannot
specify the usage fee or the recurring fee; The buyer pays the same usage or recurring fees that were set
when the reservations were originally purchased.
• You can sell up to $50,000 in Reserved Instances per year. To sell more, complete the Request to
Raise Sales Limit on Amazon EC2 Reserved Instances form.
• The minimum price is $0. The minimum allowed price in the Reserved Instance Marketplace is $0.00.
You cannot modify your listing directly. However, you can change your listing by first canceling it and
then creating another listing with new parameters.
You can cancel your listing at any time, as long as it's in the activestate. You cannot cancel the listing
if it's already matched or being processed for a sale. If some of the instances in your listing are matched
and you cancel the listing, only the remaining unmatched instances are removed from the listing.
Because the value of Reserved Instances decreases over time, by default, AWS can set prices to decrease
in equal increments month over month. However, you can set different upfront prices based on when
your reservation sells.
For example, if your Reserved Instance has nine months of its term remaining, you can specify the
amount that you would accept if a customer were to purchase that Reserved Instance with nine months
remaining. You could set another price with five months remaining, and yet another price with one
month remaining.
As a registered seller, you can choose to sell one or more of your Reserved Instances. You can choose
to sell all of them in one listing or in portions. In addition, you can list Reserved Instances with any
configuration of instance type, platform, and scope.
If you cancel your listing and a portion of that listing has already been sold, the cancellation is not
effective on the portion that has been sold. Only the unsold portion of the listing is no longer available
in the Reserved Instance Marketplace.
To list a Reserved Instance in the Reserved Instance Marketplace using the AWS Management
Console
278
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
changes over the remainder of the term by selecting the arrow next to the Months Remaining
column.
5. If you are an advanced user and you want to customize the pricing, you can enter different values for
the subsequent months. To return to the default linear price drop, choose Reset.
6. Choose Continue when you are finished configuring your listing.
7. Confirm the details of your listing, on the Confirm Your Reserved Instance Listing page and if
you're satisfied, choose List Reserved Instance.
To manage Reserved Instances in the Reserved Instance Marketplace using the AWS CLI
The information displayed by Listing State is about the status of your listing in the Reserved Instance
Marketplace. It is different from the status information that is displayed by the State column in the
Reserved Instances page. This State information is about your reservation.
Lifecycle of a Listing
When all the instances in your listing are matched and sold, the My Listings tab shows that the Total
instance count matches the count listed under Sold. Also, there are no Available instances left for your
listing, and its Status is closed.
When only a portion of your listing is sold, AWS retires the Reserved Instances in the listing and creates
the number of Reserved Instances equal to the Reserved Instances remaining in the count. So, the listing
ID and the listing that it represents, which now has fewer reservations for sale, is still active.
Any future sales of Reserved Instances in this listing are processed this way. When all the Reserved
Instances in the listing are sold, AWS marks the listing as closed.
The My Listings tab in the Reserved Instance console page displays the listing this way:
279
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
A buyer purchases two of the reservations, which leaves a count of three reservations still available for
sale. Because of this partial sale, AWS creates a new reservation with a count of three to represent the
remaining reservations that are still for sale.
If you cancel your listing and a portion of that listing has already sold, the cancelation is not effective
on the portion that has been sold. Only the unsold portion of the listing is no longer available in the
Reserved Instance Marketplace.
When your Reserved Instance is sold, AWS sends you an email notification. Each day that there is any
kind of activity, you receive one email notification capturing all the activities of the day. For example, you
create or sell a listing, or AWS sends funds to your account.
To track the status of a Reserved Instance listing in the console, choose Reserved Instance, My Listings.
The My Listings tab contains the Listing State value. It also contains information about the term, listing
price, and a breakdown of how many instances in the listing are available, pending, sold, and canceled.
You can also use the describe-reserved-instances-listings command with the appropriate filter to obtain
information about your listings.
Getting Paid
As soon as AWS receives funds from the buyer, a message is sent to the registered owner account email
for the sold Reserved Instance.
AWS sends an Automated Clearing House (ACH) wire transfer to your specified bank account.
Typically, this transfer occurs between one to three days after your Reserved Instance has been sold.
Disbursements take place once a day. You will receive an email with a disbursement report after the
funds are released. Keep in mind that you can't receive disbursements until AWS receives verification
from your bank. This can take up to two weeks.
The Reserved Instance that you sold continues to appear when you describe your Reserved Instances.
You receive a cash disbursement for your Reserved Instances through a wire transfer directly into your
bank account. AWS charges a service fee of 12 percent of the total upfront price of each Reserved
Instance you sell in the Reserved Instance Marketplace.
When you sell in the Reserved Instance Marketplace, AWS shares your company’s legal name on the
buyer’s statement in accordance with US regulations. In addition, if the buyer calls AWS Support because
280
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
the buyer needs to contact you for an invoice or for some other tax-related reason, AWS may need to
provide the buyer with your email address so that the buyer can contact you directly.
For similar reasons, the buyer's ZIP code and country information are provided to the seller in the
disbursement report. As a seller, you might need this information to accompany any necessary
transaction taxes that you remit to the government (such as sales tax and value-added tax).
AWS cannot offer tax advice, but if your tax specialist determines that you need specific additional
information, contact AWS Support.
There are a few differences between Reserved Instances purchased in the Reserved Instance Marketplace
and Reserved Instances purchased directly from AWS:
• Term—Reserved Instances that you purchase from third-party sellers have less than a full standard
term remaining. Full standard terms from AWS run for one year or three years.
• Upfront price—Third-party Reserved Instances can be sold at different upfront prices. The usage or
recurring fees remain the same as the fees set when the Reserved Instances were originally purchased
from AWS.
• Types of Reserved Instances—Only Amazon EC2 Standard Reserved Instances can be purchased
from the Reserved Instance Marketplace. Convertible Reserved Instances, Amazon RDS and Amazon
ElastiCache Reserved Instances are not available for purchase on the Reserved Instance Marketplace.
Basic information about you is shared with the seller, for example, your ZIP code and country
information.
This information enables sellers to calculate any necessary transaction taxes that they have to remit to
the government (such as sales tax or value-added tax) and is provided as a disbursement report. In rare
circumstances, AWS might have to provide the seller with your email address, so that they can contact
you regarding questions related to the sale (for example, tax questions).
For similar reasons, AWS shares the legal entity name of the seller on the buyer's purchase invoice. If you
need additional information about the seller for tax or related reasons, contact AWS Support.
You can modify all or a subset of your Reserved Instances. You can separate your original Reserved
Instances into two or more new Reserved Instances. For example, if you have a reservation for 10
instances in us-east-1a and decide to move 5 instances to us-east-1b, the modification request
results in two new reservations: one for 5 instances in us-east-1a and the other for 5 instances in us-
east-1b.
281
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
You can also merge two or more Reserved Instances into a single Reserved Instance. For example, if
you have four t2.small Reserved Instances of one instance each, you can merge them to create one
t2.large Reserved Instance. For more information, see Support For Modifying Instance Sizes (p. 283).
After modification, the benefit of the Reserved Instances is applied only to instances that match the new
parameters. For example, if you change the Availability Zone of a reservation, the capacity reservation
and pricing benefits are automatically applied to instance usage in the new Availability Zone. Instances
that no longer match the new parameters are charged at the On-Demand rate unless your account has
other applicable reservations.
• The modified reservation becomes effective immediately and the pricing benefit is applied to the new
instances beginning at the hour of the modification request. For example, if you successfully modify
your reservations at 9:15PM, the pricing benefit transfers to your new instance at 9:00PM. (You can get
the effective date of the modified Reserved Instances by using the DescribeReservedInstances API
action or the describe-reserved-instances command (AWS CLI).
• The original reservation is retired. Its end date is the start date of the new reservation, and the end
date of the new reservation is the same as the end date of the original Reserved Instance. If you
modify a three-year reservation that had 16 months left in its term, the resulting modified reservation
is a 16-month reservation with the same end date as the original one.
• The modified reservation lists a $0 fixed price and not the fixed price of the original reservation.
Note
The fixed price of the modified reservation does not affect the discount pricing tier calculations
applied to your account, which are based on the fixed price of the original reservation.
If your modification request fails, your Reserved Instances maintain their original configuration, and are
immediately available for another modification request.
There is no fee for modification, and you do not receive any new bills or invoices.
You can modify your reservations as frequently as you like, but you cannot change or cancel a pending
modification request after you submit it. After the modification has completed successfully, you can
submit another modification request to roll back any changes you made, if needed.
Topics
• Requirements and Restrictions for Modification (p. 282)
• Support For Modifying Instance Sizes (p. 283)
• Submitting Modification Requests (p. 287)
• Troubleshooting Modification Requests (p. 288)
Change the scope from Linux and Windows If you change the scope from
Availability Zone to Region and Availability Zone to Region, you
vice versa lose the capacity reservation
benefit.
282
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
Change the instance size within Linux only The reservation must use Linux
the same instance family and default tenancy. You cannot
use Red Hat Enterprise Linux or
SUSE.
Change the network from EC2- Linux and Windows The network platform must be
Classic to Amazon VPC and vice available in your AWS account.
versa If you created your AWS account
after 2013-12-04, it does not
support EC2-Classic.
Requirements
Amazon EC2 processes your modification request if there is sufficient capacity for your target
configuration (if applicable), and if the following conditions are met:
• The Reserved Instance cannot be modified before or at the same time that you purchase it
• The Reserved Instance must be active
• There cannot be a pending modification request
• The Reserved Instance is not listed in the Reserved Instance Marketplace
• There must be a match between the instance size footprint of the active reservation and the target
configuration. For more information, see Support For Modifying Instance Sizes (p. 283).
• The input Reserved Instances are all Standard Reserved Instances or all Convertible Reserved
Instances, not some of each type
• The input Reserved Instances must expire within the same hour, if they are Standard Reserved
Instances
283
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
You cannot modify the instance size of the Reserved Instances for the following instance types, because
only one size is available for each of the instance families.
• cc2.8xlarge
• cr1.8xlarge
• hs1.8xlarge
• t1.micro
Each Reserved Instance has an instance size footprint, which is determined by the normalization factor of
the instance type and the number of instances in the reservation. When you modify a Reserved Instance,
the footprint of the target configuration must match that of the original configuration, otherwise the
modification request is not processed.
The normalization factor is based on instance size within the instance family (for example, m1.xlarge
instances within the m1 instance family). This is only meaningful within the same instance family.
Instance types cannot be modified from one family to another. In the Amazon EC2 console, the
normalization factor is measured in units. The following table illustrates the normalization factor that
applies within an instance family.
nano 0.25
micro 0.5
small 1
medium 2
large 4
xlarge 8
2xlarge 16
4xlarge 32
8xlarge 64
9xlarge 72
10xlarge 80
12xlarge 96
16xlarge 128
18xlarge 144
24xlarge 192
32xlarge 256
To calculate the instance size footprint of a Reserved Instance, multiply the number of instances by the
normalization factor. For example, a t2.medium has a normalization factor of 2 so a reservation for four
t2.medium instances has a footprint of 8 units.
284
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
You can allocate your reservations into different instance sizes across the same instance family, for
example, across the T2 instance family, as long as the instance size footprint of your reservation
remains the same. For example, you can divide a reservation for one t2.large (1 x 4) instance into four
t2.small (4 x 1) instances, or you can combine a reservation for four t2.small instances into one
t2.large instance. However, you cannot change your reservation for two t2.small (2 x 1) instances
into one t2.large (1 x 4) instance. This is because the existing instance size footprint of your current
reservation is smaller than the proposed reservation.
In the following example, you have a reservation with two t2.micro instances (giving you a footprint
of 1) and a reservation with one t2.small instance (giving you a footprint of 1). You merge both
reservations to a single reservation with one t2.medium instance—the combined instance size footprint
of the two original reservations equals the footprint of the modified reservation.
You can also modify a reservation to divide it into two or more reservations. In the following example,
you have a reservation with a t2.medium instance. You divide the reservation into a reservation with
two t2.nano instances and a reservation with three t2.micro instances.
285
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
You can modify .metal Reserved Instances into other sizes within the same family, and, similarly, you
can modify other sized Reserved Instances in the same family into .metal Reserved Instances. A bare
metal instance is the same size as the largest instance within the same instance family. For example, an
i3.metal is the same size as an i3.16xlarge, so they have the same normalization factor.
Note
The .metal instance sizes do not have a single normalization factor. They vary based on the
specific instance family.
c5.metal 192
i3.metal 128
r5.metal 192
r5d.metal 192
z1d.metal 96
m5.metal 192
m5d.metal 192
For example, an i3.metal instance has a normalization factor of 128. If you purchase an i3.metal
default tenancy Amazon Linux/Unix Reserved Instance, you can divide the reservation as follows:
• An i3.16xlarge is the same size as an i3.metal instance, so its normalization factor is 128 (128/1).
The reservation for one i3.metal instance can be modified into one i3.16xlarge instance.
• An i3.8xlarge is half the size of an i3.metal instance, so its normalization factor is 64 (128/2). The
reservation for one i3.metal instance can be divided into two i3.8xlarge instances.
286
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
• Scope: Choose whether the Reserved Instance applies to an Availability Zone or to the whole
Region.
• Availability Zone: Choose the required Availability Zone. Not applicable for regional Reserved
Instances.
• Instance Type: Select the required instance type. Only available for supported platforms. For
more information, see Requirements and Restrictions for Modification (p. 282).
• Count: Specify the number of instances to be covered by the reservation.
Note
If your combined target configurations are larger or smaller than the instance size footprint
of your original Reserved Instances, the allocated total in the Units column displays in red.
4. To confirm your modification choices when you finish specifying your target configurations, choose
Submit Modifications. If you change your mind at any point, choose Cancel to exit the wizard.
You can determine the status of your modification request by looking at the State column in the
Reserved Instances screen. The following table illustrates the possible State values.
State Description
287
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
State Description
-Or-
To modify your Reserved Instances, you can use one of the following:
In some situations, you might get a message indicating incomplete or failed modification requests
instead of a confirmation. Use the information in such messages as a starting point for resubmitting
another modification request. Ensure that you have read the applicable restrictions (p. 282) before
submitting the request.
Amazon EC2 identifies and lists the Reserved Instances that cannot be modified. If you receive a message
like this, go to the Reserved Instances page in the Amazon EC2 console and check the information for
the Reserved Instances.
You submitted one or more Reserved Instances for modification and none of your requests can be
processed. Depending on the number of reservations you are modifying, you can get different versions of
the message.
Amazon EC2 displays the reasons why your request cannot be processed. For example, you might have
specified the same target configuration—a combination of Availability Zone and platform—for one or
more subsets of the Reserved Instances you are modifying. Try submitting the modification requests
again, but ensure that the instance details of the reservations match, and that the target configurations
for all subsets being modified are unique.
288
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
When you exchange your Convertible Reserved Instance, the number of instances for your current
reservation is exchanged for a number of instances that cover the equal or higher value of the
configuration of the target Convertible Reserved Instance. Amazon EC2 calculates the number of
Reserved Instances that you can receive as a result of the exchange.
Contents
• Requirements for Exchanging Convertible Reserved Instances (p. 289)
• Calculating Convertible Reserved Instances Exchanges (p. 290)
• Merging Convertible Reserved Instances (p. 290)
• Exchanging a Portion of a Convertible Reserved Instance (p. 291)
• Submitting Exchange Requests (p. 292)
• Active
• Not pending a previous exchange request
• Convertible Reserved Instances can only be exchanged for other Convertible Reserved Instances
currently offered by AWS.
• Convertible Reserved Instances are associated with a specific Region, which is fixed for the duration
of the reservation's term. You cannot exchange a Convertible Reserved Instance for a Convertible
Reserved Instance in a different Region.
• You can exchange one or more Convertible Reserved Instances at a time for one Convertible Reserved
Instance only.
• To exchange a portion of a Convertible Reserved Instance, you can modify it into two or more
reservations, and then exchange one or more of the reservations for a new Convertible Reserved
Instance. For more information, see Exchanging a Portion of a Convertible Reserved Instance (p. 291).
For more information about modifying your Reserved Instances, see Modifying Reserved
Instances (p. 281).
• All Upfront Convertible Reserved Instances can be exchanged for Partial Upfront Convertible Reserved
Instances, and vice versa.
Note
If the total upfront payment required for the exchange (true-up cost) is less than $0.00, AWS
automatically gives you a quantity of instances in the Convertible Reserved Instance that
ensures that true-up cost is $0.00 or more.
Note
If the total value (upfront price + hourly price * number of remaining hours) of the new
Convertible Reserved Instance is less than the total value of the exchanged Convertible
Reserved Instance, AWS automatically gives you a quantity of instances in the Convertible
Reserved Instance that ensures that the total value is the same or higher than that of the
exchanged Convertible Reserved Instance.
289
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
• To benefit from better pricing, you can exchange a No Upfront Convertible Reserved Instance for an All
Upfront or Partial Upfront Convertible Reserved Instance.
• You cannot exchange All Upfront and Partial Upfront Convertible Reserved Instances for No Upfront
Convertible Reserved Instances.
• You can exchange a No Upfront Convertible Reserved Instance for another No Upfront Convertible
Reserved Instance only if the new Convertible Reserved Instance's hourly price is the same or higher
than the exchanged Convertible Reserved Instance's hourly price.
Note
If the total value (hourly price * number of remaining hours) of the new Convertible Reserved
Instance is less than the total value of the exchanged Convertible Reserved Instance, AWS
automatically gives you a quantity of instances in the Convertible Reserved Instance that
ensures that the total value is the same or higher than that of the exchanged Convertible
Reserved Instance.
• If you exchange multiple Convertible Reserved Instances that have different expiration dates, the
expiration date for the new Convertible Reserved Instance is the date that's furthest in the future.
• If you exchange a single Convertible Reserved Instance, it must have the same term (1-year or 3-
years) as the new Convertible Reserved Instance. If you merge multiple Convertible Reserved Instances
with different term lengths, the new Convertible Reserved Instance has a 3-year term. For more
information, see Merging Convertible Reserved Instances (p. 290).
Each Convertible Reserved Instance has a list value. This list value is compared to the list value of the
Convertible Reserved Instances that you want in order to determine how many instance reservations you
can receive from the exchange.
For example: You have 1 x $35-list value Convertible Reserved Instance that you want to exchange for a
new instance type with a list value of $10.
$35/$10 = 3.5
You can exchange your Convertible Reserved Instance for three $10 Convertible Reserved Instances.
It's not possible to purchase half reservations; therefore you must purchase an additional Convertible
Reserved Instance to cover the remainder:
The fourth Convertible Reserved Instance has the same end date as the other three. If you are
exchanging Partial or All Upfront Convertible Reserved Instances, you pay the true-up cost for the fourth
reservation. If the remaining upfront cost of your Convertible Reserved Instances is $500, and the target
reservation would normally cost $600 on a prorated basis, you are charged $100.
$600 prorated upfront cost of new reservations - $500 remaining upfront cost of original
reservations = $100 difference.
290
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
For example, you have the following Convertible Reserved Instances in your account:
• You can merge aaaa1111 and bbbb2222 and exchange them for a 1-year Convertible Reserved
Instance. You cannot exchange them for a 3-year Convertible Reserved Instance. The expiration date of
the new Convertible Reserved Instance is 2018-12-31.
• You can merge bbbb2222 and cccc3333 and exchange them for a 3-year Convertible Reserved
Instance. You cannot exchange them for a 1-year Convertible Reserved Instance. The expiration date of
the new Convertible Reserved Instance is 2018-07-31.
• You can merge cccc3333 and dddd4444 and exchange them for a 3-year Convertible Reserved
Instance. You cannot exchange them for a 1-year Convertible Reserved Instance. The expiration date of
the new Convertible Reserved Instance is 2019-12-31.
In this example, you have a t2.micro Convertible Reserved Instance with four instances in the
reservation. To exchange two t2.micro instances for an m4.xlarge instance:
1. Modify the t2.micro Convertible Reserved Instance by splitting it into two t2.micro Convertible
Reserved Instances with two instances each.
2. Exchange one of the new t2.micro Convertible Reserved Instances for an m4.xlarge Convertible
Reserved Instance.
In this example, you have a t2.large Convertible Reserved Instance. To change it to a smaller
t2.medium instance and a m3.medium instance:
291
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reserved Instances
1. Modify the t2.large Convertible Reserved Instance by splitting it into two t2.medium Convertible
Reserved Instances. A single t2.large instance has the same instance size footprint as two
t2.medium instances. For more information, see Support For Modifying Instance Sizes (p. 283).
2. Exchange one of the new t2.medium Convertible Reserved Instances for an m3.medium Convertible
Reserved Instance.
For more information, see Support For Modifying Instance Sizes (p. 283) and Submitting Exchange
Requests (p. 292).
Not all Reserved Instances can be modified. Ensure that you read the applicable restrictions (p. 282).
You can search for Convertible Reserved Instances offerings and select your new configuration from the
choices provided.
The Reserved Instances that were exchanged are retired, and the new Reserved Instances are displayed in
the Amazon EC2 console. This process can take a few minutes to propagate.
To exchange a Convertible Reserved Instance, first find a target Convertible Reserved Instance that
meets your needs:
292
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Scheduled Instances
Get a quote for the exchange, which includes the number of Reserved Instances you get from the
exchange, and the true-up cost for the exchange:
Scheduled Instances are a good choice for workloads that do not run continuously, but do run on a
regular schedule. For example, you can use Scheduled Instances for an application that runs during
business hours or for batch processing that runs at the end of the week.
If you require a capacity reservation on a continuous basis, Reserved Instances might meet your
needs and decrease costs. For more information, see Reserved Instances (p. 256). If you are flexible
about when your instances run, Spot Instances might meet your needs and decrease costs. For more
information, see Spot Instances (p. 297).
Contents
• How Scheduled Instances Work (p. 293)
• Service-Linked Roles for Scheduled Instances (p. 294)
• Purchasing a Scheduled Instance (p. 294)
• Launching a Scheduled Instance (p. 295)
• Scheduled Instance Limits (p. 296)
To get started, you must search for an available schedule. You can search across multiple pools or a
single pool. After you locate a suitable schedule, purchase it.
You must launch your Scheduled Instances during their scheduled time periods, using a launch
configuration that matches the following attributes of the schedule that you purchased: instance type,
Availability Zone, network, and platform. When you do so, Amazon EC2 launches EC2 instances on your
behalf, based on the specified launch specification. Amazon EC2 must ensure that the EC2 instances
have terminated by the end of the current scheduled time period so that the capacity is available for any
other Scheduled Instances it is reserved for. Therefore, Amazon EC2 terminates the EC2 instances three
minutes before the end of the current scheduled time period.
You can't stop or reboot Scheduled Instances, but you can terminate them manually as needed. If you
terminate a Scheduled Instance before its current scheduled time period ends, you can launch it again
after a few minutes. Otherwise, you must wait until the next scheduled time period.
293
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Scheduled Instances
If you purchased Scheduled Instances before October 2017, when Amazon EC2 began supporting this
service-linked role, Amazon EC2 created the AWSServiceRoleForEC2ScheduledInstances role in your
AWS account. For more information, see A New Role Appeared in My Account in the IAM User Guide.
If you no longer need to use Scheduled Instances, we recommend that you delete the
AWSServiceRoleForEC2ScheduledInstances role. After this role is deleted from your account, Amazon
EC2 will create the role again if you purchase Scheduled Instances.
a. Under Create a schedule, select the starting date from Starting on, the schedule recurrence
(daily, weekly, or monthly) from Recurring, and the minimum duration from for duration. Note
that the console ensures that you specify a value for the minimum duration that meets the
minimum required utilization for your Scheduled Instance (1,200 hours per year).
294
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Scheduled Instances
b. Under Instance details, select the operating system and network from Platform. To narrow the
results, select one or more instance types from Instance type or one or more Availability Zones
from Availability Zone.
Use the describe-scheduled-instance-availability command to list the available schedules that meet your
needs, and then use the purchase-scheduled-instances command to complete the purchase.
Use the describe-scheduled-instances command to list your Scheduled Instances, and then use the run-
scheduled-instances command to launch each Scheduled Instance during its scheduled time periods.
295
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Scheduled Instances
• The following are the only supported instance types: C3, C4, M4, and R3.
• The required term is 365 days (one year).
• The minimum required utilization is 1,200 hours per year.
• You can purchase a Scheduled Instance up to three months in advance.
• They are available in the following Regions: US East (N. Virginia), US West (Oregon), and Europe
(Ireland).
296
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
Spot Instances
A Spot Instance is an unused EC2 instance that is available for less than the On-Demand price. Because
Spot Instances enable you to request unused EC2 instances at steep discounts, you can lower your
Amazon EC2 costs significantly. The hourly price for a Spot Instance is called a Spot price. The Spot price
of each instance type in each Availability Zone is set by Amazon EC2, and adjusted gradually based on
the long-term supply of and demand for Spot Instances. Your Spot Instance runs whenever capacity is
available and the maximum price per hour for your request exceeds the Spot price.
Spot Instances are a cost-effective choice if you can be flexible about when your applications run and if
your applications can be interrupted. For example, Spot Instances are well-suited for data analysis, batch
jobs, background processing, and optional tasks. For more information, see Amazon EC2 Spot Instances.
Topics
Concepts
Before you get started with Spot Instances, you should be familiar with the following concepts:
• Spot Instance pool – A set of unused EC2 instances with the same instance type (for example,
m5.large), operating system, Availability Zone, and network platform.
• Spot price – The current price of a Spot Instance per hour.
• Spot Instance request – Provides the maximum price per hour that you are willing to pay for a Spot
Instance. If you don't specify a maximum price, the default maximum price is the On-Demand price.
When the maximum price per hour for your request exceeds the Spot price, Amazon EC2 fulfills your
request if capacity is available. A Spot Instance request is either one-time or persistent. Amazon EC2
automatically resubmits a persistent Spot request after the Spot Instance associated with the request
is terminated. Your Spot Instance request can optionally specify a duration for the Spot Instances.
• Spot Fleet – A set of Spot Instances that is launched based on criteria that you specify. The Spot
Fleet selects the Spot Instance pools that meet your needs and launches Spot Instances to meet the
target capacity for the fleet. By default, Spot Fleets are set to maintain target capacity by launching
replacement instances after Spot Instances in the fleet are terminated. You can submit a Spot Fleet as
a one-time request, which does not persist after the instances have been terminated. You can include
On-Demand Instance requests in a Spot Fleet request.
• Spot Instance interruption – Amazon EC2 terminates, stops, or hibernates your Spot Instance when the
Spot price exceeds the maximum price for your request or capacity is no longer available. Amazon EC2
provides a Spot Instance interruption notice, which gives the instance a two-minute warning before it
is interrupted.
Launch time Can only be launched immediately if the Can only be launched immediately if
Spot Request is active and capacity is you make a manual launch request and
available. capacity is available.
297
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
Available If capacity is not available, the Spot If capacity is not available when you
capacity Request continues to automatically make a launch request, you get an
make the launch request until capacity insufficient capacity error (ICE).
becomes available.
Hourly price The hourly price for Spot Instances varies The hourly price for On-Demand
based on demand. Instances is static.
Instance You can’t stop and start an Amazon EBS- You determine when an On-Demand
interruption backed Spot Instance; only the Amazon Instance is interrupted (stopped or
EC2 Spot service can do this. The Amazon terminated).
EC2 Spot service can interrupt (p. 351)
an individual Spot Instance if capacity
is no longer available, the Spot price
exceeds your maximum price, or demand
for Spot Instances increases.
Another strategy is to launch Spot Instances with a specified duration (also known as Spot blocks),
which are designed not to be interrupted and will run continuously for the duration you select. In
rare situations, Spot blocks may be interrupted due to Amazon EC2 capacity needs. In these cases,
we provide a two-minute warning before we terminate an instance, and you are not charged for the
terminated instances even if you used them. For more information, see Specifying a Duration for Your
Spot Instances (p. 311).
Spot basics
298
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
Related Services
You can provision Spot Instances directly using Amazon EC2. You can also provision Spot Instances using
other services in AWS. For more information, see the following documentation.
You can create launch configurations with the maximum price that you are willing to pay, so that
Amazon EC2 Auto Scaling can launch Spot Instances. For more information, see Launching Spot
Instances in Your Auto Scaling Group and Using Multiple Instance Types and Purchase Options in the
Amazon EC2 Auto Scaling User Guide.
Amazon EMR and Spot Instances
There are scenarios where it can be useful to run Spot Instances in an Amazon EMR cluster. For
more information, see Spot Instances and When Should You Use Spot Instances in the Amazon EMR
Management Guide.
AWS CloudFormation Templates
AWS CloudFormation enables you to create and manage a collection of AWS resources using
a template in JSON format. AWS CloudFormation templates can include the maximum price
you are willing to pay. For more information, see EC2 Spot Instance Updates - Auto Scaling and
CloudFormation Integration.
AWS SDK for Java
You can use the Java programming language to manage your Spot Instances. For more information,
see Tutorial: Amazon EC2 Spot Instances and Tutorial: Advanced Amazon EC2 Spot Request
Management.
AWS SDK for .NET
You can use the .NET programming environment to manage your Spot Instances. For more
information, see Tutorial: Amazon EC2 Spot Instances.
Spot Instances with a predefined duration use a fixed hourly price that remains in effect for the Spot
Instance while it runs.
299
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
View Prices
To view the current (updated every five minutes) lowest Spot price per region and instance type, see the
Spot Instances Pricing page.
To view the Spot price history for the past three months, use the Amazon EC2 console or the
describe-spot-price-history command (AWS CLI). For more information, see Spot Instance Pricing
History (p. 308).
We independently map Availability Zones to codes for each AWS account. Therefore, you can get
different results for the same Availability Zone code (for example, us-west-2a) between different
accounts.
View Savings
You can view the savings made from using Spot Instances for a single Spot Fleet or for all Spot Instances.
You can view the savings made in the last hour or the last three days, and you can view the average cost
per vCPU hour and per memory (GiB) hour. Savings are estimated and may differ from actual savings
because they do not include the billing adjustments for your usage. For more information about viewing
savings information, see Savings From Purchasing Spot Instances (p. 309).
View Billing
To review your bill, go to your AWS Account Activity page. Your bill contains links to usage reports that
provide details about your bill. For more information, see AWS Account Billing.
If you have questions concerning AWS billing, accounts, and events, contact AWS Support.
When you use Spot Instances, you must be prepared for interruptions. Amazon EC2 can interrupt
your Spot Instance when the Spot price exceeds your maximum price, when the demand for Spot
Instances rises, or when the supply of Spot Instances decreases. When Amazon EC2 interrupts a Spot
Instance, it provides a Spot Instance interruption notice, which gives the instance a two-minute warning
before Amazon EC2 interrupts it. You can't enable termination protection for Spot Instances. For more
information, see Spot Instance Interruptions (p. 351).
You can't stop and start an Amazon EBS-backed instance if it is a Spot Instance (only the Spot service can
stop and start a Spot Instance), but you can reboot or terminate a Spot Instance.
Contents
• Launching Spot Instances in a Launch Group (p. 300)
• Launching Spot Instances in an Availability Zone Group (p. 301)
• Launching Spot Instances in a VPC (p. 301)
300
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
instances in a launch group (for example, if the Spot price exceeds your maximum price), it must
terminate them all. However, if you terminate one or more of the instances in a launch group, Amazon
EC2 does not terminate the remaining instances in the launch group.
Although this option can be useful, adding this constraint can decrease the chances that your Spot
Instance request is fulfilled and increase the chances that your Spot Instances are terminated. For
example, your launch group includes instances in multiple Availability Zones. If capacity in one of these
Availability Zones decreases and is no longer available, then Amazon EC2 terminates all instances for the
launch group.
If you create another successful Spot Instance request that specifies the same (existing) launch group
as an earlier successful request, then the new instances are added to the launch group. Subsequently, if
an instance in this launch group is terminated, all instances in the launch group are terminated, which
includes instances launched by the first and second requests.
Although this option can be useful, adding this constraint can lower the chances that your Spot Instance
request is fulfilled.
If you specify an Availability Zone group but don't specify an Availability Zone in the Spot Instance
request, the result depends on the network you specified.
Default VPC
Amazon EC2 uses the Availability Zone for the specified subnet. If you don't specify a subnet, it selects
an Availability Zone and its default subnet, but not necessarily the lowest-priced zone. If you deleted the
default subnet for an Availability Zone, then you must specify a different subnet.
Nondefault VPC
Amazon EC2 uses the Availability Zone for the specified subnet.
• You should use the default maximum price (the On-Demand price), or base your maximum price on the
Spot price history of Spot Instances in a VPC.
• [Default VPC] If you want your Spot Instance launched in a specific low-priced Availability Zone, you
must specify the corresponding subnet in your Spot Instance request. If you do not specify a subnet,
Amazon EC2 selects one for you, and the Availability Zone for this subnet might not have the lowest
Spot price.
• [Nondefault VPC] You must specify the subnet for your Spot Instance.
The Spot Fleet attempts to launch the number of Spot Instances and On-Demand Instances to meet the
target capacity that you specified in the Spot Fleet request. The request for Spot Instances is fulfilled
301
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
if there is available capacity and the maximum price you specified in the request exceeds the current
Spot price. The Spot Fleet also attempts to maintain its target capacity fleet if your Spot Instances are
interrupted.
You can also set a maximum amount per hour that you’re willing to pay for your fleet, and Spot Fleet
launches instances until it reaches the maximum amount. When the maximum amount you're willing to
pay is reached, the fleet stops launching instances even if it hasn’t met the target capacity.
A Spot Instance pool is a set of unused EC2 instances with the same instance type (for example,
m5.large), operating system, Availability Zone, and network platform. When you make a Spot Fleet
request, you can include multiple launch specifications, that vary by instance type, AMI, Availability Zone,
or subnet. The Spot Fleet selects the Spot Instance pools that are used to fulfill the request, based on
the launch specifications included in your Spot Fleet request, and the configuration of the Spot Fleet
request. The Spot Instances come from the selected pools.
Contents
• On-Demand in Spot Fleet (p. 302)
• Allocation Strategy for Spot Instances (p. 302)
• Spot Price Overrides (p. 304)
• Control Spending (p. 304)
• Spot Fleet Instance Weighting (p. 304)
• Walkthrough: Using Spot Fleet with Instance Weighting (p. 306)
When Spot Fleet attempts to fulfill your On-Demand capacity, it defaults to launching the lowest-priced
instance type first. If OnDemandAllocationStrategy is set to prioritized, Spot Fleet uses priority
to determine which instance type to use first in fulfilling On-Demand capacity. The priority is assigned to
the launch template override, and the highest priority is launched first.
For example, you have configured three launch template overrides, each with a different instance type:
c3.large, c4.large, and c5.large. The On-Demand price for c5.large is less than for c4.large.
c3.large is the cheapest. If you do not use priority to determine the order, the fleet fulfills On-Demand
capacity by starting with c3.large, and then c5.large. Because you often have unused Reserved
Instances for c4.large, you can set the launch template override priority so that the order is c4.large,
c3.large, and then c5.large.
lowestPrice
The Spot Instances come from the pool with the lowest price. This is the default strategy.
302
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
diversified
The Spot Instances are distributed across the number of Spot pools that you specify. This parameter
is valid only when used in combination with lowestPrice.
After Spot Instances are terminated due to a change in the Spot price or available capacity of a Spot
Instance pool, a Spot Fleet of type maintain launches replacement Spot Instances. If the allocation
strategy is lowestPrice, the fleet launches replacement instances in the pool where the Spot price is
currently the lowest. If the allocation strategy is diversified, the fleet distributes the replacement
Spot Instances across the remaining pools. If the allocation strategy is lowestPrice in combination
with InstancePoolsToUseCount, the fleet selects the Spot pools with the lowest price and launches
Spot Instances across the number of Spot pools that you specify.
To optimize the costs for your use of Spot Instances, specify the lowestPrice allocation strategy so
that Spot Fleet automatically deploys the cheapest combination of instance types and Availability Zones
based on the current Spot price.
For On-Demand Instance target capacity, Spot Fleet always selects the cheapest instance type based on
the public On-Demand price, while continuing to follow the allocation strategy (either lowestPrice or
diversified) for Spot Instances.
To create a fleet of Spot Instances that is both cheap and diversified, use the lowestPrice allocation
strategy in combination with InstancePoolsToUseCount. Spot Fleet automatically deploys the
cheapest combination of instance types and Availability Zones based on the current Spot price across the
number of Spot pools that you specify. This combination can be used to avoid the most expensive Spot
Instances.
You can optimize your Spot Fleets based on your use case.
If your fleet is small or runs for a short time, the probability that your Spot Instances may be interrupted
is low, even with all the instances in a single Spot Instance pool. Therefore, the lowestPrice strategy is
likely to meet your needs while providing the lowest cost.
If your fleet is large or runs for a long time, you can improve the availability of your fleet by distributing
the Spot Instances across multiple pools. For example, if your Spot Fleet request specifies 10 pools and
a target capacity of 100 instances, the fleet launches 10 Spot Instances in each pool. If the Spot price
for one pool exceeds your maximum price for this pool, only 10% of your fleet is affected. Using this
strategy also makes your fleet less sensitive to increases in the Spot price in any one pool over time.
With the diversified strategy, the Spot Fleet does not launch Spot Instances into any pools with a
Spot price that is equal to or higher than the On-Demand price.
To create a cheap and diversified fleet, use the lowestPrice strategy in combination with
InstancePoolsToUseCount. You can use a low or high number of Spot pools across which to allocate
your Spot Instances. For example, if you run batch processing, we recommend specifying a low number
of Spot pools (for example, InstancePoolsToUseCount=2) to ensure that your queue always has
compute capacity while maximizing savings. If you run a web service, we recommend specifying a high
303
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
number of Spot pools (for example, InstancePoolsToUseCount=10) to minimize the impact if a Spot
Instance pool becomes temporarily unavailable.
You can optionally specify a maximum price in one or more launch specifications. This price is specific
to the launch specification. If a launch specification includes a specific price, the Spot Fleet uses this
maximum price, overriding the global maximum price. Any other launch specifications that do not
include a specific maximum price still use the global maximum price.
Control Spending
Spot Fleet stops launching instances when it has either reached the target capacity or the maximum
amount you’re willing to pay. To control the amount you pay per hour for your fleet, you can specify the
SpotMaxTotalPrice for Spot Instances and the OnDemandMaxTotalPrice for On-Demand Instances.
When the maximum total price is reached, Spot Fleet stops launching instances even if it hasn’t met the
target capacity.
The following examples show two different scenarios. In the first, Spot Fleet stops launching instances
when it has met the target capacity. In the second, Spot Fleet stops launching instances when it has
reached the maximum amount you’re willing to pay.
Spot Fleet launches 10 On-Demand Instances because the total of $1.00 (10 instances x $0.10) does not
exceed the OnDemandMaxTotalPrice of $1.50.
If Spot Fleet launches the On-Demand target capacity (10 On-Demand Instances), the total cost per
hour would be $1.00. This is more than the amount ($0.80) specified for OnDemandMaxTotalPrice.
To prevent spending more than you're willing to pay, Spot Fleet launches only 8 On-Demand
Instances (below the On-Demand target capacity) because launching more would exceed the
OnDemandMaxTotalPrice.
304
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
By default, the price that you specify is per instance hour. When you use the instance weighting feature,
the price that you specify is per unit hour. You can calculate your price per unit hour by dividing your
price for an instance type by the number of units that it represents. Spot Fleet calculates the number
of Spot Instances to launch by dividing the target capacity by the instance weight. If the result isn't an
integer, the Spot Fleet rounds it up to the next integer, so that the size of your fleet is not below its
target capacity. Spot Fleet can select any pool that you specify in your launch specification, even if the
capacity of the instances launched exceeds the requested target capacity.
The following tables provide examples of calculations to determine the price per unit for a Spot Fleet
request with a target capacity of 10.
Instance type Instance Price per Price per unit Number of instances launched
weight instance hour hour
Instance type Instance Price per Price per unit Number of instances launched
weight instance hour hour
Use Spot Fleet instance weighting as follows to provision the target capacity that you want in the pools
with the lowest price per unit at the time of fulfillment:
1. Set the target capacity for your Spot Fleet either in instances (the default) or in the units of your
choice, such as virtual CPUs, memory, storage, or throughput.
2. Set the price per unit.
3. For each launch configuration, specify the weight, which is the number of units that the instance
type represents toward the target capacity.
• A target capacity of 24
• A launch specification with an instance type r3.2xlarge and a weight of 6
• A launch specification with an instance type c3.xlarge and a weight of 5
The weights represent the number of units that instance type represents toward the target capacity. If
the first launch specification provides the lowest price per unit (price for r3.2xlarge per instance hour
divided by 6), the Spot Fleet would launch four of these instances (24 divided by 6).
If the second launch specification provides the lowest price per unit (price for c3.xlarge per instance
hour divided by 5), the Spot Fleet would launch five of these instances (24 divided by 5, result rounded
up).
305
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
• A target capacity of 30
• A launch specification with an instance type c3.2xlarge and a weight of 8
• A launch specification with an instance type m3.xlarge and a weight of 8
• A launch specification with an instance type r3.xlarge and a weight of 8
The Spot Fleet would launch four instances (30 divided by 8, result rounded up). With the lowestPrice
strategy, all four instances come from the pool that provides the lowest price per unit. With the
diversified strategy, the Spot Fleet launches one instance in each of the three pools, and the fourth
instance in whichever pool provides the lowest price per unit.
Objective
Example Corp, a pharmaceutical company, wants to leverage the computational power of Amazon EC2
for screening chemical compounds that might be used to fight cancer.
Planning
Example Corp first reviews Spot Best Practices. Next, Example Corp determines the following
requirements for their Spot Fleet.
Instance Types
Example Corp has a compute- and memory-intensive application that performs best with at least 60 GB
of memory and eight virtual CPUs (vCPUs). They want to maximize these resources for the application at
the lowest possible price. Example Corp decides that any of the following EC2 instance types would meet
their needs:
r3.2xlarge 61 8
r3.4xlarge 122 16
r3.8xlarge 244 32
With instance weighting, target capacity can equal a number of instances (the default) or a combination
of factors such as cores (vCPUs), memory (GiBs), and storage (GBs). By considering the base for their
application (60 GB of RAM and eight vCPUs) as 1 unit, Example Corp decides that 20 times this amount
would meet their needs. So the company sets the target capacity of their Spot Fleet request to 20.
Instance Weights
After determining the target capacity, Example Corp calculates instance weights. To calculate the
instance weight for each instance type, they determine the units of each instance type that are required
to reach the target capacity as follows:
306
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
Therefore, Example Corp assigns instance weights of 1, 2, and 4 to the respective launch configurations
in their Spot Fleet request.
Example Corp uses the On-Demand price per instance hour as a starting point for their price. They could
also use recent Spot prices, or a combination of the two. To calculate the price per unit hour, they divide
their starting price per instance hour by the weight. For example:
Instance type On-Demand price Instance weight Price per unit hour
Example Corp could use a global price per unit hour of $0.7 and be competitive for all three instance
types. They could also use a global price per unit hour of $0.7 and a specific price per unit hour of $0.9 in
the r3.8xlarge launch specification.
Verifying Permissions
Before creating a Spot Fleet request, Example Corp verifies that it has an IAM role with the required
permissions. For more information, see Spot Fleet Prerequisites (p. 321).
{
"SpotPrice": "0.70",
"TargetCapacity": 20,
"IamFleetRole": "arn:aws:iam::123456789012:role/aws-ec2-spot-fleet-tagging-role",
"LaunchSpecifications": [
{
"ImageId": "ami-1a2b3c4d",
"InstanceType": "r3.2xlarge",
"SubnetId": "subnet-482e4972",
"WeightedCapacity": 1
},
{
"ImageId": "ami-1a2b3c4d",
"InstanceType": "r3.4xlarge",
"SubnetId": "subnet-482e4972",
"WeightedCapacity": 2
},
{
"ImageId": "ami-1a2b3c4d",
"InstanceType": "r3.8xlarge",
"SubnetId": "subnet-482e4972",
"SpotPrice": "0.90",
"WeightedCapacity": 4
}
]
}
Example Corp creates the Spot Fleet request using the following request-spot-fleet command:
307
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
Fulfillment
The allocation strategy determines which Spot Instance pools your Spot Instances come from.
With the lowestPrice strategy (which is the default strategy), the Spot Instances come from the pool
with the lowest price per unit at the time of fulfillment. To provide 20 units of capacity, the Spot Fleet
launches either 20 r3.2xlarge instances (20 divided by 1), 10 r3.4xlarge instances (20 divided by 2),
or 5 r3.8xlarge instances (20 divided by 4).
If Example Corp used the diversified strategy, the Spot Instances would come from all three pools.
The Spot Fleet would launch 6 r3.2xlarge instances (which provide 6 units), 3 r3.4xlarge instances
(which provide 6 units), and 2 r3.8xlarge instances (which provide 8 units), for a total of 20 units.
5. (Optional) To review the Spot price history for a specific Availability Zone, select a zone from the list.
You can also select a different product, instance type, or date range.
308
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
The following screenshot from the Spot Requests page shows the Spot usage and savings information
for a Spot Fleet.
• Spot Instances – The number of Spot Instances launched and terminated by the Spot Fleet. When
viewing the savings summary, the number represents all your running Spot Instances.
• vCPU-hours – The number of vCPU hours used across all the Spot Instances for the selected time
frame.
• Mem(GiB)-hours – The number of GiB hours used across all the Spot Instances for the selected time
frame.
• On-Demand total – The total amount you would've paid for the selected time frame had you launched
these instances as On-Demand Instances.
• Spot total – The total amount to pay for the selected time frame.
• Savings – The percentage that you are saving by not paying the On-Demand price.
• Average cost per vCPU-hour – The average hourly cost of using the vCPUs across all the Spot
Instances for the selected time frame, calculated as follows: Average cost per vCPU-hour = Spot total
/ vCPU-hours.
• Average cost per mem(GiB)-hour – The average hourly cost of using the GiBs across all the Spot
Instances for the selected time frame, calculated as follows: Average cost per mem(GiB)-hour = Spot
total / Mem(GiB)-hours.
• Details table – The different instance types (the number of instances per instance type is in
parentheses) that comprise the Spot Fleet. When viewing the savings summary, these comprise all
your running Spot Instances.
Savings information can only be viewed using the Amazon EC2 console.
309
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
To view the savings information for all running Spot Instances (console)
The following illustration shows how Spot requests work. Notice that the action taken for a Spot
Instance interruption depends on the request type (one-time or persistent) and the interruption behavior
(hibernate, stop, or terminate). If the request is a persistent request, the request is opened again after
your Spot Instance is interrupted.
Contents
• Spot Instance Request States (p. 310)
• Specifying a Duration for Your Spot Instances (p. 311)
• Specifying a Tenancy for Your Spot Instances (p. 312)
• Service-Linked Role for Spot Instance Requests (p. 313)
• Creating a Spot Instance Request (p. 314)
• Finding Running Spot Instances (p. 316)
• Tagging Spot Instance Requests (p. 317)
• Canceling a Spot Instance Request (p. 317)
• Terminating a Spot Instance (p. 317)
• Spot Request Example Launch Specifications (p. 318)
310
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
The following illustration represents the transitions between the request states. Notice that the
transitions depend on the request type (one-time or persistent).
A one-time Spot Instance request remains active until Amazon EC2 launches the Spot Instance, the
request expires, or you cancel the request. If the Spot price exceeds your maximum price or capacity is
not available, your Spot Instance is terminated and the Spot Instance request is closed.
A persistent Spot Instance request remains active until it expires or you cancel it, even if the request is
fulfilled. If the Spot price exceeds your maximum price or capacity is not available, your Spot Instance
is interrupted. After your instance is interrupted, when your maximum price exceeds the Spot price or
capacity becomes available again, the Spot Instance is started if stopped or resumed if hibernated. If the
Spot Instance is terminated, the Spot Instance request is opened again and Amazon EC2 launches a new
Spot Instance.
You can track the status of your Spot Instance requests, as well as the status of the Spot Instances
launched, through the status. For more information, see Spot Request Status (p. 345).
You can specify a duration of 1, 2, 3, 4, 5, or 6 hours. The price that you pay depends on the specified
duration. To view the current prices for a 1-hour duration or a 6-hour duration, see Spot Instance Prices.
You can use these prices to estimate the cost of the 2, 3, 4, and 5-hour durations. When a request with
a duration is fulfilled, the price for your Spot Instance is fixed, and this price remains in effect until the
instance terminates. You are billed at this price for each hour or partial hour that the instance is running.
A partial instance hour is billed to the nearest second.
When you specify a duration in your Spot request, the duration period for each Spot Instance starts as
soon as the instance receives its instance ID. The Spot Instance runs until you terminate it or the duration
period ends. At the end of the duration period, Amazon EC2 marks the Spot Instance for termination
and provides a Spot Instance termination notice, which gives the instance a two-minute warning before
it terminates. In rare situations, Spot blocks may be interrupted due to Amazon EC2 capacity needs. In
these cases, we provide a two-minute warning before we terminate an instance, and you are not charged
for the terminated instances even if you used them.
311
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
Select the appropriate request type. For more information, see Creating a Spot Instance
Request (p. 314).
To specify a duration for your Spot Instances, include the --block-duration-minutes option with
the request-spot-instances command. For example, the following command creates a Spot request that
launches Spot Instances that run for two hours:
To retrieve the cost for Spot Instances with a specified duration (AWS CLI)
Use the describe-spot-instance-requests command to retrieve the fixed cost for your Spot Instances with
a specified duration. The information is in the actualBlockHourlyPrice field.
• Specify a tenancy of dedicated when you create the Spot Instance request. For more information,
see Creating a Spot Instance Request (p. 314).
• Request a Spot Instance in a VPC with an instance tenancy of dedicated. For more information, see
Creating a VPC with an Instance Tenancy of Dedicated (p. 380). You cannot request a Spot Instance
with a tenancy of default if you request it in a VPC with an instance tenancy of dedicated.
Current Generation
• c4.8xlarge
• d2.8xlarge
• i3.16xlarge
• m4.10xlarge
• m4.16xlarge
• p2.16xlarge
• r4.16xlarge
• x1.32xlarge
Previous Generation
• c3.8xlarge
• cc2.8xlarge
• cr1.8xlarge
• g2.8xlarge
• i2.8xlarge
312
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
• r3.8xlarge
Amazon EC2 uses the service-linked role named AWSServiceRoleForEC2Spot to launch and manage
Spot Instances on your behalf.
Under most circumstances, you don't need to manually create a service-linked role. Amazon EC2 creates
the AWSServiceRoleForEC2Spot service-linked role the first time you request a Spot Instance using the
console.
If you had an active Spot Instance request before October 2017, when Amazon EC2 began supporting
this service-linked role, Amazon EC2 created the AWSServiceRoleForEC2Spot role in your AWS account.
For more information, see A New Role Appeared in My Account in the IAM User Guide.
Ensure that this role exists before you use the AWS CLI or an API to request a Spot Instance. To create the
role, use the IAM console as follows.
If you no longer need to use Spot Instances, we recommend that you delete the
AWSServiceRoleForEC2Spot role. After this role is deleted from your account, Amazon EC2 will create
the role again if you request Spot Instances.
Granting Access to CMKs for Use with Encrypted AMIs and EBS Snapshots
If you specify an encrypted AMI (p. 149) or an encrypted Amazon EBS snapshot (p. 903) for your
Spot Instances and you use a customer managed customer master key (CMK) for encryption, you must
grant the AWSServiceRoleForEC2Spot role permission to use the CMK so that Amazon EC2 can launch
Spot Instances on your behalf. To do this, you must add a grant to the CMK, as shown in the following
procedure.
313
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
When providing permissions, grants are an alternative to key policies. For more information, see Using
Grants and Using Key Policies in AWS KMS in the AWS Key Management Service Developer Guide.
• Use the create-grant command to add a grant to the CMK and to specify the principal (the
AWSServiceRoleForEC2Spot service-linked role) that is given permission to perform the operations
that the grant permits. The CMK is specified by the key-id parameter and the ARN of the
CMK. The principal is specified by the grantee-principal parameter and the ARN of the
AWSServiceRoleForEC2Spot service-linked role.
If you request multiple Spot Instances at one time, Amazon EC2 creates separate Spot Instance requests
so that you can track the status of each request separately. For more information about tracking Spot
Instance requests, see Spot Request Status (p. 345).
Prerequisites
Before you begin, decide on your maximum price, how many Spot Instances you'd like, and what instance
type to use. To review Spot price trends, see Spot Instance Pricing History (p. 308).
To use Request and Maintain, see Creating a Spot Fleet Request (p. 324).
5. For Target capacity, enter the number of units to request. You can choose instances or performance
characteristics that are important to your application workload, such as vCPUs, memory, and
storage.
6. For Requirements, do the following:
a. [Spot Fleet] (Optional) For Launch template, choose a launch template. The launch template
must specify an Amazon Machine Image (AMI), as you cannot override the AMI using Spot Fleet
if you specify a launch template.
b. For AMI, choose one of the basic AMIs provided by AWS, or choose Use custom AMI to specify
your own AMI.
314
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
c. For Instance type(s), choose Select. Select the instance types that have the minimum hardware
specifications that you need (vCPUs, memory, and storage).
d. For Network, you can select an existing VPC or create a new one.
[New VPC] Choose Create new VPC to go to the Amazon VPC console. When you are done,
return to the wizard and refresh the list.
e. (Optional) For Availability Zones, the default is to let AWS choose the Availability Zones for
your Spot Instances. If you prefer, you can specify specific Availability Zones.
Select one or more Availability Zones. If you have more than one subnet in an Availability Zone,
select the appropriate subnet from Subnet. To add subnets, select Create new subnet to go to
the Amazon VPC console. When you are done, return to the wizard and refresh the list.
f. (Optional) To add storage, specify additional instance store volumes or EBS volumes, depending
on the instance type. You can also enable Amazon EBS optimization.
g. (Optional) By default, basic monitoring is enabled for your instances. To enable detailed
monitoring, choose Enable CloudWatch detailed monitoring.
h. (Optional) To run a Dedicated Spot Instance, for Tenancy, choose Dedicated - run a dedicated
instance.
i. For Security groups, select one or more security groups.
j. To connect to your instances, enable Auto-assign IPv4 Public IP.
k. (Optional) To connect to your instances, specify your key pair for Key pair name.
l. (Optional) To launch your Spot Instances with an IAM role, for IAM instance profile, specify the
role.
m. (Optional) To run a start-up script, copy it to User data.
n. [Spot Fleet] To add a tag, choose Add new tag and type the key and value for the tag. Repeat
for each tag.
7. For Spot request fulfillment, do the following:
a. [Spot Fleet] For Allocation strategy, choose the strategy that meets your needs. For more
information, see Allocation Strategy for Spot Instances (p. 302).
b. [Spot Fleet] For Maximum price, you can use the default maximum price (the On-Demand price)
or specify the maximum price that you are willing to pay. If your maximum price is lower than
the Spot price for the instance types that you selected, your Spot Instances are not launched.
c. (Optional) To create a request that is valid only during a specific time period, edit the values for
Request valid from and Request valid until.
d. [Spot Fleet] By default, we terminate your Spot Instances when the request expires. To keep
them running after your request expires, clear Terminate instances at expiration.
8. (Optional) To register your Spot Instances with a load balancer, choose Receive traffic from one or
more load balancers and select one or more Classic Load Balancers or target groups.
9. (Optional) To download a copy of the launch configuration for use with the AWS CLI, choose JSON
config.
10. Choose Launch.
[Spot Fleet] The request type is fleet. When the request is fulfilled, requests of type instance are
added, where the state is active and the status is fulfilled.
[Spot block] The request type is block and the initial state is open. When the request is fulfilled,
the state is active and the status is fulfilled.
For example launch specification files to use with these commands, see Spot Request Example Launch
Specifications (p. 318). If you download a launch specification file from the console, you must use the
request-spot-fleet command instead (the console specifies a Spot request using a Spot Fleet).
Amazon EC2 launches your Spot Instance when the maximum price exceeds the Spot price and capacity
is available. The Spot Instance runs until it is interrupted or you terminate it yourself. Use the following
describe-spot-instance-requests command to monitor your Spot Instance request:
You can see both Spot Instance requests and Spot Fleet requests. If a Spot Instance request has been
fulfilled, Capacity is the ID of the Spot Instance. For a Spot Fleet, Capacity indicates how much of
the requested capacity has been fulfilled. To view the IDs of the instances in a Spot Fleet, choose the
expand arrow, or select the fleet and choose Instances.
Note
Spot Instance requests are not tagged instantly and for a period of time may appear
separate from Spot Fleet Requests (SFR).
3. Alternatively, in the navigation pane, choose Instances. In the top right corner, choose the Show/
Hide icon, and then select Lifecycle. For each instance, Lifecycle is either normal, spot, or
scheduled.
To enumerate your Spot Instances, use the describe-spot-instance-requests command with the --query
option as follows:
[
{
"ID": "i-1234567890abcdef0"
},
316
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
{
"ID": "i-0598c7d356eba48d7"
}
]
Alternatively, you can enumerate your Spot Instances using the describe-instances command with the --
filters option as follows:
You can assign a tag to a Spot Instance request after you create it. The tags that you create for your
Spot Instance requests only apply to the requests. These tags are not added automatically to the Spot
Instance that the Spot service launches to fulfill the request. You must add tags to a Spot Instance
yourself after the Spot Instance is launched.
To add a tag to your Spot Instance request or Spot Instance using the AWS CLI
• Use the following cancel-spot-instance-requests command to cancel the specified Spot request:
317
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
a running Spot Instance that was launched by a persistent Spot request, the Spot request returns
to the open state so that a new Spot Instance can be launched. To cancel a persistent Spot request
and terminate its Spot Instances, you must cancel the Spot request first and then terminate the Spot
Instances. Otherwise, the persistent Spot request can launch a new instance. For more information about
canceling a Spot Instance request, see the previous section.
The following example does not include an Availability Zone or subnet. Amazon EC2 selects an
Availability Zone for you. Amazon EC2 launches the instances in the default subnet of the selected
Availability Zone.
{
"ImageId": "ami-1a2b3c4d",
"KeyName": "my-key-pair",
"SecurityGroupIds": [ "sg-1a2b3c4d" ],
"InstanceType": "m3.medium",
"IamInstanceProfile": {
"Arn": "arn:aws:iam::123456789012:instance-profile/my-iam-role"
}
}
The following example includes an Availability Zone. Amazon EC2 launches the instances in the default
subnet of the specified Availability Zone.
{
"ImageId": "ami-1a2b3c4d",
"KeyName": "my-key-pair",
"SecurityGroupIds": [ "sg-1a2b3c4d" ],
"InstanceType": "m3.medium",
"Placement": {
"AvailabilityZone": "us-west-2a"
},
"IamInstanceProfile": {
"Arn": "arn:aws:iam::123456789012:instance-profile/my-iam-role"
}
}
318
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
The following example includes a subnet. Amazon EC2 launches the instances in the specified subnet. If
the VPC is a nondefault VPC, the instance does not receive a public IPv4 address by default.
{
"ImageId": "ami-1a2b3c4d",
"SecurityGroupIds": [ "sg-1a2b3c4d" ],
"InstanceType": "m3.medium",
"SubnetId": "subnet-1a2b3c4d",
"IamInstanceProfile": {
"Arn": "arn:aws:iam::123456789012:instance-profile/my-iam-role"
}
}
{
"ImageId": "ami-1a2b3c4d",
"KeyName": "my-key-pair",
"InstanceType": "m3.medium",
"NetworkInterfaces": [
{
"DeviceIndex": 0,
"SubnetId": "subnet-1a2b3c4d",
"Groups": [ "sg-1a2b3c4d" ],
"AssociatePublicIpAddress": true
}
],
"IamInstanceProfile": {
"Arn": "arn:aws:iam::123456789012:instance-profile/my-iam-role"
}
}
The following example requests Spot Instance with a tenancy of dedicated. A Dedicated Spot Instance
must be launched in a VPC.
{
"ImageId": "ami-1a2b3c4d",
"KeyName": "my-key-pair",
"SecurityGroupIds": [ "sg-1a2b3c4d" ],
"InstanceType": "c3.8xlarge",
"SubnetId": "subnet-1a2b3c4d",
"Placement": {
"Tenancy": "dedicated"
}
}
319
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
There are two types of Spot Fleet requests: request and maintain. You can create a Spot Fleet to
submit a one-time request for your desired capacity, or require it to maintain a target capacity over time.
Both types of requests benefit from Spot Fleet's allocation strategy.
When you make a one-time request, Spot Fleet places the required requests but does not attempt to
replenish Spot Instances if capacity is diminished. If capacity is not available, Spot Fleet does not submit
requests in alternative Spot pools.
To maintain a target capacity, Spot Fleet places requests to meet the target capacity and automatically
replenish any interrupted instances.
It is not possible to modify the target capacity of a one-time request after it's been submitted. To change
the target capacity, cancel the request and submit a new one.
A Spot Fleet request remains active until it expires or you cancel it. When you cancel a Spot Fleet request,
you may specify whether canceling your Spot Fleet request terminates the Spot Instances in your Spot
Fleet.
Each launch specification includes the information that Amazon EC2 needs to launch an instance, such as
an AMI, instance type, subnet or Availability Zone, and one or more security groups.
Contents
• Spot Fleet Request States (p. 320)
• Spot Fleet Prerequisites (p. 321)
• Spot Fleet and IAM Users (p. 321)
• Spot Fleet Health Checks (p. 322)
• Planning a Spot Fleet Request (p. 323)
• Service-Linked Role for Spot Fleet Requests (p. 323)
• Creating a Spot Fleet Request (p. 324)
• Monitoring Your Spot Fleet (p. 327)
• Modifying a Spot Fleet Request (p. 328)
• Canceling a Spot Fleet Request (p. 329)
• Spot Fleet Example Configurations (p. 330)
• submitted – The Spot Fleet request is being evaluated and Amazon EC2 is preparing to launch the
target number of Spot Instances.
• active – The Spot Fleet has been validated and Amazon EC2 is attempting to maintain the target
number of running Spot Instances. The request remains in this state until it is modified or canceled.
• modifying – The Spot Fleet request is being modified. The request remains in this state until the
modification is fully processed or the Spot Fleet is canceled. A one-time request cannot be modified,
and this state does not apply to such Spot requests.
• cancelled_running – The Spot Fleet is canceled and does not launch additional Spot Instances. Its
existing Spot Instances continue to run until they are interrupted or terminated. The request remains
in this state until all instances are interrupted or terminated.
• cancelled_terminating – The Spot Fleet is canceled and its Spot Instances are terminating. The
request remains in this state until all instances are terminated.
• cancelled – The Spot Fleet is canceled and has no running Spot Instances. The Spot Fleet request is
deleted two days after its instances were terminated.
320
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
The following illustration represents the transitions between the request states. If you exceed your Spot
Fleet limits, the request is canceled immediately.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
321
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
"ec2:*"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"iam:ListRoles",
"iam:PassRole",
"iam:ListInstanceProfiles"
],
"Resource": "*"
}
]
}
The ec2:* grants an IAM user permission to call all Amazon EC2 API actions. To limit the user to
specific Amazon EC2 API actions, specify those actions instead.
An IAM user must have permission to call the iam:ListRoles action to enumerate
existing IAM roles, the iam:PassRole action to specify the Spot Fleet role, and the
iam:ListInstanceProfiles action to enumerate existing instance profiles.
(Optional) To enable an IAM user to create roles or instance profiles using the IAM console, you must
also add the following actions to the policy:
• iam:AddRoleToInstanceProfile
• iam:AttachRolePolicy
• iam:CreateInstanceProfile
• iam:CreateRole
• iam:GetRole
• iam:ListPolicies
4. On the Review policy page, type a policy name and description and choose Create policy.
5. In the navigation pane, choose Users and select the user.
6. Choose Permissions, Add permissions.
7. Choose Attach existing policies directly. Select the policy that you created earlier and choose Next:
Review.
8. Choose Add permissions.
You can configure your Spot Fleet to replace unhealthy instances. After enabling health check
replacement, an instance is replaced after its health status is reported as unhealthy. The Spot Fleet
could go below its target capacity for up to a few minutes while an unhealthy instance is being replaced.
Requirements
• Health check replacement is supported only with Spot Fleets that maintain a target capacity, not with
one-time Spot Fleets.
322
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
• You can configure your Spot Fleet to replace unhealthy instances only when you create it.
• IAM users can use health check replacement only if they have permission to call the
ec2:DescribeInstanceStatus action.
• Determine whether you want to create a Spot Fleet that submits a one-time request for the desired
target capacity, or one that maintains a target capacity over time.
• Determine the instance types that meet your application requirements.
• Determine the target capacity for your Spot Fleet request. You can set the target capacity in instances
or in custom units. For more information, see Spot Fleet Instance Weighting (p. 304).
• Determine what portion of the Spot Fleet target capacity must be On-Demand capacity. You can
specify 0 for On-Demand capacity.
• Determine your price per unit, if you are using instance weighting. To calculate the price per unit,
divide the price per instance hour by the number of units (or weight) that this instance represents. If
you are not using instance weighting, the default price per unit is the price per instance hour.
• Review the possible options for your Spot Fleet request. For more information, see the request-spot-
fleet command in the AWS CLI Command Reference. For additional examples, see Spot Fleet Example
Configurations (p. 330).
Amazon EC2 uses the service-linked role named AWSServiceRoleForEC2SpotFleet to launch and
manage Spot Instances on your behalf.
Under most circumstances, you don't need to manually create a service-linked role. Amazon EC2 creates
the AWSServiceRoleForEC2SpotFleet service-linked role the first time you create a Spot Fleet using the
console.
323
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
If you had an active Spot Fleet request before October 2017, when Amazon EC2 began supporting this
service-linked role, Amazon EC2 created the AWSServiceRoleForEC2SpotFleet role in your AWS account.
For more information, see A New Role Appeared in My Account in the IAM User Guide.
Ensure that this role exists before you use the AWS CLI or an API to create a Spot Fleet. To create the
role, use the IAM console as follows.
If you no longer need to use Spot Fleet, we recommend that you delete the
AWSServiceRoleForEC2SpotFleet role. After this role is deleted from your account, Amazon EC2 will
create the role again if you request a Spot Fleet.
Granting Access to CMKs for Use with Encrypted AMIs and EBS Snapshots
If you specify an encrypted AMI (p. 149) or an encrypted Amazon EBS snapshot (p. 903) in your Spot
Fleet request and you use a customer managed customer master key (CMK) for encryption, you must
grant the AWSServiceRoleForEC2SpotFleet role permission to use the CMK so that Amazon EC2 can
launch Spot Instances on your behalf. To do this, you must add a grant to the CMK, as shown in the
following procedure.
When providing permissions, grants are an alternative to key policies. For more information, see Using
Grants and Using Key Policies in AWS KMS in the AWS Key Management Service Developer Guide.
• Use the create-grant command to add a grant to the CMK and to specify the principal (the
AWSServiceRoleForEC2SpotFleet service-linked role) that is given permission to perform the
operations that the grant permits. The CMK is specified by the key-id parameter and the ARN of
the CMK. The principal is specified by the grantee-principal parameter and the ARN of the
AWSServiceRoleForEC2SpotFleet service-linked role.
324
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
• For as specs, specify the required number of vCPUs and amount of memory.
• For as an instance type, accept the default instance type, or choose Change instance type to
choose a different instance type.
5. Under Tell us how much capacity you need, for Total target capacity, specify the number of units
to request for target capacity. You can choose instances or vCPUs.
6. Review the recommended Fleet request settings based on your application or task selection, and
choose Launch.
You can create a Spot Fleet using the parameters that you define.
a. (Optional) For Launch template, choose a launch template. The launch template must specify
an Amazon Machine Image (AMI), as you cannot override the AMI using Spot Fleet if you specify
a launch template.
Important
If you intend to specify Optional On-Demand portion, you must choose a launch
template.
b. For AMI, choose one of the basic AMIs provided by AWS, or choose Search for AMI to use an
AMI from our user community, the AWS Marketplace, or one of your own.
c. For Minimum compute unit, choose the minimum hardware specifications (vCPUs, memory,
and storage) that you need for your application or task, either as specs or as an instance type.
• For as specs, specify the required number of vCPUs and amount of memory.
• For as an instance type, accept the default instance type, or choose Change instance type to
choose a different instance type.
d. (Optional) For Network, choose an existing VPC or create a new one.
325
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
[New VPC] Choose Create new VPC to go the Amazon VPC console. When you are done, return
to the wizard and refresh the list.
e. (Optional) For Availability Zone, let AWS choose the Availability Zones for your Spot Instances,
or specify one or more Availability Zones.
If you have more than one subnet in an Availability Zone, choose the appropriate subnet from
Subnet. To add subnets, choose Create new subnet to go to the Amazon VPC console. When
you are done, return to the wizard and refresh the list.
f. (Optional) For Key pair name, choose an existing key pair or create a new one.
[New key pair] Choose Create new key pair to go the Amazon VPC console. When you are done,
return to the wizard and refresh the list.
5. (Optional) For Additional configurations, do the following:
a. (Optional) To add storage, specify additional instance store volumes or Amazon EBS volumes,
depending on the instance type.
b. (Optional) To enable Amazon EBS optimization, for EBS-optimized, choose Launch EBS-
optimized instances.
c. (Optional) To add temporary block-level storage for your instances, for Instance store, choose
Attach at launch.
d. (Optional) By default, basic monitoring is enabled for your instances. To enable detailed
monitoring, for Monitoring, choose Enable CloudWatch detailed monitoring.
e. (Optional) To replace unhealthy instances, for Health check, choose Replace unhealthy
instances. To enable this option, you must first choose Maintain target capacity.
f. (Optional) To run a Dedicated Spot Instance, for Tenancy, choose Dedicated - run a dedicated
instance.
g. (Optional) For Security groups, choose one or more security groups or create a new one.
[New security group] Choose Create new security group to go the Amazon VPC console. When
you are done, return to the wizard and refresh the list.
h. (Optional) To make your instances reachable from the internet, for Auto-assign IPv4 Public IP,
choose Enable.
i. (Optional) To launch your Spot Instances with an IAM role, for IAM instance profile, choose the
role .
j. (Optional) To run a start-up script, copy it to User data.
k. (Optional) To add a tag, choose Add new tag and enter the key and value for the tag. Repeat for
each tag.
6. For Tell us how much capacity you need, do the following:
a. For Total target capacity, specify the number of units to request for target capacity. You can
choose instances or vCPUs. To specify a target capacity of 0 so that you can add capacity later,
choose Maintain target capacity.
b. (Optional) For Optional On-Demand portion, specify the number of On-Demand units to
request. The number must be less than the Total target capacity. Amazon EC2 calculates the
difference, and allocates the difference to Spot units to request.
Important
To specify an optional On-Demand portion, you must first choose a launch template.
c. (Optional) By default, the Spot service terminates Spot Instances when they are interrupted. To
maintain the target capacity, choose Maintain target capacity. You can then specify that the
326
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
Spot service terminates, stops, or hibernates Spot Instances when they are interrupted. To do
so, choose the corresponding option from Interruption behavior.
7. For Fleet request settings, do the following:
a. Review the fleet request and fleet allocation strategy based on your application or task
selection. To change the instance types or allocation strategy, clear Apply recommendations.
b. (Optional) To remove instance types, for Fleet request, choose Remove. To add instance types,
choose Select instance types.
c. (Optional) For Fleet allocation strategy, choose the strategy that meets your needs. For more
information, see Allocation Strategy for Spot Instances (p. 302).
8. For Additional request details, do the following:
a. Review the additional request details. To make changes, clear Apply defaults.
b. (Optional) For IAM fleet role, you can use the default role or choose a different role. To use the
default role after changing the role, choose Use default role.
c. (Optional) For Maximum price, you can use the default maximum price (the On-Demand price)
or specify the maximum price you are willing to pay. If your maximum price is lower than the
Spot price for the instance types that you selected, your Spot Instances are not launched.
d. (Optional) To create a request that is valid only during a specific time period, edit Request valid
from and Request valid until.
e. (Optional) By default, we terminate your Spot Instances when the request expires. To keep them
running after your request expires, clear Terminate the instances when the request expires.
f. (Optional) To register your Spot Instances with a load balancer, choose Receive traffic from one
or more load balancers and choose one or more Classic Load Balancers or target groups.
9. (Optional) To download a copy of the launch configuration for use with the AWS CLI, choose JSON
config.
10. Choose Launch.
The Spot Fleet request type is fleet. When the request is fulfilled, requests of type instance are
added, where the state is active and the status is fulfilled.
For example configuration files, see Spot Fleet Example Configurations (p. 330).
{
"SpotFleetRequestId": "sfr-73fbd2ce-aa30-494c-8788-1cee4EXAMPLE"
}
327
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
Use the following describe-spot-fleet-requests command to describe your Spot Fleet requests:
Use the following describe-spot-fleet-instances command to describe the Spot Instances for the
specified Spot Fleet:
Use the following describe-spot-fleet-request-history command to describe the history for the specified
Spot Fleet request:
Note
You can't modify a one-time Spot Fleet request. You can only modify a Spot Fleet request if you
selected Maintain target capacity when you created the Spot Fleet request.
You can only modify the Spot Instance portion of a Spot Fleet request; you can't modify the On-
Demand Instance portion of a Spot Fleet request.
When you increase the target capacity, the Spot Fleet launches the additional Spot Instances according
to the allocation strategy for its Spot Fleet request. If the allocation strategy is lowestPrice, the Spot
Fleet launches the instances from the lowest-priced Spot Instance pool in the Spot Fleet request. If the
allocation strategy is diversified, the Spot Fleet distributes the instances across the pools in the Spot
Fleet request.
When you decrease the target capacity, the Spot Fleet cancels any open requests that exceed the new
target capacity. You can request that the Spot Fleet terminate Spot Instances until the size of the fleet
reaches the new target capacity. If the allocation strategy is lowestPrice, the Spot Fleet terminates
the instances with the highest price per unit. If the allocation strategy is diversified, the Spot Fleet
terminates instances across the pools. Alternatively, you can request that the Spot Fleet keep the fleet at
its current size, but not replace any Spot Instances that are interrupted or that you terminate manually.
When a Spot Fleet terminates an instance because the target capacity was decreased, the instance
receives a Spot Instance interruption notice.
328
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
Use the following modify-spot-fleet-request command to update the target capacity of the specified
Spot Fleet request:
You can modify the previous command as follows to decrease the target capacity of the specified Spot
Fleet without terminating any Spot Instances as a result:
Use the following cancel-spot-fleet-requests command to cancel the specified Spot Fleet request and
terminate the instances:
{
"SuccessfulFleetRequests": [
{
329
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
"SpotFleetRequestId": "sfr-73fbd2ce-aa30-494c-8788-1cee4EXAMPLE",
"CurrentSpotFleetRequestState": "cancelled_terminating",
"PreviousSpotFleetRequestState": "active"
}
],
"UnsuccessfulFleetRequests": []
}
You can modify the previous command as follows to cancel the specified Spot Fleet request without
terminating the instances:
{
"SuccessfulFleetRequests": [
{
"SpotFleetRequestId": "sfr-73fbd2ce-aa30-494c-8788-1cee4EXAMPLE",
"CurrentSpotFleetRequestState": "cancelled_running",
"PreviousSpotFleetRequestState": "active"
}
],
"UnsuccessfulFleetRequests": []
}
1. Launch Spot Instances using the lowest-priced Availability Zone or subnet in the region (p. 330)
2. Launch Spot Instances using the lowest-priced Availability Zone or subnet in a specified list (p. 331)
3. Launch Spot Instances using the lowest-priced instance type in a specified list (p. 332)
4. Override the price for the request (p. 333)
5. Launch a Spot Fleet using the diversified allocation strategy (p. 334)
6. Launch a Spot Fleet using instance weighting (p. 336)
7. Launch a Spot Fleet with On-Demand capacity (p. 337)
Example 1: Launch Spot Instances Using the Lowest-Priced Availability Zone or Subnet in the
Region
The following example specifies a single launch specification without an Availability Zone or subnet. The
Spot Fleet launches the instances in the lowest-priced Availability Zone that has a default subnet. The
price you pay does not exceed the On-Demand price.
{
"TargetCapacity": 20,
"IamFleetRole": "arn:aws:iam::123456789012:role/aws-ec2-spot-fleet-tagging-role",
"LaunchSpecifications": [
{
"ImageId": "ami-1a2b3c4d",
"KeyName": "my-key-pair",
"SecurityGroups": [
{
330
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
"GroupId": "sg-1a2b3c4d"
}
],
"InstanceType": "m3.medium",
"IamInstanceProfile": {
"Arn": "arn:aws:iam::123456789012:instance-profile/my-iam-role"
}
}
]
}
Example 2: Launch Spot Instances Using the Lowest-Priced Availability Zone or Subnet in a
Specified List
The following examples specify two launch specifications with different Availability Zones or subnets,
but the same instance type and AMI.
Availability Zones
The Spot Fleet launches the instances in the default subnet of the lowest-priced Availability Zone that
you specified.
{
"TargetCapacity": 20,
"IamFleetRole": "arn:aws:iam::123456789012:role/aws-ec2-spot-fleet-tagging-role",
"LaunchSpecifications": [
{
"ImageId": "ami-1a2b3c4d",
"KeyName": "my-key-pair",
"SecurityGroups": [
{
"GroupId": "sg-1a2b3c4d"
}
],
"InstanceType": "m3.medium",
"Placement": {
"AvailabilityZone": "us-west-2a, us-west-2b"
},
"IamInstanceProfile": {
"Arn": "arn:aws:iam::123456789012:instance-profile/my-iam-role"
}
}
]
}
Subnets
You can specify default subnets or nondefault subnets, and the nondefault subnets can be from a
default VPC or a nondefault VPC. The Spot service launches the instances in whichever subnet is in the
lowest-priced Availability Zone.
You can't specify different subnets from the same Availability Zone in a Spot Fleet request.
{
"TargetCapacity": 20,
"IamFleetRole": "arn:aws:iam::123456789012:role/aws-ec2-spot-fleet-tagging-role",
"LaunchSpecifications": [
{
"ImageId": "ami-1a2b3c4d",
"KeyName": "my-key-pair",
"SecurityGroups": [
{
"GroupId": "sg-1a2b3c4d"
331
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
}
],
"InstanceType": "m3.medium",
"SubnetId": "subnet-a61dafcf, subnet-65ea5f08",
"IamInstanceProfile": {
"Arn": "arn:aws:iam::123456789012:instance-profile/my-iam-role"
}
}
]
}
If the instances are launched in a default VPC, they receive a public IPv4 address by default. If the
instances are launched in a nondefault VPC, they do not receive a public IPv4 address by default. Use
a network interface in the launch specification to assign a public IPv4 address to instances launched in
a nondefault VPC. When you specify a network interface, you must include the subnet ID and security
group ID using the network interface.
...
{
"ImageId": "ami-1a2b3c4d",
"KeyName": "my-key-pair",
"InstanceType": "m3.medium",
"NetworkInterfaces": [
{
"DeviceIndex": 0,
"SubnetId": "subnet-1a2b3c4d",
"Groups": [ "sg-1a2b3c4d" ],
"AssociatePublicIpAddress": true
}
],
"IamInstanceProfile": {
"Arn": "arn:aws:iam::880185128111:instance-profile/my-iam-role"
}
}
...
Example 3: Launch Spot Instances Using the Lowest-Priced Instance Type in a Specified List
The following examples specify two launch configurations with different instance types, but the same
AMI and Availability Zone or subnet. The Spot Fleet launches the instances using the specified instance
type with the lowest price.
Availability Zone
{
"TargetCapacity": 20,
"IamFleetRole": "arn:aws:iam::123456789012:role/aws-ec2-spot-fleet-tagging-role",
"LaunchSpecifications": [
{
"ImageId": "ami-1a2b3c4d",
"SecurityGroups": [
{
"GroupId": "sg-1a2b3c4d"
}
],
"InstanceType": "cc2.8xlarge",
"Placement": {
"AvailabilityZone": "us-west-2b"
}
},
{
"ImageId": "ami-1a2b3c4d",
332
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
"SecurityGroups": [
{
"GroupId": "sg-1a2b3c4d"
}
],
"InstanceType": "r3.8xlarge",
"Placement": {
"AvailabilityZone": "us-west-2b"
}
}
]
}
Subnet
{
"TargetCapacity": 20,
"IamFleetRole": "arn:aws:iam::123456789012:role/aws-ec2-spot-fleet-tagging-role",
"LaunchSpecifications": [
{
"ImageId": "ami-1a2b3c4d",
"SecurityGroups": [
{
"GroupId": "sg-1a2b3c4d"
}
],
"InstanceType": "cc2.8xlarge",
"SubnetId": "subnet-1a2b3c4d"
},
{
"ImageId": "ami-1a2b3c4d",
"SecurityGroups": [
{
"GroupId": "sg-1a2b3c4d"
}
],
"InstanceType": "r3.8xlarge",
"SubnetId": "subnet-1a2b3c4d"
}
]
}
The following examples specify a maximum price for the fleet request and maximum prices for two
of the three launch specifications. The maximum price for the fleet request is used for any launch
specification that does not specify a maximum price. The Spot Fleet launches the instances using the
instance type with the lowest price.
Availability Zone
{
"SpotPrice": "1.00",
"TargetCapacity": 30,
"IamFleetRole": "arn:aws:iam::123456789012:role/aws-ec2-spot-fleet-tagging-role",
"LaunchSpecifications": [
{
"ImageId": "ami-1a2b3c4d",
"InstanceType": "c3.2xlarge",
333
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
"Placement": {
"AvailabilityZone": "us-west-2b"
},
"SpotPrice": "0.10"
},
{
"ImageId": "ami-1a2b3c4d",
"InstanceType": "c3.4xlarge",
"Placement": {
"AvailabilityZone": "us-west-2b"
},
"SpotPrice": "0.20"
},
{
"ImageId": "ami-1a2b3c4d",
"InstanceType": "c3.8xlarge",
"Placement": {
"AvailabilityZone": "us-west-2b"
}
}
]
}
Subnet
{
"SpotPrice": "1.00",
"TargetCapacity": 30,
"IamFleetRole": "arn:aws:iam::123456789012:role/aws-ec2-spot-fleet-tagging-role",
"LaunchSpecifications": [
{
"ImageId": "ami-1a2b3c4d",
"InstanceType": "c3.2xlarge",
"SubnetId": "subnet-1a2b3c4d",
"SpotPrice": "0.10"
},
{
"ImageId": "ami-1a2b3c4d",
"InstanceType": "c3.4xlarge",
"SubnetId": "subnet-1a2b3c4d",
"SpotPrice": "0.20"
},
{
"ImageId": "ami-1a2b3c4d",
"InstanceType": "c3.8xlarge",
"SubnetId": "subnet-1a2b3c4d"
}
]
}
Availability Zone
{
"SpotPrice": "0.70",
"TargetCapacity": 30,
"AllocationStrategy": "diversified",
334
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
"IamFleetRole": "arn:aws:iam::123456789012:role/aws-ec2-spot-fleet-tagging-role",
"LaunchSpecifications": [
{
"ImageId": "ami-1a2b3c4d",
"InstanceType": "c4.2xlarge",
"Placement": {
"AvailabilityZone": "us-west-2b"
}
},
{
"ImageId": "ami-1a2b3c4d",
"InstanceType": "m3.2xlarge",
"Placement": {
"AvailabilityZone": "us-west-2b"
}
},
{
"ImageId": "ami-1a2b3c4d",
"InstanceType": "r3.2xlarge",
"Placement": {
"AvailabilityZone": "us-west-2b"
}
}
]
}
Subnet
{
"SpotPrice": "0.70",
"TargetCapacity": 30,
"AllocationStrategy": "diversified",
"IamFleetRole": "arn:aws:iam::123456789012:role/aws-ec2-spot-fleet-tagging-role",
"LaunchSpecifications": [
{
"ImageId": "ami-1a2b3c4d",
"InstanceType": "c4.2xlarge",
"SubnetId": "subnet-1a2b3c4d"
},
{
"ImageId": "ami-1a2b3c4d",
"InstanceType": "m3.2xlarge",
"SubnetId": "subnet-1a2b3c4d"
},
{
"ImageId": "ami-1a2b3c4d",
"InstanceType": "r3.2xlarge",
"SubnetId": "subnet-1a2b3c4d"
}
]
}
A best practice to increase the chance that a spot request can be fulfilled by EC2 capacity in the event
of an outage in one of the Availability Zones is to diversify across AZs. For this scenario, include each AZ
available to you in the launch specification. And, instead of using the same subnet each time, use three
unique subnets (each mapping to a different AZ).
Availability Zone
{
"SpotPrice": "0.70",
"TargetCapacity": 30,
"AllocationStrategy": "diversified",
335
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
"IamFleetRole": "arn:aws:iam::123456789012:role/aws-ec2-spot-fleet-tagging-role",
"LaunchSpecifications": [
{
"ImageId": "ami-1a2b3c4d",
"InstanceType": "c4.2xlarge",
"Placement": {
"AvailabilityZone": "us-west-2a"
}
},
{
"ImageId": "ami-1a2b3c4d",
"InstanceType": "m3.2xlarge",
"Placement": {
"AvailabilityZone": "us-west-2b"
}
},
{
"ImageId": "ami-1a2b3c4d",
"InstanceType": "r3.2xlarge",
"Placement": {
"AvailabilityZone": "us-west-2c"
}
}
]
}
Subnet
{
"SpotPrice": "0.70",
"TargetCapacity": 30,
"AllocationStrategy": "diversified",
"IamFleetRole": "arn:aws:iam::123456789012:role/aws-ec2-spot-fleet-tagging-role",
"LaunchSpecifications": [
{
"ImageId": "ami-1a2b3c4d",
"InstanceType": "c4.2xlarge",
"SubnetId": "subnet-1a2b3c4d"
},
{
"ImageId": "ami-1a2b3c4d",
"InstanceType": "m3.2xlarge",
"SubnetId": "subnet-2a2b3c4d"
},
{
"ImageId": "ami-1a2b3c4d",
"InstanceType": "r3.2xlarge",
"SubnetId": "subnet-3a2b3c4d"
}
]
}
If the r3.2xlarge request is successful, Spot provisions 4 of these instances. Divide 20 by 6 for a total
of 3.33 instances, then round up to 4 instances.
336
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
If the c3.xlarge request is successful, Spot provisions 7 of these instances. Divide 20 by 3 for a total of
6.66 instances, then round up to 7 instances.
For more information, see Spot Fleet Instance Weighting (p. 304).
Availability Zone
{
"SpotPrice": "0.70",
"TargetCapacity": 20,
"IamFleetRole": "arn:aws:iam::123456789012:role/aws-ec2-spot-fleet-tagging-role",
"LaunchSpecifications": [
{
"ImageId": "ami-1a2b3c4d",
"InstanceType": "r3.2xlarge",
"Placement": {
"AvailabilityZone": "us-west-2b"
},
"WeightedCapacity": 6
},
{
"ImageId": "ami-1a2b3c4d",
"InstanceType": "c3.xlarge",
"Placement": {
"AvailabilityZone": "us-west-2b"
},
"WeightedCapacity": 3
}
]
}
Subnet
{
"SpotPrice": "0.70",
"TargetCapacity": 20,
"IamFleetRole": "arn:aws:iam::123456789012:role/aws-ec2-spot-fleet-tagging-role",
"LaunchSpecifications": [
{
"ImageId": "ami-1a2b3c4d",
"InstanceType": "r3.2xlarge",
"SubnetId": "subnet-1a2b3c4d",
"WeightedCapacity": 6
},
{
"ImageId": "ami-1a2b3c4d",
"InstanceType": "c3.xlarge",
"SubnetId": "subnet-1a2b3c4d",
"WeightedCapacity": 3
}
]
}
To ensure that you always have instance capacity, you can include a request for On-Demand capacity in
your Spot Fleet request. If there is capacity, the On-Demand request is always fulfilled. The balance of
the target capacity is fulfilled as Spot if there is capacity and availability.
The following example specifies the desired target capacity as 10, of which 5 must be On-Demand
capacity. Spot capacity is not specified; it is implied in the balance of the target capacity minus the On-
337
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
Demand capacity. Amazon EC2 launches 5 capacity units as On-Demand, and 5 capacity units (10-5=5) as
Spot if there is available Amazon EC2 capacity and availability.
{
"IamFleetRole": "arn:aws:iam::781603563322:role/aws-ec2-spot-fleet-tagging-role",
"AllocationStrategy": "lowestPrice",
"TargetCapacity": 10,
"SpotPrice": null,
"ValidFrom": "2018-04-04T15:58:13Z",
"ValidUntil": "2019-04-04T15:58:13Z",
"TerminateInstancesWithExpiration": true,
"LaunchSpecifications": [],
"Type": "maintain",
"OnDemandTargetCapacity": 5,
"LaunchTemplateConfigs": [
{
"LaunchTemplateSpecification": {
"LaunchTemplateId": "lt-0dbb04d4a6cca5ad1",
"Version": "2"
},
"Overrides": [
{
"InstanceType": "t2.medium",
"WeightedCapacity": 1,
"SubnetId": "subnet-d0dc51fb"
}
]
}
]
}
For more information about CloudWatch metrics provided by Amazon EC2, see Monitoring Your
Instances Using CloudWatch (p. 558).
Metric Description
AvailableInstancePoolsCount The Spot Instance pools specified in the Spot Fleet request.
Units: Count
BidsSubmittedForCapacity The capacity for which Amazon EC2 has submitted bids.
Units: Count
338
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
Metric Description
EligibleInstancePoolCount The Spot Instance pools specified in the Spot Fleet request
where Amazon EC2 can fulfill bids. Amazon EC2 does not fulfill
bids in pools where your bid price is less than the Spot price
or the Spot price is greater than the price for On-Demand
Instances.
Units: Count
Units: Count
Units: Percent
Units: Count
Units: Percent
Units: Count
Units: Count
If the unit of measure for a metric is Count, the most useful statistic is Average.
Dimensions Description
339
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
Metrics are grouped first by namespace, and then by the various combinations of dimensions within each
namespace. For example, you can view all Spot Fleet metrics or Spot Fleet metrics groups by Spot Fleet
request ID, instance type, or Availability Zone.
If you are using instance weighting, keep in mind that Spot Fleet can exceed the target capacity as
needed. Fulfilled capacity can be a floating-point number but target capacity must be an integer, so Spot
Fleet rounds up to the next integer. You must take these behaviors into account when you look at the
outcome of a scaling policy when an alarm is triggered. For example, suppose that the target capacity
is 30, the fulfilled capacity is 30.1, and the scaling policy subtracts 1. When the alarm is triggered, the
automatic scaling process subtracts 1 from 30.1 to get 29.1 and then rounds it up to 30, so no scaling
action is taken. As another example, suppose that you selected instance weights of 2, 4, and 8, and a
target capacity of 10, but no weight 2 instances were available so Spot Fleet provisioned instances of
weights 4 and 8 for a fulfilled capacity of 12. If the scaling policy decreases target capacity by 20% and
an alarm is triggered, the automatic scaling process subtracts 12*0.2 from 12 to get 9.6 and then rounds
it up to 10, so no scaling action is taken.
You can also configure the cooldown period for a scaling policy. This is the number of seconds after a
scaling activity completes where previous trigger-related scaling activities can influence future scaling
events. For scale-out policies, while the cooldown period is in effect, the capacity that has been added by
the previous scale-out event that initiated the cooldown is calculated as part of the desired capacity for
the next scale out. The intention is to continuously (but not excessively) scale out. For scale in policies,
the cooldown period is used to block subsequent scale in requests until it has expired. The intention is
to scale in conservatively to protect your application's availability. However, if another alarm triggers a
340
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
scale-out policy during the cooldown period after a scale-in, automatic scaling scales out your scalable
target immediately.
You can create multiple target tracking scaling policies for a Spot Fleet, provided that each of them
uses a different metric. The fleet scales based on the policy that provides the largest fleet capacity. This
enables you to cover multiple scenarios and ensure that there is always enough capacity to process your
application workloads.
To ensure application availability, the fleet scales out proportionally to the metric as fast as it can, but
scales in more gradually.
When a Spot Fleet terminates an instance because the target capacity was decreased, the instance
receives a Spot Instance interruption notice.
Do not edit or delete the CloudWatch alarms that Spot Fleet manages for a target tracking scaling policy.
Spot Fleet deletes the alarms automatically when you delete the target tracking scaling policy.
Limits
• The Spot Fleet request must have a request type of maintain. Automatic scaling is not supported for
one-time requests or Spot blocks.
341
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
10. (Optional) Select Disable scale-in to omit creating a scale-in policy based on the current
configuration. You can create a scale-in policy using a different configuration.
11. Choose Save.
1. Register the Spot Fleet request as a scalable target using the register-scalable-target command.
2. Create a scaling policy using the put-scaling-policy command.
When you create a step scaling policy, you must specify one of the following scaling adjustment types:
• Add – Increase the target capacity of the fleet by a specified number of capacity units or a specified
percentage of the current capacity.
• Remove – Decrease the target capacity of the fleet by a specified number of capacity units or a
specified percentage of the current capacity.
• Set to – Set the target capacity of the fleet to the specified number of capacity units.
When an alarm is triggered, the automatic scaling process calculates the new target capacity using the
fulfilled capacity and the scaling policy, and then updates the target capacity accordingly. For example,
suppose that the target capacity and fulfilled capacity are 10 and the scaling policy adds 1. When
the alarm is triggered, the automatic scaling process adds 1 to 10 to get 11, so Spot Fleet launches 1
instance.
When a Spot Fleet terminates an instance because the target capacity was decreased, the instance
receives a Spot Instance interruption notice.
Limits
• The Spot Fleet request must have a request type of maintain. Automatic scaling is not supported for
one-time requests or Spot blocks.
Prerequisites
• Consider which CloudWatch metrics are important to your application. You can create CloudWatch
alarms based on metrics provided by AWS or your own custom metrics.
• For the AWS metrics that you will use in your scaling policies, enable CloudWatch metrics collection if
the service that provides the metrics does not enable it by default.
• If you use the AWS Management Console to enable automatic scaling for your Spot Fleet, it creates
a role named aws-ec2-spot-fleet-autoscale-role that grants Amazon EC2 Auto Scaling
permission to describe the alarms for your policies, monitor the current capacity of the fleet, and
modify the capacity of the fleet. If you configure automatic scaling using the AWS CLI or an API, you
can use this role if it exists, or manually create your own role for this purpose.
342
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
To configure step scaling policies for your Spot Fleet using the AWS CLI
1. Register the Spot Fleet request as a scalable target using the register-scalable-target command.
343
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
Limits
• The Spot Fleet request must have a request type of maintain. Automatic scaling is not supported for
one-time requests or Spot blocks.
344
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
• put-scheduled-action
• describe-scheduled-actions
• delete-scheduled-action
At each step of the process—also called the Spot request lifecycle, specific events determine successive
request states.
Contents
• Life Cycle of a Spot Request (p. 345)
• Getting Request Status Information (p. 349)
• Spot Request Status Codes (p. 349)
345
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
Pending evaluation
As soon as you make a Spot Instance request, it goes into the pending-evaluation state unless one or
more request parameters are not valid (bad-parameters).
Holding
If one or more request constraints are valid but can't be met yet, or if there is not enough capacity, the
request goes into a holding state waiting for the constraints to be met. The request options affect the
likelihood of the request being fulfilled. For example, if you specify a maximum price below the current
Spot price, your request stays in a holding state until the Spot price goes below your maximum price.
If you specify an Availability Zone group, the request stays in a holding state until the Availability Zone
constraint is met.
In the event of an outage of one of the Availability Zones, there is a chance that the spare EC2 capacity
available for Spot instance requests in other Availability Zones can be affected.
346
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
Pending evaluation/fulfillment-terminal
Your Spot Instance request can go to a terminal state if you create a request that is valid only during
a specific time period and this time period expires before your request reaches the pending fulfillment
phase. It might also happen if you cancel the request, or if a system error occurs.
Pending fulfillment
When the constraints you specified (if any) are met and your maximum price is equal to or higher than
the current Spot price, your Spot request goes into the pending-fulfillment state.
At this point, Amazon EC2 is getting ready to provision the instances that you requested. If the process
stops at this point, it is likely to be because it was canceled by the user before a Spot Instance was
launched. It may also be because an unexpected system error occurred.
Fulfilled
When all the specifications for your Spot Instances are met, your Spot request is fulfilled. Amazon
EC2 launches the Spot Instances, which can take a few minutes. If a Spot Instance is hibernated or
stopped when interrupted, it remains in this state until the request can be fulfilled again or the request is
canceled.
347
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
Fulfilled-terminal
Your Spot Instances continue to run as long as your maximum price is at or above the Spot price, there
is available capacity for your instance type, and you don't terminate the instance. If a change in the
Spot price or available capacity requires Amazon EC2 to terminate your Spot Instances, the Spot request
goes into a terminal state. For example, if your price equals the Spot price but Spot Instances are not
available, the status code is instance-terminated-capacity-oversubscribed. A request also
goes into the terminal state if you cancel the Spot request or terminate the Spot Instances.
† A Spot Instance can only get to this state if a user runs the shutdown command from the instance. We
do not recommend that you do this, as the Spot service might restart the instance.
* The request state is closed if you terminate the instance but do not cancel the request. The request
state is cancelled if you terminate the instance and cancel the request. Even if you terminate a Spot
Instance before you cancel its request, there might be a delay before Amazon EC2 detects that your Spot
Instance was terminated. In this case, the request state can either be closed or cancelled.
Persistent requests
348
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
When your Spot Instances are terminated (either by you or Amazon EC2), if the Spot request is a
persistent request, it returns to the pending-evaluation state and then Amazon EC2 can launch a
new Spot Instance when the constraints are met.
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
az-group-constraint
Amazon EC2 cannot launch all the instances you requested in the same Availability Zone.
bad-parameters
One or more parameters for your Spot request are not valid (for example, the AMI you specified does
not exist). The status message indicates which parameter is not valid.
cancelled-before-fulfillment
There is not enough capacity available for the instances that you requested.
capacity-oversubscribed
There is not enough capacity available for the instances that you requested.
constraint-not-fulfillable
The Spot request can't be fulfilled because one or more constraints are not valid (for example, the
Availability Zone does not exist). The status message indicates which constraint is not valid.
fulfilled
The Spot request is active, and Amazon EC2 is launching your Spot Instances.
instance-stopped-by-price
Your instance was stopped because the Spot price exceeded your maximum price.
349
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
instance-stopped-by-user
Your instance was stopped because a user ran shutdown -h from the instance.
instance-stopped-capacity-oversubscribed
Your instance was stopped because the number of Spot requests with maximum prices equal to or
higher than the Spot price exceeded the available capacity in this Spot Instance pool. The Spot price
might not have changed.
instance-stopped-no-capacity
Your instance was stopped because there was no longer enough Spot capacity available for the
instance.
instance-terminated-by-price
Your instance was terminated because the Spot price exceeded your maximum price. If your request
is persistent, the process restarts, so your request is pending evaluation.
instance-terminated-by-schedule
Your Spot Instance was terminated at the end of its scheduled duration.
instance-terminated-by-service
You terminated a Spot Instance that had been fulfilled, so the request state is closed (unless it's a
persistent request) and the instance state is terminated.
instance-terminated-capacity-oversubscribed
Your instance was terminated because the number of Spot requests with maximum prices equal to
or higher than the Spot price exceeded the available capacity in this Spot Instance pool. The Spot
price might not have changed.
instance-terminated-launch-group-constraint
One or more of the instances in your launch group was terminated, so the launch group constraint is
no longer fulfilled.
instance-terminated-no-capacity
Your instance was terminated because there is no longer enough Spot capacity available for the
instance.
launch-group-constraint
Amazon EC2 cannot launch all the instances that you requested at the same time. All instances in a
launch group are started and terminated together.
limit-exceeded
The limit on the number of EBS volumes or total volume storage was exceeded. For more
information about these limits and how to request an increase, see Amazon EBS Limits in the
Amazon Web Services General Reference.
marked-for-stop
350
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
pending-evaluation
After you make a Spot Instance request, it goes into the pending-evaluation state while the
system evaluates the parameters of your request.
pending-fulfillment
The Spot request can't be fulfilled yet because a Spot Instance can't be added to the placement
group at this time.
price-too-low
The request can't be fulfilled yet because your maximum price is below the Spot price. In this case,
no instance is launched and your request remains open.
request-canceled-and-instance-running
You canceled the Spot request while the Spot Instances are still running. The request is cancelled,
but the instances remain running.
schedule-expired
The Spot request expired because it was not fulfilled before the specified date.
system-error
There was an unexpected system error. If this is a recurring issue, please contact AWS Support for
assistance.
Contents
• Reasons for Interruption (p. 351)
• Interruption Behavior (p. 352)
• Preparing for Interruptions (p. 354)
• Preparing for Instance Hibernation (p. 354)
• Spot Instance Interruption Notices (p. 355)
351
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
Interruption Behavior
You can specify whether Amazon EC2 should hibernate, stop, or terminate Spot Instances when they are
interrupted. You can choose the interruption behavior that meets your needs. The default is to terminate
Spot Instances when they are interrupted. To change the interruption behavior, choose an option from
Interruption behavior in the console or InstanceInterruptionBehavior in the launch configuration
or the launch template.
You can change the behavior so that Amazon EC2 stops Spot Instances when they are interrupted if the
following requirements are met.
Requirements
• For a Spot Instance request, the type must be persistent. You cannot specify a launch group in the
Spot Instance request.
• For an EC2 Fleet or Spot Fleet request, the type must be maintain.
• The root volume must be an EBS volume, not an instance store volume.
After a Spot Instance is stopped by the Spot service, only the Spot service can restart the Spot Instance,
and the same launch specification must be used.
For a Spot Instance launched by a persistent Spot Instance request, the Spot service restarts the
stopped instance when capacity is available in the same Availability Zone and for the same instance type
as the stopped instance.
If instances in an EC2 Fleet or Spot Fleet are stopped and the fleet is of type maintain, the Spot
service launches replacement instances to maintain the target capacity. The Spot service finds
the best pool(s) based on the specified allocation strategy (lowestPrice, diversified, or
InstancePoolsToUseCount); it does not prioritize the pool with the earlier stopped instances. Later, if
the allocation strategy leads to a pool containing the earlier stopped instances, the Spot service restarts
the stopped instances to meet the target capacity.
For example, consider a Spot Fleet with the lowestPrice allocation strategy. At initial launch, a
c3.large pool meets the lowestPrice criteria for the launch specification. Later, when the c3.large
instances are interrupted, the Spot service stops the instances and replenishes capacity from another
pool that fits the lowestPrice strategy. This time, the pool happens to be a c4.large pool and the
Spot service launches c4.large instances to meet the target capacity. Similarly, Spot Fleet could move
to a c5.large pool the next time. In each of these transitions, the Spot service does not prioritize pools
with earlier stopped instances, but rather prioritizes purely on the specified allocation strategy. The
lowestPrice strategy can lead back to pools with earlier stopped instances. For example, if instances
are interrupted in the c5.large pool and the lowestPrice strategy leads it back to the c3.large or
c4.large pools, the earlier stopped instances are restarted to fulfil target capacity.
While a Spot Instance is stopped, you can modify some of its instance attributes, but not the instance
type. If you detach or delete an EBS volume, it is not attached when the Spot Instance is started. If you
detach the root volume and the Spot service attempts to start the Spot Instance, instance start fails and
the Spot service terminates the stopped instance.
You can terminate a Spot Instance while it is stopped. If you cancel a Spot request, an EC2 Fleet, or a
Spot Fleet, the Spot service terminates any associated Spot Instances that are stopped.
While a Spot Instance is stopped, you are charged only for the EBS volumes, which are preserved. With
EC2 Fleet and Spot Fleet, if you have many stopped instances, you can exceed the limit on the number of
EBS volumes for your account.
352
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
You can change the behavior so that Amazon EC2 hibernates Spot Instances when they are interrupted if
the following requirements are met.
Requirements
• For a Spot Instance request, the type must be persistent. You cannot specify a launch group in the
Spot Instance request.
• For an EC2 Fleet or Spot Fleet request, the type must be maintain.
• The root volume must be an EBS volume, not an instance store volume, and it must be large enough to
store the instance memory (RAM) during hibernation.
• The following instances are supported: C3, C4, C5, M4, M5, R3, and R4, with less than 100 GB of
memory.
• The following operating systems are supported: Amazon Linux 2, Amazon Linux AMI, Ubuntu with an
AWS-tuned Ubuntu kernel (linux-aws) greater than 4.4.0-1041, and Windows Server 2008 R2 and later.
• Install the hibernation agent on a supported operating system, or use one of the following AMIs, which
already include the agent:
• Amazon Linux 2
• Amazon Linux AMI 2017.09.1 or later
• Ubuntu Xenial 16.04 20171121 or later
• Windows Server 2008 R2 AMI 2017.11.19 or later
• Windows Server 2012 or Windows Server 2012 R2 AMI 2017.11.19 or later
• Windows Server 2016 AMI 2017.11.19 or later
• Windows Server 2019
• Start the agent. We recommend that you use user data to start the agent on instance startup.
Alternatively, you could start the agent manually.
Recommendation
• We strongly recommend that you use an encrypted Amazon EBS volume as the root volume, because
instance memory is stored on the root volume during hibernation. This ensures that the contents
of memory (RAM) are encrypted when the data is at rest on the volume and when data is moving
between the instance and volume. Use one of the following three options to ensure that the root
volume is an encrypted Amazon EBS volume:
• EBS “single-step” encryption: In a single run-instances API call, you can launch encrypted EBS-
backed EC2 instances from an unencrypted AMI. For more information, see Using Encryption with
EBS-Backed AMIs (p. 149).
• EBS encryption by default: You can enable EBS encryption by default to ensure all new EBS
volumes created in your AWS account are encrypted. For more information, see Encryption by
Default (p. 904).
• Encrypted AMI: You can enable EBS encryption by using an encrypted AMI to launch your instance.
If your AMI does not have an encrypted root snapshot, you can copy it to a new AMI and request
encryption. For more information, see Encrypt an Unencrypted Image during Copy (p. 153) and
Copying an AMI (p. 157).
When a Spot Instance is hibernated by the Spot service, the EBS volumes are preserved and instance
memory (RAM) is preserved on the root volume. The private IP addresses of the instance are also
preserved. Instance storage volumes and public IP addresses, other than Elastic IP addresses, are not
preserved. While the instance is hibernating, you are charged only for the EBS volumes. With EC2 Fleet
and Spot Fleet, if you have many hibernated instances, you can exceed the limit on the number of EBS
volumes for your account.
353
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
The agent prompts the operating system to hibernate when the instance receives a signal from the Spot
service. If the agent is not installed, the underlying operating system doesn't support hibernation, or
there isn't enough volume space to save the instance memory, hibernation fails and the Spot service
stops the instance instead.
When the Spot service hibernates a Spot Instance, you receive an interruption notice, but you do not
have two minutes before the Spot Instance is interrupted. Hibernation begins immediately. While the
instance is in the process of hibernating, instance health checks might fail. When the hibernation process
completes, the state of the instance is stopped.
After a Spot Instance is hibernated by the Spot service, it can only be resumed by the Spot service. The
Spot service resumes the instance when capacity becomes available with a Spot price that is less than
your specified maximum price.
For more information, see Preparing for Instance Hibernation (p. 354).
For information about hibernating On-Demand Instances, see Hibernate Your Instance (p. 470).
The following procedures help you prepare a Linux instance. For directions to prepare a Windows
instance, see Preparing for Instance Hibernation in the Amazon EC2 User Guide for Windows Instances.
1. Verify that your kernel supports hibernation and update the kernel if necessary.
2. If your AMI doesn't include the agent, install the agent using the following command:
✔!/bin/bash
354
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
/usr/bin/enable-ec2-spot-hibernation
1. If your AMI doesn't include the agent, install the agent using the following command:
✔!/bin/bash
/usr/bin/enable-ec2-spot-hibernation
This warning is made available as a CloudWatch event and as an item in the instance metadata (p. 526)
on the Spot Instance.
If you specify hibernation as the interruption behavior, you receive an interruption notice, but you do not
receive a two-minute warning because the hibernation process begins immediately.
The following is an example of the event for Spot Instance interruption. The possible values for
instance-action are hibernate, stop, and terminate.
{
"version": "0",
"id": "12345678-1234-1234-1234-123456789012",
"detail-type": "EC2 Spot Instance Interruption Warning",
"source": "aws.ec2",
"account": "123456789012",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "us-east-2",
"resources": ["arn:aws:ec2:us-east-2:123456789012:instance/i-1234567890abcdef0"],
"detail": {
"instance-id": "i-1234567890abcdef0",
"instance-action": "action"
}
}
instance-action
If your Spot Instance is marked to be stopped or terminated by the Spot service, the instance-action
item is present in your instance metadata. Otherwise, it is not present. You can retrieve instance-
action as follows.
355
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
The instance-action item specifies the action and the approximate time, in UTC, when the action will
occur.
The following example indicates the time at which this instance will be stopped:
The following example indicates the time at which this instance will be terminated:
If Amazon EC2 is not preparing to stop or terminate the instance, or if you terminated the instance
yourself, instance-action is not present and you receive an HTTP 404 error.
termination-time
This item is maintained for backward compatibility; you should use instance-action instead.
If your Spot Instance is marked for termination by the Spot service, the termination-time item is
present in your instance metadata. Otherwise, it is not present. You can retrieve termination-time as
follows.
The termination-time item specifies the approximate time in UTC when the instance receives the
shutdown signal. For example:
2015-01-05T18:02:00Z
If Amazon EC2 is not preparing to terminate the instance, or if you terminated the Spot Instance yourself,
the termination-time item is either not present (so you receive an HTTP 404 error) or contains a
value that is not a time value.
If Amazon EC2 fails to terminate the instance, the request status is set to fulfilled. The
termination-time value remains in the instance metadata with the original approximate time, which
is now in the past.
Data feed files arrive in your bucket typically once an hour, and each hour of usage is typically covered in
a single data file. These files are compressed (gzip) before they are delivered to your bucket. Amazon EC2
can write multiple files for a given hour of usage where files are large (for example, when file contents
for the hour exceed 50 MB before compression).
Note
If you don't have a Spot Instance running during a certain hour, you don't receive a data feed file
for that hour.
Contents
• Data Feed File Name and Format (p. 357)
356
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
bucket-name.s3.amazonaws.com/{optional prefix}/aws-account-id.YYYY-MM-DD-HH.n.unique-id.gz
For example, if your bucket name is myawsbucket and your prefix is myprefix, your file names are
similar to the following:
myawsbucket.s3.amazonaws.com/myprefix/111122223333.2014-03-17-20.001.pwBdGTJG.gz
The Spot Instance data feed files are tab-delimited. Each line in the data file corresponds to one instance
hour and contains the fields listed in the following table.
Field Description
Timestamp The timestamp used to determine the price charged for this instance usage.
UsageType The type of usage and instance type being charged for. For m1.small Spot
Instances, this field is set to SpotUsage. For all other instance types, this field is
set to SpotUsage:{instance-type}. For example, SpotUsage:c1.medium.
Operation The product being charged for. For Linux Spot Instances, this field is
set to RunInstances. For Windows Spot Instances, this field is set to
RunInstances:0002. Spot usage is grouped according to Availability Zone.
InstanceID The ID of the Spot Instance that generated this instance usage.
MyBidID The ID for the Spot Instance request that generated this instance usage.
MyMaxPrice The maximum price specified for this Spot Instance request.
MarketPrice The Spot price at the time specified in the Timestamp field.
Version The version included in the data feed file name for this record.
• You must have FULL_CONTROL permission to the bucket, which includes permission for the
s3:GetBucketAcl and s3:PutBucketAcl actions.
If you're the bucket owner, you have this permission by default. Otherwise, the bucket owner must
grant your AWS account this permission.
• When you subscribe to a data feed, these permissions are used to update the bucket ACL to give the
AWS data feed account FULL_CONTROL permission. The AWS data feed account writes data feed files
357
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot Instances
to the bucket. If your account doesn't have the required permissions, the data feed files cannot be
written to the bucket.
Note
If you update the ACL and remove the permissions for the AWS data feed account, the data
feed files cannot be written to the bucket. You must resubscribe to the data feed to receive
the data feed files.
• Each data feed file has its own ACL (separate from the ACL for the bucket). The bucket owner
has FULL_CONTROL permission to the data files. The AWS data feed account has read and write
permissions.
• If you delete your data feed subscription, Amazon EC2 doesn't remove the read and write permissions
for the AWS data feed account on either the bucket or the data files. You must remove these
permissions yourself.
{
"SpotDatafeedSubscription": {
"OwnerId": "111122223333",
"Prefix": "myprefix",
"Bucket": "myawsbucket",
"State": "Active"
}
}
Limits
• Spot Request Limits (p. 358)
• Spot Fleet Limits (p. 359)
• T3 Instances (p. 359)
• T2 Instances (p. 359)
358
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Dedicated Hosts
Spot Instance limits are dynamic. When your account is new, your limit might be lower than 20 to start,
but can increase over time. In addition, your account might have limits on specific Spot Instance types. If
you submit a Spot Instance request and you receive the error Max spot instance count exceeded,
you can complete the AWS Support Center Create case form to request a Spot Instance limit increase. For
Limit type, choose EC2 Spot Instances. For more information, see Amazon EC2 Service Limits (p. 1005).
• The number of active Spot Fleets and EC2 Fleets per Region: 1,000*
• The number of launch specifications per fleet: 50*
• The size of the user data in a launch specification: 16 KB*
• The target capacity per Spot Fleet or EC2 Fleet: 10,000
• The target capacity across all Spot Fleets and EC2 Fleets in a Region: 100,000
• A Spot Fleet request or an EC2 Fleet request can't span Regions.
• A Spot Fleet request or an EC2 Fleet request can't span different subnets from the same Availability
Zone.
If you need more than the default limits for target capacity, complete the AWS Support Center Create
case form to request a limit increase. For Limit type, choose EC2 Fleet, choose a Region, and then choose
Target Fleet Capacity per Fleet (in units) or Target Fleet Capacity per Region (in units), or both.
* These are hard limits. You cannot request a limit increase for these limits.
T3 Instances
If you plan to use your T3 Spot Instances immediately and for a short duration, with no idle time for
accruing CPU credits, we recommend that you launch your T3 Spot Instances in standard (p. 203) mode
to avoid paying higher costs.
If you launch your T3 Spot Instances in unlimited (p. 196) mode and burst CPU immediately, you'll
spend surplus credits for bursting. If you use the instance for a short duration, your instance doesn't have
time to accrue CPU credits to pay down the surplus credits, and you are charged for the surplus credits
when you terminate your instance.
Unlimited mode for T3 Spot Instances is suitable only if the instance runs for long enough to accrue
CPU credits for bursting. Otherwise, paying for surplus credits makes T3 Spot Instances more expensive
than M5 or C5 instances.
T2 Instances
Launch credits are meant to provide a productive initial launch experience for T2 instances by providing
sufficient compute resources to configure the instance. Repeated launches of T2 instances to access new
launch credits is not permitted. If you require sustained CPU, you can earn credits (by idling over some
period), use T2 Unlimited (p. 196), or use an instance type with dedicated CPU (for example, c4.large).
Dedicated Hosts
An Amazon EC2 Dedicated Host is a physical server with EC2 instance capacity fully dedicated to your
use. Dedicated Hosts allow you to use your existing per-socket, per-core, or per-VM software licenses,
including Windows Server, Microsoft SQL Server, SUSE, Linux Enterprise Server, and so on.
Contents
359
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Dedicated Hosts
There are no performance, security, or physical differences between Dedicated Instances and instances
on Dedicated Hosts. The following table highlights some of the key differences between Dedicated Hosts
and Dedicated Instances:
These are the general steps to follow in order to bring your own volume licensed machine image into
Amazon EC2.
1. Verify that the license terms controlling the use of your machine images allow usage in a virtualized
cloud environment.
360
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Dedicated Hosts
2. After you have verified that your machine image can be used within Amazon EC2, import it using VM
Import/Export. For information about how to import your machine image, see the VM Import/Export
User Guide.
3. After you import your machine image, you can launch instances from it onto active Dedicated Hosts in
your account.
4. When you run these instances, depending on the operating system, you may be required to activate
these instances against your own KMS server.
Note
To track how your images are used in AWS, enable host recording in AWS Config. You can
use AWS Config to record configuration changes to a Dedicated Host and use the output
as a data source for license reporting. For more information, see Tracking Configuration
Changes (p. 376).
• RHEL, SUSE Linux, and Windows AMIs (whether offered by AWS or on the AWS Marketplace) cannot be
used with Dedicated Hosts.
• Up to two On-Demand Dedicated Hosts per instance family, per Region can be allocated. It is possible
to request a limit increase: Request to Raise Allocation Limit on Amazon EC2 Dedicated Hosts.
• The instances that run on a Dedicated Host can only be launched in a VPC.
• Host limits are independent from instance limits. Instances that you are running on Dedicated Hosts do
not count towards your instance limits.
• Auto Scaling groups are not supported.
• Amazon RDS instances are not supported.
• The AWS Free Usage tier is not available for Dedicated Hosts.
• Instance placement control refers to managing instance launches onto Dedicated Hosts. Placement
groups are not supported for Dedicated Hosts.
The On-Demand price for a Dedicated Host varies by instance family and Region. You are charged an
hourly rate for the Dedicated Host, regardless of the quantity or the size of instances that you choose
to launch on it. In other words, you are charged for the entire Dedicated Host, and not the individual
instances that you choose to run on it. For more information about On-Demand pricing, see Amazon EC2
Dedicated Hosts On-Demand Pricing.
You can release an On-Demand Dedicated Host at any time to stop accruing charges for it. For
information about releasing a Dedicated Host, see Releasing Dedicated Hosts (p. 369).
361
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Dedicated Hosts
• No Upfront—No Upfront Reservations provide you with a discount on your Dedicated Host usage over
a term and do not require an upfront payment. Available for a one-year term only.
• Partial Upfront—A portion of the reservation must be paid upfront and the remaining hours in the
term are billed at a discounted rate. Available in one-year and three-year terms.
• All Upfront—Provides the lowest effective price. Available in one-year and three-year terms and
covers the entire cost of the term upfront, with no additional future charges.
You must have active Dedicated Hosts in your account before you can purchase reservations. Each
reservation covers a single, specific Dedicated Host in your account. Reservations are applied to the
instance family on the host, not the instance size. If you have three Dedicated Hosts with different
instances sizes (m4.xlarge, m4.medium, and m4.large) you can associate a single m4 reservation with
all those Dedicated Hosts. The instance family and Region of the reservation must match that of the
Dedicated Hosts you want to associate it with.
When a reservation is associated with a Dedicated Host, the Dedicated Host can't be released until the
reservation's term is over.
For more information about reservation pricing, see Amazon EC2 Dedicated Hosts Pricing.
If you no longer need an On-Demand host, you can stop the instances running on the host, direct them
to launch on a different host, and then release the host.
Contents
• Understanding Auto-Placement and Affinity (p. 362)
• Allocating Dedicated Hosts (p. 363)
• Launching Instances onto Dedicated Hosts (p. 364)
• Modifying Dedicated Host Auto-Placement (p. 365)
• Modifying Instance Tenancy and Affinity (p. 366)
• Viewing Dedicated Hosts (p. 367)
• Tagging Dedicated Hosts (p. 367)
• Monitoring Dedicated Hosts (p. 368)
• Releasing Dedicated Hosts (p. 369)
• Purchasing Dedicated Host Reservations (p. 370)
• Viewing Dedicated Host Reservations (p. 371)
• Tagging Dedicated Host Reservations (p. 372)
362
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Dedicated Hosts
Auto-Placement
Auto-placement allows you to manage whether instances that you launch are launched onto a specific
host, or onto any available host that has matching configurations. Auto-placement must be configured at
the host level.
When a Dedicated Host's auto-placement is disabled, it only accepts Host tenancy instance launches that
specify its unique host ID. This is the default setting for new Dedicated Hosts.
When a Dedicated Host's auto-placement is enabled, it accepts any untargeted instance launches that
match its instance type configuration.
When launching an instance, you need to configure its tenancy. Launching an instance onto a Dedicated
Host without providing a specific HostId, enables it to launch on any Dedicated Host that has auto-
placement enabled and matches its instance type.
Host Affinity
Host Affinity is configured at the instance level. It establishes a launch relationship between an instance
and a Dedicated Host.
When affinity is set to Host, an instance launched onto a specific host always restarts on the same host
if stopped. This applies to both targeted and untargeted launches.
When affinity is set to Off, and you stop and restart the instance, it can be restarted on any available
host. However, it tries to launch back onto the last Dedicated Host on which it ran (on a best-effort
basis).
a. Instance type—The type of instance that you want to launch on the Dedicated Host.
b. Availability Zone—The Availability Zone in which the Dedicated Host is located.
c. To allow the Dedicated Host to accept untargeted instance launches that match its instance
type, for Instance auto-placement, choose Enable.
Use one of the following commands. The following commands allocate a Dedicated Host that supports
untargeted m4.large instance launches in the eu-west-1a Availability Zone, enable host recovery, and
apply a tag with a key of purpose and a value of production.
363
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Dedicated Hosts
The TagSpecification parameter used to tag a Dedicated Host on creation requires an object that
specifies the type of resource to be tagged, the tag key, and the tag value. The following commands
create the required object.
The following command allocates the Dedicated Host and applies the tag specified in the $tagspec
object.
If you launch instances with host tenancy but do not have any active Dedicated Host in your account,
you receive an error and the instance launch fails.
Before you launch your instances, take note of the limitations. For more information, see Dedicated
Hosts Limitations and Restrictions (p. 361).
To launch an instance onto a specific Dedicated Host from the Dedicated Hosts page
• Off—The instance launches onto the specified host, but it is not guaranteed to restart on the
same Dedicated Host if stopped.
364
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Dedicated Hosts
For more information about Affinity, see Understanding Auto-Placement and Affinity (p. 362).
Note
The Tenancy and Host options are pre-configured based on the host that you selected.
7. Choose Review and Launch.
8. On the Review Instance Launch page, choose Launch.
9. When prompted, select an existing key pair or create a new one, and then choose Launch Instances.
To launch an instance onto a Dedicated Host using the Launch Instance wizard
For more information, see Understanding Auto-Placement and Affinity (p. 362).
Note
If you are unable to see these settings, check that you have selected a VPC in the Network
menu.
6. Choose Review and Launch.
7. On the Review Instance Launch page, choose Launch.
8. When prompted, select an existing key pair or create a new one, and then choose Launch Instances.
To launch an instance onto a Dedicated Host using the command line tools
Use one of the following commands and specify the instance affinity, tenancy, and host in the
Placement request parameter:
365
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Dedicated Hosts
Use one of the following commands. The following examples enable auto-placement for the specified
Dedicated Host.
To modify instance tenancy and affinity using the Amazon EC2 console
For more information, see Understanding Auto-Placement and Affinity (p. 362).
366
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Dedicated Hosts
6. Choose Save.
To modify instance tenancy and affinity using the command line tools
Use one of the following commands. The following examples change the specified instance's affinity
from default to host, and specify the Dedicated Host that the instance has affinity with.
To view details of instances on a Dedicated Host using the Amazon EC2 console
To view details of instances on a Dedicated Host using the command line tools
You can also apply tags to Dedicated Hosts at the time of creation. For more information, see Allocating
Dedicated Hosts (p. 363).
You can tag a Dedicated Host using the Amazon EC2 console and command line tools.
367
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Dedicated Hosts
The following command tags the specified Dedicated Host with Owner=TeamA.
The New-EC2Tag command needs a Tag object, which specifies the key and value pair to be used for
the Dedicated Host tag. The following commands create a Tag object named $tag, with a key and
value pair of Owner and TeamA respectively.
The following command tags the specified Dedicated Host with the $tag object.
To view the state of a Dedicated Host using the Amazon EC2 console
To view the state of a Dedicated Host using the command line tools
Use one of the following commands and then review the state property in the hostSet response
element:
368
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Dedicated Hosts
State Description
available AWS hasn't detected an issue with the Dedicated Host. No maintenance or
repairs are scheduled. Instances can be launched onto this Dedicated Host.
released The Dedicated Host has been released. The host ID is no longer in use.
Released hosts cannot be reused.
under-assessment AWS is exploring a possible issue with the Dedicated Host. If action must be
taken, you are notified via the AWS Management Console or email. Instances
cannot be launched onto a Dedicated Host in this state.
permanent-failure An unrecoverable failure has been detected. You receive an eviction notice
through your instances and by email. Your instances might continue to run.
If you stop or terminate all instances on a Dedicated Host with this state,
AWS retires the host. AWS does not restart instances in this state. Instances
cannot be launched onto Dedicated Hosts in this state.
released- AWS permanently releases Dedicated Hosts that have failed and no longer
permanent-failure have running instances on them. The Dedicated Host ID is no longer
available for use.
369
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Dedicated Hosts
After you release a Dedicated Host, you cannot reuse the same host or host ID again, and you are no
longer charged On-Demand billing rates for it. The Dedicated Host's state is changed to released, and
you are not able to launch any instances onto that host.
Note
If you have recently released Dedicated Hosts, it may take some time for them to stop counting
towards your limit. During this time, you may experience LimitExceeded errors when trying
to allocate new Dedicated Hosts. If this is the case, try allocating new hosts again after a few
minutes.
The instances that were stopped are still available for use and are listed on the Instances page. They
retain their host tenancy setting.
• Host instance family—The options listed correspond with the Dedicated Hosts in your account
that are not already assigned to a reservation.
• Availability Zone—The Availability Zone of the Dedicated Hosts in your account that aren't
already assigned to a reservation.
• Payment option—The payment option for the offering.
• Term—The term of the reservation, which can be one or three years.
4. Choose Find offering and select an offering that matches your requirements.
5. Choose the Dedicated Hosts to associate with the reservation, and then choose Review.
6. Review your order and choose Purchase.
1. Use one of the following commands to list the available offerings that match your needs. The
following examples list the offerings that support instances in the m4 instance family and have a
one-year term.
Note
The term is specified in seconds. A one-year term includes 31536000 seconds, and a three-
year term includes 94608000 seconds.
370
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Dedicated Hosts
Both commands return a list of offerings that match your criteria. Note the offeringId of the
offering to purchase.
2. Use one of the following commands to purchase the offering and provide the offeringId noted in
the previous step. The following examples purchase the specified reservation and associate it with a
specific Dedicated Host that is already allocated in the AWS account.
PS C:\> Get-EC2HostReservation
371
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Dedicated Hosts
You can tag a Dedicated Host Reservation using the AWS CLI only.
The New-EC2Tag command needs a Tag parameter, which specifies the key and value pair to be used
for the Dedicated Host Reservation tag. The following commands create the Tag parameter.
Host Recovery
Host recovery automatically restarts your instances on to a new replacement host if failures are detected
on your Dedicated Host. Host recovery reduces the need for manual intervention and lowers the
operational burden if there is an unexpected Dedicated Host failure.
Additionally, built-in integration with AWS License Manager automates the tracking and management of
your licenses if a host recovery occurs.
Note
AWS License Manager integration is supported only in Regions in which AWS License Manager is
available.
Contents
• Host Recovery Basics (p. 372)
• Configuring Host Recovery (p. 373)
• Host Recovery States (p. 375)
• Supported Instance Configurations (p. 375)
• Manually Recovering Unsupported Instances (p. 375)
• Related Services (p. 376)
• Pricing (p. 376)
372
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Dedicated Hosts
When a system failure is detected on your Dedicated Host, host recovery is initiated and Amazon EC2
automatically allocates a replacement Dedicated Host. The replacement Dedicated Host receives a new
host ID, but retains the same attributes as the original Dedicated Host, including:
• Availability Zone
• Instance type
• Tags
• Auto placement settings
After the replacement Dedicated Host is allocated, the instances are recovered on to the replacement
Dedicated Host. The recovered instances retain the same attributes as the original instances, including:
• Instance ID
• Private IP addresses
• Elastic IP addresses
• EBS volume attachments
• All instance metadata
If instances have a host affinity relationship with the impaired Dedicated Host, the recovered instances
establish host affinity with the replacement Dedicated Host.
When all of the instances have been recovered on to the replacement Dedicated Host, the impaired
Dedicated Host is released, and the replacement Dedicated Host becomes available for use.
When host recovery is initiated, the AWS account owner is notified by email and by an AWS Personal
Health Dashboard event. A second notification is sent after the host recovery has been successfully
completed.
Stopped instances are not recovered on to the replacement Dedicated Host. If you attempt to start
a stopped instance that targets the impaired Dedicated Host, the instance start fails. We recommend
that you modify the stopped instance to either target a different Dedicated Host, or to launch on any
available Dedicated Host with matching configurations and auto-placement enabled.
If you are using AWS License Manager to track your licenses, AWS License Manager allocates new licenses
for the replacement Dedicated Host based on the license configuration limits. If the license configuration
has hard limits that will be breached as a result of the host recovery, the recovery process is not allowed
and you are notified of the host recovery failure through an Amazon SNS notification. If the license
configuration has soft limits that will be breached as a result of the host recovery, the recovery is allowed
to continue and you are notified of the limit breach through an Amazon SNS notification. For more
information about setting license configuration limits, see Using License Configurations in the AWS
License Manager User Guide.
Contents
• Enabling Host Recovery (p. 374)
• Disabling Host Recovery (p. 374)
• Viewing Host Recovery Configuration (p. 374)
373
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Dedicated Hosts
For more information about enabling host recovery at the time of Dedicated Host allocation, see
Allocating Dedicated Hosts (p. 363).
To view the host recovery configuration for a Dedicated Host (AWS CLI)
374
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Dedicated Hosts
The HostRecovery response element indicates whether host recovery is enabled or disabled.
After the replacement Dedicated Host is allocated, it enters the pending state. It remains in this
state until the host recovery process is complete. You cannot launch instances on to the replacement
Dedicated Host while it is in the pending state. Recovered instances on the replacement Dedicated Host
remain in the impaired state during the recovery process.
After the host recovery is complete, the replacement Dedicated Host enters the available state,
and the recovered instances return to the running state. You can launch instances on to the
replacement Dedicated Host after it enters the available state. The original impaired Dedicated Host is
permanently released and it enters the released-permanent-failure state.
If the impaired Dedicated Host has instances that do not support host recovery, such as instances with
instance store-backed volumes, the Dedicated Host is not released. Instead, it is marked for retirement
and enters the permanent-failure state.
• Use any instance type, except C5d, M5d, R5d, F1, H1, D2, I2, I3, I3en, P3dn, Z1d, and bare metal
instances
• Run in an Amazon VPC
• Use Amazon EBS volumes only
Note
If the impaired Dedicated Host has instances with block device mappings for instance store
volumes that do not support host recovery, they remain on the impaired Dedicated Host and
are not automatically recovered on to the replacement Dedicated Host during recovery. As
a remedial measure, the impaired Dedicated Host is marked for retirement and you receive
a retirement notification after the host recovery is complete. Follow the remedial steps
described in the retirement notification within the specified time period to manually recover
the remaining instances on the impaired Dedicated Host. For more information, see Manually
Recovering Unsupported Instances (p. 375).
375
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Dedicated Hosts
1. Launch a replacement instance on a new Dedicated Host from your most recent AMI.
2. Migrate all of the necessary data to the replacement instance.
3. Terminate the original instance on the impaired Dedicated Host.
Related Services
Dedicated Host integrates with the following AWS services:
• AWS License Manager—Tracks licenses across your Amazon EC2 Dedicated Hosts (supported only
in Regions in which AWS License Manager is available). For more information, see the AWS License
Manager User Guide.
Pricing
There are no additional charges for using host recovery, but the usual Dedicated Host charges apply. For
more information, see Amazon EC2 Dedicated Hosts Pricing.
As soon as host recovery is initiated, you are no longer billed for the impaired Dedicated Host. Billing for
the replacement Dedicated Host begins only after it enters the available state.
If the impaired Dedicated Host was billed using the On-Demand rate, the replacement Dedicated Host
is also billed using the On-Demand rate. If the impaired Dedicated Host had an active Dedicated Host
Reservation, it is transferred to the replacement Dedicated Host.
AWS Config records configuration information for Dedicated Hosts and instances individually and pairs
this information through relationships. There are three reporting conditions:
• AWS Config recording status—When On, AWS Config is recording one or more AWS resource types,
which can include Dedicated Hosts and Dedicated Instances. To capture the information required for
license reporting, verify that hosts and instances are being recorded with the following fields.
• Host recording status—When Enabled, the configuration information for Dedicated Hosts is recorded.
• Instance recording status—When Enabled, the configuration information for Dedicated Instances is
recorded.
If any of these three conditions are disabled, the icon in the Edit Config Recording button is red. To
derive the full benefit of this tool, ensure that all three recording methods are enabled. When all three
are enabled, the icon is green. To edit the settings, choose Edit Config Recording. You are directed to
the Set up AWS Config page in the AWS Config console, where you can set up AWS Config and start
recording for your hosts, instances, and other supported resource types. For more information, see
Setting up AWS Config using the Console in the AWS Config Developer Guide.
Note
AWS Config records your resources after it discovers them, which might take several minutes.
After AWS Config starts recording configuration changes to your hosts and instances, you can get the
configuration history of any host that you have allocated or released and any instance that you have
376
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Dedicated Instances
launched, stopped, or terminated. For example, at any point in the configuration history of a Dedicated
Host, you can look up how many instances are launched on that host, along with the number of sockets
and cores on the host. For any of those instances, you can also look up the ID of its Amazon Machine
Image (AMI). You can use this information to report on licensing for your own server-bound software
that is licensed per-socket or per-core.
• By using the AWS Config console. For each recorded resource, you can view a timeline page, which
provides a history of configuration details. To view this page, choose the gray icon in the Config
Timeline column of the Dedicated Hosts page. For more information, see Viewing Configuration
Details in the AWS Config Console in the AWS Config Developer Guide.
• By running AWS CLI commands. First, you can use the list-discovered-resources command to get a
list of all hosts and instances. Then, you can use the get-resource-config-history command to get the
configuration details of a host or instance for a specific time interval. For more information, see View
Configuration Details Using the CLI in the AWS Config Developer Guide.
• By using the AWS Config API in your applications. First, you can use the ListDiscoveredResources action
to get a list of all hosts and instances. Then, you can use the GetResourceConfigHistory action to get
the configuration details of a host or instance for a specific time interval.
For example, to get a list of all of your Dedicated Hosts from AWS Config, run a CLI command such as the
following.
To obtain the configuration history of a Dedicated Host from AWS Config, run a CLI command such as
the following.
For more information, see Viewing Configuration Details in the AWS Config Console.
• Using the AWS CLI, see Viewing Configuration Details (AWS CLI) in the AWS Config Developer Guide.
• Using the Amazon EC2 API, see GetResourceConfigHistory.
Dedicated Instances
Dedicated Instances are Amazon EC2 instances that run in a virtual private cloud (VPC) on hardware
that's dedicated to a single customer. Dedicated Instances that belong to different AWS accounts are
physically isolated at the hardware level. In addition, Dedicated Instances that belong to AWS accounts
that are linked to a single payer account are also physically isolated at the hardware level. However,
Dedicated Instances may share hardware with other instances from the same AWS account that are not
Dedicated Instances.
377
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Dedicated Instances
Note
A Dedicated Host is also a physical server that's dedicated for your use. With a Dedicated
Host, you have visibility and control over how instances are placed on the server. For more
information, see Dedicated Hosts (p. 359).
After you launch an instance, there are some limitations to changing its tenancy.
• You cannot change the tenancy of an instance from default to dedicated or host after you've
launched it.
• You cannot change the tenancy of an instance from dedicated or host to default after you've
launched it.
You can change the tenancy of an instance from dedicated to host, or from host to dedicated after
you've launched it. For more information, see Changing the Tenancy of an Instance (p. 381).
Each VPC has a related instance tenancy attribute. This attribute has the following values.
default An instance launched into the VPC runs on shared hardware by default, unless you
explicitly specify a different tenancy during instance launch.
dedicated An instance launched into the VPC is a Dedicated Instance by default, unless you
explicitly specify a tenancy of host during instance launch. You cannot specify a
tenancy of default during instance launch.
You can change the instance tenancy of a VPC from dedicated to default after you create it. You
cannot change the instance tenancy of a VPC to dedicated.
• Create the VPC with the instance tenancy set to dedicated (all instances launched into this VPC are
Dedicated Instances).
• Create the VPC with the instance tenancy set to default, and specify a tenancy of dedicated for any
instances when you launch them.
378
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Dedicated Instances
Some instance types cannot be launched into a VPC with the instance tenancy set to dedicated. For
more information about supported instances types, see Amazon EC2 Dedicated Instances.
When you purchase a Dedicated Reserved Instance, you are purchasing the capacity to launch a
Dedicated Instance into a VPC at a much reduced usage fee; the price break in the usage charge applies
only if you launch an instance with dedicated tenancy. When you purchase a Reserved Instance with
default tenancy, it applies only to a running instance with default tenancy; it would not apply to a
running instance with dedicated tenancy.
You can't use the modification process to change the tenancy of a Reserved Instance after you've
purchased it. However, you can exchange a Convertible Reserved Instance for a new Convertible
Reserved Instance with a different tenancy.
Topics
• Creating a VPC with an Instance Tenancy of Dedicated (p. 380)
• Launching Dedicated Instances into a VPC (p. 380)
• Displaying Tenancy Information (p. 381)
• Changing the Tenancy of an Instance (p. 381)
• Changing the Tenancy of a VPC (p. 382)
379
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Dedicated Instances
To create a VPC with an instance tenancy of dedicated (Create VPC dialog box)
To set the tenancy option when you create a VPC using the command line
If you launch an instance into a VPC that has an instance tenancy of dedicated, your instance is
automatically a Dedicated Instance, regardless of the tenancy of the instance.
To launch a Dedicated Instance into a default tenancy VPC using the console
For more information about launching an instance with a tenancy of host, see Launching Instances onto
Dedicated Hosts (p. 364).
To set the tenancy option for an instance during launch using the command line
380
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Dedicated Instances
• Choose Show/Hide Columns (the gear-shaped icon), Tenancy in the Show/Hide Columns dialog
box, and then Close.
• Select the instance. The Description tab in the details pane displays information about the
instance, including its tenancy.
To describe the tenancy value of a Reserved Instance using the command line
To describe the tenancy value of a Reserved Instance offering using the command line
381
Amazon Elastic Compute Cloud
User Guide for Linux Instances
On-Demand Capacity Reservations
Hosts (p. 362). Similarly, you can change the tenancy of a stopped Dedicated Host instance to
dedicated after launching it. The next time the instance starts, it's started on single-tenant hardware
that we control.
You can modify the instance tenancy attribute of a VPC using the AWS CLI, an AWS SDK, or the Amazon
EC2 API only.
To modify the instance tenancy attribute of a VPC using the AWS CLI
• Use the modify-vpc-tenancy command to specify the ID of the VPC and instance tenancy value. The
only supported value is default.
When you create a Capacity Reservation, you specify the Availability Zone in which you want to reserve
the capacity, the number of instances for which you want to reserve capacity, and the instance attributes,
including the instance type, tenancy, and platform/OS. Capacity Reservations can only be used by
instances that match their attributes. By default, they are automatically used by running instances that
match the attributes. If you don't have any running instances that match the attributes of the Capacity
Reservation, it remains unused until you launch an instance with matching attributes.
382
Amazon Elastic Compute Cloud
User Guide for Linux Instances
On-Demand Capacity Reservations
In addition, you can use your Regional RIs with your Capacity Reservations to benefit from billing
discounts. This gives you the flexibility to selectively add capacity reservations and still get the Regional
RI discounts for that usage. AWS automatically applies your RI discount when the attributes of a Capacity
Reservation match the attributes of an active Regional RI.
Contents
• Differences between Capacity Reservations and RIs (p. 383)
• Capacity Reservation Limits (p. 383)
• Capacity Reservation Limitations and Restrictions (p. 383)
• Capacity Reservation Pricing and Billing (p. 384)
• Working with Capacity Reservations (p. 385)
• Active and unused Capacity Reservations count towards your On-Demand Instance limits
• Capacity Reservations can't be shared across AWS accounts
• Capacity Reservations are not transferable from one AWS account to another
383
Amazon Elastic Compute Cloud
User Guide for Linux Instances
On-Demand Capacity Reservations
For example, if you create a Capacity Reservation for 20 m4.large Linux instances and run 15 m4.large
Linux instances in the same Availability Zone, you will be charged for 15 instances and for 5 unused spots
in the reservation.
Note
Regional RIs billing discounts apply to Capacity Reservations. AWS automatically applies your
active Regional RIs to active and unused Capacity Reservations that have matching attributes.
For more information about Regional RIs, see Reserved Instances (p. 256).
For more information about Amazon EC2 pricing, see Amazon EC2 Pricing.
Billing
Capacity Reservations are billed at per-second granularity. This means that you are charged for partial
hours. For example, if a reservation remains active in your account for 24 hours and 15 minutes, you will
be billed for 24.25 reservation hours.
The following example shows how a Capacity Reservation is billed. The Capacity Reservation is created
for one m4.large Linux instance, which has an On-Demand rate of $0.10 per usage hour. In this example,
the Capacity Reservation is active in the account for five hours. The Capacity Reservation is unused for
the first hour, so it is billed for one unused hour at the m4.large instance type's standard On-Demand
rate. In hours two through five, the Capacity Reservation is occupied by an m4.large instance. During
this time, the Capacity Reservation accrues no charges, and the account is instead billed for the m4.large
instance occupying it. In the sixth hour, the Capacity Reservation is canceled and the m4.large instance
runs normally outside of the reserved capacity. For that hour, it is charged at the On-Demand rate of the
m4.large instance type.
Billing Discounts
Regional RIs billing discounts apply to Capacity Reservations. AWS automatically applies your active
Regional RIs to active Capacity Reservations that have matching attributes. For more information about
Regional RIs, see Reserved Instances (p. 256).
Note
Zonal RI billing discounts do not apply to Capacity Reservations.
384
Amazon Elastic Compute Cloud
User Guide for Linux Instances
On-Demand Capacity Reservations
When your instance-hours and reservation-hours combined exceed your total eligible discounted
Regional RI hours, discounts are preferentially applied to instance-hours first and then to unused
reservation-hours.
You can view the charges online, or you can download a CSV file. For more information, see Capacity
Reservation Line Items in the AWS Billing and Cost Management User Guide.
By default, Capacity Reservations automatically match new instances and running instances that have
matching attributes (instance type, platform, and Availability Zone). In other words, instances that
have matching attributes automatically run in the Capacity Reservation's capacity. However, you can
also target a Capacity Reservation for specific workloads. This enables you to explicitly control which
instances are allowed to run in that reserved capacity.
Contents
• Creating a Capacity Reservation (p. 385)
• Launching an Instance into an Existing Capacity Reservation (p. 387)
• Modifying a Capacity Reservation (p. 388)
• Modifying an Instance's Capacity Reservation Settings (p. 388)
• Viewing a Capacity Reservation (p. 389)
• Canceling a Capacity Reservation (p. 390)
After you create the Capacity Reservation, the capacity is available immediately. The capacity remains
reserved for your use as long as the Capacity Reservation is active, and you can launch instances into
it at any time. If the Capacity Reservation is open, new instances and existing instances that have
385
Amazon Elastic Compute Cloud
User Guide for Linux Instances
On-Demand Capacity Reservations
matching attributes automatically run in the Capacity Reservation's capacity. If the Capacity Reservation
is targeted, instances must specifically target it to run in the reserved capacity.
You can create a Capacity Reservation using the Amazon EC2 console or the AWS CLI.
a. Instance Type—Specify the type of instance to launch into the reserved capacity.
b. Launch EBS-optimized instances—Specify whether to reserve the capacity for EBS-optimized
instances. This option is selected by default for some instance types. For more information
about EBS-optimized instances, see Amazon Elastic Block Store (p. 828).
c. Attach instance store at launch—Indicate whether instances launched into the Capacity
Reservation use temporary block-level storage. The data on an instance store volume persists
only during the life of the associated instance.
d. Platform—Specify the operating system for your intended instances.
e. Availability Zone—Specify the Availability Zone in which to reserve the capacity.
f. Tenancy—Specify whether you want to run a shared hardware instance (default) or a dedicated
instance.
g. Quantity—Specify the number instances for which to reserve capacity. If you specify a quantity
that exceeds your remaining On-Demand Instance limit for the selected instance type, the
request will be denied.
4. Configure the following settings in the Reservation details section:
Note
After the reservation ends, you can no longer target instances to the Capacity
Reservation. Instances running in the reserved capacity continue to run uninterrupted.
If instances targeting a Capacity Reservation are stopped, you cannot restart them until
you remove their Capacity Reservation targeting preference or configure them to target
a different Capacity Reservation.
b. Instance eligibility—Choose one of the following options:
• open—(Default) The Capacity Reservation matches any instance that has matching attributes
(instance type, platform, and Availability Zone). If you launch an instance with matching
attributes, it is placed into the reserved capacity automatically.
• targeted—The Capacity Reservation only accepts instances that have matching attributes
(instance type, platform, and Availability Zone), and explicitly target the reservation.
5. Choose Request reservation.
386
Amazon Elastic Compute Cloud
User Guide for Linux Instances
On-Demand Capacity Reservations
You can launch an instance into a Capacity Reservation that you previously created using the Amazon
EC2 console or the command line.
• Choose Open to launch the instance into any open Capacity Reservation that has matching
attributes (instance type, platform, and Availability Zone) and sufficient capacity.
Note
If you do not have a matching open Capacity Reservation with sufficient capacity, the
instance launches into On-Demand capacity.
• Choose None to prevent the instance from launching into a Capacity Reservation.
• Choose the specific Capacity Reservation into which to launch the instance.
Note
If the selected Capacity Reservation does not have sufficient capacity, the instance launch
fails.
4. Choose Review and Launch, Launch.
5. When prompted, select an existing key pair or create a new one, and choose Launch Instances.
To launch an instance into an existing Capacity Reservation using the AWS CLI
The following example launches a t2.micro instance into any open Capacity Reservation that has
matching attributes and available capacity:
The following example launches a t2.micro instance into a targeted Capacity Reservation:
387
Amazon Elastic Compute Cloud
User Guide for Linux Instances
On-Demand Capacity Reservations
When modifying a Capacity Reservation, you can only increase or decrease the quantity and change the
way in which it is released. You cannot change a Capacity Reservation's instance type, EBS optimization,
instance store settings, platform, Availability Zone, or instance eligibility. If you need to modify any of
these attributes, we recommend that you cancel the reservation, and then create a new one with the
required attributes.
You can modify a Capacity Reservation using the Amazon EC2 console and the AWS CLI.
• Target a specific Capacity Reservation. The instance cannot launch outside of the targeted Capacity
Reservation.
• Launch on any Capacity Reservation that has matching attributes (instance type, platform, and
Availability Zone) and available capacity.
• Avoid launching in a Capacity Reservation. The instance is prevented from launching in any Capacity
Reservation, even if the reservation is open and has matching attributes (instance type, platform, and
Availability Zone).
Note
You can only modify an instance's Capacity Reservation settings while it is stopped.
You can modify an instance's Capacity Reservation settings using the Amazon EC2 console and the AWS
CLI.
388
Amazon Elastic Compute Cloud
User Guide for Linux Instances
On-Demand Capacity Reservations
• Choose Open to configure the instance to run in any open Capacity Reservation that has matching
attributes (instance type, platform, and Availability Zone) and sufficient capacity.
Note
If you do not have a matching open Capacity Reservation with sufficient capacity, the
instance launches into On-Demand capacity.
• Choose None to prevent the instance from launching into a Capacity Reservation.
• Choose the specific Capacity Reservation in which the instance should run.
Note
If the instance attributes (instance type, platform, and Availability Zone) do not match
those of the selected Capacity Reservation, or if the selected Capacity Reservation does
not have sufficient capacity, the instance launch fails.
• active—The Capacity Reservation is active and the capacity is available for your use.
• expired—The Capacity Reservation expired automatically at the date and time specified in your
reservation request. The reserved capacity is no longer available for your use.
• cancelled—The Capacity Reservation was manually canceled. The reserved capacity is no longer
available for your use.
• pending—The Capacity Reservation request was successful but the capacity provisioning is still
pending.
• failed—The Capacity Reservation request has failed. A request might fail due to invalid request
parameters, capacity constraints, or instance limit constraints. Failed requests are retained for 60
minutes.
You can view your active Capacity Reservations using the Amazon EC2 console and the AWS CLI.
389
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Lifecycle
You can cancel empty Capacity Reservations and Capacity Reservations that have running instances. If
you cancel a Capacity Reservation that has running instances, the instances continue to run normally
outside of the capacity reservation at standard On-Demand Instance rates or at a discounted rate if you
have an active matching Regional RI.
After you cancel a Capacity Reservation, instances that target it can no longer launch. Modify these
instances so that they either target a different Capacity Reservation, launch into any 'open' Capacity
Reservation with matching attributes and sufficient capacity, or avoid launching into a Capacity
Reservation. For more information, see Modifying an Instance's Capacity Reservation Settings (p. 388).
You can cancel a Capacity Reservation using the Amazon EC2 console and the AWS CLI.
Instance Lifecycle
By working with Amazon EC2 to manage your instances from the moment you launch them through
their termination, you ensure that your customers have the best possible experience with the
applications or sites that you host on your instances.
The following illustration represents the transitions between instance states. Notice that you can't
stop and start an instance store-backed instance. For more information about instance store-backed
instances, see Storage for the Root Device (p. 97).
The following table provides a brief description of each instance state and indicates whether it is billed
or not.
390
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Launch
Note
The table indicates billing for instance usage only. Some AWS resources, such as Amazon EBS
volumes and Elastic IP addresses, incur charges regardless of the instance's state. For more
information, see Avoiding Unexpected Charges in the AWS Billing and Cost Management User
Guide.
Note
Rebooting an instance doesn't start a new instance billing period because the instance stays in
the running state.
Instance Launch
When you launch an instance, it enters the pending state. The instance type that you specified at launch
determines the hardware of the host computer for your instance. We use the Amazon Machine Image
(AMI) you specified at launch to boot the instance. After the instance is ready for you, it enters the
running state. You can connect to your running instance and use it the way that you'd use a computer
sitting in front of you.
As soon as your instance transitions to the running state, you're billed for each second, with a one-
minute minimum, that you keep the instance running, even if the instance remains idle and you don't
connect to it.
For more information, see Launch Your Instance (p. 395) and Connect to Your Linux Instance (p. 446).
391
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Stop and Start (Amazon
EBS-Backed Instances Only)
When you stop your instance, it enters the stopping state, and then the stopped state. We don't
charge usage or data transfer fees for your instance after you stop it, but we do charge for the storage
for any Amazon EBS volumes. While your instance is in the stopped state, you can modify certain
attributes of the instance, including the instance type.
When you start your instance, it enters the pending state, and in most cases, we move the instance
to a new host computer. (Your instance may stay on the same host computer if there are no problems
with the host computer.) When you stop and start your instance, you lose any data on the instance store
volumes on the previous host computer.
Your instance retains its private IPv4 address, which means that an Elastic IP address associated with the
private IPv4 address or network interface is still associated with your instance. If your instance has an
IPv6 address, it retains its IPv6 address.
Each time you transition an instance from stopped to running, we charge per second when the
instance is running, with a minimum of one minute every time you restart your instance.
For more information, see Stop and Start Your Instance (p. 468).
When you hibernate your instance, it enters the stopping state, and then the stopped state. We don't
charge usage for a hibernated instance when it is in the stopped state, but we do charge while it is in
the stopping state, unlike when you stop an instance (p. 392) without hibernating it. We don't charge
usage for data transfer fees, but we do charge for the storage for any Amazon EBS volumes, including
storage for the RAM data.
When you restart your hibernated instance, it enters the pending state, and in most cases, we move
the instance to a new host computer. Your instance may stay on the same host computer if there are no
problems with the host computer.
Your instance retains its private IPv4 address, which means that an Elastic IP address associated with the
private IPv4 address or network interface is still associated with your instance. If your instance has an
IPv6 address, it retains its IPv6 address.
Instance Reboot
You can reboot your instance using the Amazon EC2 console, a command line tool, and the Amazon EC2
API. We recommend that you use Amazon EC2 to reboot your instance instead of running the operating
system reboot command from your instance.
392
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Retirement
Rebooting an instance is equivalent to rebooting an operating system. The instance remains on the same
host computer and maintains its public DNS name, private IP address, and any data on its instance store
volumes. It typically takes a few minutes for the reboot to complete, but the time it takes to reboot
depends on the instance configuration.
Rebooting an instance doesn't start a new instance billing period; per second billing continues without a
further one-minute minimum charge.
Instance Retirement
An instance is scheduled to be retired when AWS detects the irreparable failure of the underlying
hardware hosting the instance. When an instance reaches its scheduled retirement date, it is stopped or
terminated by AWS. If your instance root device is an Amazon EBS volume, the instance is stopped, and
you can start it again at any time. If your instance root device is an instance store volume, the instance is
terminated, and cannot be used again.
Instance Termination
When you've decided that you no longer need an instance, you can terminate it. As soon as the status of
an instance changes to shutting-down or terminated, you stop incurring charges for that instance.
If you enable termination protection, you can't terminate the instance using the console, CLI, or API.
After you terminate an instance, it remains visible in the console for a short while, and then the entry
is automatically deleted. You can also describe a terminated instance using the CLI and API. Resources
(such as tags) are gradually disassociated from the terminated instance, therefore may no longer be
visible on the terminated instance after a short while. You can't connect to or recover a terminated
instance.
Each Amazon EBS volume supports the DeleteOnTermination attribute, which controls whether the
volume is deleted or preserved when you terminate the instance it is attached to. The default is to delete
the root device volume and preserve any other EBS volumes.
393
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Differences Between Reboot,
Stop, Hibernate, and Terminate
Characteristic Reboot Stop/start (Amazon Hibernate (Amazon Terminate
EBS-backed EBS-backed instances
instances only) only)
Your instance may Your instance may
stay on the same host stay on the same host
computer if there are computer if there are
no problems with the no problems with the
host computer. host computer.
Private and These addresses The instance keeps its The instance keeps its None
public IPv4 stay the same private IPv4 address. private IPv4 address.
addresses The instance gets The instance gets
a new public IPv4 a new public IPv4
address, unless it has address, unless it has
an Elastic IP address, an Elastic IP address,
which doesn't change which doesn't change
during a stop/start. during a stop/start.
Elastic IP The Elastic IP The Elastic IP address The Elastic IP address The Elastic
addresses address remains remains associated remains associated IP address is
(IPv4) associated with with the instance with the instance disassociated from
the instance the instance
IPv6 The address stays The instance keeps its The instance keeps its None
address the same IPv6 address IPv6 address
Instance The data is The data is erased The data is erased The data is erased
store preserved
volumes
Root device The volume is The volume is The volume is The volume is
volume preserved preserved preserved deleted by default
RAM The RAM is erased The RAM is erased The RAM is saved The RAM is erased
(contents of to a file on the root
memory) volume
Billing The instance You stop incurring You incur charges You stop incurring
billing hour charges for an while the instance is in charges for
doesn't change. instance as soon as the stopping state, an instance
its state changes but stop incurring as soon as its
to stopping. charges when the state changes to
Each time an instance is in the shutting-down.
instance transitions stopped state. Each
from stopped to time an instance
running, we start a transitions from
new instance billing stopped to running,
period, billing a we start a new
minimum of one instance billing period,
minute every time billing a minimum
you restart your of one minute every
instance. time you restart your
instance.
Operating system shutdown commands always terminate an instance store-backed instance. You can
control whether operating system shutdown commands stop or terminate an Amazon EBS-backed
instance. For more information, see Changing the Instance Initiated Shutdown Behavior (p. 482).
394
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
When you sign up for AWS, you can get started with Amazon EC2 for free using the AWS Free Tier. You
can use the free tier to launch and use a micro instance for free for 12 months. If you launch an instance
that is not within the free tier, you incur the standard Amazon EC2 usage fees for the instance. For more
information, see the Amazon EC2 Pricing.
Method Documentation
[Amazon EC2 console] Use the launch instance Launching an Instance Using the Launch Instance
wizard to specify the launch parameters. Wizard (p. 395)
[Amazon EC2 console] Create a launch template Launching an Instance from a Launch
and launch the instance from the launch Template (p. 403)
template.
[Amazon EC2 console] Use an existing instance as Launching an Instance Using Parameters from an
the base. Existing Instance (p. 415)
[Amazon EC2 console] Use an Amazon EBS Launching a Linux Instance from a
snapshot that you created. Backup (p. 416)
[Amazon EC2 console] Use an AMI that you Launching an AWS Marketplace Instance (p. 417)
purchased from the AWS Marketplace.
[AWS CLI] Use an AMI that you select. Using Amazon EC2 through the AWS CLI
[AWS Tools for Windows PowerShell] Use an AMI Amazon EC2 from the AWS Tools for Windows
that you select. PowerShell
[AWS CLI] Use EC2 Fleet to provision capacity Launching an EC2 Fleet (p. 418)
across different EC2 instance types and
Availability Zones, and across On-Demand
Instance, Reserved Instance, and Spot Instance
purchase models.
After you launch your instance, you can connect to it and use it. To begin, the instance state is pending.
When the instance state is running, the instance has started booting. There might be a short time
before you can connect to the instance. The instance receives a public DNS name that you can use
to contact the instance from the internet. The instance also receives a private DNS name that other
instances within the same VPC can use to contact the instance. For more information about connecting
to your instance, see Connect to Your Linux Instance (p. 446).
When you are finished with an instance, be sure to terminate it. For more information, see Terminate
Your Instance (p. 479).
395
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
Important
When you launch an instance that's not within the AWS Free Tier, you are charged for the time
that the instance is running, even if it remains idle.
To launch an instance
396
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
Quick Start
A selection of popular AMIs to help you get started quickly. To select an AMI that is eligible
for the free tier, choose Free tier only in the left pane. These AMIs are marked Free tier
eligible.
My AMIs
The private AMIs that you own, or private AMIs that have been shared with you. To view
AMIs shared with you, choose Shared with me in the left pane.
397
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
AWS Marketplace
An online store where you can buy software that runs on AWS, including AMIs. For more
information about launching an instance from the AWS Marketplace, see Launching an AWS
Marketplace Instance (p. 417).
Community AMIs
The AMIs that AWS community members have made available for others to use. To filter
the list of AMIs by operating system, choose the appropriate check box under Operating
system. You can also filter by architecture and root device type.
b. Check the Root device type listed for each AMI. Notice which AMIs are the type that you need,
either ebs (backed by Amazon EBS) or instance-store (backed by instance store). For more
information, see Storage for the Root Device (p. 97).
c. Check the Virtualization type listed for each AMI. Notice which AMIs are the type that you
need, either hvm or paravirtual. For example, some instance types require HVM. For more
information, see Linux AMI Virtualization Types (p. 99).
d. Choose an AMI that meets your needs, and then choose Select.
5. On the Choose an Instance Type page, select the hardware configuration and size of the instance
to launch. Larger instance types have more CPU and memory. For more information, see Instance
Types (p. 178).
To remain eligible for the free tier, choose the t2.micro instance type. For more information, see
Burstable Performance Instances (p. 192).
By default, the wizard displays current generation instance types, and selects the first available
instance type based on the AMI that you selected. To view previous generation instance types,
choose All generations from the filter list.
Note
To set up an instance quickly for testing purposes, choose Review and Launch to accept
the default configuration settings, and launch your instance. Otherwise, to configure your
instance further, choose Next: Configure Instance Details.
6. On the Configure Instance Details page, change the following settings as necessary (expand
Advanced Details to see all the settings), and then choose Next: Add Storage:
398
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
do not. You can select Enable or Disable to override the subnet's default setting. For more
information, see Public IPv4 Addresses and External DNS Hostnames (p. 707).
• Auto-assign IPv6 IP: Specify whether your instance receives an IPv6 address from the range of
the subnet. Select Enable or Disable to override the subnet's default setting. This option is only
available if you've associated an IPv6 CIDR block with your VPC and subnet. For more information,
see Your VPC and Subnets in the Amazon VPC User Guide.
• Capacity Reservation: Specify whether to launch the instance into shared capacity or an existing
Capacity Reservation. For more information, see Launching an Instance into an Existing Capacity
Reservation (p. 387).
• IAM role: Select an AWS Identity and Access Management (IAM) role to associate with the
instance. For more information, see IAM Roles for Amazon EC2 (p. 696).
• CPU options: Choose Specify CPU options to specify a custom number of vCPUs during launch.
Set the number of CPU cores and threads per core. For more information, see Optimizing CPU
Options (p. 504).
• Shutdown behavior: Select whether the instance should stop or terminate when shut down. For
more information, see Changing the Instance Initiated Shutdown Behavior (p. 482).
• Enable termination protection: To prevent accidental termination, select this check box. For more
information, see Enabling Termination Protection for an Instance (p. 481).
• Monitoring: Select this check box to enable detailed monitoring of your instance using Amazon
CloudWatch. Additional charges apply. For more information, see Monitoring Your Instances Using
CloudWatch (p. 558).
• EBS-Optimized instance: An Amazon EBS-optimized instance uses an optimized configuration
stack and provides additional, dedicated capacity for Amazon EBS I/O. If the instance type
supports this feature, select this check box to enable it. Additional charges apply. For more
information, see Amazon EBS–Optimized Instances (p. 915).
• Tenancy: If you are launching your instance into a VPC, you can choose to run your instance on
isolated, dedicated hardware (Dedicated) or on a Dedicated Host (Dedicated host). Additional
charges may apply. For more information, see Dedicated Instances (p. 377) and Dedicated
Hosts (p. 359).
• T2/T3 Unlimited: Select this check box to enable applications to burst beyond the baseline for as
long as needed. Additional charges may apply. For more information, see Burstable Performance
Instances (p. 192).
• Network interfaces: If you selected a specific subnet, you can specify up to two network
interfaces for your instance:
• For Network Interface, select New network interface to let AWS create a new interface, or
select an existing, available network interface.
• For Primary IP, enter a private IPv4 address from the range of your subnet, or leave Auto-
assign to let AWS choose a private IPv4 address for you.
• For Secondary IP addresses, choose Add IP to assign more than one private IPv4 address to the
selected network interface.
• (IPv6-only) For IPv6 IPs, choose Add IP, and enter an IPv6 address from the range of the subnet,
or leave Auto-assign to let AWS choose one for you.
• Choose Add Device to add a secondary network interface. A secondary network interface
can reside in a different subnet of the VPC, provided it's in the same Availability Zone as your
instance.
For more information, see Elastic Network Interfaces (p. 729). If you specify more than one
network interface, your instance cannot receive a public IPv4 address. Additionally, if you specify
an existing network interface for eth0, you cannot override the subnet's public IPv4 setting using
Auto-assign Public IP. For more information, see Assigning a Public IPv4 Address During Instance
Launch (p. 711).
• Kernel ID: (Only valid for paravirtual (PV) AMIs) Select Use default unless you want to use a
specific kernel.
399
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
• RAM disk ID: (Only valid for paravirtual (PV) AMIs) Select Use default unless you want to use a
specific RAM disk. If you have selected a kernel, you may need to select a specific RAM disk with
the drivers to support it.
• Placement group: A placement group determines the placement strategy of your instances.
Select an existing placement group, or create a new one. This option is only available if you've
selected an instance type that supports placement groups. For more information, see Placement
Groups (p. 784).
• User data: You can specify user data to configure an instance during launch, or to run a
configuration script. To attach a file, select the As file option and browse for the file to attach.
7. The AMI you selected includes one or more volumes of storage, including the root device volume. On
the Add Storage page, you can specify additional volumes to attach to the instance by choosing Add
New Volume. You can configure the following options for each volume:
• Type: Select instance store or Amazon EBS volumes to associate with your instance. The types of
volume available in the list depend on the instance type you've chosen. For more information, see
Amazon EC2 Instance Store (p. 956) and Amazon EBS Volumes (p. 830).
• Device: Select from the list of available device names for the volume.
• Snapshot: Enter the name or ID of the snapshot from which to restore a volume. You can also
search for available shared and public snapshots by typing text into the Snapshot field. Snapshot
descriptions are case-sensitive.
• Size: For Amazon EBS-backed volumes, you can specify a storage size. Even if you have selected an
AMI and instance that are eligible for the free tier, to stay within the free tier, you must keep under
30 GiB of total storage.
Note
Linux AMIs require GPT partition tables and GRUB 2 for boot volumes 2 TiB (2048 GiB) or
larger. Many Linux AMIs today use the MBR partitioning scheme, which only supports up
to 2047 GiB boot volumes. If your instance does not boot with a boot volume that is 2 TiB
or larger, the AMI you are using may be limited to a 2047 GiB boot volume size. Non-boot
volumes do not have this limitation on Linux instances.
Note
If you increase the size of your root volume at this point (or any other volume created
from a snapshot), you need to extend the file system on that volume in order to use the
extra space. For more information about extending your file system after your instance
has launched, see Amazon EBS Elastic Volumes (p. 892).
• Volume Type: For Amazon EBS volumes, select either a General Purpose SSD, Provisioned IOPS
SSD, or Magnetic volume. For more information, see Amazon EBS Volume Types (p. 832).
Note
If you select a Magnetic boot volume, you'll be prompted when you complete the wizard
to make General Purpose SSD volumes the default boot volume for this instance and
future console launches. (This preference persists in the browser session, and does
not affect AMIs with Provisioned IOPS SSD boot volumes.) We recommended that you
make General Purpose SSD volumes the default because they provide a much faster
boot experience and they are the optimal volume type for most workloads. For more
information, see Amazon EBS Volume Types (p. 832).
Note
Some AWS accounts created before 2012 might have access to Availability Zones in us-
west-1 or ap-northeast-1 that do not support Provisioned IOPS SSD (io1) volumes. If
you are unable to create an io1 volume (or launch an instance with an io1 volume in
its block device mapping) in one of these Regions, try a different Availability Zone in the
Region. You can verify that an Availability Zone supports io1 volumes by creating a 4 GiB
io1 volume in that zone.
• IOPS: If you have selected a Provisioned IOPS SSD volume type, then you can enter the number of
I/O operations per second (IOPS) that the volume can support.
400
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
• Delete on Termination: For Amazon EBS volumes, select this check box to delete the volume
when the instance is terminated. For more information, see Preserving Amazon EBS Volumes on
Instance Termination (p. 483).
• Encrypted: This field allows you to change the encryption state of the volume.
You apply encryption to EBS volumes by setting the Encrypted parameter to true. (The
Encrypted parameter is optional if encryption by default (p. 904) is enabled).
Optionally, you can use KmsKeyId to specify a custom key to use to encrypt the volume. (The
Encrypted parameter must also be set to true, even if encryption by default is enabled.) If
KmsKeyId is not specified, the key that is used for encryption depends on the encryption state of
the source snapshot and its ownership.
The following table describes the encryption outcome for each possible combination of settings.
Encryption Outcomes
401
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
* This is the default CMK used for EBS encryption for the AWS account and Region. By default this
is a unique AWS managed CMK for EBS, or you can specify a customer managed CMK. For more
information, see Encryption Key Management (p. 905).
** This is a customer managed CMK specified for the volume at launch time. This CMK is used
instead of the default CMK for the AWS account and Region.
To override any of these defaults, click in the Encrypted field to see available keys, and choose a
key alias or type a key ARN. You can encrypt a volume restored from an unencrypted snapshot, or
re-encrypt any volume to which you have access using a key that you own.
Note
Encrypted volumes may only be attached to supported instance types (p. 904).
a. To select an existing security group, choose Select an existing security group, and select your
security group.
402
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
Note
(Optional) You can't edit the rules of an existing security group, but you can copy them
to a new group by choosing Copy to new. Then you can add rules as described in the
next step.
b. To create a new security group, choose Create a new security group. The wizard automatically
defines the launch-wizard-x security group and creates an inbound rule to allow you to connect
to your instance over SSH (port 22).
c. You can add rules to suit your needs. For example, if your instance is a web server, open ports 80
(HTTP) and 443 (HTTPS) to allow internet traffic.
To add a rule, choose Add Rule, select the protocol to open to network traffic, and then specify
the source. Choose My IP from the Source list to let the wizard add your computer's public IP
address. However, if you are connecting through an ISP or from behind your firewall without a
static IP address, you need to find out the range of IP addresses used by client computers.
Warning
Rules that enable all IP addresses (0.0.0.0/0) to access your instance over SSH or
RDP are acceptable for this short exercise, but are unsafe for production environments.
You should authorize only a specific IP address or range of addresses to access your
instance.
10. On the Review Instance Launch page, check the details of your instance, and make any necessary
changes by choosing the appropriate Edit link.
To launch your instance, select the acknowledgment check box, then choose Launch Instances.
Important
If you choose the Proceed without key pair option, you won't be able to connect to the
instance unless you choose an AMI that is configured to allow users another way to log in.
12. (Optional) You can create a status check alarm for the instance (additional fees may apply). (If you're
not sure, you can always add one later.) On the confirmation screen, choose Create status check
alarms and follow the directions. For more information, see Creating and Editing Status Check
Alarms (p. 550).
13. If the instance fails to launch or the state immediately goes to terminated instead of running, see
Troubleshooting Instance Launch Issues (p. 1018).
For each launch template, you can create one or more numbered launch template versions. Each version
can have different launch parameters. When you launch an instance from a launch template, you can
use any version of the launch template. If you do not specify a version, the default version is used. You
can set any version of the launch template as the default version—by default, it's the first version of the
launch template.
The following diagram shows a launch template with three versions. The first version specifies the
instance type, AMI ID, subnet, and key pair to use to launch the instance. The second version is based
403
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
on the first version and also specifies a security group for the instance. The third version uses different
values for some of the parameters. Version 2 is set as the default version. If you launched an instance
from this launch template, the launch parameters from version 2 would be used if no other version were
specified.
Contents
• Launch Template Restrictions (p. 404)
• Using Launch Templates to Control Launch Parameters (p. 404)
• Controlling the Use of Launch Templates (p. 405)
• Creating a Launch Template (p. 405)
• Managing Launch Template Versions (p. 411)
• Launching an Instance from a Launch Template (p. 413)
• Using Launch Templates with Amazon EC2 Auto Scaling (p. 414)
• Using Launch Templates with EC2 Fleet (p. 414)
• Using Launch Templates with Spot Fleet (p. 414)
• Deleting a Launch Template (p. 415)
• You are limited to creating 5,000 launch templates per Region and 10,000 versions per launch
template.
• Launch parameters are optional. However, you must ensure that your request to launch an instance
includes all required parameters. For example, if your launch template does not include an AMI ID, you
must specify both the launch template and an AMI ID when you launch an instance.
• Launch template parameters are not validated when you create the launch template. Ensure that you
specify the correct values for the parameters and that you use supported parameter combinations. For
example, to launch an instance in a placement group, you must specify a supported instance type.
• You can tag a launch template, but you cannot tag a launch template version.
• Launch template versions are numbered in the order in which they are created. When you create a
launch template version, you cannot specify the version number yourself.
404
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
Note
You cannot remove launch template parameters during launch (for example, you cannot specify
a null value for the parameter). To remove a parameter, create a new version of the launch
template without the parameter and use that version to launch the instance.
To launch instances, IAM users must have permissions to use the ec2:RunInstances action. You must
also have permissions to create or use the resources that are created or associated with the instance. You
can use resource-level permissions for the ec2:RunInstances action to control the launch parameters
that users can specify. Alternatively, you can grant users permissions to launch an instance using a launch
template. This enables you to manage launch parameters in a launch template rather than in an IAM
policy, and to use a launch template as an authorization vehicle for launching instances. For example,
you can specify that users can only launch instances using a launch template, and that they can only use
a specific launch template. You can also control the launch parameters that users can override in the
launch template. For example policies, see Launch Templates (p. 681).
Take care when granting users permissions to use the ec2:CreateLaunchTemplate and
ec2:CreateLaunchTemplateVersion actions. These actions do not support resource-level
permissions that enable you to control which resources users can specify in the launch template. To
restrict the resources that are used to launch an instance, ensure that you grant permissions to create
launch templates and launch template versions only to appropriate administrators.
• AMI ID: An AMI from which to launch the instance. To search through all available AMIs,
choose Search for AMI. To select a commonly used AMI, choose Quick Start. Or, choose
AWS Marketplace or Community AMIs. You can use an AMI that you own or find a suitable
AMI (p. 100).
• Instance type: Ensure that the instance type is compatible with the AMI that you've specified. For
more information, see Instance Types (p. 178).
• Key pair name: The key pair for the instance. For more information, see Amazon EC2 Key
Pairs (p. 598).
• Network type: If applicable, whether to launch the instance into a VPC or EC2-Classic. If you
choose VPC, specify the subnet in the Network interfaces section. If you choose Classic, ensure
that the specified instance type is supported in EC2-Classic and specify the Availability Zone for
the instance.
• Security Groups: One or more security groups to associate with the instance. For more
information, see Amazon EC2 Security Groups for Linux Instances (p. 607).
405
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
5. For Network interfaces, you can specify up to two network interfaces (p. 729) for the instance.
• Device: The device number for the network interface, for example, eth0 for the primary network
interface. If you leave the field blank, AWS creates the primary network interface.
• Network interface: The ID of the network interface, or leave blank to let AWS create a new
network interface.
• Description: (Optional) A description for the new network interface.
• Subnet: The subnet in which to create a new network interface. For the primary network interface
(eth0), this is the subnet in which the instance is launched. If you've entered an existing network
interface for eth0, the instance is launched in the subnet in which the network interface is
located.
• Auto-assign public IP: Whether to automatically assign a public IP address to the network
interface with the device index of eth0. This setting can only be enabled for a single, new network
interface.
• Primary IP: A private IPv4 address from the range of your subnet. Leave blank to let AWS choose a
private IPv4 address for you.
• Secondary IP: A secondary private IPv4 address from the range of your subnet. Leave blank to let
AWS choose one for you.
• (IPv6-only) IPv6 IPs: An IPv6 address from the range of the subnet.
• Security group ID: The ID of a security group in your VPC with which to associate the network
interface.
• Delete on termination: Whether the network interface is deleted when the instance is deleted.
• Elastic Fabric Adapter: Indicates whether the network interface is an Elastic Fabric Adapter. For
more information, see Elastic Fabric Adapter.
6. For Storage (Volumes), specify volumes to attach to the instance besides the volumes specified by
the AMI.
• Volume type: The instance store or Amazon EBS volumes with which to associate your instance.
The type of volume depends on the instance type that you've chosen. For more information, see
Amazon EC2 Instance Store (p. 956) and Amazon EBS Volumes (p. 830).
• Device name: A device name for the volume.
• Snapshot: The ID of the snapshot from which to create the volume.
• Size: For Amazon EBS volumes, the storage size.
• Volume type: For Amazon EBS volumes, the volume type. For more information, see Amazon EBS
Volume Types (p. 832).
• IOPS: For the Provisioned IOPS SSD volume type, the number of I/O operations per second (IOPS)
that the volume can support.
• Delete on termination: For Amazon EBS volumes, whether to delete the volume when the
instance is terminated. For more information, see Preserving Amazon EBS Volumes on Instance
Termination (p. 483).
• Encrypted: Allows you to change the encryption state of a volume created by the template.
You apply encryption to EBS volumes by setting the Encrypted parameter to true. (The
Encrypted parameter is optional if encryption by default (p. 904) is enabled).
Optionally, you can use KmsKeyId to specify a custom key to use to encrypt the volume. (The
Encrypted parameter must also be set to true, even if encryption by default is enabled.) If
KmsKeyId is not specified, the key that is used for encryption depends on the encryption state of
the source snapshot and its ownership.
The following table describes the encryption outcome for each possible combination of settings.
406
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
Encryption Outcomes
407
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
* This is the default CMK used for EBS encryption for the AWS account and Region. By default this
is a unique AWS managed CMK for EBS, or you can specify a customer managed CMK. For more
information, see Encryption Key Management (p. 905).
** This is a customer managed CMK specified for the volume at launch time. This CMK is used
instead of the default CMK for the AWS account and Region.
Encrypted volumes may only be attached to supported instance types (p. 904).
• Key: The CMK to use for non-default changes to volume encryption state. Enter any customer
master key (CMK) that you previously created using the AWS Key Management Service. You can
paste the full ARN of any key to which you have access. For more information, see the AWS Key
Management Service Developer Guide.
Note
Providing a CMK without also setting the Encrypted parameter results in an error.
7. For Tags, specify tags (p. 995) by providing key and value combinations. You can tag the instance,
the volumes, or both.
8. For Advanced Details, expand the section to view the fields and specify any additional parameters
for the instance.
• Purchasing option: The purchasing model. Choose Request Spot instances to request
Spot Instances at the Spot price, capped at the On-Demand price, and choose Customize
Spot parameters to change the default Spot Instance settings. If you do not request a Spot
Instance, EC2 launches an On-Demand Instance by default. For more information, see Spot
Instances (p. 297).
• IAM instance profile: An AWS Identity and Access Management (IAM) instance profile to associate
with the instance. For more information, see IAM Roles for Amazon EC2 (p. 696).
• Shutdown behavior: Whether the instance should stop or terminate when shut down. For more
information, see Changing the Instance Initiated Shutdown Behavior (p. 482).
• Stop - Hibernate behavior: Whether the instance is enabled for hibernation. This field is only valid
for instances that meet the hibernation prerequisites. For more information, see Hibernate Your
Instance (p. 470).
• Termination protection: Whether to prevent accidental termination. For more information, see
Enabling Termination Protection for an Instance (p. 481).
• Monitoring: Whether to enable detailed monitoring of the instance using Amazon CloudWatch.
Additional charges apply. For more information, see Monitoring Your Instances Using
CloudWatch (p. 558).
• T2/T3 Unlimited: Whether to enable applications to burst beyond the baseline for as long as
needed. This field is only valid for T2 and T3 instances. Additional charges may apply. For more
information, see Burstable Performance Instances (p. 192).
• Placement group name: Specify a placement group in which to launch the instance. Not all
instance types can be launched in a placement group. For more information, see Placement
Groups (p. 784).
408
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
• EBS-optimized instance: Provides additional, dedicated capacity for Amazon EBS I/O. Not all
instance types support this feature, and additional charges apply. For more information, see
Amazon EBS–Optimized Instances (p. 915).
• Tenancy: Choose whether to run your instance on shared hardware (Shared), isolated, dedicated
hardware (Dedicated), or on a Dedicated Host (Dedicated host). Additional charges may apply. For
more information, see Dedicated Instances (p. 377) and Dedicated Hosts (p. 359). If you specify
a Dedicated Host, you can choose a specific host and the affinity for the instance.
• RAM disk ID: A RAM disk for the instance. If you have specified a kernel, you may need to specify a
specific RAM disk with the drivers to support it. Only valid for paravirtual (PV) AMIs.
• Kernel ID: A kernel for the instance. Only valid for paravirtual (PV) AMIs.
• User data: You can specify user data to configure an instance during launch, or to run a
configuration script. For more information, see Running Commands on Your Linux Instance at
Launch (p. 520).
9. Choose Create launch template.
• Use the create-launch-template (AWS CLI) command. The following example creates a launch
template that specifies the following:
The template assigns a public IP address and an IPv6 address to the instance and creates a tag for
the instance (Name=webserver).
409
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
{
"NetworkInterfaces": [{
"AssociatePublicIpAddress": true,
"DeviceIndex": 0,
"Ipv6AddressCount": 1,
"SubnetId": "subnet-7b16de0c"
}],
"ImageId": "ami-8c1be5f6",
"InstanceType": "r4.4xlarge",
"TagSpecifications": [{
"ResourceType": "instance",
"Tags": [{
"Key":"Name",
"Value":"webserver"
}]
}],
"CpuOptions": {
"CoreCount":4,
"ThreadsPerCore":2
}
}
{
"LaunchTemplate": {
"LatestVersionNumber": 1,
"LaunchTemplateId": "lt-01238c059e3466abc",
"LaunchTemplateName": "TemplateForWebServer",
"DefaultVersionNumber": 1,
"CreatedBy": "arn:aws:iam::123456789012:root",
"CreateTime": "2017-11-27T09:13:24.000Z"
}
}
• Use the get-launch-template-data (AWS CLI) command and specify the instance ID. You can use
the output as a base to create a new launch template or launch template version. By default, the
output includes a top-level LaunchTemplateData object, which cannot be specified in your launch
template data. Use the --query option to exclude this object.
{
"Monitoring": {},
"ImageId": "ami-8c1be5f6",
"BlockDeviceMappings": [
{
410
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
"DeviceName": "/dev/xvda",
"Ebs": {
"DeleteOnTermination": true
}
}
],
"EbsOptimized": false,
"Placement": {
"Tenancy": "default",
"GroupName": "",
"AvailabilityZone": "us-east-1a"
},
"InstanceType": "t2.micro",
"NetworkInterfaces": [
{
"Description": "",
"NetworkInterfaceId": "eni-35306abc",
"PrivateIpAddresses": [
{
"Primary": true,
"PrivateIpAddress": "10.0.0.72"
}
],
"SubnetId": "subnet-7b16de0c",
"Groups": [
"sg-7c227019"
],
"Ipv6Addresses": [
{
"Ipv6Address": "2001:db8:1234:1a00::123"
}
],
"PrivateIpAddress": "10.0.0.72"
}
]
}
Tasks
• Creating a Launch Template Version (p. 411)
• Setting the Default Launch Template Version (p. 412)
• Deleting a Launch Template Version (p. 412)
When you create a launch template version, you can specify new launch parameters or use an existing
version as the base for the new version. For more information about the launch parameters, see Creating
a Launch Template (p. 405).
411
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
• Use the create-launch-template-version (AWS CLI) command. You can specify a source version on
which to base the new version. The new version inherits the launch parameters from this version,
and you can override parameters using --launch-template-data. The following example creates
a new version based on version 1 of the launch template and specifies a different AMI ID.
You can set the default version for the launch template. When you launch an instance from a launch
template and do not specify a version, the instance is launched using the parameters of the default
version.
• Use the modify-launch-template (AWS CLI) command and specify the version that you want to set as
the default.
If you no longer require a launch template version, you can delete it. You cannot replace the version
number after you delete it. You cannot delete the default version of the launch template; you must first
assign a different version as the default.
412
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
• Use the delete-launch-template-versions (AWS CLI) command and specify the version numbers to
delete.
Instances that are launched using a launch template are automatically assigned two tags with the keys
aws:ec2launchtemplate:id and aws:ec2launchtemplate:version. You cannot remove or edit
these tags.
• Use the run-instances AWS CLI command and specify the --launch-template parameter. Optionally
specify the launch template version to use. If you don't specify the version, the default version is used.
• To override a launch template parameter, specify the parameter in the run-instances command. The
following example overrides the instance type that's specified in the launch template (if any).
• If you specify a nested parameter that's part of a complex structure, the instance is launched using the
complex structure as specified in the launch template plus any additional nested parameters that you
specify.
413
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
In the following example, the instance is launched with the tag Owner=TeamA as well as any other
tags that are specified in the launch template. If the launch template has an existing tag with a key of
Owner, the value is replaced with TeamA.
In the following example, the instance is launched with a volume with the device name /dev/xvdb
as well as any other block device mappings that are specified in the launch template. If the launch
template has an existing volume defined for /dev/xvdb, its values are replaced with specified values.
If the instance fails to launch or the state immediately goes to terminated instead of running, see
Troubleshooting Instance Launch Issues (p. 1018).
For more information, see Creating an Auto Scaling Group Using a Launch Template in the Amazon EC2
Auto Scaling User Guide.
To create or update an Amazon EC2 Auto Scaling group with a launch template (AWS CLI)
• Use the create-auto-scaling-group or the update-auto-scaling-group AWS CLI command and specify
the --launch-template parameter.
• Use the create-fleet AWS CLI command. Use the --launch-template-configs parameter to
specify the launch template and any overrides for the launch template.
414
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
• Use the request-spot-fleet AWS CLI command. Use the LaunchTemplateConfigs parameter to
specify the launch template and any overrides for the launch template.
• Use the delete-launch-template (AWS CLI) command and specify the launch template.
The following configuration details are copied from the selected instance into the launch wizard:
• AMI ID
• Instance type
• Availability Zone, or the VPC and subnet in which the selected instance is located
• Public IPv4 address. If the selected instance currently has a public IPv4 address, the new instance
receives a public IPv4 address - regardless of the selected instance's default public IPv4 address
setting. For more information about public IPv4 addresses, see Public IPv4 Addresses and External DNS
Hostnames (p. 707).
• Placement group, if applicable
• IAM role associated with the instance, if applicable
• Shutdown behavior setting (stop or terminate)
• Termination protection setting (true or false)
415
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
The following configuration details are not copied from your selected instance; instead, the wizard
applies their default settings or behavior:
• Number of network interfaces: The default is one network interface, which is the primary network
interface (eth0).
• Storage: The default storage configuration is determined by the AMI and the instance type.
When you are ready, choose Launch to select a key pair and launch your instance.
4. If the instance fails to launch or the state immediately goes to terminated instead of running, see
Troubleshooting Instance Launch Issues (p. 1018).
Use the following procedure to create an AMI from the root volume of your instance using the console.
If you prefer, you can use one of the following commands instead: register-image (AWS CLI) or Register-
EC2Image (AWS Tools for Windows PowerShell). You specify the snapshot using the block device
mapping.
416
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
To launch an instance from the AWS Marketplace using the launch wizard
The wizard creates a new security group according to the vendor's specifications for the product. The
security group may include rules that allow all IPv4 addresses (0.0.0.0/0) access on SSH (port 22)
on Linux or RDP (port 3389) on Windows. We recommend that you adjust these rules to allow only a
specific address or range of addresses to access your instance over those ports.
417
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
7. On the Review Instance Launch page, check the details of the AMI from which you're about to
launch the instance, as well as the other configuration details you set up in the wizard. When you're
ready, choose Launch to select or create a key pair, and launch your instance.
8. Depending on the product you've subscribed to, the instance may take a few minutes or more to
launch. You are first subscribed to the product before your instance can launch. If there are any
problems with your credit card details, you will be asked to update your account details. When the
launch confirmation page displays, choose View Instances to go to the Instances page.
Note
You are charged the subscription price as long as your instance is running, even if it is idle. If
your instance is stopped, you may still be charged for storage.
9. When your instance is in the running state, you can connect to it. To do this, select your instance
in the list and choose Connect. Follow the instructions in the dialog. For more information about
connecting to your instance, see Connect to Your Linux Instance (p. 446).
Important
Check the vendor's usage instructions carefully, as you may need to use a specific user name
to log in to the instance. For more information about accessing your subscription details,
see Managing Your AWS Marketplace Subscriptions (p. 115).
10. If the instance fails to launch or the state immediately goes to terminated instead of running, see
Troubleshooting Instance Launch Issues (p. 1018).
Launching an AWS Marketplace AMI Instance Using the API and CLI
To launch instances from AWS Marketplace products using the API or command line tools, first ensure
that you are subscribed to the product. You can then launch an instance with the product's AMI ID using
the following methods:
Method Documentation
AWS CLI Use the run-instances command, or see the following topic for more
information: Launching an Instance.
AWS Tools for Windows Use the New-EC2Instance command, or see the following topic for
PowerShell more information: Launch an Amazon EC2 Instance Using Windows
PowerShell
• Define separate On-Demand and Spot capacity targets and the maximum amount you’re willing to pay
per hour
• Specify the instance types that work best for your applications
• Specify how Amazon EC2 should distribute your fleet capacity within each purchasing option
You can also set a maximum amount per hour that you’re willing to pay for your fleet, and EC2 Fleet
launches instances until it reaches the maximum amount. When the maximum amount you're willing to
pay is reached, the fleet stops launching instances even if it hasn’t met the target capacity.
418
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
The EC2 Fleet attempts to launch the number of instances that are required to meet the target capacity
specified in your request. If you specified a total maximum price per hour, it fulfills the capacity until it
reaches the maximum amount that you’re willing to pay. The fleet can also attempt to maintain its target
Spot capacity if your Spot Instances are interrupted. For more information, see How Spot Instances
Work (p. 300).
You can specify an unlimited number of instance types per EC2 Fleet. Those instance types can be
provisioned using both On-Demand and Spot purchasing options. You can also specify multiple
Availability Zones, specify different maximum Spot prices for each instance, and choose additional
Spot options for each fleet. Amazon EC2 uses the specified options to provision capacity when the fleet
launches.
While the fleet is running, if Amazon EC2 reclaims a Spot Instance because of a price increase or instance
failure, EC2 Fleet can try to replace the instances with any of the instance types that you specify. This
makes it easier to regain capacity during a spike in Spot pricing. You can develop a flexible and elastic
resourcing strategy for each fleet. For example, within specific fleets, your primary capacity can be On-
Demand supplemented with less-expensive Spot capacity if available.
If you have Reserved Instances and you specify On-Demand Instances in your fleet, EC2 Fleet uses your
Reserved Instances. For example, if your fleet specifies an On-Demand Instance as c4.large, and you
have Reserved Instances for c4.large, you receive the Reserved Instance pricing.
There is no additional charge for using EC2 Fleet. You pay only for the EC2 instances that the fleet
launches for you.
Contents
• EC2 Fleet Limitations (p. 419)
• EC2 Fleet Limits (p. 419)
• EC2 Fleet Configuration Strategies (p. 420)
• Managing an EC2 Fleet (p. 429)
419
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
If you need more than the default limits for target capacity, complete the AWS Support Center Create
case form to request a limit increase. For Limit type, choose EC2 Fleet, choose a Region, and then choose
Target Fleet Capacity per Fleet (in units) or Target Fleet Capacity per Region (in units), or both.
* These limits apply to both your EC2 Fleets and your Spot Fleets.
† These are hard limits. You cannot request a limit increase for these limits.
T3 Instances
If you plan to use your T3 Spot Instances immediately and for a short duration, with no idle time for
accruing CPU credits, we recommend that you launch your T3 Spot Instances in standard (p. 203) mode
to avoid paying higher costs.
If you launch your T3 Spot Instances in unlimited (p. 196) mode and burst CPU immediately, you'll
spend surplus credits for bursting. If you use the instance for a short duration, your instance doesn't have
time to accrue CPU credits to pay down the surplus credits, and you are charged for the surplus credits
when you terminate your instance.
Unlimited mode for T3 Spot Instances is suitable only if the instance runs for long enough to accrue
CPU credits for bursting. Otherwise, paying for surplus credits makes T3 Spot Instances more expensive
than M5 or C5 instances.
T2 Instances
Launch credits are meant to provide a productive initial launch experience for T2 instances by providing
sufficient compute resources to configure the instance. Repeated launches of T2 instances to access new
launch credits is not permitted. If you require sustained CPU, you can earn credits (by idling over some
period), use T2 Unlimited (p. 196), or use an instance type with dedicated CPU (for example, c4.large).
The EC2 Fleet attempts to launch the number of instances that are required to meet the target capacity
that you specify in the fleet request. The fleet can comprise only On-Demand Instances, only Spot
Instances, or a combination of both On-Demand Instances and Spot Instances. The request for Spot
Instances is fulfilled if there is available capacity and the maximum price per hour for your request
exceeds the Spot price. The fleet also attempts to maintain its target capacity if your Spot Instances are
interrupted.
You can also set a maximum amount per hour that you’re willing to pay for your fleet, and EC2 Fleet
launches instances until it reaches the maximum amount. When the maximum amount you're willing to
pay is reached, the fleet stops launching instances even if it hasn’t met the target capacity.
A Spot Instance pool is a set of unused EC2 instances with the same instance type, operating system,
Availability Zone, and network platform. When you create an EC2 Fleet, you can include multiple launch
specifications, which vary by instance type, Availability Zone, subnet, and maximum price. The fleet
selects the Spot Instance pools that are used to fulfill the request, based on the launch specifications
420
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
included in your request, and the configuration of the request. The Spot Instances come from the
selected pools.
An EC2 Fleet enables you to provision large amounts of EC2 capacity that makes sense for your
application based on number of cores or instances, or amount of memory. For example, you can specify
an EC2 Fleet to launch a target capacity of 200 instances, of which 130 are On-Demand Instances and
the rest are Spot Instances. Or you can request 1000 cores with a minimum of 2 GB of RAM per core. The
fleet determines the combination of Amazon EC2 options to launch that capacity at the absolute lowest
cost.
Use the appropriate configuration strategies to create an EC2 Fleet that meets your needs.
Contents
• Planning an EC2 Fleet (p. 421)
• EC2 Fleet Request Types (p. 421)
• Allocation Strategies for Spot Instances (p. 422)
• Configuring EC2 Fleet for On-Demand Backup (p. 423)
• Maximum Price Overrides (p. 424)
• Control Spending (p. 424)
• EC2 Fleet Instance Weighting (p. 424)
• Tutorial: Using EC2 Fleet with Instance Weighting (p. 426)
• Tutorial: Using EC2 Fleet with On-Demand as the Primary Capacity (p. 428)
When planning your EC2 Fleet, we recommend that you do the following:
• Determine whether you want to create an EC2 Fleet that submits a synchronous or asynchronous one-
time request for the desired target capacity, or one that maintains a target capacity over time. For
more information, see EC2 Fleet Request Types (p. 421).
• Determine the instance types that meet your application requirements.
• If you plan to include Spot Instances in your EC2 Fleet, review Spot Best Practices before you create
the fleet. Use these best practices when you plan your fleet so that you can provision the instances at
the lowest possible price.
• Determine the target capacity for your EC2 Fleet. You can set target capacity in instances or in custom
units. For more information, see EC2 Fleet Instance Weighting (p. 424).
• Determine what portion of the EC2 Fleet target capacity must be On-Demand capacity and Spot
capacity. You can specify 0 for On-Demand capacity or Spot capacity, or both.
• Determine your price per unit, if you are using instance weighting. To calculate the price per unit,
divide the price per instance hour by the number of units (or weight) that this instance represents. If
you are not using instance weighting, the default price per unit is the price per instance hour.
• Determine the maximum amount per hour that you’re willing to pay for your fleet. For more
information, see Control Spending (p. 424).
• Review the possible options for your EC2 Fleet. For more information, see the EC2 Fleet JSON
Configuration File Reference (p. 434). For EC2 Fleet configuration examples, see EC2 Fleet Example
Configurations (p. 443).
421
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
instant
If you configure the request type as instant, EC2 Fleet places a synchronous one-time request for
your desired capacity. In the API response, it returns the instances that launched, along with errors
for those instances that could not be launched.
request
If you configure the request type as request, EC2 Fleet places an asynchronous one-time request
for your desired capacity. Thereafter, if capacity is diminished because of Spot interruptions, the
fleet does not attempt to replenish Spot Instances, nor does it submit requests in alternative Spot
Instance pools if capacity is unavailable.
maintain
(Default) If you configure the request type as maintain, EC2 Fleet places an asynchronous request
for your desired capacity, and maintains capacity by automatically replenishing any interrupted Spot
Instances.
You cannot modify the target capacity of an instant or request EC2 Fleet request after it is
submitted. To change the target capacity of an instant or request fleet request, delete the fleet and
create a new one.
All three types of requests benefit from an allocation strategy. For more information, see Allocation
Strategies for Spot Instances (p. 422).
The allocation strategy for your EC2 Fleet determines how it fulfills your request for Spot Instances from
the possible Spot Instance pools represented by its launch specifications. The following are the allocation
strategies that you can specify in your fleet:
lowestPrice
The Spot Instances come from the pool with the lowest price. This is the default strategy.
diversified
The Spot Instances are distributed across the number of Spot pools that you specify. This parameter
is valid only when used in combination with lowestPrice.
After Spot Instances are terminated due to a change in the Spot price or available capacity of a Spot
Instance pool, an EC2 Fleet of type maintain launches replacement Spot Instances. If the allocation
strategy is lowestPrice, the fleet launches replacement instances in the pool where the Spot price is
currently the lowest. If the allocation strategy is diversified, the fleet distributes the replacement
Spot Instances across the remaining pools. If the allocation strategy is lowestPrice in combination
with InstancePoolsToUseCount, the fleet selects the Spot pools with the lowest price and launches
Spot Instances across the number of Spot pools that you specify.
To optimize the costs for your use of Spot Instances, specify the lowestPrice allocation strategy so
that EC2 Fleet automatically deploys the cheapest combination of instance types and Availability Zones
based on the current Spot price.
422
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
For On-Demand Instance target capacity, EC2 Fleet always selects the cheapest instance type based on
the public On-Demand price, while continuing to follow the allocation strategy (either lowestPrice or
diversified) for Spot Instances.
If your fleet is small or runs for a short time, the probability that your Spot Instances will be interrupted
is low, even with all of the instances in a single Spot Instance pool. Therefore, the lowestPrice strategy
is likely to meet your needs while providing the lowest cost.
If your fleet is large or runs for a long time, you can improve the availability of your fleet by distributing
the Spot Instances across multiple pools. For example, if your EC2 Fleet specifies 10 pools and a target
capacity of 100 instances, the fleet launches 10 Spot Instances in each pool. If the Spot price for one
pool exceeds your maximum price for this pool, only 10% of your fleet is affected. Using this strategy
also makes your fleet less sensitive to increases in the Spot price in any one pool over time.
With the diversified strategy, the EC2 Fleet does not launch Spot Instances into any pools with a
Spot price that is equal to or higher than the On-Demand price.
To create a cheap and diversified fleet, use the lowestPrice strategy in combination with
InstancePoolsToUseCount. You can use a low or high number of Spot pools across which to allocate
your Spot Instances. For example, if you run batch processing, we recommend specifying a low number
of Spot pools (for example, InstancePoolsToUseCount=2) to ensure that your queue always has
compute capacity while maximizing savings. If you run a web service, we recommend specifying a high
number of Spot pools (for example, InstancePoolsToUseCount=10) to minimize the impact if a Spot
Instance pool becomes temporarily unavailable.
For example, you have configured three launch template overrides, each with a different instance type:
c3.large, c4.large, and c5.large. The On-Demand price for c5.large is less than the price for
c4.large. c3.large is the cheapest. If you do not use priority to determine the order, the fleet fulfills
On-Demand capacity by starting with c3.large, and then c5.large. Because you often have unused
Reserved Instances for c4.large, you can set the launch template override priority so that the order is
c4.large, c3.large, and then c5.large.
423
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
Each EC2 Fleet can either include a global maximum price, or use the default (the On-Demand price). The
fleet uses this as the default maximum price for each of its launch specifications.
You can optionally specify a maximum price in one or more launch specifications. This price is specific
to the launch specification. If a launch specification includes a specific price, the EC2 Fleet uses this
maximum price, overriding the global maximum price. Any other launch specifications that do not
include a specific maximum price still use the global maximum price.
Control Spending
EC2 Fleet stops launching instances when it has met one of the following parameters: the
TotalTargetCapacity or the MaxTotalPrice (the maximum amount you’re willing to pay). To
control the amount you pay per hour for your fleet, you can specify the MaxTotalPrice. When the
maximum total price is reached, EC2 Fleet stops launching instances even if it hasn’t met the target
capacity.
The following examples show two different scenarios. In the first, EC2 Fleet stops launching instances
when it has met the target capacity. In the second, EC2 Fleet stops launching instances when it has
reached the maximum amount you’re willing to pay (MaxTotalPrice).
EC2 Fleet launches 10 On-Demand Instances because the total of $1.00 (10 instances x $0.10) does not
exceed the MaxTotalPrice of $1.50 for On-Demand Instances.
If EC2 Fleet launches the On-Demand target capacity (10 On-Demand Instances), the total cost per
hour would be $1.00. This is more than the amount ($0.80) specified for MaxTotalPrice for On-
Demand Instances. To prevent spending more than you're willing to pay, EC2 Fleet launches only 8 On-
Demand Instances (below the On-Demand target capacity) because launching more would exceed the
MaxTotalPrice for On-Demand Instances.
When you create an EC2 Fleet, you can define the capacity units that each instance type would
contribute to your application's performance. You can then adjust your maximum price for each launch
specification by using instance weighting.
By default, the price that you specify is per instance hour. When you use the instance weighting feature,
the price that you specify is per unit hour. You can calculate your price per unit hour by dividing your
price for an instance type by the number of units that it represents. EC2 Fleet calculates the number of
instances to launch by dividing the target capacity by the instance weight. If the result isn't an integer,
424
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
the fleet rounds it up to the next integer, so that the size of your fleet is not below its target capacity.
The fleet can select any pool that you specify in your launch specification, even if the capacity of the
instances launched exceeds the requested target capacity.
The following table includes examples of calculations to determine the price per unit for an EC2 Fleet
with a target capacity of 10.
Instance Instance Target Number of Price per Price per unit hour
type weight capacity instances instance
launched hour
Use EC2 Fleet instance weighting as follows to provision the target capacity that you want in the pools
with the lowest price per unit at the time of fulfillment:
1. Set the target capacity for your EC2 Fleet either in instances (the default) or in the units of your
choice, such as virtual CPUs, memory, storage, or throughput.
2. Set the price per unit.
3. For each launch specification, specify the weight, which is the number of units that the instance type
represents toward the target capacity.
• A target capacity of 24
• A launch specification with an instance type r3.2xlarge and a weight of 6
• A launch specification with an instance type c3.xlarge and a weight of 5
The weights represent the number of units that instance type represents toward the target capacity. If
the first launch specification provides the lowest price per unit (price for r3.2xlarge per instance hour
divided by 6), the EC2 Fleet would launch four of these instances (24 divided by 6).
If the second launch specification provides the lowest price per unit (price for c3.xlarge per instance
hour divided by 5), the EC2 Fleet would launch five of these instances (24 divided by 5, result rounded
up).
425
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
The EC2 Fleet would launch four instances (30 divided by 8, result rounded up). With the lowestPrice
strategy, all four instances come from the pool that provides the lowest price per unit. With the
diversified strategy, the fleet launches one instance in each of the three pools, and the fourth
instance in whichever of the three pools provides the lowest price per unit.
Objective
Example Corp, a pharmaceutical company, wants to use the computational power of Amazon EC2 for
screening chemical compounds that might be used to fight cancer.
Planning
Example Corp first reviews Spot Best Practices. Next, Example Corp determines the requirements for
their EC2 Fleet.
Instance Types
Example Corp has a compute- and memory-intensive application that performs best with at least 60 GB
of memory and eight virtual CPUs (vCPUs). They want to maximize these resources for the application at
the lowest possible price. Example Corp decides that any of the following EC2 instance types would meet
their needs:
r3.2xlarge 61 8
r3.4xlarge 122 16
r3.8xlarge 244 32
With instance weighting, target capacity can equal a number of instances (the default) or a combination
of factors such as cores (vCPUs), memory (GiBs), and storage (GBs). By considering the base for their
application (60 GB of RAM and eight vCPUs) as one unit, Example Corp decides that 20 times this
amount would meet their needs. So the company sets the target capacity of their EC2 Fleet request to
20.
Instance Weights
After determining the target capacity, Example Corp calculates instance weights. To calculate the
instance weight for each instance type, they determine the units of each instance type that are required
to reach the target capacity as follows:
Therefore, Example Corp assigns instance weights of 1, 2, and 4 to the respective launch configurations
in their EC2 Fleet request.
426
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
Example Corp uses the On-Demand price per instance hour as a starting point for their price. They could
also use recent Spot prices, or a combination of the two. To calculate the price per unit hour, they divide
their starting price per instance hour by the weight. For example:
Instance type On-Demand price Instance weight Price per unit hour
Example Corp could use a global price per unit hour of $0.7 and be competitive for all three instance
types. They could also use a global price per unit hour of $0.7 and a specific price per unit hour of $0.9 in
the r3.8xlarge launch specification.
Verifying Permissions
Before creating an EC2 Fleet, Example Corp verifies that it has an IAM role with the required permissions.
For more information, see EC2 Fleet Prerequisites (p. 430).
{
"LaunchTemplateConfigs": [
{
"LaunchTemplateSpecification": {
"LaunchTemplateId": "lt-07b3bc7625cdab851",
"Version": "1"
},
"Overrides": [
{
"InstanceType": "r3.2xlarge",
"SubnetId": "subnet-482e4972",
"WeightedCapacity": 1
},
{
"InstanceType": "r3.4xlarge",
"SubnetId": "subnet-482e4972",
"WeightedCapacity": 2
},
{
"InstanceType": "r3.8xlarge",
"MaxPrice": "0.90",
"SubnetId": "subnet-482e4972",
"WeightedCapacity": 4
}
]
}
],
"TargetCapacitySpecification": {
"TotalTargetCapacity": 20,
"DefaultTargetCapacityType": "spot"
}
}
Example Corp creates the EC2 Fleet using the following create-fleet command.
427
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
Fulfillment
The allocation strategy determines which Spot Instance pools your Spot Instances come from.
With the lowestPrice strategy (which is the default strategy), the Spot Instances come from the pool
with the lowest price per unit at the time of fulfillment. To provide 20 units of capacity, the EC2 Fleet
launches either 20 r3.2xlarge instances (20 divided by 1), 10 r3.4xlarge instances (20 divided by 2),
or 5 r3.8xlarge instances (20 divided by 4).
If Example Corp used the diversified strategy, the Spot Instances would come from all three pools.
The EC2 Fleet would launch 6 r3.2xlarge instances (which provide 6 units), 3 r3.4xlarge instances
(which provide 6 units), and 2 r3.8xlarge instances (which provide 8 units), for a total of 20 units.
This tutorial uses a fictitious company called ABC Online to illustrate the process of requesting an EC2
Fleet with On-Demand as the primary capacity, and Spot capacity if available.
Objective
ABC Online, a restaurant delivery company, wants to be able to provision Amazon EC2 capacity across
EC2 instance types and purchasing options to achieve their desired scale, performance, and cost.
Planning
ABC Online requires a fixed capacity to operate during peak periods, but would like to benefit from
increased capacity at a lower price. ABC Online determines the following requirements for their EC2
Fleet:
• On-Demand Instance capacity – ABC Online requires 15 On-Demand Instances to ensure that they can
accommodate traffic at peak periods.
• Spot Instance capacity – ABC Online would like to improve performance, but at a lower price, by
provisioning 5 Spot Instances.
Verifying Permissions
Before creating an EC2 Fleet, ABC Online verifies that it has an IAM role with the required permissions.
For more information, see EC2 Fleet Prerequisites (p. 430).
ABC Online creates a file, config.json, with the following configuration for its EC2 Fleet.
{
"LaunchTemplateConfigs": [
{
"LaunchTemplateSpecification": {
"LaunchTemplateId": "lt-07b3bc7625cdab851",
"Version": "2"
}
}
],
"TargetCapacitySpecification": {
428
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
"TotalTargetCapacity": 20,
"OnDemandTargetCapacity":15,
"DefaultTargetCapacityType": "spot"
}
}
ABC Online creates the EC2 Fleet using the following create-fleet command.
Fulfillment
The allocation strategy determines that the On-Demand capacity is always fulfilled, while the balance of
the target capacity is fulfilled as Spot if there is capacity and availability.
If your fleet includes Spot Instances, Amazon EC2 can attempt to maintain your fleet target capacity as
Spot prices change.
An EC2 Fleet request remains active until it expires or you delete it. When you delete a fleet, you can
specify whether deletion terminates the instances in that fleet.
Contents
• EC2 Fleet Request States (p. 429)
• EC2 Fleet Prerequisites (p. 430)
• EC2 Fleet Health Checks (p. 432)
• Generating an EC2 Fleet JSON Configuration File (p. 433)
• Creating an EC2 Fleet (p. 437)
• Tagging an EC2 Fleet (p. 440)
• Monitoring Your EC2 Fleet (p. 429)
• Modifying an EC2 Fleet (p. 442)
• Deleting an EC2 Fleet (p. 442)
• EC2 Fleet Example Configurations (p. 443)
• submitted – The EC2 Fleet request is being evaluated and Amazon EC2 is preparing to launch the
target number of instances, which can include On-Demand Instances, Spot Instances, or both.
• active – The EC2 Fleet request has been validated and Amazon EC2 is attempting to maintain the
target number of running instances. The request remains in this state until it is modified or deleted.
429
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
• modifying – The EC2 Fleet request is being modified. The request remains in this state until the
modification is fully processed or the request is deleted. Only a maintain request type can be
modified. This state does not apply to other request types.
• deleted_running – The EC2 Fleet request is deleted and does not launch additional instances. Its
existing instances continue to run until they are interrupted or terminated. The request remains in this
state until all instances are interrupted or terminated.
• deleted_terminating – The EC2 Fleet request is deleted and its instances are terminating. The
request remains in this state until all instances are terminated.
• deleted – The EC2 Fleet is deleted and has no running instances. The request is deleted two days
after its instances are terminated.
The following illustration represents the transitions between the EC2 Fleet request states. If you exceed
your fleet limits, the request is deleted immediately.
Launch Template
A launch template includes information about the instances to launch, such as the instance type,
Availability Zone, and the maximum price that you are willing to pay. For more information, see
Launching an Instance from a Launch Template (p. 403).
The AWSServiceRoleForEC2Fleet role grants the EC2 Fleet permission to request, launch, terminate,
and tag instances on your behalf. Amazon EC2 uses this service-linked role to complete the following
actions:
430
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
Ensure that this role exists before you use the AWS CLI or an API to create an EC2 Fleet. To create the
role, use the IAM console as follows.
If you no longer need to use EC2 Fleet, we recommend that you delete the AWSServiceRoleForEC2Fleet
role. After this role is deleted from your account, you can create the role again if you create another fleet.
For more information, see Using Service-Linked Roles in the IAM User Guide.
Granting Access to CMKs for Use with Encrypted AMIs and EBS Snapshots
If you specify an encrypted AMI (p. 149) or an encrypted Amazon EBS snapshot (p. 903) in your EC2
Fleet and you use a customer managed customer master key (CMK) for encryption, you must grant the
AWSServiceRoleForEC2Fleet role permission to use the CMK so that Amazon EC2 can launch instances
on your behalf. To do this, you must add a grant to the CMK, as shown in the following procedure.
When providing permissions, grants are an alternative to key policies. For more information, see Using
Grants and Using Key Policies in AWS KMS in the AWS Key Management Service Developer Guide.
• Use the create-grant command to add a grant to the CMK and to specify the principal (the
AWSServiceRoleForEC2Fleet service-linked role) that is given permission to perform the operations
that the grant permits. The CMK is specified by the key-id parameter and the ARN of the
CMK. The principal is specified by the grantee-principal parameter and the ARN of the
AWSServiceRoleForEC2Fleet service-linked role.
431
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
4. On the Create policy page, choose the JSON tab, replace the text with the following, and choose
Review policy.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:*"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"iam:ListRoles",
"iam:PassRole",
"iam:ListInstanceProfiles"
],
"Resource": "*"
}
]
}
The ec2:* grants an IAM user permission to call all Amazon EC2 API actions. To limit the user to
specific Amazon EC2 API actions, specify those actions instead.
An IAM user must have permission to call the iam:ListRoles action to enumerate
existing IAM roles, the iam:PassRole action to specify the EC2 Fleet role, and the
iam:ListInstanceProfiles action to enumerate existing instance profiles.
(Optional) To enable an IAM user to create roles or instance profiles using the IAM console, you must
also add the following actions to the policy:
• iam:AddRoleToInstanceProfile
• iam:AttachRolePolicy
• iam:CreateInstanceProfile
• iam:CreateRole
• iam:GetRole
• iam:ListPolicies
5. On the Review policy page, enter a policy name and description, and choose Create policy.
6. In the navigation pane, choose Users and select the user.
7. On the Permissions tab, choose Add permissions.
8. Choose Attach existing policies directly. Select the policy that you created earlier and choose Next:
Review.
9. Choose Add permissions.
EC2 Fleet checks the health status of the instances in the fleet every two minutes. The health status
of an instance is either healthy or unhealthy. The fleet determines the health status of an instance
using the status checks provided by Amazon EC2. If the status of either the instance status check or the
system status check is impaired for three consecutive health checks, the health status of the instance is
unhealthy. Otherwise, the health status is healthy. For more information, see Status Checks for Your
Instances (p. 547).
432
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
You can configure your EC2 Fleet to replace unhealthy instances. After enabling health check
replacement, an instance is replaced after its health status is reported as unhealthy. The fleet could go
below its target capacity for up to a few minutes while an unhealthy instance is being replaced.
Requirements
• Health check replacement is supported only with EC2 Fleets that maintain a target capacity, not with
one-time fleets.
• You can configure your EC2 Fleet to replace unhealthy instances only when you create it.
• IAM users can use health check replacement only if they have permission to call the
ec2:DescribeInstanceStatus action.
To create an EC2 Fleet, you need only specify the launch template, total target capacity, and whether
the default purchasing option is On-Demand or Spot. If you do not specify a parameter, the fleet uses
the default value. To view the full list of fleet configuration parameters, you can generate a JSON file as
follows.
To generate a JSON file with all possible EC2 Fleet parameters using the command line
• Use the create-fleet (AWS CLI) command and the --generate-cli-skeleton parameter to
generate an EC2 Fleet JSON file:
{
"DryRun": true,
"ClientToken": "",
"SpotOptions": {
"AllocationStrategy": "lowestPrice",
"InstanceInterruptionBehavior": "hibernate",
"InstancePoolsToUseCount": 0
"SingleInstanceType": true,
"SingleAvailabilityZone": true,
"MaxTotalPrice": 0
"MinTargetCapacity": 0
},
"OnDemandOptions": {
"AllocationStrategy": "prioritized"
"SingleInstanceType": true,
"SingleAvailabilityZone": true,
"MaxTotalPrice": 0
"MinTargetCapacity": 0
},
"ExcessCapacityTerminationPolicy": "termination",
"LaunchTemplateConfigs": [
{
"LaunchTemplateSpecification": {
"LaunchTemplateId": "",
"LaunchTemplateName": "",
"Version": ""
},
"Overrides": [
{
"InstanceType": "t2.micro",
"MaxPrice": "",
"SubnetId": "",
433
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
"AvailabilityZone": "",
"WeightedCapacity": null,
"Priority": null
"Placement": {
"AvailabilityZone": "",
"Affinity": "",
"GroupName": "",
"PartitionNumber": 0,
"HostId": "",
"Tenancy": "dedicated",
"SpreadDomain": ""
}
]
}
],
"TargetCapacitySpecification": {
"TotalTargetCapacity": 0,
"OnDemandTargetCapacity": 0,
"SpotTargetCapacity": 0,
"DefaultTargetCapacityType": "spot"
},
"TerminateInstancesWithExpiration": true,
"Type": "maintain",
"ValidFrom": "1970-01-01T00:00:00",
"ValidUntil": "1970-01-01T00:00:00",
"ReplaceUnhealthyInstances": true,
"TagSpecifications": [
{
"ResourceType": "fleet",
"Tags": [
{
"Key": "",
"Value": ""
}
]
}
]
}
(Optional) Indicates how to allocate the Spot Instance target capacity across the Spot Instance
pools specified by the EC2 Fleet. Valid values are lowestPrice and diversified. The default is
lowestPrice. Specify the allocation strategy that meets your needs. For more information, see
Allocation Strategies for Spot Instances (p. 422).
InstanceInterruptionBehavior
(Optional) The behavior when a Spot Instance is interrupted. Valid values are hibernate, stop, and
terminate. By default, the Spot service terminates Spot Instances when they are interrupted. If
the fleet type is maintain, you can specify that the Spot service hibernates or stops Spot Instances
when they are interrupted.
InstancePoolsToUseCount
The number of Spot pools across which to allocate your target Spot capacity. Valid only when Spot
AllocationStrategy is set to lowestPrice. EC2 Fleet selects the cheapest Spot pools and evenly
allocates your target Spot capacity across the number of Spot pools that you specify.
434
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
SingleInstanceType
Indicates that the fleet uses a single instance type to launch all Spot Instances in the fleet.
SingleAvailabilityZone
Indicates that the fleet launches all Spot Instances into a single Availability Zone.
MaxTotalPrice
The maximum amount per hour for Spot Instances that you're willing to pay.
MinTargetCapacity
The minimum target capacity for Spot Instances in the fleet. If the minimum target capacity is not
reached, the fleet launches no instances.
AllocationStrategy (for OnDemandOptions)
The order of the launch template overrides to use in fulfilling On-Demand capacity. If you specify
lowestPrice, EC2 Fleet uses price to determine the order, launching the lowest price first. If
you specify prioritized, EC2 Fleet uses the priority that you assigned to each launch template
override, launching the highest priority first. If you do not specify a value, EC2 Fleet defaults to
lowestPrice.
SingleInstanceType
Indicates that the fleet uses a single instance type to launch all On-Demand Instances in the fleet.
SingleAvailabilityZone
Indicates that the fleet launches all On-Demand Instances into a single Availability Zone.
MaxTotalPrice
The maximum amount per hour for On-Demand Instances that you're willing to pay.
MinTargetCapacity
The minimum target capacity for On-Demand Instances in the fleet. If the minimum target capacity
is not reached, the fleet launches no instances.
ExcessCapacityTerminationPolicy
(Optional) Indicates whether running instances should be terminated if the total target capacity
of the EC2 Fleet is decreased below the current size of the EC2 Fleet. Valid values are no-
termination and termination.
LaunchTemplateId
The ID of the launch template to use. You must specify either the launch template ID or launch
template name. The launch template must specify an Amazon Machine Image (AMI). For
more information about creating launch templates, see Launching an Instance from a Launch
Template (p. 403).
LaunchTemplateName
The name of the launch template to use. You must specify either the launch template ID or launch
template name. The launch template must specify an Amazon Machine Image (AMI). For more
information, see Launching an Instance from a Launch Template (p. 403).
Version
(Optional) The instance type. If entered, this value overrides the launch template. The instance types
must have the minimum hardware specifications that you need (vCPUs, memory, or storage).
435
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
MaxPrice
(Optional) The maximum price per unit hour that you are willing to pay for a Spot Instance. If
entered, this value overrides the launch template. You can use the default maximum price (the On-
Demand price) or specify the maximum price that you are willing to pay. Your Spot Instances are
not launched if your maximum price is lower than the Spot price for the instance types that you
specified.
SubnetId
(Optional) The ID of the subnet in which to launch the instances. If entered, this value overrides the
launch template.
To create a new VPC, go the Amazon VPC console. When you are done, return to the JSON file and
enter the new subnet ID.
AvailabilityZone
(Optional) The Availability Zone in which to launch the instances. The default is to let AWS choose
the zones for your instances. If you prefer, you can specify specific zones. If entered, this value
overrides the launch template.
Specify one or more Availability Zones. If you have more than one subnet in a zone, specify the
appropriate subnet. To add subnets, go to the Amazon VPC console. When you are done, return to
the JSON file and enter the new subnet ID.
WeightedCapacity
(Optional) The number of units provided by the specified instance type. If entered, this value
overrides the launch template.
Priority
The priority for the launch template override. If AllocationStrategy is set to prioritized, EC2
Fleet uses priority to determine which launch template override to use first in fulfilling On-Demand
capacity. The highest priority is launched first. Valid values are whole numbers starting at 0. The
lower the number, the higher the priority. If no number is set, the override has the lowest priority.
TotalTargetCapacity
The number of instances to launch. You can choose instances or performance characteristics that are
important to your application workload, such as vCPUs, memory, or storage. If the request type is
maintain, you can specify a target capacity of 0 and add capacity later.
OnDemandTargetCapacity
(Optional) The number of On-Demand Instances to launch. This number must be less than the
TotalTargetCapacity.
SpotTargetCapacity
(Optional) The number of Spot Instances to launch. This number must be less than the
TotalTargetCapacity.
DefaultTargetCapacityType
If the value for TotalTargetCapacity is higher than the combined values for
OnDemandTargetCapacity and SpotTargetCapacity, the difference is launched as the instance
purchasing option specified here. Valid values are on-demand or spot.
TerminateInstancesWithExpiration
(Optional) By default, Amazon EC2 terminates your instances when the EC2 Fleet request expires.
The default value is true. To keep them running after your request expires, do not enter a value for
this parameter.
436
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
Type
(Optional) Indicates whether the EC2 Fleet submits a synchronous one-time request for your desired
capacity (instant), or an asynchronous one-time request for your desired capacity, but with
no attempt maintain the capacity or to submit requests in alternative capacity pools if capacity
is unavailable (request), or submits an asynchronous request for your desired capacity and
continues to maintain your desired capacity by replenishing interrupted Spot Instances (maintain).
Valid values are instant, request, and maintain. The default value is maintain. For more
information, see EC2 Fleet Request Types (p. 421).
ValidFrom
(Optional) To create a request that is valid only during a specific time period, enter a start date.
ValidUntil
(Optional) To create a request that is valid only during a specific time period, enter an end date.
ReplaceUnhealthyInstances
(Optional) To replace unhealthy instances in an EC2 Fleet that is configured to maintain the fleet,
enter true. Otherwise, leave this parameter empty.
TagSpecifications
(Optional) The key-value pair for tagging the EC2 Fleet request on creation. The value for
ResourceType must be fleet, otherwise the fleet request fails. To tag instances at launch, specify
the tags in the launch template (p. 405). For information about tagging after launch, see Tagging
Your Resources (p. 997).
When you create an EC2 Fleet, you must specify a launch template that includes information about the
instances to launch, such as the instance type, Availability Zone, and the maximum price you are willing
to pay.
You can create an EC2 Fleet that includes multiple launch specifications that override the launch
template. The launch specifications can vary by instance type, Availability Zone, subnet, and maximum
price, and can include a different weighted capacity.
When you create an EC2 Fleet, use a JSON file to specify information about the instances to launch. For
more information, see EC2 Fleet JSON Configuration File Reference (p. 434).
• Use the following create-fleet (AWS CLI) command to create an EC2 Fleet.
For example configuration files, see EC2 Fleet Example Configurations (p. 443).
{
"FleetId": "fleet-12a34b55-67cd-8ef9-ba9b-9208dEXAMPLE"
}
The following is example output for a fleet of type instant that launched the target capacity.
437
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
{
"FleetId": "fleet-12a34b55-67cd-8ef9-ba9b-9208dEXAMPLE",
"Errors": [],
"Instances": [
{
"LaunchTemplateAndOverrides": {
"LaunchTemplateSpecification": {
"LaunchTemplateId": "lt-01234a567b8910abcEXAMPLE",
"Version": "1"
},
"Overrides": {
"InstanceType": "c5.large",
"AvailabilityZone": "us-east-1a"
}
},
"Lifecycle": "on-demand",
"InstanceIds": [
"i-1234567890abcdef0",
"i-9876543210abcdef9"
],
"InstanceType": "c5.large",
"Platform": null
},
{
"LaunchTemplateAndOverrides": {
"LaunchTemplateSpecification": {
"LaunchTemplateId": "lt-01234a567b8910abcEXAMPLE",
"Version": "1"
},
"Overrides": {
"InstanceType": "c4.large",
"AvailabilityZone": "us-east-1a"
}
},
"Lifecycle": "on-demand",
"InstanceIds": [
"i-5678901234abcdef0",
"i-5432109876abcdef9"
],
"InstanceType": "c4.large",
"Platform": null
},
]
}
The following is example output for a fleet of type instant that launched part of the target capacity
with errors for instances that were not launched.
{
"FleetId": "fleet-12a34b55-67cd-8ef9-ba9b-9208dEXAMPLE",
"Errors": [
{
"LaunchTemplateAndOverrides": {
"LaunchTemplateSpecification": {
"LaunchTemplateId": "lt-01234a567b8910abcEXAMPLE",
"Version": "1"
},
"Overrides": {
"InstanceType": "c4.xlarge",
"AvailabilityZone": "us-east-1a",
}
},
"Lifecycle": "on-demand",
"ErrorCode": "InsufficientInstanceCapacity",
438
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
"ErrorMessage": "",
"InstanceType": "c4.xlarge",
"Platform": null
},
],
"Instances": [
{
"LaunchTemplateAndOverrides": {
"LaunchTemplateSpecification": {
"LaunchTemplateId": "lt-01234a567b8910abcEXAMPLE",
"Version": "1"
},
"Overrides": {
"InstanceType": "c5.large",
"AvailabilityZone": "us-east-1a"
}
},
"Lifecycle": "on-demand",
"InstanceIds": [
"i-1234567890abcdef0",
"i-9876543210abcdef9"
],
"InstanceType": "c5.large",
"Platform": null
},
]
}
The following is example output for a fleet of type instant that launched no instances.
{
"FleetId": "fleet-12a34b55-67cd-8ef9-ba9b-9208dEXAMPLE",
"Errors": [
{
"LaunchTemplateAndOverrides": {
"LaunchTemplateSpecification": {
"LaunchTemplateId": "lt-01234a567b8910abcEXAMPLE",
"Version": "1"
},
"Overrides": {
"InstanceType": "c4.xlarge",
"AvailabilityZone": "us-east-1a",
}
},
"Lifecycle": "on-demand",
"ErrorCode": "InsufficientCapacity",
"ErrorMessage": "",
"InstanceType": "c4.xlarge",
"Platform": null
},
{
"LaunchTemplateAndOverrides": {
"LaunchTemplateSpecification": {
"LaunchTemplateId": "lt-01234a567b8910abcEXAMPLE",
"Version": "1"
},
"Overrides": {
"InstanceType": "c5.large",
"AvailabilityZone": "us-east-1a",
}
},
"Lifecycle": "on-demand",
"ErrorCode": "InsufficientCapacity",
"ErrorMessage": "",
"InstanceType": "c5.large",
439
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
"Platform": null
},
],
"Instances": []
}
To help categorize and manage your EC2 Fleet requests, you can tag them with custom metadata. For
more information, see Tagging Your Amazon EC2 Resources (p. 995).
You can assign a tag to an EC2 Fleet request when you create it, or afterward. Tags assigned to the fleet
request are not assigned to the instances launched by the fleet.
To tag an EC2 Fleet request when you create it, specify the key-value pair in the JSON file (p. 433) used
to create the fleet. The value for ResourceType must be fleet. If you specify another value, the fleet
request fails.
To tag instances when they are launched by the fleet, specify the tags in the launch template (p. 405)
that is referenced in the EC2 Fleet request.
The EC2 Fleet launches On-Demand Instances when there is available capacity, and launches Spot
Instances when your maximum price exceeds the Spot price and capacity is available. The On-Demand
Instances run until you terminate them, and the Spot Instances run until they are interrupted or you
terminate them.
The returned list of running instances is refreshed periodically and might be out of date.
{
"Fleets": [
{
"Type": "maintain",
"FulfilledCapacity": 2.0,
"LaunchTemplateConfigs": [
{
"LaunchTemplateSpecification": {
"Version": "2",
"LaunchTemplateId": "lt-07b3bc7625cdab851"
}
440
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
}
],
"TerminateInstancesWithExpiration": false,
"TargetCapacitySpecification": {
"OnDemandTargetCapacity": 0,
"SpotTargetCapacity": 2,
"TotalTargetCapacity": 2,
"DefaultTargetCapacityType": "spot"
},
"FulfilledOnDemandCapacity": 0.0,
"ActivityStatus": "fulfilled",
"FleetId": "fleet-76e13e99-01ef-4bd6-ba9b-9208de883e7f",
"ReplaceUnhealthyInstances": false,
"SpotOptions": {
"InstanceInterruptionBehavior": "terminate",
"InstancePoolsToUseCount": 1,
"AllocationStrategy": "lowestPrice"
},
"FleetState": "active",
"ExcessCapacityTerminationPolicy": "termination",
"CreateTime": "2018-04-10T16:46:03.000Z"
}
]
}
Use the following describe-fleet-instances command to describe the instances for the specified EC2
Fleet.
{
"ActiveInstances": [
{
"InstanceId": "i-09cd595998cb3765e",
"InstanceHealth": "healthy",
"InstanceType": "m4.large",
"SpotInstanceRequestId": "sir-86k84j6p"
},
{
"InstanceId": "i-09cf95167ca219f17",
"InstanceHealth": "healthy",
"InstanceType": "m4.large",
"SpotInstanceRequestId": "sir-dvxi7fsm"
}
],
"FleetId": "fleet-73fbd2ce-aa30-494c-8788-1cee4EXAMPLE"
}
Use the following describe-fleet-history command to describe the history for the specified EC2 Fleet for
the specified time.
{
"HistoryRecords": [],
"FleetId": "fleet-73fbd2ce-aa30-494c-8788-1cee4EXAMPLE",
"LastEvaluatedTime": "1970-01-01T00:00:00.000Z",
"StartTime": "2018-04-09T23:53:20.000Z"
}
441
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
Note
You can only modify an EC2 Fleet that has Type=maintain.
When you increase the target capacity, the EC2 Fleet launches the additional instances according to the
instance purchasing option specified for DefaultTargetCapacityType, which are either On-Demand
Instances or Spot Instances.
If the DefaultTargetCapacityType is spot, the EC2 Fleet launches the additional Spot Instances
according to its allocation strategy. If the allocation strategy is lowestPrice, the fleet launches
the instances from the lowest-priced Spot Instance pool in the request. If the allocation strategy is
diversified, the fleet distributes the instances across the pools in the request.
When you decrease the target capacity, the EC2 Fleet deletes any open requests that exceed the new
target capacity. You can request that the fleet terminate instances until the size of the fleet reaches
the new target capacity. If the allocation strategy is lowestPrice, the fleet terminates the instances
with the highest price per unit. If the allocation strategy is diversified, the fleet terminates instances
across the pools. Alternatively, you can request that EC2 Fleet keep the fleet at its current size, but not
replace any Spot Instances that are interrupted or any instances that you terminate manually.
When an EC2 Fleet terminates a Spot Instance because the target capacity was decreased, the instance
receives a Spot Instance interruption notice.
Use the following modify-fleet command to update the target capacity of the specified EC2 Fleet.
If you are decreasing the target capacity but want to keep the fleet at its current size, you can modify the
previous command as follows.
You must specify whether the EC2 Fleet must terminate its instances. If you specify that the instances
must be terminated when the fleet is deleted, it enters the deleted_terminating state. Otherwise, it
enters the deleted_running state, and the instances continue to run until they are interrupted or you
terminate them manually.
442
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
Use the delete-fleets command and the --terminate-instances parameter to delete the specified
EC2 Fleet and terminate the instances.
{
"UnsuccessfulFleetDeletions": [],
"SuccessfulFleetDeletions": [
{
"CurrentFleetState": "deleted_terminating",
"PreviousFleetState": "active",
"FleetId": "fleet-73fbd2ce-aa30-494c-8788-1cee4EXAMPLE"
}
]
}
You can modify the previous command using the --no-terminate-instances parameter to delete
the specified EC2 Fleet without terminating the instances.
{
"UnsuccessfulFleetDeletions": [],
"SuccessfulFleetDeletions": [
{
"CurrentFleetState": "deleted_running",
"PreviousFleetState": "active",
"FleetId": "fleet-4b8aaae8-dfb5-436d-a4c6-3dafa4c6b7dcEXAMPLE"
}
]
}
The following examples show launch configurations that you can use with the create-fleet
command to create an EC2 Fleet. For more information, see the EC2 Fleet JSON Configuration File
Reference (p. 434).
The following example specifies the minimum parameters required in an EC2 Fleet: a launch template,
target capacity, and default purchasing option. The launch template is identified by its launch template
ID and version number. The target capacity for the fleet is 2 instances, and the default purchasing option
is spot, which results in the fleet launching 2 Spot Instances.
443
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
{
"LaunchTemplateConfigs": [
{
"LaunchTemplateSpecification": {
"LaunchTemplateId": "lt-0e8c754449b27161c",
"Version": "1"
}
}
],
"TargetCapacitySpecification": {
"TotalTargetCapacity": 2,
"DefaultTargetCapacityType": "spot"
}
}
The following example specifies the minimum parameters required in an EC2 Fleet: a launch template,
target capacity, and default purchasing option. The launch template is identified by its launch template
ID and version number. The target capacity for the fleet is 2 instances, and the default purchasing option
is on-demand, which results in the fleet launching 2 On-Demand Instances.
{
"LaunchTemplateConfigs": [
{
"LaunchTemplateSpecification": {
"LaunchTemplateId": "lt-0e8c754449b27161c",
"Version": "1"
}
}
],
"TargetCapacitySpecification": {
"TotalTargetCapacity": 2,
"DefaultTargetCapacityType": "on-demand"
}
}
The following example specifies the total target capacity of 2 instances for the fleet, and a target
capacity of 1 On-Demand Instance. The default purchasing option is spot. The fleet launches 1
On-Demand Instance as specified, but needs to launch one more instance to fulfill the total target
capacity. The purchasing option for the difference is calculated as TotalTargetCapacity –
OnDemandTargetCapacity = DefaultTargetCapacityType, which results in the fleet launching 1
Spot Instance.
{
"LaunchTemplateConfigs": [
{
"LaunchTemplateSpecification": {
"LaunchTemplateId": "lt-0e8c754449b27161c",
"Version": "1"
}
}
],
"TargetCapacitySpecification": {
"TotalTargetCapacity": 2,
"OnDemandTargetCapacity":1,
444
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch
"DefaultTargetCapacityType": "spot"
}
}
Example 4: Launch Spot Instances Using the Lowest Price Allocation Strategy
If the allocation strategy for Spot Instances is not specified, the default allocation strategy, which is
lowestPrice, is used. The following example uses the lowestPrice allocation strategy. The three
launch specifications, which override the launch template, have different instance types but the same
weighted capacity and subnet. The total target capacity is 2 instances and the default purchasing option
is spot. The EC2 Fleet launches 2 Spot Instances using the instance type of the launch specification with
the lowest price.
{
"LaunchTemplateConfigs": [
{
"LaunchTemplateSpecification": {
"LaunchTemplateId": "lt-0e8c754449b27161c",
"Version": "1"
}
"Overrides": [
{
"InstanceType": "c4.large",
"WeightedCapacity": 1,
"SubnetId": "subnet-a4f6c5d3"
},
{
"InstanceType": "c3.large",
"WeightedCapacity": 1,
"SubnetId": "subnet-a4f6c5d3"
},
{
"InstanceType": "c5.large",
"WeightedCapacity": 1,
"SubnetId": "subnet-a4f6c5d3"
}
]
}
],
"TargetCapacitySpecification": {
"TotalTargetCapacity": 2,
"DefaultTargetCapacityType": "spot"
}
}
445
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Connect
To connect to a Windows instance, see Connecting to Your Windows Instance in the Amazon EC2 User
Guide for Windows Instances.
Connection Method
Your local computer's operating system determines the type of method you use to connect to your Linux
instance.
After you connect to your Linux instance, you can try one of our tutorials, such as Tutorial: Install a
LAMP Web Server with the Amazon Linux AMI (p. 42) or Tutorial: Hosting a WordPress Blog with Amazon
Linux (p. 52).
You can get the ID of your instance using the Amazon EC2 console (from the Instance ID column). If
you prefer, you can use the describe-instances (AWS CLI) or Get-EC2Instance (AWS Tools for Windows
PowerShell) command.
• Get the public DNS name of the instance.
You can get the public DNS for your instance using the Amazon EC2 console. Check the Public DNS
(IPv4) column. If this column is hidden, choose the Show/Hide icon and select Public DNS (IPv4). If
446
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Connect
you prefer, you can use the describe-instances (AWS CLI) or Get-EC2Instance (AWS Tools for Windows
PowerShell) command.
• (IPv6 only) Get the IPv6 address of the instance.
If you've assigned an IPv6 address to your instance, you can optionally connect to the instance using
its IPv6 address instead of a public IPv4 address or public IPv4 DNS hostname. Your local computer
must have an IPv6 address and must be configured to use IPv6. You can get the IPv6 address of
your instance using the Amazon EC2 console. Check the IPv6 IPs field. If you prefer, you can use the
describe-instances (AWS CLI) or Get-EC2Instance (AWS Tools for Windows PowerShell) command. For
more information about IPv6, see IPv6 Addresses (p. 708).
• Get the default user name for the AMI that you used to launch your instance:
• For Amazon Linux 2 or the Amazon Linux AMI, the user name is ec2-user.
• For a CentOS AMI, the user name is centos.
• For a Debian AMI, the user name is admin or root.
• For a Fedora AMI, the user name is ec2-user or fedora.
• For a RHEL AMI, the user name is ec2-user or root.
• For a SUSE AMI, the user name is ec2-user or root.
• For an Ubuntu AMI, the user name is ubuntu.
• Otherwise, if ec2-user and root don't work, check with the AMI provider.
Ensure that the security group associated with your instance allows incoming SSH traffic from your IP
address. The default security group for the VPC does not allow incoming SSH traffic by default. The
security group created by the launch wizard enables SSH traffic by default. For more information, see
Authorizing Inbound Traffic for Your Linux Instances (p. 704).
Get the fully-qualified path to the location on your computer of the .pem file for the key pair that you
specified when you launched the instance. For more information about how you created your key pair,
see Creating a Key Pair Using Amazon EC2.
Verify that the .pem file has permissions of 0400, not 0777. For more information, see Error:
Unprotected Private Key File (p. 1025).
1. In a command line shell, change directories to the location of the private key file that you created
when you launched the instance.
2. Use the following command to set the permissions of your private key file so that only you can read
it.
If you do not set these permissions, then you cannot connect to your instance using this key pair. For
more information, see Error: Unprotected Private Key File (p. 1025).
447
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Connect
First you get the instance fingerprint. Then, when you connect to the instance, you are prompted to
verify the fingerprint. You can compare the fingerprint you obtained with the fingerprint displayed for
verification. If these fingerprints don't match, someone might be attempting a "man-in-the-middle"
attack. If they match, you can confidently connect to your instance.
• To get the instance fingerprint, you must use the AWS CLI. For information about installing the AWS
CLI, see Installing the AWS Command Line Interface in the AWS Command Line Interface User Guide.
• The instance must be in the running state, not the pending state.
1. On your local computer (not on the instance), use the get-console-output (AWS CLI) command to
obtain the fingerprint, as follows:
2. In the output that was generated, locate the SSH HOST KEY FINGERPRINTS section and note the
RSA fingerprint (for example, 1f:51:ae:28:bf:89:e9:d8:1f:25:5d:37:2d:7d:b8:ca:9f:f5:f1:6f). The SSH
HOST KEY FINGERPRINTS section is only available after the first boot of the instance.
After you launch your instance, you can connect to it and use it the way that you'd use a computer sitting
in front of you.
Note
After you launch an instance, it can take a few minutes for the instance to be ready so that
you can connect to it. Check that your instance has passed its status checks. You can view this
information in the Status Checks column on the Instances page.
Prerequisites
Before you connect to your Linux instance, complete the following prerequisites:
For more information, see General Prerequisites for Connecting to Your Instance (p. 446).
• Install an SSH client on your local computer.
448
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Connect
Your local computer most likely has an SSH client installed by default. You can check for an SSH client
by typing ssh at the command line. If your local computer doesn't recognize the command, you can
install an SSH client. For information about installing an SSH client on Linux or macOS X, see http://
www.openssh.com. For information about installing an SSH client on Windows 10, see OpenSSH in
Windows.
1. In a terminal window, use the ssh command to connect to the instance. You specify the private key
(.pem) file, the user name for your AMI, and the public DNS name for your instance. For example,
if you used Amazon Linux 2 or the Amazon Linux AMI, the user name is ec2-user. For more
information about finding the user name for an AMI and the DNS name for an instance, see Get
Information About Your Instance (p. 446).
2. (IPv6 only) Alternatively, you can connect to the instance using its IPv6 address. Specify the ssh
command with the path to the private key (.pem) file, the appropriate user name, and the IPv6
address. For example, if you used Amazon Linux 2 or the Amazon Linux AMI, the user name is ec2-
user.
3. (Optional) Verify that the fingerprint in the security alert matches the fingerprint that you previously
obtained in (Optional) Get the Instance Fingerprint (p. 448). If these fingerprints don't match,
someone might be attempting a "man-in-the-middle" attack. If they match, continue to the next
step.
4. Enter yes. You see a response like the following:
Prerequisites
449
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Connect
The general prerequisites for transferring files to an instance are the same as the general prerequisites
for connecting to an instance. For more information, see General Prerequisites for Connecting to Your
Instance (p. 446).
• Install an SCP client
Most Linux, Unix, and Apple computers include an SCP client by default. If yours doesn't, the OpenSSH
project provides a free implementation of the full suite of SSH tools, including an SCP client. For more
information, see http://www.openssh.org.
The following procedure steps you through using SCP to transfer a file. If you've already connected to
the instance with SSH and have verified its fingerprints, you can start with the step that contains the SCP
command (step 4).
1. Transfer a file to your instance using the instance's public DNS name. For
example, if the name of the private key file is my-key-pair, the file to transfer is
SampleFile.txt, the user name is ec2-user, and the public DNS name of the instance is
ec2-198-51-100-1.compute-1.amazonaws.com, use the following command to copy the file to
the ec2-user home directory.
2. (IPv6 only) Alternatively, you can transfer a file using the IPv6 address for the instance. The IPv6
address must be enclosed in square brackets ([]), which must be escaped (\).
3. (Optional) Verify that the fingerprint in the security alert matches the fingerprint that you previously
obtained in (Optional) Get the Instance Fingerprint (p. 448). If these fingerprints don't match,
someone might be attempting a "man-in-the-middle" attack. If they match, continue to the next
step.
4. Enter yes.
If you receive a "bash: scp: command not found" error, you must first install scp on your Linux
instance. For some operating systems, this is located in the openssh-clients package. For
Amazon Linux variants, such as the Amazon ECS-optimized AMI, use the following command to
install scp:
450
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Connect
5. To transfer files in the other direction (from your Amazon EC2 instance to your local computer),
reverse the order of the host parameters. For example, to transfer the SampleFile.txt file from
your EC2 instance back to the home directory on your local computer as SampleFile2.txt, use
the following command on your local computer:
6. (IPv6 only) Alternatively, you can transfer files in the other direction using the instance's IPv6
address:
You can use the Instance Connect feature to connect to your Linux instances from the Amazon EC2
console, the Amazon EC2 Instance Connect CLI, or the Amazon EC2 API.
Note
If you are connecting to a Linux instance from a local computer running Windows, see the
following documentation instead: Connecting to Your Linux Instance from Windows Using
PuTTY (p. 459) and Connecting to Your Linux Instance from Windows Using Windows
Subsystem for Linux (p. 464).
Contents
• How EC2 Instance Connect Works (p. 451)
• Set Up EC2 Instance Connect (p. 452)
• Connect Using EC2 Instance Connect (p. 456)
• Uninstall EC2 Instance Connect (p. 458)
You can use Instance Connect to connect to your instances using any SSH client of your choice or the
Instance Connect CLI, or you can connect to your instances by using the new browser-based SSH client in
the Amazon EC2 console.
451
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Connect
Limitations
Prerequisites
• Verify the general prerequisites for connecting to your instance using SSH.
For more information, see General Prerequisites for Connecting to Your Instance (p. 446).
• Install an SSH client on your local computer.
Your local computer most likely has an SSH client installed by default. You can check for an SSH client
by typing ssh at the command line. If your local computer doesn't recognize the command, you can
install an SSH client. For information about installing an SSH client on Linux or macOS X, see http://
www.openssh.com. For information about installing an SSH client on Windows 10, see OpenSSH in
Windows.
• Install the AWS CLI on your local computer.
To configure the IAM permissions and to install the EC2 Instance Connect CLI, you must use the
AWS CLI. For more information about installing the AWS CLI, see Installing the AWS CLI in the AWS
Command Line Interface User Guide.
• [Ubuntu] Install the AWS CLI on your instance.
To install EC2 Instance Connect on an Ubuntu instance, you must use the AWS CLI on the instance. For
more information about installing the AWS CLI, see Installing the AWS CLI in the AWS Command Line
Interface User Guide.
452
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Connect
Use the SSH key pair that was assigned to your instance when you launched it and the default user
name of the AMI that you used to launch your instance. For Amazon Linux 2, the default user name
is ec2-user.
For example, if your instance was launched using Amazon Linux 2, your instance's public
DNS is ec2-a-b-c-d.us-west-2.compute.amazonaws.com, and the key pair is
my_ec2_private_key.pem, use the following command to SSH into your instance:
For more information about connecting to your instance, see Connecting to Your Linux Instance
Using SSH (p. 448).
2. Install the EC2 Instance Connect package on your instance.
eic_curl_authorized_keys
eic_harvest_hostkeys
eic_parse_authorized_keys
eic_run_authorized_keys
3. (Optional) Verify that Instance Connect was successfully installed on your instance.
Use the sudo less command to check that the /etc/ssh/sshd_config file was correctly updated
as follows:
AuthorizedKeysCommand /opt/aws/bin/eic_run_authorized_keys %u %f
AuthorizedKeysCommandUser ec2-instance-connect
Note
If you previously configured AuthorizedKeysCommand and
AuthorizedKeysCommandUser, the Instance Connect installation will not change the
values and you will not be able to use Instance Connect.
To install EC2 Instance Connect on an instance launched with Ubuntu 16.04 or later
453
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Connect
Use the SSH key pair that was assigned to your instance when you launched it and use the default
user name of the AMI that you used to launch your instance. For an Ubuntu AMI, the user name is
ubuntu.
If your instance was launched using Ubuntu, your instance's public DNS is ec2-a-b-c-d.us-
west-2.compute.amazonaws.com, and the key pair is my_ec2_private_key.pem, use the
following command to SSH into your instance:
For more information about connecting to your instance, see Connecting to Your Linux Instance
Using SSH (p. 448).
2. Install the Instance Connect package on your instance.
For Ubuntu, use the sudo apt-get command to install the .deb package.
eic_curl_authorized_keys
eic_harvest_hostkeys
eic_parse_authorized_keys
eic_run_authorized_keys
3. (Optional) Verify that Instance Connect was successfully installed on your instance.
AuthorizedKeysCommand /usr/share/ec2-instance-connect/eic_run_authorized_keys %u %f
AuthorizedKeysCommandUser ec2-instance-connect
Note
If you previously configured AuthorizedKeysCommand and
AuthorizedKeysCommandUser, the Instance Connect installation will not change the
values and you will not be able to use Instance Connect.
The EC2 Instance Connect CLI provides a similar interface to standard SSH calls, which includes querying
EC2 instance information, generating and publishing ephemeral public keys, and establishing an SSH
connection through a single command, mssh instance_id.
454
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Connect
Note
There is no need to install the EC2 Instance Connect CLI if users only use the console or an SSH
client to connect to an instance.
If your IAM users will connect to an instance using EC2 Instance Connect, be sure to grant them the
required permission to push the public key to the instance. The following instructions explain how to
create the policy and attach it to the user using the AWS CLI. For information about how to do this using
the AWS Management Console, see Creating IAM Policies (Console) and Adding Permissions by Attaching
Policies Directly to the User in the IAM User Guide.
Note
We currently do not support tag-based authorization for Instance Connect. Tags and context
keys in the ec2 namespace are not automatically applied to ec2-instance-connect.
To grant an IAM user permission for EC2 Instance Connect (AWS CLI)
1. Create a JSON document that includes the following content for the new policy:
• If your users only use the console or an SSH client to connect to an instance, use the following
content for the policy:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "ec2-instance-connect:SendSSHPublicKey",
"Resource": "arn:aws:ec2:region:account-id:instance/i-instance-id",
"Condition": {
"StringEquals": {
"ec2:osuser": "ami-username"
}
}
}]
}
• If your users use the EC2 Instance Connect CLI to connect to an instance, use the following content
for the policy, which includes the ec2:DescribeInstances action:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "ec2-instance-connect:SendSSHPublicKey",
"Resource": "arn:aws:ec2:region:account-id:instance/i-instance-id",
455
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Connect
"Condition": {
"StringEquals": {
"ec2:osuser": "ami-username"
}
}
},
{
"Effect": "Allow",
"Action": "ec2:DescribeInstances",
"Resource": "*"
}
]
}
For more information, see Actions, Resources, and Condition Keys for Amazon EC2 in the IAM User
Guide.
2. Use the create-policy command to create a new managed policy, and specify the JSON document
that you created to use as the content for the new policy.
3. Use the attach-user-policy command to attach the specified managed policy to the specified IAM
user. For the --user-name parameter, specify the friendly name (not ARN) of the IAM user.
Prerequisites
For more information, see General Prerequisites for Connecting to Your Instance (p. 446).
• Your instance must allow inbound SSH traffic (p. 704) on port 22. We recommend that your
instance allows inbound SSH traffic from the recommended IP block published for the service. Use
the EC2_INSTANCE_CONNECT filter for the service parameter to get the IP address ranges in the
456
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Connect
EC2 Instance Connect subset. For more information, see AWS IP Address Ranges in the Amazon Web
Services General Reference.
• Install EC2 Instance Connect on your instance.
For more information, see Set Up EC2 Instance Connect (p. 452).
• (Optional) Install an SSH client on your local computer.
There is no need to install an SSH client if users only use the console or the EC2 Instance Connect
CLI to connect to an instance. Your local computer most likely has an SSH client installed by default.
You can check for an SSH client by typing ssh at the command line. If your local computer doesn't
recognize the command, you can install an SSH client. For information about installing an SSH client
on Linux or macOS X, see http://www.openssh.com. For information about installing an SSH client on
Windows 10, see OpenSSH in Windows.
• (Optional) Install the EC2 Instance Connect CLI on your local computer.
There is no need to install the EC2 Instance Connect CLI if users only use the console or an SSH
client to connect to an instance. For more information, see Step 2: (Optional) Install the EC2 Instance
Connect CLI (p. 454).
Connect Using EC2 Instance Connect from the Amazon EC2 Console
You can connect to an instance from the Amazon EC2 console by selecting the instance and choosing to
connect using EC2 Instance Connect. Instance Connect handles the permissions and provides a successful
connection.
Note
To connect using the console, the instance must have a public IP address (IPv4 or IPv6).
To connect to your instance using EC2 Instance Connect from the Amazon EC2 console
You can connect to an instance using the EC2 Instance Connect CLI by providing only the instance ID,
while the Instance Connect CLI performs the following three actions in one call: it generates a one-time-
use SSH public key, pushes the key to the instance where it remains for 60 seconds, and connects the
user to the instance. You can use basic SSH/SFTP commands with the Instance Connect CLI.
• Use the mssh command and the instance ID to connect to the instance.
• [Amazon Linux 2] For an instance launched using Amazon Linux 2, the default user name is ec2-
user; you do not need to specify it.
$ mssh i-001234a4bf70dec41EXAMPLE
• [Ubuntu] For an instance launched using an Ubuntu AMI, specify the ubuntu user name;
otherwise, you get an Authentication failed error.
457
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Connect
$ mssh ubuntu@i-001234a4bf70dec41EXAMPLE
You can use your own SSH key and connect to your instance from any SSH client of your choice while
using the EC2 Instance Connect API so that you can benefit from the Instance Connect capability to push
a public key to the instance.
To connect to your instance using your own key and any SSH client
You can generate new SSH private and public keys, my_rsa_key and my_rsa_key.pub, using the
following command:
Note
Only RSA key types in the OpenSSH or SSH2 format are currently supported.
2. Push your SSH public key to the instance.
Use the send-ssh-public-key command to push your SSH public key to the instance. If you launched
your instance using Amazon Linux 2, the default user name for the AMI is ec2-user. If you launched
your instance using Ubuntu, the default user name for the AMI is ubuntu.
Use the ssh command to connect to the instance using the private key before the public key is
removed from the instance metadata (you have 60 seconds before it is removed). Specify the private
key that corresponds to the public key, the default user name for the AMI that you used to launch
your instance, and the instance's public DNS.
You can uninstall EC2 Instance Connect on Amazon Linux 2 2.0.20190618 or later, which comes
preconfigured with EC2 Instance Connect.
458
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Connect
Use the SSH key pair that was assigned to your instance when you launched it and the default user
name of the AMI that you used to launch your instance. For Amazon Linux 2, the default user name
is ec2-user. For Ubuntu, the default user name is ubuntu.
For example, if your instance was launched using Amazon Linux 2, your instance's public
DNS is ec2-a-b-c-d.us-west-2.compute.amazonaws.com, and the key pair is
my_ec2_private_key.pem, use the following command to SSH into your instance:
• [Amazon Linux 2] For Amazon Linux 2, use the yum command to remove EC2 Instance Connect:
• [Ubuntu] For Ubuntu, use the apt-get command to remove EC2 Instance Connect:
After you launch your instance, you can connect to it and use it the way that you'd use a computer sitting
in front of you.
Note
After you launch an instance, it can take a few minutes for the instance to be ready so that
you can connect to it. Check that your instance has passed its status checks. You can view this
information in the Status Checks column on the Instances page.
Prerequisites
Before you connect to your Linux instance using PuTTY, complete the following prerequisites:
For more information, see General Prerequisites for Connecting to Your Instance (p. 446).
• Install PuTTY on your local computer.
Download and install PuTTY from the PuTTY download page. If you already have an older version of
PuTTY installed, we recommend that you download the latest version. Be sure to install the entire
suite.
• Convert your private key using PuTTYgen
PuTTY does not natively support the private key format (.pem) generated by Amazon EC2. PuTTY has a
tool named PuTTYgen, which can convert keys to the required PuTTY format (.ppk). You must convert
your private key into this format (.ppk) before attempting to connect to your instance using PuTTY.
459
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Connect
4. Select your .pem file for the key pair that you specified when you launched your instance and
choose Open. Choose OK.
5. To save the key in the format that PuTTY can use, choose Save private key. PuTTYgen displays a
warning about saving the key without a passphrase. Choose Yes.
Note
A passphrase on a private key is an extra layer of protection. Even if your private key is
discovered, it can't be used without the passphrase. The downside to using a passphrase
is that it makes automation harder because human intervention is needed to log on to an
instance, or to copy files to an instance.
6. Specify the same name for the key that you used for the key pair (for example, my-key-pair).
PuTTY automatically adds the .ppk file extension.
Your private key is now in the correct format for use with PuTTY. You can now connect to your instance
using PuTTY's SSH client.
1. Start PuTTY (from the Start menu, choose All Programs, PuTTY, PuTTY).
2. In the Category pane, choose Session and complete the following fields:
a. In the Host Name box, enter user_name@public_dns_name (see Get Information About Your
Instance (p. 446) for how to get the public DNS name of the instance). Be sure to specify the
appropriate user name for your AMI. For example:
• For Amazon Linux 2 or the Amazon Linux AMI, the user name is ec2-user.
• For a CentOS AMI, the user name is centos.
• For a Debian AMI, the user name is admin or root.
• For a Fedora AMI, the user name is ec2-user or fedora.
• For a RHEL AMI, the user name is ec2-user or root.
• For a SUSE AMI, the user name is ec2-user or root.
• For an Ubuntu AMI, the user name is ubuntu.
• Otherwise, if ec2-user and root don't work, check with the AMI provider.
460
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Connect
b. (IPv6 only) To connect using your instance's IPv6 address, enter user_name@ipv6_address.
Be sure to specify the appropriate user name for your AMI. For example:
• For Amazon Linux 2 or the Amazon Linux AMI, the user name is ec2-user.
• For a CentOS AMI, the user name is centos.
• For a Debian AMI, the user name is admin or root.
• For a Fedora AMI, the user name is ec2-user or fedora.
• For a RHEL AMI, the user name is ec2-user or root.
• For a SUSE AMI, the user name is ec2-user or root.
• For an Ubuntu AMI, the user name is ubuntu.
• Otherwise, if ec2-user and root don't work, check with the AMI provider.
c. Under Connection type, select SSH.
d. Ensure that the Port value is 22.
3. (Optional) You can configure PuTTY to automatically send 'keepalive' data at regular intervals to
keep the session active. This is useful to avoid disconnecting from your instance due to session
inactivity. In the Category pane, choose Connection, and then enter the required interval in the
Seconds between keepalives field. For example, if your session disconnects after 10 minutes of
inactivity, enter 180 to configure PuTTY to send keepalive data every 3 minutes.
4. In the Category pane, expand Connection, expand SSH, and then choose Auth. Complete the
following:
a. Choose Browse.
b. Select the .ppk file that you generated for your key pair and choose Open.
c. (Optional) If you plan to start this session again later, you can save the session information for
future use. Under Category, choose Session, enter a name for the session in Saved Sessions,
and then choose Save.
d. Choose Open.
461
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Connect
5. If this is the first time you have connected to this instance, PuTTY displays a security alert dialog box
that asks whether you trust the host to which you are connecting.
6. (Optional) Verify that the fingerprint in the security alert dialog box matches the fingerprint that
you previously obtained in (Optional) Get the Instance Fingerprint (p. 448). If these fingerprints
don't match, someone might be attempting a "man-in-the-middle" attack. If they match, continue to
the next step.
7. Choose Yes. A window opens and you are connected to your instance.
Note
If you specified a passphrase when you converted your private key to PuTTY's format, you
must provide that passphrase when you log in to the instance.
If you receive an error while attempting to connect to your instance, see Troubleshooting Connecting to
Your Instance.
Transferring Files to Your Linux Instance Using the PuTTY Secure Copy Client
The PuTTY Secure Copy client (PSCP) is a command line tool that you can use to transfer files between
your Windows computer and your Linux instance. If you prefer a graphical user interface (GUI), you can
use an open source GUI tool named WinSCP. For more information, see Transferring Files to Your Linux
Instance Using WinSCP (p. 463).
To use PSCP, you need the private key you generated in Convert Your Private Key Using
PuTTYgen (p. 459). You also need the public DNS address of your Linux instance.
The following example transfers the file Sample_file.txt from the C:\ drive on a Windows computer
to the ec2-user home directory on an Amazon Linux instance:
(IPv6 only) The following example transfers the file Sample_file.txt using the instance's IPv6
address. The IPv6 address must be enclosed in square brackets ([]).
462
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Connect
To use WinSCP, you need the private key that you generated in Convert Your Private Key Using
PuTTYgen (p. 459). You also need the public DNS address of your Linux instance.
1. Download and install WinSCP from http://winscp.net/eng/download.php. For most users, the
default installation options are OK.
2. Start WinSCP.
3. At the WinSCP login screen, for Host name, enter the public DNS hostname or public IPv4 address
for your instance.
(IPv6 only) To log in using your instance's IPv6 address, enter the IPv6 address for your instance.
4. For User name, enter the default user name for your AMI.
• For Amazon Linux 2 or the Amazon Linux AMI, the user name is ec2-user.
• For a CentOS AMI, the user name is centos.
• For a Debian AMI, the user name is admin or root.
• For a Fedora AMI, the user name is ec2-user or fedora.
• For a RHEL AMI, the user name is ec2-user or root.
• For a SUSE AMI, the user name is ec2-user or root.
• For an Ubuntu AMI, the user name is ubuntu.
• Otherwise, if ec2-user and root don't work, check with the AMI provider.
5. Specify the private key for your instance. For Private key, enter the path to your private key,
or choose the "..." button to browse for the file. To open the advanced site settings, for newer
versions of WinSCP, choose Advanced. To find the Private key file setting, under SSH, choose
Authentication.
463
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Connect
WinSCP requires a PuTTY private key file (.ppk). You can convert a .pem security key file to
the .ppk format using PuTTYgen. For more information, see Convert Your Private Key Using
PuTTYgen (p. 459).
6. (Optional) In the left panel, choose Directories. For Remote directory, enter the path for the
directory to which to add files. To open the advanced site settings for newer versions of WinSCP,
choose Advanced. To find the Remote directory setting, under Environment, choose Directories.
7. Choose Login. To add the host fingerprint to the host cache, choose Yes.
8. After the connection is established, in the connection window your Linux instance is on the right and
your local machine is on the left. You can drag and drop files directly into the remote file system
from your local machine. For more information on WinSCP, see the project documentation at http://
winscp.net/eng/docs/start.
If you receive a "Cannot execute SCP to start transfer" error, you must first install scp on your
Linux instance. For some operating systems, this is located in the openssh-clients package. For
Amazon Linux variants, such as the Amazon ECS-optimized AMI, use the following command to
install scp.
By installing WSL, you can use a native Linux environment to connect to your Linux EC2 instances instead
of using PuTTY or PuTTYgen. The Linux environment makes it easier to connect to your Linux instances
because it comes with a native SSH client that you can use to connect to your Linux instances and change
464
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Connect
the permissions of the .pem key file. The Amazon EC2 console provides the SSH command for connecting
to the Linux instance, and you can get verbose output from the SSH command for troubleshooting. For
more information, see the Windows Subsystem for Linux Documentation.
After you launch your instance, you can connect to it and use it the way that you'd use a computer sitting
in front of you.
Note
After you launch an instance, it can take a few minutes for the instance to be ready so that
you can connect to it. Check that your instance has passed its status checks. You can view this
information in the Status Checks column on the Instances page.
If you receive an error while attempting to connect to your instance, see Troubleshooting Connecting to
Your Instance.
Contents
• Prerequisites (p. 448)
• Connect to Your Linux Instance using WSL (p. 465)
• Transferring Files to Linux Instances from Linux Using SCP (p. 466)
• Uninstalling WSL (p. 468)
Note
After you've installed the WSL, all the prerequisites and steps are the same as those described
in Connecting to Your Linux Instance Using SSH (p. 448), and the experience is just like using
native Linux.
Prerequisites
Before you connect to your Linux instance, complete the following prerequisites:
For more information, see General Prerequisites for Connecting to Your Instance (p. 446).
• Install the Windows Subsystem for Linux (WSL) and a Linux distribution on your local computer.
Install the WSL and a Linux distribution using the instructions in the Windows 10 Installation Guide.
The example in the instructions installs the Ubuntu distribution of Linux, but you can install any
distribution. You are prompted to restart your computer for the changes to take effect.
• Copy the private key from Windows to WSL.
In a WSL terminal window, copy the .pem file (for the key pair that you specified when you launched
the instance) from Windows to WSL. Note the fully qualified path to the .pem file on WSL to use when
connecting to your instance. For information about how to specify the path to your Windows hard
drive, see How do I access my C drive?.
465
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Connect
1. In a terminal window, use the ssh command to connect to the instance. You specify the private key
(.pem) file, the user name for your AMI, and the public DNS name for your instance. For example,
if you used Amazon Linux 2 or the Amazon Linux AMI, the user name is ec2-user. For more
information about finding the user name for an AMI and the DNS name for an instance, see Get
Information About Your Instance (p. 446).
2. (IPv6 only) Alternatively, you can connect to the instance using its IPv6 address. Specify the ssh
command with the path to the private key (.pem) file, the appropriate user name, and the IPv6
address. For example, if you used Amazon Linux 2 or the Amazon Linux AMI, the user name is ec2-
user.
3. (Optional) Verify that the fingerprint in the security alert matches the fingerprint that you previously
obtained in (Optional) Get the Instance Fingerprint (p. 448). If these fingerprints don't match,
someone might be attempting a "man-in-the-middle" attack. If they match, continue to the next
step.
4. Enter yes.
Prerequisites
The general prerequisites for transferring files to an instance are the same as the general prerequisites
for connecting to an instance. For more information, see General Prerequisites for Connecting to Your
Instance (p. 446).
• Install an SCP client
Most Linux, Unix, and Apple computers include an SCP client by default. If yours doesn't, the OpenSSH
project provides a free implementation of the full suite of SSH tools, including an SCP client. For more
information, see http://www.openssh.org.
466
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Connect
The following procedure steps you through using SCP to transfer a file. If you've already connected to
the instance with SSH and have verified its fingerprints, you can start with the step that contains the SCP
command (step 4).
1. Transfer a file to your instance using the instance's public DNS name. For
example, if the name of the private key file is my-key-pair, the file to transfer is
SampleFile.txt, the user name is ec2-user, and the public DNS name of the instance is
ec2-198-51-100-1.compute-1.amazonaws.com, use the following command to copy the file to
the ec2-user home directory:
2. (IPv6 only) Alternatively, you can transfer a file using the IPv6 address for the instance. The IPv6
address must be enclosed in square brackets ([]), which must be escaped (\).
3. (Optional) Verify that the fingerprint in the security alert matches the fingerprint that you previously
obtained in (Optional) Get the Instance Fingerprint (p. 448). If these fingerprints don't match,
someone might be attempting a "man-in-the-middle" attack. If they match, continue to the next
step.
4. Enter yes.
If you receive a "bash: scp: command not found" error, you must first install scp on your Linux
instance. For some operating systems, this is located in the openssh-clients package. For
Amazon Linux variants, such as the Amazon ECS-optimized AMI, use the following command to
install scp:
5. To transfer files in the other direction (from your Amazon EC2 instance to your local computer),
reverse the order of the host parameters. For example, to transfer the SampleFile.txt file from
your EC2 instance back to the home directory on your local computer as SampleFile2.txt, use
the following command on your local computer:
467
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Stop and Start
6. (IPv6 only) Alternatively, you can transfer files in the other direction using the instance's IPv6
address:
Uninstalling WSL
For information about uninstalling Windows Subsystem for Linux, see How do I uninstall a WSL
Distribution?.
When you stop an instance, we shut it down. We don't charge usage for a stopped instance, or data
transfer fees, but we do charge for the storage for any Amazon EBS volumes. Each time you start a
stopped instance we charge a minimum of one minute for usage. After one minute, we charge only for
the seconds you use. For example, if you run an instance for 20 seconds and then stop it, we charge for
a full one minute. If you run an instance for 3 minutes and 40 seconds, we charge for exactly 3 minutes
and 40 seconds of usage.
While the instance is stopped, you can treat its root volume like any other volume, and modify it (for
example, repair file system problems or update software). You just detach the volume from the stopped
instance, attach it to a running instance, make your changes, detach it from the running instance, and
then reattach it to the stopped instance. Make sure that you reattach it using the storage device name
that's specified as the root device in the block device mapping for the instance.
If you decide that you no longer need an instance, you can terminate it. As soon as the state of an
instance changes to shutting-down or terminated, we stop charging for that instance. For more
information, see Terminate Your Instance (p. 479). If you'd rather hibernate the instance, see Hibernate
Your Instance (p. 470). For more information, see Differences Between Reboot, Stop, Hibernate, and
Terminate (p. 393).
Contents
• Overview (p. 468)
• Stopping and Starting Your Instances (p. 469)
• Modifying a Stopped Instance (p. 470)
• Troubleshooting (p. 470)
Overview
You can only stop an Amazon EBS-backed instance. To verify the root device type of your instance,
describe the instance and check whether the device type of its root volume is ebs (Amazon EBS-backed
468
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Stop and Start
instance) or instance store (instance store-backed instance). For more information, see Determining
the Root Device Type of Your AMI (p. 98).
• The instance performs a normal shutdown and stops running; its status changes to stopping and
then stopped.
• Any Amazon EBS volumes remain attached to the instance, and their data persists.
• Any data stored in the RAM of the host computer or the instance store volumes of the host computer
is gone.
• In most cases, the instance is migrated to a new underlying host computer when it's started.
• The instance retains its private IPv4 addresses and any IPv6 addresses when stopped and restarted. We
release the public IPv4 address and assign a new one when you restart it.
• The instance retains its associated Elastic IP addresses. You're charged for any Elastic IP addresses
associated with a stopped instance. With EC2-Classic, an Elastic IP address is dissociated from your
instance when you stop it. For more information, see EC2-Classic (p. 796).
• When you stop and start a Windows instance, the EC2Config service performs tasks on the instance,
such as changing the drive letters for any attached Amazon EBS volumes. For more information
about these defaults and how you can change them, see Configuring a Windows Instance Using the
EC2Config Service in the Amazon EC2 User Guide for Windows Instances.
• If your instance is in an Auto Scaling group, the Amazon EC2 Auto Scaling service marks the stopped
instance as unhealthy, and may terminate it and launch a replacement instance. For more information,
see Health Checks for Auto Scaling Instances in the Amazon EC2 Auto Scaling User Guide.
• When you stop a ClassicLink instance, it's unlinked from the VPC to which it was linked. You must
link the instance to the VPC again after restarting it. For more information about ClassicLink, see
ClassicLink (p. 804).
For more information, see Differences Between Reboot, Stop, Hibernate, and Terminate (p. 393).
You can modify the following attributes of an instance only when it is stopped:
• Instance type
• User data
• Kernel
• RAM disk
If you try to modify these attributes while the instance is running, Amazon EC2 returns the
IncorrectInstanceState error.
By default, when you initiate a shutdown from an Amazon EBS-backed instance (using the shutdown or
poweroff command), the instance stops. You can change this behavior so that it terminates instead. For
more information, see Changing the Instance Initiated Shutdown Behavior (p. 482).
469
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Hibernate
Warning
When you stop an instance, the data on any instance store volumes is erased. To keep data
from instance store volumes, be sure to back it up to persistent storage.
3. In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.
4. While your instance is stopped, you can modify certain instance attributes. For more information,
see Modifying a Stopped Instance (p. 470).
5. To restart the stopped instance, select the instance, and choose Actions, Instance State, Start.
6. In the confirmation dialog box, choose Yes, Start. It can take a few minutes for the instance to enter
the running state.
To stop and start an Amazon EBS-backed instance using the command line
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
• To change the instance type, see Changing the Instance Type (p. 250).
• To change the user data for your instance, see Working with Instance User Data (p. 529).
• To enable or disable EBS–optimization for your instance, see Modifying EBS–Optimization (p. 925).
• To change the DeleteOnTermination attribute of the root volume for your instance, see Updating
the Block Device Mapping of a Running Instance (p. 983).
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
Troubleshooting
If you have stopped your Amazon EBS-backed instance and it appears "stuck" in the stopping state, you
can forcibly stop it. For more information, see Troubleshooting Stopping Your Instance (p. 1027).
470
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Hibernate
are reloaded, and the processes that were previously running on the instance are resumed. Previously
attached data volumes are reattached and the instance retains its instance ID.
You can hibernate an instance only if it's enabled for hibernation (p. 474) and it meets the hibernation
prerequisites (p. 472). Hibernation is currently supported only for Amazon Linux.
If an instance or application takes a long time to bootstrap and build a memory footprint to become
fully productive, you can use hibernation to "pre-warm" the instance. To "pre-warm" the instance, launch
it, bring it to a desired state, and then hibernate it, ready to be resumed to the same state as needed.
We don't charge usage for a hibernated instance when it is in the stopped state. We do charge for
instance usage while the instance is in the stopping state (unlike when you stop an instance (p. 468)
without hibernating it) when the contents of the RAM are transferred to the Amazon EBS root volume.
We don't charge usage for data transfer fees, but we do charge for the storage for any Amazon EBS
volumes, including storage for the RAM contents.
If you no longer need an instance, you can terminate it at any time, including when it is in a stopped
(hibernated) state. For more information, see Terminate Your Instance (p. 479).
Important
Hibernation is currently not supported on Windows instances.
Contents
• Overview of Hibernation (p. 471)
• Hibernation Prerequisites (p. 472)
• Limitations (p. 473)
• Configuring an Existing AMI to Support Hibernation (p. 473)
• Enabling Hibernation for an Instance (p. 474)
• Hibernating an Instance (p. 475)
• Restarting a Hibernated Instance (p. 475)
• Troubleshooting Hibernation (p. 476)
Overview of Hibernation
The following diagram shows a basic overview of the hibernation process.
• When you initiate hibernation, the instance moves to the stopping state. We signal the operating
system to perform hibernation (suspend-to-disk), which freezes all the processes, saves the contents of
the RAM to the Amazon EBS root volume, and then performs a regular shutdown.
• After the shutdown is complete, the instance moves to the stopped state.
• Any Amazon EBS volumes remain attached to the instance, and their data persists, including the saved
contents of the RAM.
471
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Hibernate
• In most cases, the instance is migrated to a new underlying host computer when it's restarted, which is
the same as what happens when you stop and restart an instance.
• When you restart the instance, the instance boots up and the operating system reads in the contents
of the RAM from the Amazon EBS root volume before unfreezing processes to resume its state.
• The instance retains its private IPv4 addresses and any IPv6 addresses when hibernated and restarted.
We release the public IPv4 address and assign a new one when you restart it.
• The instance retains its associated Elastic IP addresses. You're charged for any Elastic IP addresses
associated with a hibernated instance. With EC2-Classic, an Elastic IP address is dissociated from your
instance when you hibernate it. For more information, see EC2-Classic (p. 796).
• When you hibernate a ClassicLink instance, it's unlinked from the VPC to which it was linked. You must
link the instance to the VPC again after restarting it. For more information, see ClassicLink (p. 804).
For information about how hibernation differs from reboot, stop, and terminate, see Differences
Between Reboot, Stop, Hibernate, and Terminate (p. 393).
Hibernation Prerequisites
To hibernate an instance, the following prerequisites must be in place:
• Instance families: The following instance families are supported: C3, C4, C5, M3, M4, M5, R3, R4, and
R5, with less than 150 GB of RAM. Hibernation is not supported for *.metal instances.
• Instance RAM size: The instance RAM size must be less than 150 GB.
• Supported AMIs: The following AMIs support hibernation: Amazon Linux AMI 2018.03 released
2018.11.16 or later.
Support for Amazon Linux 2 and Ubuntu is coming soon. Only HVM AMIs support hibernation.
To configure your own AMI to support hibernation, see Configuring an Existing AMI to Support
Hibernation (p. 473).
• Root volume type: The instance root volume must be an Amazon EBS volume, not an instance store
volume.
• Amazon EBS root volume size: The root volume must be large enough to store the RAM contents and
accommodate your expected usage, for example, OS or applications. If you enable hibernation, space is
allocated on the root volume at launch to store the RAM.
• Amazon EBS root volume encryption: To use hibernation, the root volume must be encrypted to
ensure the protection of sensitive content that is in memory at the time of hibernation. When RAM
data is moved to the Amazon EBS root volume, it is always encrypted. Encryption of the root volume is
enforced at instance launch. Use one of the following three options to ensure that the root volume is
an encrypted Amazon EBS volume:
• EBS “single-step” encryption: In a single run-instances API call, you can launch encrypted EBS-
backed EC2 instances from an unencrypted AMI and also enable hibernation at the same time. For
more information, see Using Encryption with EBS-Backed AMIs (p. 149).
• EBS encryption by default: You can enable EBS encryption by default to ensure all new EBS volumes
created in your AWS account are encrypted. This way, you can enable hibernation for your instances
without specifying encryption intent at instance launch. For more information, see Encryption by
Default (p. 904).
• Encrypted AMI: You can enable EBS encryption by using an encrypted AMI to launch your instance.
If your AMI does not have an encrypted root snapshot, you can copy it to a new AMI and request
encryption. For more information, see Encrypt an Unencrypted Image during Copy (p. 153) and
Copying an AMI (p. 157).
• Enable hibernation at launch: At launch, enable hibernation using the Amazon EC2 console or the
AWS CLI. You cannot enable hibernation on an existing instance (running or stopped). For more
information, see Enabling Hibernation for an Instance (p. 474).
472
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Hibernate
• Purchasing options: This feature is only available for On-Demand Instances and Reserved Instances.
For more information, see Hibernating Interrupted Spot Instances (p. 353).
Limitations
The following actions are not supported for hibernation:
You can't hibernate an instance that has more than 150 GB of RAM.
You cannot hibernate an instance that is in an Auto Scaling group or used by Amazon ECS. If your
instance is in an Auto Scaling group and you try to hibernate it, the Amazon EC2 Auto Scaling service
marks the stopped instance as unhealthy, and may terminate it and launch a replacement instance. For
more information, see Health Checks for Auto Scaling Instances in the Amazon EC2 Auto Scaling User
Guide.
We do not support keeping an instance hibernated for more than 60 days. To keep the instance for
longer than 60 days, you must restart the hibernated instance, stop the instance, and restart it.
We constantly update our platform with upgrades and security patches, which can conflict with existing
hibernated instances. We notify you about critical updates that require a restart for hibernated instances
so that we can perform a shutdown or a reboot to apply the necessary upgrades and security patches.
*For C3 and R3 instances that are enabled for hibernation, do not use instance store volumes.
If you use one of the supported AMIs (p. 472), or you create an AMI based on one of the supported
AMIs (p. 472), you do not need to configure it to support hibernation. The supported AMIs come
preconfigured to support hibernation.
1. Update to the latest kernel to 4.14.77-70.59 or later using the following command:
2. Install the ec2-hibinit-agent package from the repositories using the following command:
uname -a
5. Stop the instance and create an AMI. For more information, see Creating a Linux AMI from an
Instance (p. 117).
473
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Hibernate
1. Follow the Launching an Instance Using the Launch Instance Wizard (p. 395) procedure.
2. On the Choose an Amazon Machine Image (AMI) page, select an AMI that supports hibernation. For
more information about supported AMIs, see Hibernation Prerequisites (p. 472).
3. On the Choose an Instance Type page, select a supported instance type, and choose Next:
Configure Instance Details. For information about supported instance types, see Hibernation
Prerequisites (p. 472).
4. On the Configure Instance Details page, for Stop - Hibernate Behavior, select the Enable
hibernation as an additional stop behavior check box.
5. Continue as prompted by the wizard. When you've finished reviewing your options on the Review
Instance Launch page, choose Launch. For more information, see Launching an Instance Using the
Launch Instance Wizard (p. 395).
• Use the run-instances command to launch an instance. Enable hibernation using the --
hibernation-options Configured=true parameter.
The following field in the output indicates that the instance is enabled for hibernation:
"HibernationOptions": {
"Configured": true
}
474
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Hibernate
Hibernating an Instance
You can hibernate an instance using the console or the command line if the instance is enabled for
hibernation (p. 474) and meets the hibernation prerequisites (p. 472). If an instance cannot hibernate
successfully, a normal shutdown occurs.
The following field in the output indicates that hibernation was initiated on the instance.
"StateReason": {
"Code": Client.UserInitiatedHibernate
}
475
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Reboot
Troubleshooting Hibernation
Use this information to help you diagnose and fix issues that you might encounter when hibernating an
instance.
You must wait for about two minutes after launch before hibernating.
Takes too long to transition from stopping to stopped, and memory state not
restored after start
If it takes a long time for your hibernating instance to transition from the stopping state to stopped,
and the memory state is not restored after you start, this could indicate that hibernation was not
properly configured.
Check the instance system log and look for messages that are related to hibernation. To access the
system log, connect (p. 446) to the instance or use the get-console-output command. Find log lines
from the hibinit-agent. If the log lines indicate a failure or the log lines are missing, there was most
likely a failure configuring hibernation at launch.
For example, the following message indicates that the instance root volume is not large enough:
hibinit-agent: Insufficient disk space. Cannot create setup for hibernation.
Please allocate a larger root device.
If the last log line from the hibinit-agent is hibinit-agent: Running: swapoff /swap,
hibernation was successfully configured.
If you do not see any logs from these processes, your AMI might not support hibernation. For
information about supported AMIs, see Hibernation Prerequisites (p. 472). If you used your own
AMI, make sure that you followed the instructions for Configuring an Existing AMI to Support
Hibernation (p. 473).
476
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Retire
your instance keeps its public DNS name (IPv4), private IPv4 address, IPv6 address (if applicable), and any
data on its instance store volumes.
Rebooting an instance doesn't start a new instance billing period (with a minimum one-minute charge),
unlike stopping and restarting your instance.
We might schedule your instance for a reboot for necessary maintenance, such as to apply updates that
require a reboot. No action is required on your part; we recommend that you wait for the reboot to occur
within its scheduled window. For more information, see Scheduled Events for Your Instances (p. 552).
We recommend that you use the Amazon EC2 console, a command line tool, or the Amazon EC2 API to
reboot your instance instead of running the operating system reboot command from your instance. If
you use the Amazon EC2 console, a command line tool, or the Amazon EC2 API to reboot your instance,
we perform a hard reboot if the instance does not cleanly shut down within four minutes. If you use
AWS CloudTrail, then using Amazon EC2 to reboot your instance also creates an API record of when your
instance was rebooted.
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
Instance Retirement
An instance is scheduled to be retired when AWS detects irreparable failure of the underlying hardware
hosting the instance. When an instance reaches its scheduled retirement date, it is stopped or terminated
by AWS. If your instance root device is an Amazon EBS volume, the instance is stopped, and you can start
it again at any time. Starting the stopped instance migrates it to new hardware. If your instance root
device is an instance store volume, the instance is terminated, and cannot be used again.
Contents
• Identifying Instances Scheduled for Retirement (p. 477)
• Working with Instances Scheduled for Retirement (p. 478)
For more information about types of instance events, see Scheduled Events for Your Instances (p. 552).
477
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Retire
3. If you have an instance with a scheduled event listed, select its link below the region name to go to
the Events page.
4. The Events page lists all resources with events associated with them. To view instances that are
scheduled for retirement, select Instance resources from the first filter list, and then Instance stop
or retirement from the second filter list.
5. If the filter results show that an instance is scheduled for retirement, select it, and note the date and
time in the Start time field in the details pane. This is your instance retirement date.
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
1. In the navigation pane, select Events. Use the filter lists to identify retiring instances, as
demonstrated in the procedure above, Identifying instances scheduled for retirement (p. 478).
2. In the Resource Id column, select the instance ID to go to the Instances page.
3. Select the instance and locate the Root device type field in the Description tab. If the value is ebs,
then your instance is EBS-backed. If the value is instance-store, then your instance is instance
store-backed.
To determine your instance root device type using the command line
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
478
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Terminate
EBS Create an EBS-backed AMI from your instance so that you have a backup.
Wait for the scheduled retirement date - when the instance is stopped
- or stop the instance yourself before the retirement date. You can start
the instance again at any time. For more information about stopping and
starting your instance, and what to expect when your instance is stopped,
such as the effect on public, private and Elastic IP addresses associated with
your instance, see Stop and Start Your Instance (p. 468).
EBS Create an EBS-backed AMI from your instance, and launch a replacement
instance. For more information, see Creating an Amazon EBS-Backed Linux
AMI (p. 116).
Instance store Create an instance store-backed AMI from your instance using the AMI tools,
and launch a replacement instance. For more information, see Creating an
Instance Store-Backed Linux AMI (p. 119).
Instance store Convert your instance to an EBS-backed instance by transferring your data
to an EBS volume, taking a snapshot of the volume, and then creating an
AMI from the snapshot. You can launch a replacement instance from your
new AMI. For more information, see Converting your Instance Store-Backed
AMI to an Amazon EBS-Backed AMI (p. 130).
You can't connect to or restart an instance after you've terminated it. However, you can launch additional
instances using the same AMI. If you'd rather stop and restart your instance, or hibernate it, see Stop and
Start Your Instance (p. 468) or Hibernate Your Instance (p. 470). For more information, see Differences
Between Reboot, Stop, Hibernate, and Terminate (p. 393).
Contents
• Instance Termination (p. 480)
• Terminating an Instance (p. 480)
• Enabling Termination Protection for an Instance (p. 481)
• Changing the Instance Initiated Shutdown Behavior (p. 482)
479
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Terminate
Instance Termination
After you terminate an instance, it remains visible in the console for a short while, and then the entry
is automatically deleted. You cannot delete the terminated instance entry yourself. After an instance is
terminated, resources such as tags and volumes are gradually disassociated from the instance, therefore
may no longer be visible on the terminated instance after a short while.
When an instance terminates, the data on any instance store volumes associated with that instance is
deleted.
By default, Amazon EBS root device volumes are automatically deleted when the instance terminates.
However, by default, any additional EBS volumes that you attach at launch, or any EBS volumes that
you attach to an existing instance persist even after the instance terminates. This behavior is controlled
by the volume's DeleteOnTermination attribute, which you can modify. For more information, see
Preserving Amazon EBS Volumes on Instance Termination (p. 483).
You can prevent an instance from being terminated accidentally by someone using the AWS
Management Console, the CLI, and the API. This feature is available for both Amazon EC2 instance store-
backed and Amazon EBS-backed instances. Each instance has a DisableApiTermination attribute
with the default value of false (the instance can be terminated through Amazon EC2). You can modify
this instance attribute while the instance is running or stopped (in the case of Amazon EBS-backed
instances). For more information, see Enabling Termination Protection for an Instance (p. 481).
You can control whether an instance should stop or terminate when shutdown is initiated from the
instance using an operating system command for system shutdown. For more information, see Changing
the Instance Initiated Shutdown Behavior (p. 482).
If you run a script on instance termination, your instance might have an abnormal termination, because
we have no way to ensure that shutdown scripts run. Amazon EC2 attempts to shut an instance down
cleanly and run any system shutdown scripts; however, certain events (such as hardware failure) may
prevent these system shutdown scripts from running.
• The API request will send a button press event to the guest.
• Various system services will be stopped as a result of the button press event. systemd handles a
graceful shutdown of the system. This is true for both stop and termination. Graceful shutdown is
triggered by the ACPI shutdown button press event from the hypervisor.
• ACPI shutdown will be initiated.
• The instance will shut down when the graceful shutdown process exits. There is no configurable OS
shutdown time.
Terminating an Instance
You can terminate an instance using the AWS Management Console or the command line.
1. Before you terminate the instance, verify that you won't lose any data by checking that your Amazon
EBS volumes won't be deleted on termination and that you've copied any data that you need from
your instance store volumes to Amazon EBS or Amazon S3.
480
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Terminate
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
The DisableApiTermination attribute does not prevent you from terminating an instance by
initiating shutdown from the instance (using an operating system command for system shutdown) when
the InstanceInitiatedShutdownBehavior attribute is set. For more information, see Changing the
Instance Initiated Shutdown Behavior (p. 482).
Limits
You can't enable termination protection for Spot instances — a Spot instance is terminated when the
Spot price exceeds your bid price. However, you can prepare your application to handle Spot instance
interruptions. For more information, see Spot Instance Interruptions (p. 351).
The DisableApiTermination attribute does not prevent Amazon EC2 Auto Scaling from terminating
an instance. For instances in an Auto Scaling group, use the following Amazon EC2 Auto Scaling features
instead of Amazon EC2 termination protection:
• To prevent instances that are part of an Auto Scaling group from terminating on scale in, use instance
protection. For more information, see Instance Protection in the Amazon EC2 Auto Scaling User Guide.
• To prevent Amazon EC2 Auto Scaling from terminating unhealthy instances, suspend the
ReplaceUnhealthy process. For more information, see Suspending and Resuming Scaling Processes
in the Amazon EC2 Auto Scaling User Guide.
• To specify which instances Amazon EC2 Auto Scaling should terminate first, choose a termination
policy. For more information, see Customizing the Termination Policy in the Amazon EC2 Auto Scaling
User Guide.
481
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Terminate
1. Select the instance, choose Actions, Instance Settings, and then choose Change Termination
Protection.
2. Select Yes, Enable.
1. Select the instance, choose Actions, Instance Settings, and then choose Change Termination
Protection.
2. Select Yes, Disable.
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
You can update the InstanceInitiatedShutdownBehavior attribute using the Amazon EC2 console
or the command line. The InstanceInitiatedShutdownBehavior attribute only applies when you
perform a shutdown from the operating system of the instance itself; it does not apply when you stop an
instance using the StopInstances API or the Amazon EC2 console.
482
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Terminate
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
By default, the DeletionOnTermination attribute for the root volume of an instance is set to true.
Therefore, the default is to delete the root volume of an instance when the instance terminates.
By default, when you attach an EBS volume to an instance, its DeleteOnTermination attribute is set to
false. Therefore, the default is to preserve these volumes. You must delete a volume to avoid incurring
further charges. For more information, see Deleting an Amazon EBS Volume (p. 866). After the instance
terminates, you can take a snapshot of the preserved volume or attach it to another instance.
To verify the value of the DeleteOnTermination attribute for an EBS volume that is in-use, look at
the instance's block device mapping. For more information, see Viewing the EBS Volumes in an Instance
Block Device Mapping (p. 984).
You can change value of the DeleteOnTermination attribute for a volume when you launch the
instance or while the instance is running.
Examples
• Changing the Root Volume to Persist at Launch Using the Console (p. 484)
• Changing the Root Volume to Persist at Launch Using the Command Line (p. 484)
• Changing the Root Volume of a Running Instance to Persist Using the Command Line (p. 484)
483
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Terminate
To change the root volume of an instance to persist at launch using the console
You can verify the setting by viewing details for the root device volume on the instance's details pane.
Next to Block devices, click the entry for the root device volume. By default, Delete on termination is
True. If you change the default behavior, Delete on termination is False.
Changing the Root Volume to Persist at Launch Using the Command Line
When you launch an EBS-backed instance, you can use one of the following commands to change the
root device volume to persist. For more information about these command line interfaces, see Accessing
Amazon EC2 (p. 3).
--block-device-mappings file://mapping.json
[
{
"DeviceName": "/dev/sda1",
"Ebs": {
"DeleteOnTermination": false,
"SnapshotId": "snap-1234567890abcdef0",
"VolumeType": "gp2"
}
}
]
Changing the Root Volume of a Running Instance to Persist Using the Command
Line
You can use one of the following commands to change the root device volume of a running EBS-backed
instance to persist. For more information about these command line interfaces, see Accessing Amazon
EC2 (p. 3).
484
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Recover
[
{
"DeviceName": "/dev/sda1",
"Ebs": {
"DeleteOnTermination": false
}
}
]
Troubleshooting
If your instance is in the shutting-down state for longer than usual, it will eventually be cleaned
up (terminated) by automated processes within the Amazon EC2 service. For more information, see
Troubleshooting Terminating (Shutting Down) Your Instance (p. 1029).
When the StatusCheckFailed_System alarm is triggered, and the recover action is initiated, you
will be notified by the Amazon SNS topic that you selected when you created the alarm and associated
the recover action. During instance recovery, the instance is migrated during an instance reboot, and
any data that is in-memory is lost. When the process is complete, information is published to the SNS
topic you've configured for the alarm. Anyone who is subscribed to this SNS topic will receive an email
notification that includes the status of the recovery attempt and any further instructions. You will notice
an instance reboot on the recovered instance.
The recover action can also be triggered when an instance is scheduled by AWS to stop or retire due to
degradation of the underlying hardware. For more information about scheduled events, see Scheduled
Events for Your Instances (p. 552).
If your instance has a public IPv4 address, it retains the public IPv4 address after recovery.
Requirements
The recover action is supported only on instances with the following characteristics:
485
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Configure Instances
• Use one of the following instance types: A1, C3, C4, C5, C5n, M3, M4, M5, M5a, P3, R3, R4, R5, R5a, T2,
T3, T3a, X1, or X1e
• Use default or dedicated instance tenancy
• Use EBS volumes only (do not configure instance store volumes)
The automatic recovery process attempts to recover your instance for up to three separate failures per
day. If the instance system status check failure persists, we recommend that you manually start and stop
the instance. For more information, see Stop and Start Your Instance (p. 468).
Your instance may subsequently be retired if automatic recovery fails and a hardware degradation is
determined to be the root cause for the original system status check failure.
Contents
• Common Configuration Scenarios (p. 486)
• Managing Software on Your Linux Instance (p. 487)
• Managing User Accounts on Your Linux Instance (p. 492)
• Processor State Control for Your EC2 Instance (p. 494)
• Setting the Time for Your Linux Instance (p. 499)
• Optimizing CPU Options (p. 504)
• Changing the Hostname of Your Linux Instance (p. 516)
• Setting Up Dynamic DNS on Your Linux Instance (p. 518)
• Running Commands on Your Linux Instance at Launch (p. 520)
• Instance Metadata and User Data (p. 526)
486
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Managing Software
repositories, and even more packages are available for you to build from source code. For more
information on installing and building software from these locations, see Managing Software on Your
Linux Instance (p. 487).
Amazon Linux instances come pre-configured with an ec2-user account, but you may want to add
other user accounts that do not have super-user privileges. For more information on adding and
removing user accounts, see Managing User Accounts on Your Linux Instance (p. 492).
The default time configuration for Amazon Linux instances uses Amazon Time Sync Service to set the
system time on an instance. The default time zone is UTC. For more information on setting the time zone
for an instance or using your own time server, see Setting the Time for Your Linux Instance (p. 499).
If you have your own network with a domain name registered to it, you can change the hostname of an
instance to identify itself as part of that domain. You can also change the system prompt to show a more
meaningful name without changing the hostname settings. For more information, see Changing the
Hostname of Your Linux Instance (p. 516). You can configure an instance to use a dynamic DNS service
provider. For more information, see Setting Up Dynamic DNS on Your Linux Instance (p. 518).
When you launch an instance in Amazon EC2, you have the option of passing user data to the instance
that can be used to perform common configuration tasks and even run scripts after the instance starts.
You can pass two types of user data to Amazon EC2: cloud-init directives and shell scripts. For more
information, see Running Commands on Your Linux Instance at Launch (p. 520).
Contents
• Updating Instance Software (p. 488)
• Adding Repositories (p. 489)
• Finding Software Packages (p. 490)
• Installing Software Packages (p. 490)
• Preparing to Compile Software (p. 491)
It is important to keep software up-to-date. Many packages in a Linux distribution are updated
frequently to fix bugs, add features, and protect against security exploits. For more information, see
Updating Instance Software (p. 488).
By default, Amazon Linux instances launch with the following repositories enabled:
While there are many packages available in these repositories that are updated by Amazon Web Services,
there may be a package that you wish to install that is contained in another repository. For more
information, see Adding Repositories (p. 489). For help finding packages in enabled repositories, see
Finding Software Packages (p. 490). For information about installing software on an Amazon Linux
instance, see Installing Software Packages (p. 490).
Not all software is available in software packages stored in repositories; some software must be
compiled on an instance from its source code. For more information, see Preparing to Compile
Software (p. 491).
487
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Managing Software
Amazon Linux instances manage their software using the yum package manager. The yum package
manager can install, remove, and update software, as well as manage all of the dependencies for each
package. Debian-based Linux distributions, like Ubuntu, use the apt-get command and dpkg package
manager, so the yum examples in the following sections do not work for those distributions.
1. (Optional) Start a screen session in your shell window. Sometimes you may experience a network
interruption that can disconnect the SSH connection to your instance. If this happens during a
long software update, it can leave the instance in a recoverable, although confused state. A screen
session allows you to continue running the update even if your connection is interrupted, and you
can reconnect to the session later without problems.
b. If your session is disconnected, log back into your instance and list the available screens.
c. Reconnect to the screen using the screen -r command and the process ID from the previous
command.
d. When you are finished using screen, use the exit command to close the session.
2. Run the yum update command. Optionally, you can add the --security flag to apply only security
updates.
3. Review the packages listed, type y, and press Enter to accept the updates. Updating all of the
packages on a system can take several minutes. The yum output shows the status of the update
while it is running.
4. (Optional) Reboot your instance to ensure that you are using the latest packages and libraries from
your update; kernel updates are not loaded until a reboot occurs. Updates to any glibc libraries
should also be followed by a reboot. For updates to packages that control services, it may be
sufficient to restart the services to pick up the updates, but a system reboot ensures that all previous
package and library updates are complete.
488
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Managing Software
Use this procedure to update a single package (and its dependencies) and not the entire system.
1. Run the yum update command with the name of the package you would like to update.
2. Review the package information listed, type y, and press Enter to accept the update or updates.
Sometimes there will be more than one package listed if there are package dependencies that must
be resolved. The yum output shows the status of the update while it is running.
3. (Optional) Reboot your instance to ensure that you are using the latest packages and libraries from
your update; kernel updates are not loaded until a reboot occurs. Updates to any glibc libraries
should also be followed by a reboot. For updates to packages that control services, it may be
sufficient to restart the services to pick up the updates, but a system reboot ensures that all previous
package and library updates are complete.
Adding Repositories
By default, Amazon Linux instances launch with two repositories enabled: amzn-main and amzn-
updates. While there are many packages available in these repositories that are updated by Amazon
Web Services, there may be a package that you wish to install that is contained in another repository.
Important
These procedures are intended for use with Amazon Linux. For more information about other
distributions, see their specific documentation.
To install a package from a different repository with yum, you need to add the repository information
to the /etc/yum.conf file or to its own repository.repo file in the /etc/yum.repos.d directory.
You can do this manually, but most yum repositories provide their own repository.repo file at their
repository URL.
The resulting output lists the installed repositories and reports the status of each. Enabled
repositories display the number of packages they contain.
1. Find the location of the .repo file. This will vary depending on the repository you are adding. In this
example, the .repo file is at https://www.example.com/repository.repo.
2. Add the repository with the yum-config-manager command.
489
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Managing Software
After you install a repository, you must enable it as described in the next procedure.
• Use the yum-config-manager command with the --enable repository flag. The following
command enables the Extra Packages for Enterprise Linux (EPEL) repository from the Fedora project.
By default, this repository is present in /etc/yum.repos.d on Amazon Linux AMI instances, but it
is not enabled.
Note
To enable the EPEL repository on Amazon Linux 2, use the following command:
For information on enabling the EPEL repository on other distributions, such as Red Hat and
CentOS, see the EPEL documentation at https://fedoraproject.org/wiki/EPEL.
Multiple word search queries in quotation marks only return results that match the exact query. If you
don't see the expected package, simplify your search to one keyword and then scan the results. You can
also try keyword synonyms to broaden your search.
490
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Managing Software
To install a package from a repository, use the yum install package command, replacing package with
the name of the software to install. For example, to install the links text-based web browser, enter the
following command.
You can also use yum install to install RPM package files that you have downloaded from the Internet.
To do this, simply append the path name of an RPM file to the installation command instead of a
repository package name.
Because software compilation is not a task that every Amazon EC2 instance requires, these tools are not
installed by default, but they are available in a package group called "Development Tools" that is easily
added to an instance with the yum groupinstall command.
Software source code packages are often available for download (from web sites such as https://
github.com/ and http://sourceforge.net/) as a compressed archive file, called a tarball. These tarballs will
usually have the .tar.gz file extension. You can decompress these archives with the tar command.
After you have decompressed and unarchived the source code package, you should look for a README or
INSTALL file in the source code directory that can provide you with further instructions for compiling
and installing the source code.
Amazon Web Services provides the source code for maintained packages. You can download the source
code for any installed packages with the yumdownloader --source command.
• Run the yumdownloader --source package command to download the source code for package.
For example, to download the source code for the htop package, enter the following command.
491
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Managing Users
(1/2): amzn-updates-source/latest/primary_db
| 52 kB 00:00:00
(2/2): amzn-main-source/latest/primary_db
| 734 kB 00:00:00
htop-1.0.1-2.3.amzn1.src.rpm
The location of the source RPM is in the directory from which you ran the command.
Contents
• Best Practice (p. 492)
• Creating a User Account (p. 492)
• Removing a User Account (p. 493)
Best Practice
Using the default user account is adequate for many applications. However, you may choose to add
user accounts so that individuals can have their own files and workspaces. Furthermore, creating user
accounts for new users is much more secure than granting multiple (possibly inexperienced) users access
to the default user account, because the default user account can cause a lot of damage to a system
when used improperly. For more information, see Tips for Securing Your EC2 Instance.
Prerequisites
For more information, see Creating a Key Pair Using Amazon EC2 (p. 599).
• Retrieve the public key from the key pair.
For more information, see Retrieving the Public Key for Your Key Pair on Linux (p. 601) or Retrieving
the Public Key for Your Key Pair on Windows (p. 602).
1. Use the adduser command to create the user account and add it to the system (with an entry in the
/etc/passwd file). The command also creates a group and a home directory for the account. In this
example, the user account is named newuser.
492
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Managing Users
[Ubuntu] When adding a user to an Ubuntu system, include the --disabled-password parameter
with this command to avoid adding a password to the account.
2. Switch to the new account so that the directory and file that you will create will have the proper
ownership.
Notice that, in this example, the prompt changes from ec2-user to newuser to indicate that you
have switched the shell session to the new account.
3. Add the SSH public key to the user account. First create a directory in the user's home directory for
the SSH key file, then create the key file, and finally paste the public key into the key file.
a. Create a .ssh directory in the newuser home directory and change its file permissions to 700
(only the owner can read, write, or open the directory).
Important
Without these exact file permissions, the user will not be able to log in.
b. Create a file named authorized_keys in the .ssh directory and change its file permissions to
600 (only the owner can read or write to the file).
Important
Without these exact file permissions, the user will not be able to log in.
c. Open the authorized_keys file using your favorite text editor (such as vim or nano).
Paste the public key for the key pair into the file and save the changes. For example:
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQClKsfkNkuSevGj3eYhCe53pcjqP3maAhDFcvBS7O6V
hz2ItxCih+PnDSUaw+WNQn/mZphTk/a/gU8jEzoOWbkM4yxyb/wB96xbiFveSFJuOp/d6RJhJOI0iBXr
lsLnBItntckiJ7FbtxJMXLvvwJryDUilBMTjYtwB+QhYXUMOzce5Pjz5/i8SeJtjnV3iAoG/cQk+0FzZ
qaeJAAHco+CY/5WrUBkrHmFJr6HcXkvJdWPkYQS3xqC0+FmUZofz221CBt5IMucxXPkX4rWi+z7wB3Rb
BQoQzd8v7yeb7OzlPnWOyN0qFU0XA246RA8QFYiCNYwI3f05p6KLxEXAMPLE
The user should now be able to log into the newuser account on your instance using the private
key that corresponds to the public key that you added to the authorized_keys file.
493
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Processor State Control
• Use the userdel command to remove the user account from the system. When you specify the -r
parameter, the user's home directory and mail spool are deleted. To keep the user's home directory
and mail spool, omit the -r parameter.
The following instance types provide the ability for an operating system to control processor C-states
and P-states:
The following instance types provide the ability for an operating system to control processor C-states:
You might want to change the C-state or P-state settings to increase processor performance consistency,
reduce latency, or tune your instance for a specific workload. The default C-state and P-state settings
provide maximum performance, which is optimal for most workloads. However, if your application would
benefit from reduced latency at the cost of higher single- or dual-core frequencies, or from consistent
performance at lower frequencies as opposed to bursty Turbo Boost frequencies, consider experimenting
with the C-state or P-state settings that are available to these instances.
The following sections describe the different processor state configurations and how to monitor the
effects of your configuration. These procedures were written for, and apply to Amazon Linux; however,
they may also work for other Linux distributions with a Linux kernel version of 3.9 or newer. For more
information about other Linux distributions and processor state control, see your system-specific
documentation.
494
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Processor State Control
Note
The examples on this page use the turbostat utility (which is available on Amazon Linux by
default) to display processor frequency and C-state information, and the stress command (which
can be installed by running sudo yum install -y stress) to simulate a workload.
If the output does not display the C-state information, include the --debug option in the
command (sudo turbostat --debug stress <options>).
Contents
• Highest Performance with Maximum Turbo Boost Frequency (p. 495)
• High Performance and Low Latency by Limiting Deeper C-states (p. 496)
• Baseline Performance with the Lowest Variability (p. 497)
The following example shows a c4.8xlarge instance with two cores actively performing work reaching
their maximum processor Turbo Boost frequency.
In this example, vCPUs 21 and 28 are running at their maximum Turbo Boost frequency because
the other cores have entered the C6 sleep state to save power and provide both power and thermal
headroom for the working cores. vCPUs 3 and 10 (each sharing a processor core with vCPUs 21 and 28)
are in the C1 state, waiting for instruction.
In the following example, all 18 cores are actively performing work, so there is no headroom for
maximum Turbo Boost, but they are all running at the "all core Turbo Boost" speed of 3.2 GHz.
495
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Processor State Control
99.27 3.20 2.90 0 0.26 0.00 0.47 0.00 0.00 0.00 0.00 0.00
228.59 31.33 199.26 0.00
0 0 0 99.08 3.20 2.90 0 0.27 0.01 0.64 0.00 0.00 0.00 0.00 0.00
114.69 18.55 99.32 0.00
0 0 18 98.74 3.20 2.90 0 0.62
0 1 1 99.14 3.20 2.90 0 0.09 0.00 0.76 0.00
0 1 19 98.75 3.20 2.90 0 0.49
0 2 2 99.07 3.20 2.90 0 0.10 0.02 0.81 0.00
0 2 20 98.73 3.20 2.90 0 0.44
0 3 3 99.02 3.20 2.90 0 0.24 0.00 0.74 0.00
0 3 21 99.13 3.20 2.90 0 0.13
0 4 4 99.26 3.20 2.90 0 0.09 0.00 0.65 0.00
0 4 22 98.68 3.20 2.90 0 0.67
0 5 5 99.19 3.20 2.90 0 0.08 0.00 0.73 0.00
0 5 23 98.58 3.20 2.90 0 0.69
0 6 6 99.01 3.20 2.90 0 0.11 0.00 0.89 0.00
0 6 24 98.72 3.20 2.90 0 0.39
...
A common scenario for disabling deeper sleep states is a Redis database application, which stores the
database in system memory for the fastest possible query response time.
496
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Processor State Control
2. Edit the kernel line of the first entry and add the intel_idle.max_cstate=1 option to set C1 as
the deepest C-state for idle cores.
✔ created by imagebuilder
default=0
timeout=1
hiddenmenu
The following example shows a c4.8xlarge instance with two cores actively performing work at the "all
core Turbo Boost" core frequency.
In this example, the cores for vCPUs 19 and 28 are running at 3.2 GHz, and the other cores are in the C1
C-state, awaiting instruction. Although the working cores are not reaching their maximum Turbo Boost
frequency, the inactive cores will be much faster to respond to new requests than they would be in the
deeper C6 C-state.
Intel Advanced Vector Extensions (AVX or AVX2) workloads can perform well at lower frequencies, and
AVX instructions can use more power. Running the processor at a lower frequency, by disabling Turbo
Boost, can reduce the amount of power used and keep the speed more consistent. For more information
497
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Processor State Control
about optimizing your instance configuration and workload for AVX, see http://www.intel.com/
content/dam/www/public/us/en/documents/white-papers/performance-xeon-e5-v3-advanced-vector-
extensions-paper.pdf.
This section describes how to limit deeper sleep states and disable Turbo Boost (by requesting the P1 P-
state) to provide low-latency and the lowest processor speed variability for these types of workloads.
To limit deeper sleep states and disable Turbo Boost on Amazon Linux 2
6. When you need the low processor speed variability that the P1 P-state provides, execute the
following command to disable Turbo Boost.
7. When your workload is finished, you can re-enable Turbo Boost with the following command.
To limit deeper sleep states and disable Turbo Boost on Amazon Linux AMI
2. Edit the kernel line of the first entry and add the intel_idle.max_cstate=1 option to set C1 as
the deepest C-state for idle cores.
✔ created by imagebuilder
default=0
timeout=1
hiddenmenu
498
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Setting the Time
5. When you need the low processor speed variability that the P1 P-state provides, execute the
following command to disable Turbo Boost.
6. When your workload is finished, you can re-enable Turbo Boost with the following command.
The following example shows a c4.8xlarge instance with two vCPUs actively performing work at the
baseline core frequency, with no Turbo Boost.
The cores for vCPUs 21 and 28 are actively performing work at the baseline processor speed of 2.9
GHz, and all inactive cores are also running at the baseline speed in the C1 C-state, ready to accept
instructions.
Amazon provides the Amazon Time Sync Service, which is accessible from all EC2 instances, and is also
used by other AWS services. This service uses a fleet of satellite-connected and atomic reference clocks
in each Region to deliver accurate current time readings of the Coordinated Universal Time (UTC) global
standard through Network Time Protocol (NTP). The Amazon Time Sync Service automatically smooths
any leap seconds that are added to UTC.
The Amazon Time Sync Service is available through NTP at the 169.254.169.123 IP address for any
instance running in a VPC. Your instance does not require access to the internet, and you do not have
499
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Setting the Time
to configure your security group rules or your network ACL rules to allow access. The latest versions of
Amazon Linux 2 and Amazon Linux AMIs synchronize with the Amazon Time Sync Service by default.
Use the following procedures to configure the Amazon Time Sync Service on your instance using the
chrony client. Alternatively, you can use external NTP sources. For more information about NTP and
public time sources, see http://www.ntp.org/. An instance needs access to the internet for the external
NTP time sources to work.
With the Amazon Linux AMI, you must edit the chrony configuration file to add a server entry for the
Amazon Time Sync Service.
3. Open the /etc/chrony.conf file using a text editor (such as vim or nano). Verify that the file
includes the following line:
If the line is present, then the Amazon Time Sync Service is already configured and you can go to the
next step. If not, add the line after any other server or pool statements that are already present in
the file, and save your changes.
4. Start the chrony daemon (chronyd).
Starting chronyd: [ OK ]
Note
On RHEL and CentOS (up to version 6), the service name is chrony instead of chronyd.
5. Use the chkconfig command to configure chronyd to start at each system boot.
6. Verify that chrony is using the 169.254.169.123 IP address to synchronize the time.
500
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Setting the Time
.-- Source mode '^' = server, '=' = peer, '✔' = local clock.
/ .- Source state '*' = current synced, '+' = combined , '-' = not combined,
| / '?' = unreachable, 'x' = time may be in error, '~' = time too variable.
|| .- xxxx [ yyyy ] +/- zzzz
|| Reachability register (octal) -. | xxxx = adjusted offset,
|| Log2(Polling interval) --. | | yyyy = measured offset,
|| \ | | zzzz = estimated error.
|| | | \
MS Name/IP address Stratum Poll Reach LastRx Last sample
===============================================================================
^* 169.254.169.123 3 6 17 43 -30us[ -226us] +/- 287us
^- ec2-12-34-231-12.eu-west> 2 6 17 43 -388us[ -388us] +/- 11ms
^- tshirt.heanet.ie 1 6 17 44 +178us[ +25us] +/- 1959us
^? tbag.heanet.ie 0 6 0 - +0ns[ +0ns] +/- 0ns
^? bray.walcz.net 0 6 0 - +0ns[ +0ns] +/- 0ns
^? 2a05:d018:c43:e312:ce77:> 0 6 0 - +0ns[ +0ns] +/- 0ns
^? 2a05:d018:dab:2701:b70:b> 0 6 0 - +0ns[ +0ns] +/- 0ns
1. Connect to your instance and use apt to install the chrony package.
Note
If necessary, update your instance first by running sudo apt update.
2. Open the /etc/chrony/chrony.conf file using a text editor (such as vim or nano). Add the
following line before any other server or pool statements that are already present in the file, and
save your changes:
501
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Setting the Time
4. Verify that chrony is using the 169.254.169.123 IP address to synchronize the time.
.-- Source mode '^' = server, '=' = peer, '✔' = local clock.
/ .- Source state '*' = current synced, '+' = combined , '-' = not combined,
| / '?' = unreachable, 'x' = time may be in error, '~' = time too variable.
|| .- xxxx [ yyyy ] +/- zzzz
|| Reachability register (octal) -. | xxxx = adjusted offset,
|| Log2(Polling interval) --. | | yyyy = measured offset,
|| \ | | zzzz = estimated error.
|| | | \
MS Name/IP address Stratum Poll Reach LastRx Last sample
===============================================================================
^* 169.254.169.123 3 6 17 12 +15us[ +57us] +/- 320us
^- tbag.heanet.ie 1 6 17 13 -3488us[-3446us] +/- 1779us
^- ec2-12-34-231-12.eu-west- 2 6 17 13 +893us[ +935us] +/- 7710us
^? 2a05:d018:c43:e312:ce77:6 0 6 0 10y +0ns[ +0ns] +/- 0ns
^? 2a05:d018:d34:9000:d8c6:5 0 6 0 10y +0ns[ +0ns] +/- 0ns
^? tshirt.heanet.ie 0 6 0 10y +0ns[ +0ns] +/- 0ns
^? bray.walcz.net 0 6 0 10y +0ns[ +0ns] +/- 0ns
Open the /etc/chrony.conf file using a text editor (such as vim or nano). Verify that the file contains
the following line:
502
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Setting the Time
If this line is not present, add it. Comment out any other server or pool lines. Open yast and enable the
chrony service.
1. Identify the time zone to use on the instance. The /usr/share/zoneinfo directory contains a
hierarchy of time zone data files. Browse the directory structure at that location to find a file for
your time zone.
Some of the entries at this location are directories (such as America), and these directories contain
time zone files for specific cities. Find your city (or a city in your time zone) to use for the instance.
In this example, you can use the time zone file for Los Angeles, /usr/share/zoneinfo/America/
Los_Angeles.
2. Update the /etc/sysconfig/clock file with the new time zone.
a. Open the /etc/sysconfig/clock file with your favorite text editor (such as vim or nano).
You need to use sudo with your editor command because /etc/sysconfig/clock is owned
by root.
b. Locate the ZONE entry, and change it to the time zone file (omitting the /usr/share/
zoneinfo section of the path). For example, to change to the Los Angeles time zone, change
the ZONE entry to the following:
ZONE="America/Los_Angeles"
Note
Do not change the UTC=true entry to another value. This entry is for the hardware
clock, and does not need to be adjusted when you're setting a different time zone on
your instance.
c. Save the file and exit the text editor.
3. Create a symbolic link between /etc/localtime and your time zone file so that the instance finds
the time zone file when it references local time information.
4. Reboot the system to pick up the new time zone information in all services and applications.
503
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Optimizing CPU Options
In most cases, there is an Amazon EC2 instance type that has a combination of memory and number
of vCPUs to suit your workloads. However, you can specify the following CPU options to optimize your
instance for specific workloads or business needs:
• Number of CPU cores: You can customize the number of CPU cores for the instance. You might do
this to potentially optimize the licensing costs of your software with an instance that has sufficient
amounts of RAM for memory-intensive workloads but fewer CPU cores.
• Threads per core: You can disable multithreading by specifying a single thread per CPU core. You
might do this for certain workloads, such as high performance computing (HPC) workloads.
You can specify these CPU options during instance launch. There is no additional or reduced charge
for specifying CPU options. You're charged the same as instances that are launched with default CPU
options.
Contents
• Rules for Specifying CPU Options (p. 504)
• CPU Cores and Threads Per CPU Core Per Instance Type (p. 504)
• Specifying CPU Options for Your Instance (p. 514)
• Viewing the CPU Options for Your Instance (p. 515)
• CPU options are currently supported using the Amazon EC2 console, the AWS CLI, an AWS SDK, or the
Amazon EC2 API.
• CPU options can only be specified during instance launch and cannot be modified after launch.
• When you launch an instance, you must specify both the number of CPU cores and threads per core in
the request. For example requests, see Specifying CPU Options for Your Instance (p. 514).
• The number of vCPUs for the instance is the number of CPU cores multiplied by the threads per core.
To specify a custom number of vCPUs, you must specify a valid number of CPU cores and threads per
core for the instance type. You cannot exceed the default number of vCPUs for the instance. For more
information, see CPU Cores and Threads Per CPU Core Per Instance Type (p. 504).
• To disable multithreading, specify one thread per core.
• When you change the instance type (p. 250) of an existing instance, the CPU options automatically
change to the default CPU options for the new instance type.
• The specified CPU options persist after you stop, start, or reboot an instance.
CPU Cores and Threads Per CPU Core Per Instance Type
The following tables list the instance types that support specifying CPU options. For each type, the table
shows the default and supported number of CPU cores and threads per core.
504
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Optimizing CPU Options
Instance type Default vCPUs Default CPU Default Valid number Valid number
cores threads per of CPU cores of threads per
core core
f1.2xlarge 8 4 2 1, 2, 3, 4 1, 2
f1.4xlarge 16 8 2 1, 2, 3, 4, 5, 6, 1, 2
7, 8
f1.16xlarge 64 32 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24, 26,
28, 30, 32
g3.4xlarge 16 8 2 1, 2, 3, 4, 5, 6, 1, 2
7, 8
g3.8xlarge 32 16 2 1, 2, 3, 4, 5, 6, 1, 2
7, 8, 9, 10, 11,
12, 13, 14, 15,
16
g3.16xlarge 64 32 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24, 26,
28, 30, 32
g3s.xlarge 4 2 2 1, 2 1, 2
p2.xlarge 4 2 2 1, 2 1, 2
p2.8xlarge 32 16 2 1, 2, 3, 4, 5, 6, 1, 2
7, 8, 9, 10, 11,
12, 13, 14, 15,
16
p2.16xlarge 64 32 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24, 26,
28, 30, 32
p3.2xlarge 8 4 2 1, 2, 3, 4 1, 2
p3.8xlarge 32 16 2 1, 2, 3, 4, 5, 6, 1, 2
7, 8, 9, 10, 11,
12, 13, 14, 15,
16
p3.16xlarge 64 32 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24, 26,
28, 30, 32
505
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Optimizing CPU Options
Instance type Default vCPUs Default CPU Default Valid number Valid number
cores threads per of CPU cores of threads per
core core
38, 40, 42, 44,
46, 48
Instance type Default vCPUs Default CPU Default Valid number Valid number
cores threads per of CPU cores of threads per
core core
c4.large 2 1 2 1 1, 2
c4.xlarge 4 2 2 1, 2 1, 2
c4.2xlarge 8 4 2 1, 2, 3, 4 1, 2
c4.4xlarge 16 8 2 1, 2, 3, 4, 5, 6, 1, 2
7, 8
c4.8xlarge 36 18 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18
c5.large 2 1 2 1 1, 2
c5.xlarge 4 2 2 2 1, 2
c5.2xlarge 8 4 2 2, 4 1, 2
c5.4xlarge 16 8 2 2, 4, 6, 8 1, 2
c5.9xlarge 36 18 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18
c5d.large 2 1 2 1 1, 2
c5d.xlarge 4 2 2 2 1, 2
c5d.2xlarge 8 4 2 2, 4 1, 2
c5d.4xlarge 16 8 2 2, 4, 6, 8 1, 2
506
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Optimizing CPU Options
Instance type Default vCPUs Default CPU Default Valid number Valid number
cores threads per of CPU cores of threads per
core core
c5d.9xlarge 36 18 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18
c5n.large 2 1 2 1 1, 2
c5n.xlarge 4 2 2 2 1, 2
c5n.2xlarge 8 4 2 2, 4 1, 2
c5n.4xlarge 16 8 2 2, 4, 6, 8 1, 2
c5n.9xlarge 36 18 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18
Instance type Default vCPUs Default CPU Default Valid number Valid number
cores threads per of CPU cores of threads per
core core
m5.large 2 1 2 1 1, 2
m5.xlarge 4 2 2 2 1, 2
m5.2xlarge 8 4 2 2, 4 1, 2
m5.4xlarge 16 8 2 2, 4, 6, 8 1, 2
m5.8xlarge 32 16 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16
m5.12xlarge 48 24 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24
507
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Optimizing CPU Options
Instance type Default vCPUs Default CPU Default Valid number Valid number
cores threads per of CPU cores of threads per
core core
38, 40, 42, 44,
46, 48
m5a.large 2 1 2 1 1, 2
m5a.xlarge 4 2 2 2 1, 2
m5a.2xlarge 8 4 2 2, 4 1, 2
m5a.4xlarge 16 8 2 2, 4, 6, 8 1, 2
m5a.8xlarge 32 16 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16
m5ad.large 2 1 2 1 1, 2
m5ad.xlarge 4 2 2 2 1, 2
m5ad.2xlarge 8 4 2 2, 4 1, 2
m5ad.4xlarge 16 8 2 2, 4, 6, 8 1, 2
m5d.large 2 1 2 1 1, 2
m5d.xlarge 4 2 2 2 1, 2
m5d.2xlarge 8 4 2 2, 4 1, 2
m5d.4xlarge 16 8 2 2, 4, 6, 8 1, 2
m5d.8xlarge 32 16 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16
m5d.12xlarge 48 24 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24
508
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Optimizing CPU Options
Instance type Default vCPUs Default CPU Default Valid number Valid number
cores threads per of CPU cores of threads per
core core
t3.nano 2 1 2 1 1, 2
t3.micro 2 1 2 1 1, 2
t3.small 2 1 2 1 1, 2
t3.medium 2 1 2 1 1, 2
t3.large 2 1 2 1 1, 2
t3.xlarge 4 2 2 2 1, 2
t3.2xlarge 8 4 2 2, 4 1, 2
t3a.nano 2 1 2 1 1, 2
t3a.micro 2 1 2 1 1, 2
t3a.small 2 1 2 1 1, 2
t3a.medium 2 1 2 1 1, 2
t3a.large 2 1 2 1 1, 2
t3a.xlarge 4 2 2 2 1, 2
t3a.2xlarge 8 4 2 2, 4 1, 2
Instance type Default vCPUs Default CPU Default Valid number Valid number
cores threads per of CPU cores of threads per
core core
r4.large 2 1 2 1 1, 2
r4.xlarge 4 2 2 1, 2 1, 2
r4.2xlarge 8 4 2 1, 2, 3, 4 1, 2
r4.4xlarge 16 8 2 1, 2, 3, 4, 5, 6, 1, 2
7, 8
r4.8xlarge 32 16 2 1, 2, 3, 4, 5, 6, 1, 2
7, 8, 9, 10, 11,
12, 13, 14, 15,
16
509
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Optimizing CPU Options
Instance type Default vCPUs Default CPU Default Valid number Valid number
cores threads per of CPU cores of threads per
core core
r4.16xlarge 64 32 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24, 26,
28, 30, 32
r5.large 2 1 2 1 1, 2
r5.xlarge 4 2 2 2 1, 2
r5.2xlarge 8 4 2 2, 4 1, 2
r5.4xlarge 16 8 2 2, 4, 6, 8 1, 2
r5.8xlarge 32 16 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16
r5.12xlarge 48 24 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24
r5a.large 2 1 2 1 1, 2
r5a.xlarge 4 2 2 2 1, 2
r5a.2xlarge 8 4 2 2, 4 1, 2
r5a.4xlarge 16 8 2 2, 4, 6, 8 1, 2
r5a.8xlarge 32 16 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16
r5ad.large 2 1 2 1 1, 2
r5ad.xlarge 4 2 2 2 1, 2
510
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Optimizing CPU Options
Instance type Default vCPUs Default CPU Default Valid number Valid number
cores threads per of CPU cores of threads per
core core
r5ad.2xlarge 8 4 2 2, 4 1, 2
r5ad.4xlarge 16 8 2 2, 4, 6, 8 1, 2
r5d.large 2 1 2 1 1, 2
r5d.xlarge 4 2 2 2 1, 2
r5d.2xlarge 8 4 2 2, 4 1, 2
r5d.4xlarge 16 8 2 2, 4, 6, 8 1, 2
r5d.8xlarge 32 16 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16
r5d.12xlarge 48 24 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24
x1.16xlarge 64 32 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24, 26,
28, 30, 32
x1e.xlarge 4 2 2 1, 2 1, 2
x1e.2xlarge 8 4 2 1, 2, 3, 4 1, 2
x1e.4xlarge 16 8 2 1, 2, 3, 4, 5, 6, 1, 2
7, 8
511
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Optimizing CPU Options
Instance type Default vCPUs Default CPU Default Valid number Valid number
cores threads per of CPU cores of threads per
core core
x1e.8xlarge 32 16 2 1, 2, 3, 4, 5, 6, 1, 2
7, 8, 9, 10, 11,
12, 13, 14, 15,
16
x1e.16xlarge 64 32 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24, 26,
28, 30, 32
z1d.large 2 1 2 1 1, 2
z1d.xlarge 4 2 2 2 1, 2
z1d.2xlarge 8 4 2 2, 4 1, 2
z1d.3xlarge 12 6 2 2, 4, 6 1, 2
z1d.6xlarge 24 12 2 2, 4, 6, 8, 10, 1, 2
12
Instance type Default vCPUs Default CPU Default Valid number Valid number
cores threads per of CPU cores of threads per
core core
d2.xlarge 4 2 2 1, 2 1, 2
d2.2xlarge 8 4 2 1, 2, 3, 4 1, 2
d2.4xlarge 16 8 2 1, 2, 3, 4, 5, 6, 1, 2
7, 8
d2.8xlarge 36 18 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18
h1.2xlarge 8 4 2 1, 2, 3, 4 1, 2
512
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Optimizing CPU Options
Instance type Default vCPUs Default CPU Default Valid number Valid number
cores threads per of CPU cores of threads per
core core
h1.4xlarge 16 8 2 1, 2, 3, 4, 5, 6, 1, 2
7, 8
h1.8xlarge 32 16 2 1, 2, 3, 4, 5, 6, 1, 2
7, 8, 9, 10, 11,
12, 13, 14, 15,
16
h1.16xlarge 64 32 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24, 26,
28, 30, 32
i3.large 2 1 2 1 1, 2
i3.xlarge 4 2 2 1, 2 1, 2
i3.2xlarge 8 4 2 1, 2, 3, 4 1, 2
i3.4xlarge 16 8 2 1, 2, 3, 4, 5, 6, 1, 2
7, 8
i3.8xlarge 32 16 2 1, 2, 3, 4, 5, 6, 1, 2
7, 8, 9, 10, 11,
12, 13, 14, 15,
16
i3.16xlarge 64 32 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24, 26,
28, 30, 32
i3en.large 2 1 2 1 1, 2
i3en.xlarge 4 2 2 2 1, 2
i3en.2xlarge 8 4 2 2, 4 1, 2
i3en.3xlarge 12 6 2 2, 4, 6 1, 2
i3en.6xlarge 24 12 2 2, 4, 6, 8, 10, 1, 2
12
i3en.12xlarge 48 24 2 2, 4, 6, 8, 10, 1, 2
12, 14, 16, 18,
20, 22, 24
513
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Optimizing CPU Options
Disabling Multithreading
To disable multithreading, specify one thread per core.
1. Follow the Launching an Instance Using the Launch Instance Wizard (p. 395) procedure.
2. On the Configure Instance Details page, for CPU options, choose Specify CPU options.
3. For Core count, choose the number of required CPU cores. In this example, to specify the default
CPU core count for an r4.4xlarge instance, choose 8.
4. To disable multithreading, for Threads per core, choose 1.
5. Continue as prompted by the wizard. When you've finished reviewing your options on the Review
Instance Launch page, choose Launch. For more information, see Launching an Instance Using the
Launch Instance Wizard (p. 395).
Use the run-instances AWS CLI command and specify a value of 1 for ThreadsPerCore for the --cpu-
options parameter. For CoreCount, specify the number of CPU cores. In this example, to specify the
default CPU core count for an r4.4xlarge instance, specify a value of 8.
1. Follow the Launching an Instance Using the Launch Instance Wizard (p. 395) procedure.
2. On the Configure Instance Details page, for CPU options, choose Specify CPU options.
3. To get six vCPUs, specify three CPU cores and two threads per core, as follows:
514
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Optimizing CPU Options
Use the run-instances AWS CLI command and specify the number of CPU cores and number of threads
in the --cpu-options parameter. You can specify three CPU cores and two threads per core to get six
vCPUs.
Alternatively, specify six CPU cores and one thread per core (disable multithreading) to get six vCPUs:
...
"Instances": [
{
"Monitoring": {
"State": "disabled"
},
"PublicDnsName": "ec2-198-51-100-5.eu-central-1.compute.amazonaws.com",
"State": {
"Code": 16,
"Name": "running"
},
"EbsOptimized": false,
"LaunchTime": "2018-05-08T13:40:33.000Z",
"PublicIpAddress": "198.51.100.5",
"PrivateIpAddress": "172.31.2.206",
"ProductCodes": [],
"VpcId": "vpc-1a2b3c4d",
"CpuOptions": {
"CoreCount": 34,
"ThreadsPerCore": 1
},
515
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Changing the Hostname
"StateTransitionReason": "",
...
}
]
...
In the output that's returned, the CoreCount field indicates the number of cores for the instance. The
ThreadsPerCore field indicates the number of threads per core.
Alternatively, connect to your instance and use a tool such as lscpu to view the CPU information for your
instance.
You can use AWS Config to record, assess, audit, and evaluate configuration changes for instances,
including terminated instances. For more information, see Getting Started with AWS Config in the AWS
Config Developer Guide.
Follow this procedure if you already have a public DNS name registered.
1. • For Amazon Linux 2: Use the hostnamectl command to set your hostname to reflect the fully
qualified domain name (such as webserver.mydomain.com).
• For Amazon Linux AMI: On your instance, open the /etc/sysconfig/network configuration file
in your favorite text editor and change the HOSTNAME entry to reflect the fully qualified domain
name (such as webserver.mydomain.com).
HOSTNAME=webserver.mydomain.com
516
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Changing the Hostname
Alternatively, you can reboot using the Amazon EC2 console (on the Instances page, choose Actions,
Instance State, Reboot).
3. Log into your instance and verify that the hostname has been updated. Your prompt should show
the new hostname (up to the first ".") and the hostname command should show the fully-qualified
domain name.
1. • For Amazon Linux 2: Use the hostnamectl command to set your hostname to reflect the desired
system hostname (such as webserver).
• For Amazon Linux AMI: On your instance, open the /etc/sysconfig/network configuration
file in your favorite text editor and change the HOSTNAME entry to reflect the desired system
hostname (such as webserver).
HOSTNAME=webserver.localdomain
2. Open the /etc/hosts file in your favorite text editor and change the entry beginning with
127.0.0.1 to match the example below, substituting your own hostname.
Alternatively, you can reboot using the Amazon EC2 console (on the Instances page, choose Actions,
Instance State, Reboot).
4. Log into your instance and verify that the hostname has been updated. Your prompt should show
the new hostname (up to the first ".") and the hostname command should show the fully-qualified
domain name.
1. Create a file in /etc/profile.d that sets the environment variable called NICKNAME to the value
you want in the shell prompt. For example, to set the system nickname to webserver, run the
following command.
517
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Setting Up Dynamic DNS
2. Open the /etc/bashrc (Red Hat) or /etc/bash.bashrc (Debian/Ubuntu) file in your favorite text
editor (such as vim or nano). You need to use sudo with the editor command because /etc/bashrc
and /etc/bash.bashrc are owned by root.
3. Edit the file and change the shell prompt variable (PS1) to display your nickname instead of
the hostname. Find the following line that sets the shell prompt in /etc/bashrc or /etc/
bash.bashrc (several surrounding lines are shown below for context; look for the line that starts
with [ "$PS1"):
✔ Turn on checkwinsize
shopt -s checkwinsize
[ "$PS1" = "\\s-\\v\\\$ " ] && PS1="[\u@\h \W]\\$ "
✔ You might want to have e.g. tty in prompt (e.g. more virtual machines)
✔ and console windows
Change the \h (the symbol for hostname) in that line to the value of the NICKNAME variable.
✔ Turn on checkwinsize
shopt -s checkwinsize
[ "$PS1" = "\\s-\\v\\\$ " ] && PS1="[\u@$NICKNAME \W]\\$ "
✔ You might want to have e.g. tty in prompt (e.g. more virtual machines)
✔ and console windows
4. (Optional) To set the title on shell windows to the new nickname, complete the following steps.
c. Open the /etc/sysconfig/bash-prompt-xterm file in your favorite text editor (such as vim
or nano). You need to use sudo with the editor command because /etc/sysconfig/bash-
prompt-xterm is owned by root.
d. Add the following line to the file.
5. Log out and then log back in to pick up the new nickname value.
• How do I assign a static hostname to a private Amazon EC2 instance running RHEL 7 or Centos 7?
518
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Setting Up Dynamic DNS
the Amazon Web Services domain, these public names must be quite long for each name to remain
unique. A typical Amazon EC2 public DNS name looks something like this: ec2-12-34-56-78.us-
west-2.compute.amazonaws.com, where the name consists of the Amazon Web Services domain, the
service (in this case, compute), the region, and a form of the public IP address.
Dynamic DNS services provide custom DNS host names within their domain area that can be easy to
remember and that can also be more relevant to your host's use case; some of these services are also free
of charge. You can use a dynamic DNS provider with Amazon EC2 and configure the instance to update
the IP address associated with a public DNS name each time the instance starts. There are many different
providers to choose from, and the specific details of choosing a provider and registering a name with
them are outside the scope of this guide.
Important
These procedures are intended for use with Amazon Linux. For more information about other
distributions, see their specific documentation.
1. Sign up with a dynamic DNS service provider and register a public DNS name with their service. This
procedure uses the free service from noip.com/free as an example.
2. Configure the dynamic DNS update client. After you have a dynamic DNS service provider and
a public DNS name registered with their service, point the DNS name to the IP address for your
instance. Many providers (including noip.com) allow you to do this manually from your account page
on their website, but many also support software update clients. If an update client is running on
your EC2 instance, your dynamic DNS record is updated each time the IP address changes, as after
a shutdown and restart. In this example, you install the noip2 client, which works with the service
provided by noip.com.
a. Enable the Extra Packages for Enterprise Linux (EPEL) repository to gain access to the noip2
client.
Note
Amazon Linux instances have the GPG keys and repository information for the EPEL
repository installed by default; however, Red Hat and CentOS instances must first
install the epel-release package before you can enable the EPEL repository. For
more information and to download the latest version of this package, see https://
fedoraproject.org/wiki/EPEL.
c. Create the configuration file. Enter the login and password information when prompted and
answer the subsequent questions to configure the client.
519
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Running Commands at Launch
This command starts the client, which reads the configuration file (/etc/no-ip2.conf) that you
created earlier and updates the IP address for the public DNS name that you chose.
5. Verify that the update client has set the correct IP address for your dynamic DNS name. Allow a few
minutes for the DNS records to update, and then try to connect to your instance using SSH with the
public DNS name that you configured in this procedure.
If you are interested in more complex automation scenarios, consider using AWS CloudFormation and
AWS OpsWorks. For more information, see the AWS CloudFormation User Guide and the AWS OpsWorks
User Guide.
For information about running commands on your Windows instance at launch, see Running Commands
on Your Windows Instance at Launch and Managing Windows Instance Configuration in the Amazon EC2
User Guide for Windows Instances.
In the following examples, the commands from the Install a LAMP Web Server on Amazon Linux 2 (p. 33)
are converted to a shell script and a set of cloud-init directives that executes when the instance launches.
In each example, the following tasks are executed by the user data:
520
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Running Commands at Launch
Contents
• Prerequisites (p. 521)
• User Data and Shell Scripts (p. 521)
• User Data and the Console (p. 521)
• User Data and cloud-init Directives (p. 523)
• User Data and the AWS CLI (p. 524)
Prerequisites
The following examples assume that your instance has a public DNS name that is reachable from the
Internet. For more information, see Step 1: Launch an Instance (p. 28). You must also configure your
security group to allow SSH (port 22), HTTP (port 80), and HTTPS (port 443) connections. For more
information about these prerequisites, see Setting Up with Amazon EC2 (p. 19).
Also, these instructions are intended for use with Amazon Linux 2, and the commands and directives
may not work for other Linux distributions. For more information about other distributions, such as their
support for cloud-init, see their specific documentation.
User data shell scripts must start with the ✔! characters and the path to the interpreter you want to read
the script (commonly /bin/bash). For a great introduction on shell scripting, see the BASH Programming
HOW-TO at the Linux Documentation Project (tldp.org).
Scripts entered as user data are executed as the root user, so do not use the sudo command in the
script. Remember that any files you create will be owned by root; if you need non-root users to have file
access, you should modify the permissions accordingly in the script. Also, because the script is not run
interactively, you cannot include commands that require user feedback (such as yum update without the
-y flag).
When a user data script is processed, it is copied to and executed from /var/lib/cloud/
instances/instance-id/. The script is not deleted after it is run. Be sure to delete the user data
scripts from /var/lib/cloud/instances/instance-id/ before you create an AMI from the
instance. Otherwise, the script will exist in this directory on any instance launched from the AMI.
521
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Running Commands at Launch
In the example script below, the script creates and configures our web server.
✔!/bin/bash
yum update -y
amazon-linux-extras install -y lamp-mariadb10.2-php7.2 php7.2
yum install -y httpd mariadb-server
systemctl start httpd
systemctl enable httpd
usermod -a -G apache ec2-user
chown -R ec2-user:apache /var/www
chmod 2775 /var/www
find /var/www -type d -exec chmod 2775 {} \;
find /var/www -type f -exec chmod 0664 {} \;
echo "<?php phpinfo(); ?>" > /var/www/html/phpinfo.php
Allow enough time for the instance to launch and execute the commands in your script, and then check
to see that your script has completed the tasks that you intended.
For our example, in a web browser, enter the URL of the PHP test file the script created. This URL is the
public DNS address of your instance followed by a forward slash and the file name.
http://my.public.dns.amazonaws.com/phpinfo.php
You should see the PHP information page. If you are unable to see the PHP information page, check that
the security group you are using contains a rule to allow HTTP (port 80) traffic. For more information, see
Adding Rules to a Security Group (p. 613).
(Optional) If your script did not accomplish the tasks you were expecting it to, or if you just want to
verify that your script completed without errors, examine the cloud-init output log file at /var/log/
cloud-init-output.log and look for error messages in the output.
For additional debugging information, you can create a Mime multipart archive that includes a cloud-init
data section with the following directive:
This directive sends command output from your script to /var/log/cloud-init-output.log. For
more information about cloud-init data formats and creating Mime multi part archive, see cloud-init
Formats.
522
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Running Commands at Launch
4. When prompted for confirmation, choose Yes, Stop. It can take a few minutes for the instance to
stop.
5. With the instance still selected, choose Actions, Instance Settings, View/Change User Data. You
can't change the user data if the instance is running, but you can view it.
6. In the View/Change User Data dialog box, update the user data, and then choose Save.
7. Restart the instance. The new user data is visible on your instance after you restart it; however, user
data scripts are not executed.
The cloud-init user directives can be passed to an instance at launch the same way that a script
is passed, although the syntax is different. For more information about cloud-init, go to http://
cloudinit.readthedocs.org/en/latest/index.html.
Important
By default, user data scripts and cloud-init directives run only during the boot cycle when you
first launch an instance. You can update your configuration to ensure that your user data scripts
and cloud-init directives run every time you restart your instance. For more information, see
How can I execute user data with every restart of my EC2 instance? in the AWS Knowledge
Center.
Adding these tasks at boot time adds to the amount of time it takes to boot an instance. You should
allow a few minutes of extra time for the tasks to complete before you test that your user data directives
have completed.
1. Follow the procedure for launching an instance at Launching Your Instance from an AMI (p. 396),
but when you get to Step 6 (p. 398) in that procedure, enter your cloud-init directive text in the User
data field, and then complete the launch procedure.
In the example below, the directives create and configure a web server on Amazon Linux 2. The
✔cloud-config line at the top is required in order to identify the commands as cloud-init
directives.
✔cloud-config
repo_update: true
repo_upgrade: all
packages:
- httpd
- mariadb-server
runcmd:
- [ sh, -c, "amazon-linux-extras install -y lamp-mariadb10.2-php7.2 php7.2" ]
- systemctl start httpd
- sudo systemctl enable httpd
- [ sh, -c, "usermod -a -G apache ec2-user" ]
- [ sh, -c, "chown -R ec2-user:apache /var/www" ]
- chmod 2775 /var/www
- [ find, /var/www, -type, d, -exec, chmod, 2775, {}, \; ]
- [ find, /var/www, -type, f, -exec, chmod, 0664, {}, \; ]
- [ sh, -c, 'echo "<?php phpinfo(); ?>" > /var/www/html/phpinfo.php' ]
523
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Running Commands at Launch
2. Allow enough time for the instance to launch and execute the directives in your user data, and then
check to see that your directives have completed the tasks you intended.
For our example, in a web browser, enter the URL of the PHP test file the directives created. This URL
is the public DNS address of your instance followed by a forward slash and the file name.
http://my.public.dns.amazonaws.com/phpinfo.php
You should see the PHP information page. If you are unable to see the PHP information page,
check that the security group you are using contains a rule to allow HTTP (port 80) traffic. For more
information, see Adding Rules to a Security Group (p. 613).
3. (Optional) If your directives did not accomplish the tasks you were expecting them to, or if you
just want to verify that your directives completed without errors, examine the output log file at /
var/log/cloud-init-output.log and look for error messages in the output. For additional
debugging information, you can add the following line to your directives:
On Windows, you can use the AWS Tools for Windows PowerShell instead of using the AWS CLI. For more
information, see User Data and the Tools for Windows PowerShell in the Amazon EC2 User Guide for
Windows Instances.
To specify user data when you launch your instance, use the run-instances command with the --user-
data parameter. With run-instances, the AWS CLI performs base64 encoding of the user data for you.
The following example shows how to specify a script as a string on the command line:
The following example shows how to specify a script using a text file. Be sure to use the file:// prefix
to specify the file.
✔!/bin/bash
yum update -y
service httpd start
chkconfig httpd on
524
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Running Commands at Launch
You can modify the user data of a stopped instance using the modify-instance-attribute command. With
modify-instance-attribute, the AWS CLI does not perform base64 encoding of the user data for you.
On Windows, use the certutil command to encode the user data. Before you can use this file with the
AWS CLI, you must remove the first (BEGIN CERTIFICATE) and last (END CERTIFICATE) lines.
Use the --attribute and --value parameters to use the encoded text file to specify the user data. Be
sure to use the file:// prefix to specify the file.
To retrieve the user data for an instance, use the describe-instance-attribute command. With describe-
instance-attribute, the AWS CLI does not perform base64 decoding of the user data for you.
The following is example output with the user data base64 encoded.
{
"UserData": {
"Value":
"IyEvYmluL2Jhc2gKeXVtIHVwZGF0ZSAteQpzZXJ2aWNlIGh0dHBkIHN0YXJ0CmNoa2NvbmZpZyBodHRwZCBvbg=="
},
"InstanceId": "i-1234567890abcdef0"
}
On Linux, use the --query option to get the encoded user data and the base64 command to decode it.
On Windows, use the --query option to get the coded user data and the certutil command to decode it.
Note that the encoded output is stored in a file and the decoded output is stored in another file.
✔!/bin/bash
yum update -y
service httpd start
chkconfig httpd on
525
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Metadata and User Data
You can also use instance metadata to access user data that you specified when launching your instance.
For example, you can specify parameters for configuring your instance, or attach a simple script. You
can also use this data to build more generic AMIs that can be modified by configuration files supplied at
launch time. For example, if you run web servers for various small businesses, they can all use the same
AMI and retrieve their content from the Amazon S3 bucket you specify in the user data at launch. To add
a new customer at any time, simply create a bucket for the customer, add their content, and launch your
AMI. If you launch more than one instance at the same time, the user data is available to all instances in
that reservation.
EC2 instances can also include dynamic data, such as an instance identity document that is generated
when the instance is launched. For more information, see Dynamic Data Categories (p. 537).
Contents
• Retrieving Instance Metadata (p. 526)
• Working with Instance User Data (p. 529)
• Retrieving Dynamic Data (p. 530)
• Example: AMI Launch Index Value (p. 530)
• Instance Metadata Categories (p. 532)
• Instance Identity Documents (p. 538)
To view all categories of instance metadata from within a running instance, use the following URI:
http://169.254.169.254/latest/meta-data/
The IP address 169.254.169.254 is a link-local address and is valid only from the instance. For more
information, see Link-local address on Wikipedia.
Note that you are not billed for HTTP requests used to retrieve instance metadata and user data.
You can use a tool such as cURL, or if your instance supports it, the GET command; for example:
526
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Metadata and User Data
You can also download the Instance Metadata Query tool, which allows you to query the instance
metadata without having to type out the full URI or category names.
All instance metadata is returned as text (content type text/plain). A request for a specific metadata
resource returns the appropriate value, or a 404 - Not Found HTTP error code if the resource is not
available.
A request for a general metadata resource (the URI ends with a /) returns a list of available resources, or
a 404 - Not Found HTTP error code if there is no such resource. The list items are on separate lines,
terminated by line feeds (ASCII 10).
This example gets the top-level metadata items. For more information, see Instance Metadata
Categories (p. 532).
527
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Metadata and User Data
reservation-id
security-groups
services/
These examples get the value of some of the metadata items from the preceding example.
This example gets public key 0 (in the OpenSSH key format).
Throttling
We throttle queries to the instance metadata service on a per-instance basis, and we place limits on the
number of simultaneous connections from an instance to the instance metadata service.
528
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Metadata and User Data
If you're using the instance metadata service to retrieve AWS security credentials, avoid querying for
credentials during every transaction or concurrently from a high number of threads or processes, as
this may lead to throttling. Instead, we recommend that you cache the credentials until they start
approaching their expiry time.
If you're throttled while accessing the instance metadata service, retry your query with an exponential
backoff strategy.
• User data must be base64-encoded. The Amazon EC2 console can perform the base64 encoding for
you or accept base64-encoded input.
• User data is limited to 16 KB, in raw form, before it is base64-encoded. The size of a string of length n
after base64-encoding is ceil(n/3)*4.
• User data must be base64-decoded when you retrieve it. The data is decoded for you automatically if
you retrieve it using instance metadata or the console.
• User data is treated as opaque data: what you give is what you get back. It is up to the instance to be
able to interpret it.
• If you stop an instance, modify its user data, and start the instance, the updated user data is not
executed when you start the instance.
http://169.254.169.254/latest/user-data
A request for user data returns the data as it is (content type application/octet-stream).
This example returns user data that was provided as comma-separated text:
529
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Metadata and User Data
To retrieve user data for an instance from your own computer, see User Data and the AWS CLI (p. 524)
http://169.254.169.254/latest/dynamic/
This example shows how to retrieve the high-level instance identity categories:
For more information about dynamic data and examples of how to retrieve it, see Instance Identity
Documents (p. 538).
Alice wants to launch four instances of her favorite database AMI, with the first acting as master and
the remaining three acting as replicas. When she launches them, she wants to add user data about the
replication strategy for each replicant. She is aware that this data will be available to all four instances,
so she needs to structure the user data in a way that allows each instance to recognize which parts are
applicable to it. She can do this using the ami-launch-index instance metadata value, which will be
unique for each instance.
Alice launches four instances using the run-instances command, specifying the user data:
After they're launched, all instances have a copy of the user data and the common metadata shown here:
530
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Metadata and User Data
Instance 1
Metadata Value
instance-id i-1234567890abcdef0
ami-launch-index 0
public-hostname ec2-203-0-113-25.compute-1.amazonaws.com
public-ipv4 67.202.51.223
local-hostname ip-10-251-50-12.ec2.internal
local-ipv4 10.251.50.35
Instance 2
Metadata Value
instance-id i-0598c7d356eba48d7
ami-launch-index 1
public-hostname ec2-67-202-51-224.compute-1.amazonaws.com
public-ipv4 67.202.51.224
local-hostname ip-10-251-50-36.ec2.internal
local-ipv4 10.251.50.36
Instance 3
Metadata Value
instance-id i-0ee992212549ce0e7
ami-launch-index 2
public-hostname ec2-67-202-51-225.compute-1.amazonaws.com
public-ipv4 67.202.51.225
local-hostname ip-10-251-50-37.ec2.internal
local-ipv4 10.251.50.37
Instance 4
Metadata Value
instance-id i-1234567890abcdef0
ami-launch-index 3
public-hostname ec2-67-202-51-226.compute-1.amazonaws.com
public-ipv4 67.202.51.226
531
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Metadata and User Data
Metadata Value
local-hostname ip-10-251-50-38.ec2.internal
local-ipv4 10.251.50.38
Alice can use the ami-launch-index value to determine which portion of the user data is applicable to
a particular instance.
1. She connects to one of the instances, and retrieves the ami-launch-index for that instance to
ensure it is one of the replicants:
4. Finally, Alice uses the cut command to extract the portion of the user data that is applicable to that
instance:
532
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Metadata and User Data
533
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Metadata and User Data
534
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Metadata and User Data
535
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Metadata and User Data
536
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Metadata and User Data
537
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Metadata and User Data
fws/instance- Value showing whether the customer has enabled detailed 2009-04-04
monitoring one-minute monitoring in CloudWatch. Valid values:
enabled | disabled
The instance identity document is generated when the instance is launched, and exposed to the instance
through instance metadata (p. 526). It validates the attributes of the instances, such as the instance
size, instance type, operating system, and AMI.
Important
Due to the dynamic nature of instance identity documents and signatures, we recommend
retrieving the instance identity document and signature regularly.
{
"devpayProductCodes" : null,
"marketplaceProductCodes" : [ "1abc2defghijklm3nopqrs4tu" ],
"availabilityZone" : "us-west-2b",
"privateIp" : "10.158.112.84",
"version" : "2017-09-30",
"instanceId" : "i-1234567890abcdef0",
"billingProducts" : null,
"instanceType" : "t2.micro",
"accountId" : "123456789012",
"imageId" : "ami-5fb8c835",
"pendingTime" : "2016-11-19T16:32:11Z",
"architecture" : "x86_64",
"kernelId" : null,
"ramdiskId" : null,
"region" : "us-west-2"
538
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Metadata and User Data
To retrieve the instance identity signature, use the following command from your running instance:
dExamplesjNQhhJan7pORLpLSr7lJEF4V2DhKGlyoYVBoUYrY9njyBCmhEayaGrhtS/AWY+LPx
lVSQURF5n0gwPNCuO6ICT0fNrm5IH7w9ydyaexamplejJw8XvWPxbuRkcN0TAA1p4RtCAqm4ms
x2oALjWSCBExample=
To retrieve the PKCS7 signature, use the following command from your running instance:
MIICiTCCAfICCQD6m7oRw0uXOjANBgkqhkiG9w0BAQUFADCBiDELMAkGA1UEBhMC
VVMxCzAJBgNVBAgTAldBMRAwDgYDVQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6
b24xFDASBgNVBAsTC0lBTSBDb25zb2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAd
BgkqhkiG9w0BCQEWEG5vb25lQGFtYXpvbi5jb20wHhcNMTEwNDI1MjA0NTIxWhcN
MTIwNDI0MjA0NTIxWjCBiDELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAldBMRAwDgYD
VQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6b24xFDASBgNVBAsTC0lBTSBDb25z
b2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAdBgkqhkiG9w0BCQEWEG5vb25lQGFt
YXpvbi5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMaK0dn+a4GmWIWJ
21uUSfwfEvySWtC2XADZ4nB+BLYgVIk60CpiwsZ3G93vUEIO3IyNoH/f0wYK8m9T
rDHudUZg3qX4waLG5M43q7Wgc/MbQITxOUSQv7c7ugFFDzQGBzZswY6786m86gpE
Ibb3OhjZnzcvQAaRHhdlQWIMm2nrAgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAtCu4
nUhVVxYUntneD9+h8Mg9q6q+auNKyExzyLwaxlAoo7TJHidbtS4J5iNmZgXL0Fkb
FFBjvSfpJIlJ00zbhNYS5f6GuoEDmFJl0ZxBHjJnyp378OD8uTs7fLvjx79LjSTb
NYiytVbZPQUQ5Yaxu2jXnimvw3rrszlaEXAMPLE
The AWS public certificate for the regions provided by an AWS account is as follows:
-----BEGIN CERTIFICATE-----
MIIC7TCCAq0CCQCWukjZ5V4aZzAJBgcqhkjOOAQDMFwxCzAJBgNVBAYTAlVTMRkw
FwYDVQQIExBXYXNoaW5ndG9uIFN0YXRlMRAwDgYDVQQHEwdTZWF0dGxlMSAwHgYD
VQQKExdBbWF6b24gV2ViIFNlcnZpY2VzIExMQzAeFw0xMjAxMDUxMjU2MTJaFw0z
ODAxMDUxMjU2MTJaMFwxCzAJBgNVBAYTAlVTMRkwFwYDVQQIExBXYXNoaW5ndG9u
IFN0YXRlMRAwDgYDVQQHEwdTZWF0dGxlMSAwHgYDVQQKExdBbWF6b24gV2ViIFNl
cnZpY2VzIExMQzCCAbcwggEsBgcqhkjOOAQBMIIBHwKBgQCjkvcS2bb1VQ4yt/5e
ih5OO6kK/n1Lzllr7D8ZwtQP8fOEpp5E2ng+D6Ud1Z1gYipr58Kj3nssSNpI6bX3
VyIQzK7wLclnd/YozqNNmgIyZecN7EglK9ITHJLP+x8FtUpt3QbyYXJdmVMegN6P
hviYt5JH/nYl4hh3Pa1HJdskgQIVALVJ3ER11+Ko4tP6nwvHwh6+ERYRAoGBAI1j
k+tkqMVHuAFcvAGKocTgsjJem6/5qomzJuKDmbJNu9Qxw3rAotXau8Qe+MBcJl/U
hhy1KHVpCGl9fueQ2s6IL0CaO/buycU1CiYQk40KNHCcHfNiZbdlx1E9rpUp7bnF
lRa2v1ntMX3caRVDdbtPEWmdxSCYsYFDk4mZrOLBA4GEAAKBgEbmeve5f8LIE/Gf
MNmP9CM5eovQOGx5ho8WqD+aTebs+k2tn92BBPqeZqpWRa5P/+jrdKml1qx4llHW
MXrs3IgIb6+hUIB+S8dz8/mmO0bpr76RoZVCXYab2CZedFut7qc3WUH9+EUAH5mw
vSeDCOUMYQR7R9LINYwouHIziqQYMAkGByqGSM44BAMDLwAwLAIUWXBlk40xTwSw
7HX32MxXYruse9ACFBNGmdX2ZBrVNGrN9N2f6ROk0k9K
-----END CERTIFICATE-----
539
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Metadata and User Data
The AWS public certificate for the AWS GovCloud (US-West) region is as follows:
-----BEGIN CERTIFICATE-----
MIICuzCCAiQCCQDrSGnlRgvSazANBgkqhkiG9w0BAQUFADCBoTELMAkGA1UEBhMC
VVMxCzAJBgNVBAgTAldBMRAwDgYDVQQHEwdTZWF0dGxlMRMwEQYDVQQKEwpBbWF6
b24uY29tMRYwFAYDVQQLEw1FQzIgQXV0aG9yaXR5MRowGAYDVQQDExFFQzIgQU1J
IEF1dGhvcml0eTEqMCgGCSqGSIb3DQEJARYbZWMyLWluc3RhbmNlLWlpZEBhbWF6
b24uY29tMB4XDTExMDgxMjE3MTgwNVoXDTIxMDgwOTE3MTgwNVowgaExCzAJBgNV
BAYTAlVTMQswCQYDVQQIEwJXQTEQMA4GA1UEBxMHU2VhdHRsZTETMBEGA1UEChMK
QW1hem9uLmNvbTEWMBQGA1UECxMNRUMyIEF1dGhvcml0eTEaMBgGA1UEAxMRRUMy
IEFNSSBBdXRob3JpdHkxKjAoBgkqhkiG9w0BCQEWG2VjMi1pbnN0YW5jZS1paWRA
YW1hem9uLmNvbTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAqaIcGFFTx/SO
1W5G91jHvyQdGP25n1Y91aXCuOOWAUTvSvNGpXrI4AXNrQF+CmIOC4beBASnHCx0
82jYudWBBl9Wiza0psYc9flrczSzVLMmN8w/c78F/95NfiQdnUQPpvgqcMeJo82c
gHkLR7XoFWgMrZJqrcUK0gnsQcb6kakCAwEAATANBgkqhkiG9w0BAQUFAAOBgQDF
VH0+UGZr1LCQ78PbBH0GreiDqMFfa+W8xASDYUZrMvY3kcIelkoIazvi4VtPO7Qc
yAiLr6nkk69Tr/MITnmmsZJZPetshqBndRyL+DaTRnF0/xvBQXj5tEh+AmRjvGtp
6iS1rQoNanN8oEcT2j4b48rmCmnDhRoBcFHwCYs/3w==
-----END CERTIFICATE-----
For other regions, contact AWS Support to get the AWS public certificate.
1. From your instance, create a temporary file for the PKCS7 signature:
3. Append the contents of the PKCS7 signature from the instance metadata, plus a new line:
6. Add the contents of the document from your instance metadata to the temporary document file:
7. Open a text editor and create a file named AWSpubkey. Copy and paste the contents of the AWS
public certificate above to the file and save it.
8. Use the OpenSSL tools to verify the signature as follows:
[ec2-user ~]$ openssl smime -verify -in $PKCS7 -inform PEM -content $DOCUMENT -certfile
AWSpubkey -noverify > /dev/null
Verification successful
540
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Identify Instances
For information about identifying Windows instances, see Identify EC2 Windows Instances in the Amazon
EC2 User Guide for Windows Instances.
In the following example output, the UUID starts with "ec2", which indicates that the system is probably
an EC2 instance.
ec2e1916-9099-7caf-fd21-012345abcdef
On HVM instances only, you can use the Desktop Management Interface (DMI).
You can use the dmidecode tool to return the UUID. On Amazon Linux, use the following command to
install the dmidecode tool if it's not already installed on your instance:
In the following example output, the UUID starts with "EC2", which indicates that the system is probably
an EC2 instance.
541
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Inspecting the System UUID
EC2E1916-9099-7CAF-FD21-01234ABCDEF
45E12AEC-DCD1-B213-94ED-01234ABCDEF
i-0af01c0123456789a
542
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Amazon EI distributes model operations defined by TensorFlow, Apache MXNet, and the Open Neural
Network Exchange (ONNX) format through MXNet between low-cost, DL inference accelerators and the
CPU of the instance.
For more information about Amazon Elastic Inference, see the Amazon EI Developer Guide.
543
Amazon Elastic Compute Cloud
User Guide for Linux Instances
After you have defined your monitoring goals and have created your monitoring plan, the next step is
to establish a baseline for normal Amazon EC2 performance in your environment. You should measure
Amazon EC2 performance at various times and under different load conditions. As you monitor Amazon
EC2, you should store a history of monitoring data that you've collected. You can compare current
Amazon EC2 performance to this historical data to help you to identify normal performance patterns
and performance anomalies, and devise methods to address them. For example, you can monitor CPU
utilization, disk I/O, and network utilization for your EC2 instances. When performance falls outside your
established baseline, you might need to reconfigure or optimize the instance to reduce CPU utilization,
improve disk I/O, or reduce network traffic.
544
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Automated and Manual Monitoring
Topics
• Automated Monitoring Tools (p. 545)
• Manual Monitoring Tools (p. 546)
• System Status Checks - monitor the AWS systems required to use your instance to ensure they are
working properly. These checks detect problems with your instance that require AWS involvement to
repair. When a system status check fails, you can choose to wait for AWS to fix the issue or you can
resolve it yourself (for example, by stopping and restarting or terminating and replacing an instance).
Examples of problems that cause system status checks to fail include:
• Loss of network connectivity
• Loss of system power
• Software issues on the physical host
• Hardware issues on the physical host that impact network reachability
For more information, see Status Checks for Your Instances (p. 547).
• Instance Status Checks - monitor the software and network configuration of your individual instance.
These checks detect problems that require your involvement to repair. When an instance status check
fails, typically you will need to address the problem yourself (for example, by rebooting the instance
or by making modifications in your operating system). Examples of problems that may cause instance
status checks to fail include:
• Failed system status checks
• Misconfigured networking or startup configuration
• Exhausted memory
• Corrupted file system
• Incompatible kernel
For more information, see Status Checks for Your Instances (p. 547).
• Amazon CloudWatch Alarms - watch a single metric over a time period you specify, and perform
one or more actions based on the value of the metric relative to a given threshold over a number
of time periods. The action is a notification sent to an Amazon Simple Notification Service (Amazon
SNS) topic or Amazon EC2 Auto Scaling policy. Alarms invoke actions for sustained state changes only.
CloudWatch alarms will not invoke actions simply because they are in a particular state; the state
545
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Manual Monitoring Tools
must have changed and been maintained for a specified number of periods. For more information, see
Monitoring Your Instances Using CloudWatch (p. 558).
• Amazon CloudWatch Events - automate your AWS services and respond automatically to system
events. Events from AWS services are delivered to CloudWatch Events in near real time, and you can
specify automated actions to take when an event matches a rule you write. For more information, see
What is Amazon CloudWatch Events?.
• Amazon CloudWatch Logs - monitor, store, and access your log files from Amazon EC2 instances, AWS
CloudTrail, or other sources. For more information, see the Amazon CloudWatch Logs User Guide.
• Amazon EC2 Monitoring Scripts - Perl scripts that can monitor memory, disk, and swap file usage in
your instances. For more information, see Monitoring Memory and Disk Metrics for Amazon EC2 Linux
Instances.
• AWS Management Pack for Microsoft System Center Operations Manager - links Amazon EC2
instances and the Windows or Linux operating systems running inside them. The AWS Management
Pack is an extension to Microsoft System Center Operations Manager. It uses a designated computer in
your datacenter (called a watcher node) and the Amazon Web Services APIs to remotely discover and
collect information about your AWS resources. For more information, see AWS Management Pack for
Microsoft System Center.
• Make monitoring a priority to head off small problems before they become big ones.
546
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Monitoring the Status of Your Instances
• Create and implement a monitoring plan that collects monitoring data from all of the parts in your
AWS solution so that you can more easily debug a multi-point failure if one occurs. Your monitoring
plan should address, at a minimum, the following questions:
• What are your goals for monitoring?
• What resources you will monitor?
• How often you will monitor these resources?
• What monitoring tools will you use?
• Who will perform the monitoring tasks?
• Who should be notified when something goes wrong?
• Automate monitoring tasks as much as possible.
• Check the log files on your EC2 instances.
You can also see status on specific events scheduled for your instances. Events provide information about
upcoming activities such as rebooting or retirement that are planned for your instances, along with the
scheduled start and end time of each event.
Contents
• Status Checks for Your Instances (p. 547)
• Scheduled Events for Your Instances (p. 552)
Status checks are performed every minute and each returns a pass or a fail status. If all checks pass,
the overall status of the instance is OK. If one or more checks fail, the overall status is impaired. Status
checks are built into Amazon EC2, so they cannot be disabled or deleted. You can, however, create or
delete alarms that are triggered based on the result of the status checks. For example, you can create
an alarm to warn you if status checks fail on a specific instance. For more information, see Creating and
Editing Status Check Alarms (p. 550).
You can also create an Amazon CloudWatch alarm that monitors an Amazon EC2 instance and
automatically recovers the instance if it becomes impaired due to an underlying issue. For more
information, see Recover Your Instance (p. 485).
Contents
• Types of Status Checks (p. 548)
547
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Status Checks
Monitor the AWS systems on which your instance runs. These checks detect underlying problems with
your instance that require AWS involvement to repair. When a system status check fails, you can choose
to wait for AWS to fix the issue, or you can resolve it yourself. For instances backed by Amazon EBS, you
can stop and start the instance yourself, which in most cases migrates it to a new host. For instances
backed by instance store, you can terminate and replace the instance.
The following are examples of problems that can cause system status checks to fail:
Monitor the software and network configuration of your individual instance. Amazon EC2 checks the
health of the instance by sending an address resolution protocol (ARP) request to the ENI. These checks
detect problems that require your involvement to repair. When an instance status check fails, typically
you will need to address the problem yourself (for example, by rebooting the instance or by making
instance configuration changes).
The following are examples of problems that can cause instance status checks to fail:
548
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Status Checks
3. On the Instances page, the Status Checks column lists the operational status of each instance.
4. To view the status of a specific instance, select the instance, and then choose the Status Checks tab.
5. If you have an instance with a failed status check and the instance has been unreachable for over
20 minutes, choose AWS Support to submit a request for assistance. To troubleshoot system
or instance status check failures yourself, see Troubleshooting Instances with Failed Status
Checks (p. 1029).
To get the status of all instances with an instance status of impaired, use the following command:
If you have an instance with a failed status check, see Troubleshooting Instances with Failed Status
Checks (p. 1029).
We use reported feedback to identify issues impacting multiple customers, but do not respond to
individual account issues. Providing feedback does not change the status check results that you currently
see for the instance.
549
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Status Checks
550
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Status Checks
Important
If you added an email address to the list of recipients or created a new topic, Amazon SNS
sends a subscription confirmation email message to each new address. Each recipient must
confirm the subscription by choosing the link contained in that message. Alert notifications
are sent only to confirmed addresses.
If you need to make changes to an instance status alarm, you can edit it.
1. Select an existing SNS topic or create a new one. For more information, see Using the AWS CLI with
Amazon SNS in the AWS Command Line Interface User Guide.
2. Use the following list-metrics command to view the available Amazon CloudWatch metrics for
Amazon EC2:
Note
• --period is the time frame, in seconds, in which Amazon CloudWatch metrics are collected. This
example uses 300, which is 60 seconds multiplied by 5 minutes.
• --evaluation-periods is the number of consecutive periods for which the value of the metric
must be compared to the threshold. This example uses 2.
• --alarm-actions is the list of actions to perform when this alarm is triggered. Each action is
specified as an Amazon Resource Name (ARN). This example configures the alarm to send an email
using Amazon SNS.
551
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Scheduled Events
To update the contact information for your account so that you can be sure to be notified about
scheduled events, go to the Account Settings page.
Contents
• Types of Scheduled Events (p. 552)
• Viewing Scheduled Events (p. 552)
• Working with Instances Scheduled to Stop or Retire (p. 555)
• Working with Instances Scheduled for Reboot (p. 555)
• Working with Instances Scheduled for Maintenance (p. 558)
• Instance stop: The instance will be stopped. When you start it again, it's migrated to a new host.
Applies only to instances backed by Amazon EBS.
• Instance retirement: The instance will be stopped if it is backed by Amazon EBS, or terminated if it is
backed by instance store.
• Instance reboot: The instance will be rebooted.
• System reboot: The host for the instance will be rebooted.
• System maintenance: The instance might be temporarily affected by network maintenance or power
maintenance.
552
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Scheduled Events
3. Alternatively, in the navigation pane, choose EC2 Dashboard. Any resources with an associated event
are displayed under Scheduled Events.
4. Some events are also shown for affected resources. For example, in the navigation pane, choose
Instances and select an instance. If the instance has an associated instance stop or instance
retirement event, it is displayed in the lower pane.
To view scheduled events for your instances using the AWS CLI
[
"Events": [
{
"InstanceEventId": "instance-event-0d59937288b749b32",
"Code": "system-reboot",
"Description": "The instance is scheduled for a reboot",
"NotAfter": "2019-03-15T22:00:00.000Z",
"NotBefore": "2019-03-14T20:00:00.000Z",
"NotBeforeDeadline": "2019-04-05T11:00:00.000Z"
}
]
]
[
"Events": [
{
553
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Scheduled Events
"InstanceEventId": "instance-event-0e439355b779n26",
"Code": "instance-stop",
"Description": "The instance is running on degraded hardware",
"NotBefore": "2015-05-23T00:00:00.000Z"
}
]
]
To view scheduled events for your instances using the AWS Tools for Windows PowerShell
Code : instance-stop
Description : The instance is running on degraded hardware
NotBefore : 5/23/2015 12:00:00 AM
• You can retrieve information about active maintenance events for your instances from the instance
metadata (p. 526) as follows:
The following is example output with information about a scheduled system reboot event, in JSON
format.
[
{
"NotBefore" : "21 Jan 2019 09:00:43 GMT",
"Code" : "system-reboot",
"Description" : "scheduled reboot",
"EventId" : "instance-event-0d59937288b749b32",
"NotAfter" : "21 Jan 2019 09:17:23 GMT",
"State" : "active"
}
]
To view event history about completed or canceled events for your instances using instance
metadata
• You can retrieve information about completed or canceled events for your instances from the
instance metadata (p. 526) as follows:
The following is example output with information about a system reboot event that was canceled
and a system reboot event that was completed, in JSON format.
554
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Scheduled Events
[
{
"NotBefore" : "21 Jan 2019 09:00:43 GMT",
"Code" : "system-reboot",
"Description" : "[Canceled] scheduled reboot",
"EventId" : "instance-event-0d59937288b749b32",
"NotAfter" : "21 Jan 2019 09:17:23 GMT",
"State" : "canceled"
},
{
"NotBefore" : "29 Jan 2019 09:00:43 GMT",
"Code" : "system-reboot",
"Description" : "[Completed] scheduled reboot",
"EventId" : "instance-event-0d59937288b749b32",
"NotAfter" : "29 Jan 2019 09:17:23 GMT",
"State" : "completed"
}
]
You can wait for the instance to stop as scheduled. Alternatively, you can stop and start the instance
yourself, which migrates it to a new host. For more information about stopping your instance, in addition
to information about the changes to your instance configuration when it's stopped, see Stop and Start
Your Instance (p. 468).
You can automate an immediate stop and start in response to a scheduled instance stop event. For more
information, see Automating Actions for EC2 Instances in the AWS Health User Guide.
We recommend that you launch a replacement instance from your most recent AMI and migrate all
necessary data to the replacement instance before the instance is scheduled to terminate. Then, you can
terminate the original instance, or wait for it to terminate as scheduled.
555
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Scheduled Events
For scheduled reboot events, the value for Code is either system-reboot or instance-reboot.
The following example output shows a system-reboot event:
[
"Events": [
{
"InstanceEventId": "instance-event-0d59937288b749b32",
"Code": "system-reboot",
"Description": "The instance is scheduled for a reboot",
"NotAfter": "2019-03-14T22:00:00.000Z",
"NotBefore": "2019-03-14T20:00:00.000Z",
"NotBeforeDeadline": "2019-04-05T11:00:00.000Z"
}
]
]
You can wait for the instance reboot to occur within its scheduled maintenance window,
reschedule (p. 557) the instance reboot to a date and time that suits you, or reboot (p. 476) the
instance yourself at a time that is convenient for you.
After your instance is rebooted, the scheduled event is cleared and the event's description is updated.
The pending maintenance to the underlying host is completed, and you can begin using your instance
again after it has fully booted.
It is not possible for you to reboot the system yourself. You can wait for the system reboot to occur
during its scheduled maintenance window, or you can reschedule (p. 557) the system reboot to a date
and time that suits you. A system reboot typically completes in a matter of minutes. After the system
reboot has occurred, the instance retains its IP address and DNS name, and any data on local instance
store volumes is preserved. After the system reboot is complete, the scheduled event for the instance is
cleared, and you can verify that the software on your instance is operating as expected.
Alternatively, if it is necessary to maintain the instance at a different time and you can't reschedule the
system reboot, then you can stop and start an Amazon EBS-backed instance, which migrates it to a new
host. However, the data on the local instance store volumes is not preserved. You can also automate
an immediate instance stop and start in response to a scheduled system reboot event. For more
information, see Automating Actions for EC2 Instances in the AWS Health User Guide. For an instance
store-backed instance, if you can't reschedule the system reboot, then you can launch a replacement
instance from your most recent AMI, migrate all necessary data to the replacement instance before the
scheduled maintenance window, and then terminate the original instance.
556
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Scheduled Events
1. Only events that have an event deadline date, indicated by a value for NotBeforeDeadline,
can be rescheduled. Use the following describe-instance-status command to view the
NotBeforeDeadline parameter value:
The following example output shows a system-reboot event that can be rescheduled because
NotBeforeDeadline contains a value:
[
"Events": [
{
"InstanceEventId": "instance-event-0d59937288b749b32",
"Code": "system-reboot",
"Description": "The instance is scheduled for a reboot",
"NotAfter": "2019-03-14T22:00:00.000Z",
"NotBefore": "2019-03-14T20:00:00.000Z",
"NotBeforeDeadline": "2019-04-05T11:00:00.000Z"
}
]
]
2. To reschedule the event, use the modify-instance-event-start-time command. Specify the new
event start time using the not-before parameter. The new event start time must fall before the
NotBeforeDeadline.
Note
It might take 1-2 minutes before the describe-instance-status command returns the
updated not-before parameter value.
557
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Monitoring Your Instances Using CloudWatch
• Only reboot events with an event deadline date can be rescheduled. The event can be rescheduled up
to the event deadline date. The Event Deadline column in the console and the NotBeforeDeadline
field in the AWS CLI indicate if the event has a deadline date.
• Only reboot events that have not yet started can be rescheduled. The Start Time column in the
console and the NotBefore field in the AWS CLI indicate the event start time. Reboot events that are
scheduled to start in the next 5 minutes cannot be rescheduled.
• The new event start time must be at least 60 minutes from the current time.
• If you reschedule multiple events using the console, the event deadline date is determined by the
event with earliest event deadline date.
During network maintenance, scheduled instances lose network connectivity for a brief period of time.
Normal network connectivity to your instance will be restored after maintenance is complete.
During power maintenance, scheduled instances are taken offline for a brief period, and then rebooted.
When a reboot is performed, all of your instance's configuration settings are retained.
After your instance has rebooted (this normally takes a few minutes), verify that your application is
working as expected. At this point, your instance should no longer have a scheduled event associated
with it, or the description of the scheduled event begins with [Completed]. It sometimes takes up to 1
hour for the instance status description to refresh. Completed maintenance events are displayed on the
Amazon EC2 console dashboard for up to a week.
You can wait for the maintenance to occur as scheduled. Alternatively, you can stop and start the
instance, which migrates it to a new host. For more information about stopping your instance, in addition
to information about the changes to your instance configuration when it's stopped, see Stop and Start
Your Instance (p. 468).
You can automate an immediate stop and start in response to a scheduled maintenance event. For more
information, see Automating Actions for EC2 Instances in the AWS Health User Guide.
You can wait for the maintenance to occur as scheduled. Alternatively, if you want to maintain normal
operation during a scheduled maintenance window, you can launch a replacement instance from
your most recent AMI, migrate all necessary data to the replacement instance before the scheduled
maintenance window, and then terminate the original instance.
By default, Amazon EC2 sends metric data to CloudWatch in 5-minute periods. To send metric data for
your instance to CloudWatch in 1-minute periods, you can enable detailed monitoring on the instance.
For more information, see Enable or Disable Detailed Monitoring for Your Instances (p. 559).
558
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Enable Detailed Monitoring
The Amazon EC2 console displays a series of graphs based on the raw data from Amazon CloudWatch.
Depending on your needs, you might prefer to get data for your instances from Amazon CloudWatch
instead of the graphs in the console.
For more information about Amazon CloudWatch, see the Amazon CloudWatch User Guide.
Contents
• Enable or Disable Detailed Monitoring for Your Instances (p. 559)
• List the Available CloudWatch Metrics for Your Instances (p. 560)
• Get Statistics for Metrics for Your Instances (p. 569)
• Graph Metrics for Your Instances (p. 576)
• Create a CloudWatch Alarm for an Instance (p. 576)
• Create Alarms That Stop, Terminate, Reboot, or Recover an Instance (p. 577)
559
Amazon Elastic Compute Cloud
User Guide for Linux Instances
List Available Metrics
When launching an instance using the AWS Management Console, select the Monitoring check box on
the Configure Instance Details page.
Use the following monitor-instances command to enable detailed monitoring for the specified instances.
Use the run-instances command with the --monitoring flag to enable detailed monitoring.
Use the following unmonitor-instances command to disable detailed monitoring for the specified
instances.
For information about getting the statistics for these metrics, see Get Statistics for Metrics for Your
Instances (p. 569).
Instance Metrics
The AWS/EC2 namespace includes the following CPU credit metrics for your burstable performance
instances (p. 192).
560
Amazon Elastic Compute Cloud
User Guide for Linux Instances
List Available Metrics
Metric Description
CPUCreditUsage The number of CPU credits spent by the instance for CPU
utilization. One CPU credit equals one vCPU running at 100%
utilization for one minute or an equivalent combination of vCPUs,
utilization, and time (for example, one vCPU running at 50%
utilization for two minutes or two vCPUs running at 25% utilization
for two minutes).
Credits are accrued in the credit balance after they are earned,
and removed from the credit balance when they are spent. The
credit balance has a maximum limit, determined by the instance
size. After the limit is reached, any new credits that are earned are
discarded. For T2 Standard, launch credits do not count towards the
limit.
CPUSurplusCreditsCharged The number of spent surplus credits that are not paid down by
earned CPU credits, and which thus incur an additional charge.
Spent surplus credits are charged when any of the following occurs:
561
Amazon Elastic Compute Cloud
User Guide for Linux Instances
List Available Metrics
Metric Description
• The spent surplus credits exceed the maximum number of credits
that the instance can earn in a 24-hour period. Spent surplus
credits above the maximum are charged at the end of the hour.
• The instance is stopped or terminated.
• The instance is switched from unlimited to standard.
Metric Description
CPUUtilization The percentage of allocated EC2 compute units that are currently
in use on the instance. This metric identifies the processing power
required to run an application upon a selected instance.
Units: Percent
To calculate the average I/O operations per second (IOPS) for the
period, divide the total operations in the period by the number of
seconds in that period.
Units: Count
To calculate the average I/O operations per second (IOPS) for the
period, divide the total operations in the period by the number of
seconds in that period.
Units: Count
DiskReadBytes Bytes read from all instance store volumes available to the instance.
562
Amazon Elastic Compute Cloud
User Guide for Linux Instances
List Available Metrics
Metric Description
can divide this number by 300 to find Bytes/second. If you have
detailed (one-minute) monitoring, divide it by 60.
Units: Bytes
DiskWriteBytes Bytes written to all instance store volumes available to the instance.
Units: Bytes
Units: Bytes
NetworkOut The number of bytes sent out on all network interfaces by the
instance. This metric identifies the volume of outgoing network
traffic from a single instance.
The number reported is the number of bytes sent during the period.
If you are using basic (five-minute) monitoring, you can divide this
number by 300 to find Bytes/second. If you have detailed (one-
minute) monitoring, divide it by 60.
Units: Bytes
Units: Count
563
Amazon Elastic Compute Cloud
User Guide for Linux Instances
List Available Metrics
Metric Description
NetworkPacketsOut The number of packets sent out on all network interfaces by the
instance. This metric identifies the volume of outgoing traffic in
terms of the number of packets on a single instance. This metric is
available for basic monitoring only.
Units: Count
The AWS/EC2 namespace includes the following status checks metrics. By default, status check metrics
are available at a 1-minute frequency at no charge. For a newly-launched instance, status check metric
data is only available after the instance has completed the initialization state (within a few minutes
of the instance entering the running state). For more information about EC2 status checks, see Status
Checks For Your Instances.
Metric Description
StatusCheckFailed Reports whether the instance has passed both the instance status
check and the system status check in the last minute.
Units: Count
StatusCheckFailed_Instance Reports whether the instance has passed the instance status check
in the last minute.
Units: Count
StatusCheckFailed_System Reports whether the instance has passed the system status check in
the last minute.
Units: Count
The AWS/EC2 namespace includes the following Amazon EBS metrics for the Nitro-based instances
that are not bare metal instances. For the list of Nitro-based instance types, see Nitro-based
Instances (p. 181).
Note
Metric values for Nitro-based instances will always be integers (whole numbers), whereas values
for Xen-based instances support decimals. Therefore, low instance CPU utilization on Nitro-
based instances may appear to be rounded down to 0.
564
Amazon Elastic Compute Cloud
User Guide for Linux Instances
List Available Metrics
Metric Description
Unit: Count
Unit: Count
Unit: Bytes
Unit: Bytes
Unit: Percent
565
Amazon Elastic Compute Cloud
User Guide for Linux Instances
List Available Metrics
Metric Description
Unit: Percent
For information about the metrics provided for your EBS volumes, see Amazon EBS Metrics (p. 942).
For information about the metrics provided for your Spot fleets, see CloudWatch Metrics for Spot
Fleet (p. 338).
Dimension Description
AutoScalingGroupName This dimension filters the data you request for all instances in a
specified capacity group. An Auto Scaling group is a collection of
instances you define if you're using Auto Scaling. This dimension is
available only for Amazon EC2 metrics when the instances are in
such an Auto Scaling group. Available for instances with Detailed or
Basic Monitoring enabled.
ImageId This dimension filters the data you request for all instances running
this Amazon EC2 Amazon Machine Image (AMI). Available for
instances with Detailed Monitoring enabled.
InstanceId This dimension filters the data you request for the identified
instance only. This helps you pinpoint an exact instance from which
to monitor data.
InstanceType This dimension filters the data you request for all instances
running with this specified instance type. This helps you categorize
your data by the type of instance running. For example, you
might compare data from an m1.small instance and an m1.large
instance to determine which has the better business value for
your application. Available for instances with Detailed Monitoring
enabled.
566
Amazon Elastic Compute Cloud
User Guide for Linux Instances
List Available Metrics
5. To sort the metrics, use the column heading. To graph a metric, select the check box next to the
metric. To filter by resource, choose the resource ID and then choose Add to search. To filter by
metric, choose the metric name and then choose Add to search.
567
Amazon Elastic Compute Cloud
User Guide for Linux Instances
List Available Metrics
To list all the available metrics for Amazon EC2 (AWS CLI)
The following example specifies the AWS/EC2 namespace to view all the metrics for Amazon EC2.
{
"Metrics": [
{
"Namespace": "AWS/EC2",
"Dimensions": [
{
"Name": "InstanceId",
"Value": "i-1234567890abcdef0"
}
],
"MetricName": "NetworkOut"
},
{
"Namespace": "AWS/EC2",
"Dimensions": [
{
"Name": "InstanceId",
"Value": "i-1234567890abcdef0"
}
],
"MetricName": "CPUUtilization"
},
{
"Namespace": "AWS/EC2",
"Dimensions": [
{
"Name": "InstanceId",
"Value": "i-1234567890abcdef0"
568
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Get Statistics for Metrics
}
],
"MetricName": "NetworkIn"
},
...
]
}
The following example specifies the AWS/EC2 namespace and the InstanceId dimension to view the
results for the specified instance only.
The following example specifies the AWS/EC2 namespace and a metric name to view the results for the
specified metric only.
Contents
• Statistics Overview (p. 569)
• Get Statistics for a Specific Instance (p. 570)
• Aggregate Statistics Across Instances (p. 572)
• Aggregate Statistics by Auto Scaling Group (p. 574)
• Aggregate Statistics by AMI (p. 575)
Statistics Overview
Statistics are metric data aggregations over specified periods of time. CloudWatch provides statistics
based on the metric data points provided by your custom data or provided by other services in AWS to
CloudWatch. Aggregations are made using the namespace, metric name, dimensions, and the data point
unit of measure, within the time period you specify. The following table describes the available statistics.
Statistic Description
Minimum The lowest value observed during the specified period. You can use this value to
determine low volumes of activity for your application.
Maximum The highest value observed during the specified period. You can use this value to
determine high volumes of activity for your application.
Sum All values submitted for the matching metric added together. This statistic can be
useful for determining the total volume of a metric.
Average The value of Sum / SampleCount during the specified period. By comparing this
statistic with the Minimum and Maximum, you can determine the full scope of a metric
569
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Get Statistics for Metrics
Statistic Description
and how close the average use is to the Minimum and Maximum. This comparison
helps you to know when to increase or decrease your resources as needed.
SampleCount The count (number) of data points used for the statistical calculation.
pNN.NN The value of the specified percentile. You can specify any percentile, using up to two
decimal places (for example, p95.45).
Requirements
• You must have the ID of the instance. You can get the instance ID using the AWS Management Console
or the describe-instances command.
• By default, basic monitoring is enabled, but you can enable detailed monitoring. For more information,
see Enable or Disable Detailed Monitoring for Your Instances (p. 559).
570
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Get Statistics for Metrics
5. In the search field, enter CPUUtilization and press Enter. Choose the row for the specific
instance, which displays a graph for the CPUUtilization metric for the instance. To name the graph,
choose the pencil icon. To change the time range, select one of the predefined values or choose
custom.
6. To change the statistic or the period for the metric, choose the Graphed metrics tab. Choose the
column heading or an individual value, and then choose a different value.
571
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Get Statistics for Metrics
Use the following get-metric-statistics command to get the CPUUtilization metric for the specified
instance, using the specified period and time interval:
The following is example output. Each value represents the maximum CPU utilization percentage for a
single EC2 instance.
{
"Datapoints": [
{
"Timestamp": "2016-10-19T00:18:00Z",
"Maximum": 0.33000000000000002,
"Unit": "Percent"
},
{
"Timestamp": "2016-10-19T03:18:00Z",
"Maximum": 99.670000000000002,
"Unit": "Percent"
},
{
"Timestamp": "2016-10-19T07:18:00Z",
"Maximum": 0.34000000000000002,
"Unit": "Percent"
},
{
"Timestamp": "2016-10-19T12:18:00Z",
"Maximum": 0.34000000000000002,
"Unit": "Percent"
},
...
],
"Label": "CPUUtilization"
}
572
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Get Statistics for Metrics
can get statistics aggregated across instances, you must enable detailed monitoring (at an additional
charge), which provides data in 1-minute periods.
This example shows you how to use detailed monitoring to get the average CPU usage for your EC2
instances. Because no dimension is specified, CloudWatch returns statistics for all dimensions in the AWS/
EC2 namespace.
Important
This technique for retrieving all dimensions across an AWS namespace does not work for custom
namespaces that you publish to Amazon CloudWatch. With custom namespaces, you must
specify the complete set of dimensions that are associated with any given data point to retrieve
statistics that include the data point.
5. To change the statistic or the period for the metric, choose the Graphed metrics tab. Choose the
column heading or an individual value, and then choose a different value.
Use the get-metric-statistics command as follows to get the average of the CPUUtilization metric across
your instances.
573
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Get Statistics for Metrics
{
"Datapoints": [
{
"SampleCount": 238.0,
"Timestamp": "2016-10-12T07:18:00Z",
"Average": 0.038235294117647062,
"Unit": "Percent"
},
{
"SampleCount": 240.0,
"Timestamp": "2016-10-12T09:18:00Z",
"Average": 0.16670833333333332,
"Unit": "Percent"
},
{
"SampleCount": 238.0,
"Timestamp": "2016-10-11T23:18:00Z",
"Average": 0.041596638655462197,
"Unit": "Percent"
},
...
],
"Label": "CPUUtilization"
}
This example shows you how to retrieve the total bytes written to disk for one Auto Scaling group. The
total is computed for one-minute periods for a 24-hour interval across all EC2 instances in the specified
Auto Scaling group.
To display DiskWriteBytes for the instances in an Auto Scaling group (AWS CLI)
{
"Datapoints": [
{
574
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Get Statistics for Metrics
"SampleCount": 18.0,
"Timestamp": "2016-10-19T21:36:00Z",
"Sum": 0.0,
"Unit": "Bytes"
},
{
"SampleCount": 5.0,
"Timestamp": "2016-10-19T21:42:00Z",
"Sum": 0.0,
"Unit": "Bytes"
}
],
"Label": "DiskWriteBytes"
}
Before you can get statistics aggregated across instances, you must enable detailed monitoring (at an
additional charge), which provides data in 1-minute periods. For more information, see Enable or Disable
Detailed Monitoring for Your Instances (p. 559).
This example shows you how to determine average CPU utilization for all instances that use a specific
Amazon Machine Image (AMI). The average is over 60-second time intervals for a one-day period.
The following is example output. Each value represents an average CPU utilization percentage for the
EC2 instances running the specified AMI.
{
"Datapoints": [
{
"Timestamp": "2016-10-10T07:00:00Z",
"Average": 0.041000000000000009,
"Unit": "Percent"
},
{
575
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Graph Metrics
"Timestamp": "2016-10-10T14:00:00Z",
"Average": 0.079579831932773085,
"Unit": "Percent"
},
{
"Timestamp": "2016-10-10T06:00:00Z",
"Average": 0.036000000000000011,
"Unit": "Percent"
},
...
],
"Label": "CPUUtilization"
}
For more information about the metrics and the data they provide to the graphs, see List the Available
CloudWatch Metrics for Your Instances (p. 560).
You can also use the CloudWatch console to graph metric data generated by Amazon EC2 and other AWS
services. For more information, see Graph Metrics in the Amazon CloudWatch User Guide.
For examples, see Creating Amazon CloudWatch Alarms in the Amazon CloudWatch User Guide.
576
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Create Alarms That Stop, Terminate,
Reboot, or Recover an Instance
4. On the Monitoring tab, choose Create Alarm.
5. In the Create Alarm dialog box, do the following:
a. Choose create topic. For Send a notification to, enter a name for the SNS topic. For With these
recipients, enter one or more email addresses to receive notification.
b. Specify the metric and the criteria for the policy. For example, you can leave the default settings
for Whenever (Average of CPU Utilization). For Is, choose >= and enter 80 percent. For For at
least, enter 1 consecutive period of 5 Minutes.
c. Choose Create Alarm.
There are a number of scenarios in which you might want to automatically stop or terminate your
instance. For example, you might have instances dedicated to batch payroll processing jobs or scientific
computing tasks that run for a period of time and then complete their work. Rather than letting those
instances sit idle (and accrue charges), you can stop or terminate them, which can help you to save
money. The main difference between using the stop and the terminate alarm actions is that you can
easily restart a stopped instance if you need to run it again later, and you can keep the same instance
ID and root volume. However, you cannot restart a terminated instance. Instead, you must launch a new
instance.
577
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Create Alarms That Stop, Terminate,
Reboot, or Recover an Instance
You can add the stop, terminate, reboot, or recover actions to any alarm that is set on an Amazon EC2
per-instance metric, including basic and detailed monitoring metrics provided by Amazon CloudWatch
(in the AWS/EC2 namespace), as well as any custom metrics that include the InstanceId dimension, as
long as its value refers to a valid running Amazon EC2 instance.
Console Support
You can create alarms using the Amazon EC2 console or the CloudWatch console. The procedures in
this documentation use the Amazon EC2 console. For procedures that use the CloudWatch console, see
Create Alarms That Stop, Terminate, Reboot, or Recover an Instance in the Amazon CloudWatch User
Guide.
Permissions
If you are an AWS Identity and Access Management (IAM) user, you must have the following permissions
to create or modify an alarm:
If you have read/write permissions for Amazon CloudWatch but not for Amazon EC2, you can still create
an alarm but the stop or terminate actions won't be performed on the Amazon EC2 instance. However, if
you are later granted permission to use the associated Amazon EC2 APIs, the alarm actions you created
earlier are performed. For more information about IAM permissions, see Permissions and Policies in the
IAM User Guide.
Contents
• Adding Stop Actions to Amazon CloudWatch Alarms (p. 578)
• Adding Terminate Actions to Amazon CloudWatch Alarms (p. 579)
• Adding Reboot Actions to Amazon CloudWatch Alarms (p. 580)
• Adding Recover Actions to Amazon CloudWatch Alarms (p. 581)
• Using the Amazon CloudWatch Console to View Alarm and Action History (p. 582)
• Amazon CloudWatch Alarm Action Scenarios (p. 582)
Instances that use an Amazon EBS volume as the root device can be stopped or terminated, whereas
instances that use the instance store as the root device can only be terminated.
578
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Create Alarms That Stop, Terminate,
Reboot, or Recover an Instance
3. Select the instance. On the Monitoring tab, choose Create Alarm.
4. In the Create Alarm dialog box, do the following:
a. To receive an email when the alarm is triggered, for Send a notification to, choose an existing
Amazon SNS topic, or choose create topic to create a new one.
To create a new topic, for Send a notification to, enter a name for the topic, and then for With
these recipients, enter the email addresses of the recipients (separated by commas). After you
create the alarm, you will receive a subscription confirmation email that you must accept before
you can get notifications for this topic.
b. Choose Take the action, Stop this instance.
c. For Whenever, choose the statistic you want to use and then choose the metric. In this example,
choose Average and CPU Utilization.
d. For Is, specify the metric threshold. In this example, enter 10 percent.
e. For For at least, specify the evaluation period for the alarm. In this example, enter 24
consecutive period(s) of 1 Hour.
f. To change the name of the alarm, for Name of alarm, enter a new name. Alarm names must
contain only ASCII characters.
If you don't enter a name for the alarm, Amazon CloudWatch automatically creates one for you.
Note
You can adjust the alarm configuration based on your own requirements before
creating the alarm, or you can edit them later. This includes the metric, threshold,
duration, action, and notification settings. However, after you create an alarm, you
cannot edit its name later.
g. Choose Create Alarm.
a. To receive an email when the alarm is triggered, for Send a notification to, choose an existing
Amazon SNS topic, or choose create topic to create a new one.
To create a new topic, for Send a notification to, enter a name for the topic, and then for With
these recipients, enter the email addresses of the recipients (separated by commas). After you
create the alarm, you will receive a subscription confirmation email that you must accept before
you can get notifications for this topic.
b. Choose Take the action, Terminate this instance.
c. For Whenever, choose a statistic and then choose the metric. In this example, choose Average
and CPU Utilization.
579
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Create Alarms That Stop, Terminate,
Reboot, or Recover an Instance
d. For Is, specify the metric threshold. In this example, enter 10 percent.
e. For For at least, specify the evaluation period for the alarm. In this example, enter 24
consecutive period(s) of 1 Hour.
f. To change the name of the alarm, for Name of alarm, enter a new name. Alarm names must
contain only ASCII characters.
If you don't enter a name for the alarm, Amazon CloudWatch automatically creates one for you.
Note
You can adjust the alarm configuration based on your own requirements before
creating the alarm, or you can edit them later. This includes the metric, threshold,
duration, action, and notification settings. However, after you create an alarm, you
cannot edit its name later.
g. Choose Create Alarm.
Rebooting an instance doesn't start a new instance billing period (with a minimum one-minute charge),
unlike stopping and restarting your instance. For more information, see Reboot Your Instance in the
Amazon EC2 User Guide for Linux Instances.
Important
To avoid a race condition between the reboot and recover actions, avoid setting the same
number of evaluation periods for a reboot alarm and a recover alarm. We recommend that you
set reboot alarms to three evaluation periods of one minute each. For more information, see
Evaluating an Alarm in the Amazon CloudWatch User Guide.
a. To receive an email when the alarm is triggered, for Send a notification to, choose an existing
Amazon SNS topic, or choose create topic to create a new one.
To create a new topic, for Send a notification to, enter a name for the topic, and for With these
recipients, enter the email addresses of the recipients (separated by commas). After you create
the alarm, you will receive a subscription confirmation email that you must accept before you
can get notifications for this topic.
b. Select Take the action, Reboot this instance.
c. For Whenever, choose Status Check Failed (Instance).
d. For For at least, specify the evaluation period for the alarm. In this example, enter 3 consecutive
period(s) of 1 Minute.
e. To change the name of the alarm, for Name of alarm, enter a new name. Alarm names must
contain only ASCII characters.
If you don't enter a name for the alarm, Amazon CloudWatch automatically creates one for you.
580
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Create Alarms That Stop, Terminate,
Reboot, or Recover an Instance
f. Choose Create Alarm.
CloudWatch prevents you from adding a recovery action to an alarm that is on an instance which does
not support recovery actions.
When the StatusCheckFailed_System alarm is triggered, and the recover action is initiated, you are
notified by the Amazon SNS topic that you chose when you created the alarm and associated the recover
action. During instance recovery, the instance is migrated during an instance reboot, and any data that
is in-memory is lost. When the process is complete, information is published to the SNS topic you've
configured for the alarm. Anyone who is subscribed to this SNS topic receives an email notification that
includes the status of the recovery attempt and any further instructions. You notice an instance reboot
on the recovered instance.
The recover action can be used only with StatusCheckFailed_System, not with
StatusCheckFailed_Instance.
The recover action is supported only on instances with the following characteristics:
• Use one of the following instance types: A1, C3, C4, C5, C5n, M3, M4, M5, M5a, P3, R3, R4, R5, R5a, T2,
T3, T3a, X1, or X1e
• Use default or dedicated instance tenancy
• Use EBS volumes only (do not configure instance store volumes). For more information, see 'Recover
this instance' is disabled.
If your instance has a public IP address, it retains the public IP address after recovery.
Important
To avoid a race condition between the reboot and recover actions, avoid setting the same
number of evaluation periods for a reboot alarm and a recover alarm. We recommend that you
set recover alarms to two evaluation periods of one minute each. For more information, see
Evaluating an Alarm in the Amazon CloudWatch User Guide.
581
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Create Alarms That Stop, Terminate,
Reboot, or Recover an Instance
a. To receive an email when the alarm is triggered, for Send a notification to, choose an existing
Amazon SNS topic, or choose create topic to create a new one.
To create a new topic, for Send a notification to, enter a name for the topic, and for With these
recipients, enter the email addresses of the recipients (separated by commas). After you create
the alarm, you will receive a subscription confirmation email that you must accept before you
can get email for this topic.
Note
• Users must subscribe to the specified SNS topic to receive email notifications when
the alarm is triggered.
• The AWS account root user always receives email notifications when automatic
instance recovery actions occur, even if an SNS topic is not specified.
• The AWS account root user always receives email notifications when automatic
instance recovery actions occur, even if it is not subscribed to the specified SNS topic.
b. Select Take the action, Recover this instance.
c. For Whenever, choose Status Check Failed (System).
d. For For at least, specify the evaluation period for the alarm. In this example, enter 2 consecutive
period(s) of 1 Minute.
e. To change the name of the alarm, for Name of alarm, enter a new name. Alarm names must
contain only ASCII characters.
If you don't enter a name for the alarm, Amazon CloudWatch automatically creates one for you.
f. Choose Create Alarm.
582
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Create Alarms That Stop, Terminate,
Reboot, or Recover an Instance
Setting Value
1 Stop
2 Maximum
3 CPUUtilization
4 <=
5 10%
6 60 minutes
7 1
Setting Value
2 Average
583
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Create Alarms That Stop, Terminate,
Reboot, or Recover an Instance
Setting Value
3 CPUUtilization
4 <=
5 5%
6 60 minutes
7 24
Scenario 3: Send Email About Web Servers with Unusually High Traffic
Create an alarm that sends email when an instance exceeds 10 GB of outbound network traffic per day.
Setting Value
1 Email
2 Sum
3 NetworkOut
4 >
5 10 GB
6 1 day
7 1
Setting Value
2 Sum
3 NetworkOut
4 >
5 1 GB
6 1 hour
7 1
584
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Create Alarms That Stop, Terminate,
Reboot, or Recover an Instance
Note
The MemoryUtilization metric is a custom metric. In order to use the MemoryUtilization metric,
you must install the Perl scripts for Linux instances. For more information, see Monitoring
Memory and Disk Metrics for Amazon EC2 Linux Instances.
Setting Value
1 Stop
2 Maximum
3 MemoryUtilization
4 >=
5 90%
6 1 minute
7 1
Setting Value
1 Stop
2 Average
3 StatusCheckFailed_System
4 >=
5 1
6 15 minutes
7 1
Setting Value
1 Terminate
2 Maximum
3 NetworkOut
4 <=
585
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Automating Amazon EC2 with CloudWatch Events
Setting Value
5 100,000 bytes
6 5 minutes
7 1
For more information, see the Amazon CloudWatch Events User Guide.
The rest of this section is informational for customers who are still using the older Perl scripts for
monitoring. You can download these Amazon CloudWatch Monitoring Scripts for Linux from the AWS
sample code library.
586
Amazon Elastic Compute Cloud
User Guide for Linux Instances
CloudWatch Monitoring Scripts
Standard Amazon CloudWatch usage charges for custom metrics apply to your use of these scripts. For
more information, see the Amazon CloudWatch pricing page.
Contents
• Supported Systems (p. 587)
• Package Contents (p. 587)
• Prerequisites (p. 588)
• Getting Started (p. 589)
• mon-put-instance-data.pl (p. 590)
• mon-get-instance-stats.pl (p. 593)
• Viewing Your Custom Metrics in the Console (p. 594)
• Troubleshooting (p. 594)
Supported Systems
These monitoring scripts are intended for use with Amazon EC2 instances running Linux. The scripts have
been tested on instances using the following Amazon Machine Images (AMIs), both 32-bit and 64-bit
versions:
• Amazon Linux 2
• Amazon Linux AMI 2014.09.2 and later
• Red Hat Enterprise Linux 7.4 and 6.9
• SUSE Linux Enterprise Server 12
• Ubuntu Server 16.04 and 14.04
Note
On servers running SUSE Linux Enterprise Server 12, you may need to first download the perl-
Switch package. You can download and install this package with the following commands:
wget http://download.opensuse.org/repositories/devel:/languages:/perl/SLE_12_SP3/
noarch/perl-Switch-2.17-32.1.noarch.rpm
sudo rpm -i perl-Switch-2.17-32.1.noarch.rpm
You can also monitor memory and disk metrics on Amazon EC2 instances running Windows by sending
this data to CloudWatch Logs. For more information, see Sending Logs, Events, and Performance
Counters to Amazon CloudWatch in the Amazon EC2 User Guide for Windows Instances.
Package Contents
The package for the monitoring scripts contains the following files:
• CloudWatchClient.pm – Shared Perl module that simplifies calling Amazon CloudWatch from other
scripts.
587
Amazon Elastic Compute Cloud
User Guide for Linux Instances
CloudWatch Monitoring Scripts
• mon-put-instance-data.pl – Collects system metrics on an Amazon EC2 instance (memory, swap, disk
space utilization) and sends them to Amazon CloudWatch.
• mon-get-instance-stats.pl – Queries Amazon CloudWatch and displays the most recent utilization
statistics for the EC2 instance on which this script is executed.
• awscreds.template – File template for AWS credentials that stores your access key ID and secret access
key.
• LICENSE.txt – Text file containing the Apache 2.0 license.
• NOTICE.txt – Copyright notice.
Prerequisites
With some versions of Linux, you must install additional modules before the monitoring scripts will work.
1. Log on to your instance. For more information, see Connect to Your Linux Instance (p. 446).
2. At a command prompt, install packages as follows:
1. Log on to your instance. For more information, see Connect to Your Linux Instance (p. 446).
2. At a command prompt, install packages as follows:
sudo cpan
Press ENTER through the prompts until you see the following prompt:
cpan[1]>
4. At the CPAN prompt, run each of the below commands: run one command and it installs, and when
you return to the CPAN prompt, run the next command. Press ENTER like before when prompted to
continue through the process:
588
Amazon Elastic Compute Cloud
User Guide for Linux Instances
CloudWatch Monitoring Scripts
1. Log on to your instance. For more information, see Connect to Your Linux Instance (p. 446).
2. At a command prompt, install packages as follows:
1. Log on to your instance. For more information, see Connect to Your Linux Instance (p. 446).
2. At a command prompt, install packages as follows:
Ubuntu Server
You must configure your server as follows.
1. Log on to your instance. For more information, see Connect to Your Linux Instance (p. 446).
2. At a command prompt, install packages as follows:
Getting Started
The following steps show you how to download, uncompress, and configure the CloudWatch Monitoring
Scripts on an EC2 Linux instance.
1. At a command prompt, move to a folder where you want to store the monitoring scripts and run the
following command to download them:
curl https://aws-cloudwatch.s3.amazonaws.com/downloads/
CloudWatchMonitoringScripts-1.2.2.zip -O
2. Run the following commands to install the monitoring scripts you downloaded:
589
Amazon Elastic Compute Cloud
User Guide for Linux Instances
CloudWatch Monitoring Scripts
3. Ensure that the scripts have permission to perform CloudWatch operations using one of the
following options:
• If you associated an IAM role (instance profile) with your instance, verify that it grants
permissions to perform the following operations:
• cloudwatch:PutMetricData
• cloudwatch:GetMetricStatistics
• cloudwatch:ListMetrics
• ec2:DescribeTags
• Specify your AWS credentials in a credentials file. First, copy the awscreds.template file
included with the monitoring scripts to awscreds.conf as follows:
cp awscreds.template awscreds.conf
AWSAccessKeyId=my-access-key-id
AWSSecretKey=my-secret-access-key
For information about how to view your AWS credentials, see Understanding and Getting Your
Security Credentials in the Amazon Web Services General Reference.
mon-put-instance-data.pl
This script collects memory, swap, and disk space utilization data on the current system. It then makes a
remote call to Amazon CloudWatch to report the collected data as custom metrics.
Options
Name Description
--mem-used-incl-cache- If you include this option, memory currently used for cache and
buff buffers is counted as "used" when the metrics are reported for --
mem-util, --mem-used, and --mem-avail.
590
Amazon Elastic Compute Cloud
User Guide for Linux Instances
CloudWatch Monitoring Scripts
Name Description
--disk-path=/ --disk-path=/home
--disk-space-util Collects and sends the DiskSpaceUtilization metric for the selected
disks. The metric is reported in percentages.
Note that the disk utilization metrics calculated by this script differ
from the values calculated by the df -k -l command. If you find the
values from df -k -l more useful, you can change the calculations in
the script.
--disk-space-used Collects and sends the DiskSpaceUsed metric for the selected disks.
The metric is reported by default in gigabytes.
--disk-space-avail Collects and sends the DiskSpaceAvailable metric for the selected
disks. The metric is reported in gigabytes.
--disk-space- Specifies units in which to report disk space usage. If not specified,
units=UNITS disk space is reported in gigabytes. UNITS may be one of the
following: bytes, kilobytes, megabytes, gigabytes.
--aws-access-key- Specifies the AWS access key ID to use to identify the caller. Must be
id=VALUE used together with the --aws-secret-key option. Do not use this
option with the --aws-credential-file parameter.
--aws-secret-key=VALUE Specifies the AWS secret access key to use to sign the request to
CloudWatch. Must be used together with the --aws-access-key-
id option. Do not use this option with --aws-credential-file
parameter.
591
Amazon Elastic Compute Cloud
User Guide for Linux Instances
CloudWatch Monitoring Scripts
Name Description
--aws-iam-role=VALUE Specifies the IAM role used to provide AWS credentials. The value
=VALUE is required. If no credentials are specified, the default IAM
role associated with the EC2 instance is applied. Only one IAM role
can be used. If no IAM roles are found, or if more than one IAM role
is found, the script will return an error.
--aggregated[=only] Adds aggregated metrics for instance type, AMI ID, and overall
for the region. The value =only is optional; if specified, the script
reports only aggregated metrics.
--auto-scaling[=only] Adds aggregated metrics for the Auto Scaling group. The value
=only is optional; if specified, the script reports only Auto Scaling
metrics. The IAM policy associated with the IAM account or role
using the scripts need to have permissions to call the EC2 action
DescribeTags.
--verify Performs a test run of the script that collects the metrics, prepares
a complete HTTP request, but does not actually call CloudWatch
to report the data. This option also checks that credentials are
provided. When run in verbose mode, this option outputs the
metrics that will be sent to CloudWatch.
--from-cron Use this option when calling the script from cron. When this option
is used, all diagnostic output is suppressed, but error messages are
sent to the local system log of the user account.
Examples
The following examples assume that you provided an IAM role or awscreds.conf file. Otherwise, you
must provide credentials using the --aws-access-key-id and --aws-secret-key parameters for
these commands.
To collect all available memory metrics and send them to CloudWatch, counting cache and buffer
memory as used
592
Amazon Elastic Compute Cloud
User Guide for Linux Instances
CloudWatch Monitoring Scripts
crontab -e
2. Add the following command to report memory and disk space utilization to CloudWatch every five
minutes:
If the script encounters an error, the script will write the error message in the system log.
To collect aggregated metrics for an Auto Scaling group and send them to Amazon CloudWatch
without reporting individual instance metrics
To collect aggregated metrics for instance type, AMI ID and region, and send them to Amazon
CloudWatch without reporting individual instance metrics
mon-get-instance-stats.pl
This script queries CloudWatch for statistics on memory, swap, and disk space metrics within the time
interval provided using the number of most recent hours. This data is provided for the Amazon EC2
instance on which this script is executed.
Options
Name Description
--aws-access-key- Specifies the AWS access key ID to use to identify the caller. Must be
id=VALUE used together with the --aws-secret-key option. Do not use this
option with the --aws-credential-file option.
--aws-secret-key=VALUE Specifies the AWS secret access key to use to sign the request to
CloudWatch. Must be used together with the --aws-access-key-
id option. Do not use this option with --aws-credential-file
option.
--aws-iam-role=VALUE Specifies the IAM role used to provide AWS credentials. The value
=VALUE is required. If no credentials are specified, the default IAM
role associated with the EC2 instance is applied. Only one IAM role
can be used. If no IAM roles are found, or if more than one IAM role
is found, the script will return an error.
593
Amazon Elastic Compute Cloud
User Guide for Linux Instances
CloudWatch Monitoring Scripts
Name Description
--verify Performs a test run of the script. This option also checks that
credentials are provided.
Example
To get utilization statistics for the last 12 hours, run the following command:
./mon-get-instance-stats.pl --recent-hours=12
CPU Utilization
Average: 1.06%, Minimum: 0.00%, Maximum: 15.22%
Memory Utilization
Average: 6.84%, Minimum: 6.82%, Maximum: 6.89%
Swap Utilization
Average: N/A, Minimum: N/A, Maximum: N/A
Troubleshooting
The CloudWatchClient.pm module caches instance metadata locally. If you create an AMI from an
instance where you have run the monitoring scripts, any instances launched from the AMI within the
cache TTL (default: six hours, 24 hours for Auto Scaling groups) emit metrics using the instance ID of
the original instance. After the cache TTL time period passes, the script retrieves fresh data and the
monitoring scripts use the instance ID of the current instance. To immediately correct this, remove the
cached data using the following command:
rm /var/tmp/aws-mon/instance-id
594
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Logging API Calls with AWS CloudTrail
To learn more about CloudTrail, see the AWS CloudTrail User Guide.
For an ongoing record of events in your AWS account, including events for Amazon EC2 and Amazon
EBS, create a trail. A trail enables CloudTrail to deliver log files to an Amazon S3 bucket. By default, when
you create a trail in the console, the trail applies to all Regions. The trail logs events from all Regions in
the AWS partition and delivers the log files to the Amazon S3 bucket that you specify. Additionally, you
can configure other AWS services to further analyze and act upon the event data collected in CloudTrail
logs. For more information, see:
All Amazon EC2 and Amazon EBS actions are logged by CloudTrail and are documented in the Amazon
EC2 API Reference. For example, calls to the RunInstances, DescribeInstances, or CreateImage actions
generate entries in the CloudTrail log files.
Every event or log entry contains information about who generated the request. The identity
information helps you determine the following:
• Whether the request was made with root or IAM user credentials.
• Whether the request was made with temporary security credentials for a role or federated user.
• Whether the request was made by another AWS service.
595
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Understanding Amazon EC2 and
Amazon EBS Log File Entries
The following log file record shows that a user terminated an instance.
{
"Records":[
{
"eventVersion":"1.03",
"userIdentity":{
"type":"Root",
"principalId":"123456789012",
"arn":"arn:aws:iam::123456789012:root",
"accountId":"123456789012",
"accessKeyId":"AKIAIOSFODNN7EXAMPLE",
"userName":"user"
},
"eventTime":"2016-05-20T08:27:45Z",
"eventSource":"ec2.amazonaws.com",
"eventName":"TerminateInstances",
"awsRegion":"us-west-2",
"sourceIPAddress":"198.51.100.1",
"userAgent":"aws-cli/1.10.10 Python/2.7.9 Windows/7botocore/1.4.1",
"requestParameters":{
"instancesSet":{
"items":[{
"instanceId":"i-1a2b3c4d"
}]
}
},
"responseElements":{
"instancesSet":{
"items":[{
"instanceId":"i-1a2b3c4d",
"currentState":{
"code":32,
"name":"shutting-down"
},
"previousState":{
"code":16,
"name":"running"
}
}]
}
},
"requestID":"be112233-1ba5-4ae0-8e2b-1c302EXAMPLE",
"eventID":"6e12345-2a4e-417c-aa78-7594fEXAMPLE",
"eventType":"AwsApiCall",
"recipientAccountId":"123456789012"
}
]
}
596
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Auditing Users that Connect via EC2 Instance Connect
To audit SSH activity via EC2 Instance Connect using the AWS CloudTrail console
{
"eventVersion": "1.05",
"userIdentity": {
"type": "IAMUser",
"principalId": "ABCDEFGONGNOMOOCB6XYTQEXAMPLE",
"arn": "arn:aws:iam::1234567890120:user/IAM-friendly-name",
"accountId": "123456789012",
"accessKeyId": "ABCDEFGUKZHNAW4OSN2AEXAMPLE",
"userName": "IAM-friendly-name",
"sessionContext": {
"attributes": {
"mfaAuthenticated": "false",
"creationDate": "2018-09-21T21:37:58Z"}
}
},
"eventTime": "2018-09-21T21:38:00Z",
"eventSource": "ec2-instance-connect.amazonaws.com",
"eventName": "SendSSHPublicKey ",
"awsRegion": "us-west-2",
"sourceIPAddress": "123.456.789.012",
"userAgent": "aws-cli/1.15.61 Python/2.7.10 Darwin/16.7.0 botocore/1.10.60",
"requestParameters": {
"instanceId": "i-0123456789EXAMPLE",
"osUser": "ec2-user",
"SSHKey": {
"publicKey": "ssh-rsa ABCDEFGHIJKLMNO01234567890EXAMPLE"
}
"responseElements": null,
"requestID": "1a2s3d4f-bde6-11e8-a892-f7ec64543add",
"eventID": "1a2w3d4r5-a88f-4e28-b3bf-30161f75be34",
"eventType": "AwsApiCall",
"recipientAccountId": "0987654321"
}
If you have configured your AWS account to collect CloudTrail events in an S3 bucket, you can
download and audit the information programmatically. For more information, see Getting and
Viewing Your CloudTrail Log Files in the AWS CloudTrail User Guide.
597
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Key Pairs
Features
• Amazon EC2 Key Pairs (p. 598)
• Amazon EC2 Security Groups for Linux Instances (p. 607)
• Controlling Access to Amazon EC2 Resources (p. 621)
• Amazon EC2 Instance IP Addressing (p. 706)
• Bring Your Own IP Addresses (BYOIP) (p. 721)
• Elastic IP Addresses (p. 724)
• Elastic Network Interfaces (p. 729)
• Enhanced Networking on Linux (p. 750)
• Elastic Fabric Adapter (p. 775)
• Placement Groups (p. 784)
• Network Maximum Transmission Unit (MTU) for Your EC2 Instance (p. 793)
• Virtual Private Clouds (p. 795)
• EC2-Classic (p. 796)
When you launch an instance, you specify the key pair. You can specify an existing key pair or a new key
pair that you create at launch. At boot time, the public key content is placed on the instance in an entry
within ~/.ssh/authorized_keys. To log in to your instance, you must specify the private key when
you connect to the instance. For more information, see Launch Your Instance (p. 395) and Connect to
Your Linux Instance (p. 446)
You can use Amazon EC2 to create your key pair. For more information, see Creating a Key Pair Using
Amazon EC2 (p. 599).
Alternatively, you could use a third-party tool and then import the public key to Amazon EC2. For more
information, see Importing Your Own Public Key to Amazon EC2 (p. 600).
Each key pair requires a name. Be sure to choose a name that is easy to remember. Amazon EC2
associates the public key with the name that you specify as the key name.
Amazon EC2 stores the public key only, and you store the private key. Anyone who possesses your private
key can decrypt your login information, so it's important that you store your private keys in a secure
place.
598
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Creating a Key Pair Using Amazon EC2
The keys that Amazon EC2 uses are 2048-bit SSH-2 RSA keys. You can have up to five thousand key pairs
per Region.
When you launch an instance, you should specify the name of the key pair you plan to use to connect
to the instance. If you don't specify the name of an existing key pair when you launch an instance, you
won't be able to connect to the instance. When you connect to the instance, you must specify the private
key that corresponds to the key pair you specified when you launched the instance.
Note
Amazon EC2 doesn't keep a copy of your private key; therefore, if you lose a private key, there is
no way to recover it. If you lose the private key for an instance store-backed instance, you can't
access the instance; you should terminate the instance and launch another instance using a new
key pair. If you lose the private key for an EBS-backed Linux instance, you can regain access to
your instance. For more information, see Connecting to Your Linux Instance if You Lose Your
Private Key (p. 604).
If you have several users that require access to a single instance, you can add user accounts to your
instance. For more information, see Managing User Accounts on Your Linux Instance (p. 492). You can
create a key pair for each user, and add the public key information from each key pair to the .ssh/
authorized_keys file for each user on your instance. You can then distribute the private key files to
your users. That way, you do not have to distribute the same private key file that's used for the root
account to multiple users.
Contents
• Creating a Key Pair Using Amazon EC2 (p. 599)
• Importing Your Own Public Key to Amazon EC2 (p. 600)
• Retrieving the Public Key for Your Key Pair on Linux (p. 601)
• Retrieving the Public Key for Your Key Pair on Windows (p. 602)
• Retrieving the Public Key for Your Key Pair From Your Instance (p. 602)
• Verifying Your Key Pair's Fingerprint (p. 602)
• Deleting Your Key Pair (p. 603)
• Adding or Replacing a Key Pair for Your Instance (p. 604)
• Connecting to Your Linux Instance if You Lose Your Private Key (p. 604)
599
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Importing Your Own Public Key to Amazon EC2
4. For Key pair name, enter a name for the new key pair, and then choose Create.
5. The private key file is automatically downloaded by your browser. The base file name is the name
you specified as the name of your key pair, and the file name extension is .pem. Save the private key
file in a safe place.
Important
This is the only chance for you to save the private key file. You'll need to provide the name
of your key pair when you launch an instance and the corresponding private key each time
you connect to the instance.
6. If you will use an SSH client on a Mac or Linux computer to connect to your Linux instance, use the
following command to set the permissions of your private key file so that only you can read it.
If you do not set these permissions, then you cannot connect to your instance using this key pair. For
more information, see Error: Unprotected Private Key File (p. 1025).
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
Requirements
600
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Retrieving the Public Key for Your Key Pair on Linux
safe place. You'll need to provide the name of your key pair when you launch an instance and the
corresponding private key each time you connect to the instance.
Use the following steps to import your key pair using the Amazon EC2 console.
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
After the public key file is imported, you can verify that the key pair was imported successfully using the
Amazon EC2 console as follows.
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
ssh-keygen -y -f /path_to_key_pair/my-key-pair.pem
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQClKsfkNkuSevGj3eYhCe53pcjqP3maAhDFcvBS7O6V
hz2ItxCih+PnDSUaw+WNQn/mZphTk/a/gU8jEzoOWbkM4yxyb/wB96xbiFveSFJuOp/d6RJhJOI0iBXr
lsLnBItntckiJ7FbtxJMXLvvwJryDUilBMTjYtwB+QhYXUMOzce5Pjz5/i8SeJtjnV3iAoG/cQk+0FzZ
601
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Retrieving the Public Key for Your Key Pair on Windows
qaeJAAHco+CY/5WrUBkrHmFJr6HcXkvJdWPkYQS3xqC0+FmUZofz221CBt5IMucxXPkX4rWi+z7wB3Rb
BQoQzd8v7yeb7OzlPnWOyN0qFU0XA246RA8QFYiCNYwI3f05p6KLxEXAMPLE
If the command fails, ensure that you've changed the permissions on your key pair file so that only you
can view it by running the following command:
Start PuTTYgen, choose Load, and select the .ppk or .pem file. PuTTYgen displays the public key.
Retrieving the Public Key for Your Key Pair From Your
Instance
The public key that you specified when you launched an instance is also available to you through its
instance metadata. To view the public key that you specified when launching the instance, use the
following command from your instance:
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQClKsfkNkuSevGj3eYhCe53pcjqP3maAhDFcvBS7O6V
hz2ItxCih+PnDSUaw+WNQn/mZphTk/a/gU8jEzoOWbkM4yxyb/wB96xbiFveSFJuOp/d6RJhJOI0iBXr
lsLnBItntckiJ7FbtxJMXLvvwJryDUilBMTjYtwB+QhYXUMOzce5Pjz5/i8SeJtjnV3iAoG/cQk+0FzZ
qaeJAAHco+CY/5WrUBkrHmFJr6HcXkvJdWPkYQS3xqC0+FmUZofz221CBt5IMucxXPkX4rWi+z7wB3Rb
BQoQzd8v7yeb7OzlPnWOyN0qFU0XA246RA8QFYiCNYwI3f05p6KLxEXAMPLE my-key-pair
If you change the key pair that you use to connect to the instance, we don't update the instance
metadata to show the new public key; you'll continue to see the public key for the key pair you specified
when you launched the instance in the instance metadata.
Alternatively, on a Linux instance, the public key content is placed in an entry within ~/.ssh/
authorized_keys. You can open this file in an editor. The following is an example entry for the
key pair named my-key-pair. It consists of the public key followed by the name of the key pair. For
example:
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQClKsfkNkuSevGj3eYhCe53pcjqP3maAhDFcvBS7O6V
hz2ItxCih+PnDSUaw+WNQn/mZphTk/a/gU8jEzoOWbkM4yxyb/wB96xbiFveSFJuOp/d6RJhJOI0iBXr
lsLnBItntckiJ7FbtxJMXLvvwJryDUilBMTjYtwB+QhYXUMOzce5Pjz5/i8SeJtjnV3iAoG/cQk+0FzZ
qaeJAAHco+CY/5WrUBkrHmFJr6HcXkvJdWPkYQS3xqC0+FmUZofz221CBt5IMucxXPkX4rWi+z7wB3Rb
BQoQzd8v7yeb7OzlPnWOyN0qFU0XA246RA8QFYiCNYwI3f05p6KLxEXAMPLE my-key-pair
602
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Deleting Your Key Pair
pair was generated by AWS or a third-party tool. If you created the key pair using AWS, the fingerprint is
calculated using an SHA-1 hash function. If you created the key pair with a third-party tool and uploaded
the public key to AWS, or if you generated a new public key from an existing AWS-created private key
and uploaded it to AWS, the fingerprint is calculated using an MD5 hash function.
You can use the SSH2 fingerprint that's displayed on the Key Pairs page to verify that the private key
you have on your local machine matches the public key stored in AWS. From the computer where you
downloaded the private key file, generate an SSH2 fingerprint from the private key file. The output
should match the fingerprint that's displayed in the console.
If you created your key pair using AWS, you can use the OpenSSL tools to generate a fingerprint as
follows:
$ openssl pkcs8 -in path_to_private_key -inform PEM -outform DER -topk8 -nocrypt | openssl
sha1 -c
If you created a key pair using a third-party tool and uploaded the public key to AWS, you can use the
OpenSSL tools to generate the fingerprint as follows:
If you created an OpenSSH key pair using OpenSSH 7.8 or later and uploaded the public key to AWS, you
can use ssh-keygen to generate the fingerprint as follows:
You can delete a key pair using the Amazon EC2 console or the command line.
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
603
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Adding or Replacing a Key Pair for Your Instance
Note
If you create a Linux AMI from an instance, and then use the AMI to launch a new instance in a
different Region or account, the new instance includes the public key from the original instance.
This enables you to connect to the new instance using the same private key file as your original
instance. You can remove this public key from your instance by removing its entry from the
.ssh/authorized_keys file using a text editor of your choice. For more information about
managing users on your instance and providing remote access using a specific key pair, see
Managing User Accounts on Your Linux Instance (p. 492).
Before you begin, create a new key pair using the Amazon EC2 console (p. 599) or a third-party
tool (p. 600).
1. Retrieve the public key from your new key pair. For more information, see Retrieving the Public
Key for Your Key Pair on Linux (p. 601) or Retrieving the Public Key for Your Key Pair on
Windows (p. 602).
2. Connect to your instance using your existing private key file.
3. Using a text editor of your choice, open the .ssh/authorized_keys file on the instance. Paste the
public key information from your new key pair underneath the existing public key information. Save
the file.
4. Disconnect from your instance, and test that you can connect to your instance using the new private
key file.
5. (Optional) If you're replacing an existing key pair, connect to your instance and delete the public key
information for the original key pair from the .ssh/authorized_keys file.
Note
If you're using an Auto Scaling group (for example, in an Elastic Beanstalk environment), ensure
that the key pair you're replacing is not specified in your launch configuration. Amazon EC2
Auto Scaling launches a replacement instance if it detects an unhealthy instance; however, the
instance launch fails if the key pair cannot be found.
604
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Connecting to Your Linux Instance
if You Lose Your Private Key
authorized_keys file, move the volume back to the original instance, and restart the instance. For
more information about launching, connecting to, and stopping instances, see Instance Lifecycle (p. 390).
This procedure isn't supported for instance store-backed instances. To determine the root device type of
your instance, open the Amazon EC2 console, choose Instances, select the instance, and check the value
of Root device type in the details pane. The value is either ebs or instance store. If the root device is
an instance store volume, you must have the private key in order to connect to the instance.
Prerequisites
Create a new key pair using either the Amazon EC2 console or a third-party tool. If you want to name
your new key pair exactly the same as the lost private key, you must first delete the existing key pair.
• Write down the instance ID, AMI ID, and Availability Zone of the original instance.
• In the Root device field, take note of the device name for the root volume (for example, /
dev/sda1 or /dev/xvda). Choose the link and write down the volume ID in the EBS ID field
(vol-xxxxxxxxxxxxxxxxx).
4. Choose Actions, select Instance State, and then select Stop. If Stop is disabled, either the instance is
already stopped or its root device is an instance store volume.
Warning
When you stop an instance, the data on any instance store volumes is erased. To keep data
from instance store volumes, be sure to back it up to persistent storage.
5. Choose Launch Instance, and then use the launch wizard to launch a temporary instance with the
following options:
• On the Choose an AMI page, select the same AMI that you used to launch the original instance.
If this AMI is unavailable, you can create an AMI that you can use from the stopped instance. For
more information, see Creating an Amazon EBS-Backed Linux AMI (p. 116) .
• On the Choose an Instance Type page, leave the default instance type that the wizard selects for
you.
• On the Configure Instance Details page, specify the same Availability Zone as the instance you'd
like to connect to. If you're launching an instance in a VPC, select a subnet in this Availability Zone.
• On the Add Tags page, add the tag Name=Temporary to the instance to indicate that this is a
temporary instance.
• On the Review page, choose Launch. Create a new key pair, download it to a safe location on your
computer, and then choose Launch Instances.
6. In the navigation pane, choose Volumes and select the root device volume for the original instance
(you wrote down its volume ID in a previous step). Choose Actions, Detach Volume, and then select
Yes, Detach. Wait for the state of the volume to become available. (You might need to choose the
Refresh icon.)
7. With the volume still selected, choose Actions, and then select Attach Volume. Select the instance
ID of the temporary instance, write down the device name specified under Device (for example, /
dev/sdf), and then choose Attach.
Note
If you launched your original instance from an AWS Marketplace AMI and your volume
contains AWS Marketplace codes, you must first stop the temporary instance before you can
attach the volume.
605
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Connecting to Your Linux Instance
if You Lose Your Private Key
8. Connect to the temporary instance.
9. From the temporary instance, mount the volume that you attached to the instance so that you can
access its file system. For example, if the device name is /dev/sdf, use the following commands to
mount the volume as /mnt/tempvol.
Note
The device name may appear differently on your instance. For example, devices mounted
as /dev/sdf may show up as /dev/xvdf on the instance. Some versions of Red Hat (or its
variants, such as CentOS) may even increment the trailing letter by 4 characters, where /
dev/sdf becomes /dev/xvdk.
In the above example, /dev/xvda and /dev/xvdf are partitioned volumes, and /dev/xvdg
is not. If your volume is partitioned, you mount the partition (/dev/xvdf1) instead of the raw
device (/dev/xvdf) in the next steps.
b. Create a temporary directory to mount the volume.
c. Mount the volume (or partition) at the temporary mount point, using the volume name or
device name you identified earlier. The required command depends on your operating system's
file system.
Note
If you get an error stating that the file system is corrupt, run the following command to use
the fsck utility to check the file system and repair any issues:
10. From the temporary instance, use the following command to update authorized_keys on the
mounted volume with the new public key from the authorized_keys for the temporary instance.
Important
The following examples use the Amazon Linux user name ec2-user. You may need to
substitute a different user name, such as ubuntu for Ubuntu instances.
606
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Security Groups
(Optional) Otherwise, if you don't have permission to edit files in /mnt/tempvol, you'll need to
update the file using sudo and then check the permissions on the file to verify that you'll be able to
log into the original instance. Use the following command to check the permissions on the file:
In this example output, 222 is the user ID and 500 is the group ID. Next, use sudo to re-run the copy
command that failed:
Run the following command again to determine whether the permissions changed:
If the user ID and group ID have changed, use the following command to restore them:
11. From the temporary instance, unmount the volume that you attached so that you can reattach it to
the original instance. For example, use the following command to unmount the volume at /mnt/
tempvol:
12. From the Amazon EC2 console, select the volume with the volume ID that you wrote down, choose
Actions, Detach Volume, and then select Yes, Detach. Wait for the state of the volume to become
available. (You might need to choose the Refresh icon.)
13. With the volume still selected, choose Actions, Attach Volume. Select the instance ID of the original
instance, specify the device name you noted earlier for the original root device attachment (/dev/
sda1 or /dev/xvda), and then choose Attach.
Important
If you don't specify the same device name as the original attachment, you cannot start the
original instance. Amazon EC2 expects the root device volume at sda1 or /dev/xvda.
14. Select the original instance, choose Actions, select Instance State, and then choose Start. After the
instance enters the running state, you can connect to it using the private key file for your new key
pair.
Note
If the name of your new key pair and corresponding private key file is different to the name
of the original key pair, ensure that you specify the name of the new private key file when
you connect to your instance.
15. (Optional) You can terminate the temporary instance if you have no further use for it. Select the
temporary instance, choose Actions, select Instance State, and then choose Terminate.
607
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Security Group Rules
group. You can add rules to each security group that allow traffic to or from its associated instances.
You can modify the rules for a security group at any time; the new rules are automatically applied to all
instances that are associated with the security group. When we decide whether to allow traffic to reach
an instance, we evaluate all the rules from all the security groups that are associated with the instance.
When you launch an instance in a VPC, you must specify a security group that's created for that VPC.
After you launch an instance, you can change its security groups. Security groups are associated with
network interfaces. Changing an instance's security groups changes the security groups associated
with the primary network interface (eth0). For more information, see Changing an Instance's Security
Groups in the Amazon VPC User Guide. You can also change the security groups associated with any other
network interface. For more information, see Changing the Security Group (p. 745).
If you have requirements that aren't met by security groups, you can maintain your own firewall on any
of your instances in addition to using security groups.
If you need to allow traffic to a Windows instance, see Amazon EC2 Security Groups for Windows
Instances in the Amazon EC2 User Guide for Windows Instances.
Contents
• Security Group Rules (p. 608)
• Connection Tracking (p. 610)
• Default Security Groups (p. 611)
• Custom Security Groups (p. 611)
• Working with Security Groups (p. 611)
• Creating a Security Group (p. 612)
• Describing Your Security Groups (p. 613)
• Adding Rules to a Security Group (p. 613)
• Updating Security Group Rules (p. 614)
• Deleting Rules from a Security Group (p. 615)
• Deleting a Security Group (p. 615)
• Security Group Rules Reference (p. 616)
• Web Server Rules (p. 616)
• Database Server Rules (p. 616)
• Rules to Connect to Instances from Your Computer (p. 618)
• Rules to Connect to Instances from an Instance with the Same Security Group (p. 618)
• Rules for Path MTU Discovery (p. 619)
• Rules for Ping/ICMP (p. 619)
• DNS Server Rules (p. 619)
• Amazon EFS Rules (p. 620)
• Elastic Load Balancing Rules (p. 620)
• VPC Peering Rules (p. 621)
608
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Security Group Rules
• Security groups are stateful — if you send a request from your instance, the response traffic for that
request is allowed to flow in regardless of inbound security group rules. For VPC security groups, this
also means that responses to allowed inbound traffic are allowed to flow out, regardless of outbound
rules. For more information, see Connection Tracking (p. 610).
• You can add and remove rules at any time. Your changes are automatically applied to the instances
associated with the security group.
Note
The effect of some rule changes may depend on how the traffic is tracked. For more
information, see Connection Tracking (p. 610).
• When you associate multiple security groups with an instance, the rules from each security group are
effectively aggregated to create one set of rules. We use this set of rules to determine whether to
allow access.
Note
You can assign multiple security groups to an instance, therefore an instance can have
hundreds of rules that apply. This might cause problems when you access the instance. We
recommend that you condense your rules as much as possible.
• Protocol: The protocol to allow. The most common protocols are 6 (TCP) 17 (UDP), and 1 (ICMP).
• Port range : For TCP, UDP, or a custom protocol, the range of ports to allow. You can specify a single
port number (for example, 22), or range of port numbers (for example, 7000-8000).
• ICMP type and code: For ICMP, the ICMP type and code.
• Source or destination: The source (inbound rules) or destination (outbound rules) for the traffic.
Specify one of these options:
• An individual IPv4 address. You must use the /32 prefix length; for example, 203.0.113.1/32.
• An individual IPv6 address. You must use the /128 prefix length; for example
2001:db8:1234:1a00::123/128.
• A range of IPv4 addresses, in CIDR block notation, for example, 203.0.113.0/24.
• A range of IPv6 addresses, in CIDR block notation, for example, 2001:db8:1234:1a00::/64.
• The prefix list ID for the AWS service; for example, pl-1a2b3c4d. For more information, see
Gateway VPC Endpoints in the Amazon VPC User Guide.
• Another security group. This allows instances associated with the specified security group to access
instances associated with this security group. This does not add rules from the source security group
to this security group. You can specify one of the following security groups:
• The current security group
• A different security group for the same VPC
• A different security group for a peer VPC in a VPC peering connection
• (Optional) Description: You can add a description for the rule; for example, to help you identify it
later. A description can be up to 255 characters in length. Allowed characters are a-z, A-Z, 0-9, spaces,
and ._-:/()#,@[]+=;{}!$*.
When you specify a security group as the source or destination for a rule, the rule affects all instances
associated with the security group. Incoming traffic is allowed based on the private IP addresses of
the instances that are associated with the source security group (and not the public IP or Elastic IP
addresses). For more information about IP addresses, see Amazon EC2 Instance IP Addressing (p. 706).
If your security group rule references a security group in a peer VPC, and the referenced security group or
VPC peering connection is deleted, the rule is marked as stale. For more information, see Working with
Stale Security Group Rules in the Amazon VPC Peering Guide.
609
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Security Group Rules
If there is more than one rule for a specific port, we apply the most permissive rule. For example, if you
have a rule that allows access to TCP port 22 (SSH) from IP address 203.0.113.1 and another rule that
allows access to TCP port 22 from everyone, everyone has access to TCP port 22.
Connection Tracking
Your security groups use connection tracking to track information about traffic to and from the instance.
Rules are applied based on the connection state of the traffic to determine if the traffic is allowed or
denied. This allows security groups to be stateful — responses to inbound traffic are allowed to flow out
of the instance regardless of outbound security group rules, and vice versa. For example, if you initiate
an ICMP ping command to your instance from your home computer, and your inbound security group
rules allow ICMP traffic, information about the connection (including the port information) is tracked.
Response traffic from the instance for the ping command is not tracked as a new request, but rather
as an established connection and is allowed to flow out of the instance, even if your outbound security
group rules restrict outbound ICMP traffic.
Not all flows of traffic are tracked. If a security group rule permits TCP or UDP flows for all traffic
(0.0.0.0/0) and there is a corresponding rule in the other direction that permits all response traffic
(0.0.0.0/0) for all ports (0-65535), then that flow of traffic is not tracked. The response traffic is
therefore allowed to flow based on the inbound or outbound rule that permits the response traffic, and
not on tracking information.
In the following example, the security group has specific inbound rules for TCP and ICMP traffic, and an
outbound rule that allows all outbound traffic.
Inbound rules
Outbound rules
TCP traffic on port 22 (SSH) to and from the instance is tracked, because the inbound rule allows traffic
from 203.0.113.1/32 only, and not all IP addresses (0.0.0.0/0). TCP traffic on port 80 (HTTP) to
and from the instance is not tracked, because both the inbound and outbound rules allow all traffic
(0.0.0.0/0). ICMP traffic is always tracked, regardless of rules. If you remove the outbound rule from
the security group, then all traffic to and from the instance is tracked, including traffic on port 80 (HTTP).
An existing flow of traffic that is tracked may not be interrupted when you remove the security group
rule that enables that flow. Instead, the flow is interrupted when it's stopped by you or the other
host for at least a few minutes (or up to 5 days for established TCP connections). For UDP, this may
require terminating actions on the remote side of the flow. An untracked flow of traffic is immediately
interrupted if the rule that enables the flow is removed or modified. For example, if you remove a rule
that allows all inbound SSH traffic to the instance, then your existing SSH connections to the instance are
immediately dropped.
For protocols other than TCP, UDP, or ICMP, only the IP address and protocol number is tracked. If your
instance sends traffic to another host (host B), and host B initiates the same type of traffic to your
610
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Default Security Groups
instance in a separate request within 600 seconds of the original request or response, your instance
accepts it regardless of inbound security group rules, because it’s regarded as response traffic.
To ensure that traffic is immediately interrupted when you remove a security group rule, or to ensure
that all inbound traffic is subject to firewall rules, you can use a network ACL for your subnet — network
ACLs are stateless and therefore do not automatically allow response traffic. For more information, see
Network ACLs in the Amazon VPC User Guide.
A default security group is named default, and it has an ID assigned by AWS. The following are the
default rules for each default security group:
• Allows all inbound traffic from other instances associated with the default security group (the security
group specifies itself as a source security group in its inbound rules)
• Allows all outbound traffic from the instance.
You can add or remove inbound and outbound rules for any default security group.
You can't delete a default security group. If you try to delete a default security group, you'll get the
following error: Client.CannotDelete: the specified group: "sg-51530134" name:
"default" cannot be deleted by a user.
When you create a security group, you must provide it with a name and a description. Security group
names and descriptions can be up to 255 characters in length, and are limited to the following
characters:
A security group name cannot start with sg-. A security group name must be unique for the VPC.
The following are the default rules for a security group that you create:
After you've created a security group, you can change its inbound rules to reflect the type of inbound
traffic that you want to reach the associated instances. You can also change its outbound rules.
For more information about the rules you can add to a security group, see Security Group Rules
Reference (p. 616).
611
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with Security Groups
Tasks
• Creating a Security Group (p. 612)
• Describing Your Security Groups (p. 613)
• Adding Rules to a Security Group (p. 613)
• Updating Security Group Rules (p. 614)
• Deleting Rules from a Security Group (p. 615)
• Deleting a Security Group (p. 615)
The Amazon EC2 console enables you to copy the rules from an existing security group to a new security
group.
You can assign a security group to an instance when you launch the instance. When you add or remove
rules, those changes are automatically applied to all instances to which you've assigned the security
group.
After you launch an instance, you can change its security groups. For more information, see Changing an
Instance's Security Groups in the Amazon VPC User Guide.
612
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with Security Groups
For more information about choosing security group rules for specific types of access, see Security Group
Rules Reference (p. 616).
For more information about the types of rules that you can add, see Security Group Rules
Reference (p. 616).
613
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with Security Groups
5. Choose Save.
6. You can also specify outbound rules. On the Outbound tab, choose Edit, Add Rule, and do the
following:
To add one or more ingress rules to a security group using the command line
To add one or more egress rules to a security group using the command line
To update the protocol, port range, or source or destination of an existing rule using the Amazon EC2 API
or a command line tool, you cannot modify the rule. Instead, you must delete the existing rule and add a
new rule. To update the rule description only, you can use the update-security-group-rule-descriptions-
ingress and update-security-group-rule-descriptions-egress commands.
To update the description for an ingress security group rule using the command line
614
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with Security Groups
To update the description for an egress security group rule using the command line
To remove one or more ingress rules from a security group using the command line
To remove one or more egress rules from a security group using the command line
615
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Security Group Rules Reference
The following are examples of the kinds of rules that you can add to security groups for specific kinds of
access.
Examples
• Web Server Rules (p. 616)
• Database Server Rules (p. 616)
• Rules to Connect to Instances from Your Computer (p. 618)
• Rules to Connect to Instances from an Instance with the Same Security Group (p. 618)
• Rules for Path MTU Discovery (p. 619)
• Rules for Ping/ICMP (p. 619)
• DNS Server Rules (p. 619)
• Amazon EFS Rules (p. 620)
• Elastic Load Balancing Rules (p. 620)
• VPC Peering Rules (p. 621)
616
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Security Group Rules Reference
You can optionally restrict outbound traffic from your database servers, for example, if you want allow
access to the Internet for software updates, but restrict all other kinds of traffic. You must first remove
the default outbound rule that allows all outbound traffic.
617
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Security Group Rules Reference
The following table describes the inbound rule for a security group that enables associated instances to
communicate with each other. The rule allows all types of traffic.
618
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Security Group Rules Reference
To ensure that your instance can receive this message and the packet does not get dropped, you must
add an ICMP rule to your inbound security group rules.
To use the ping6 command to ping the IPv6 address for your instance, you must add the following
inbound ICMPv6 rule.
619
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Security Group Rules Reference
• The ID of a security group for the set of instances in your network that require access to the DNS
server
TCP 6 53
UDP 17 53
To mount an Amazon EFS file system on your Amazon EC2 instance, you must connect to your instance.
Therefore, the security group associated with your instance must have rules that allow inbound SSH from
your local computer or local network.
Inbound
620
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Controlling Access
For an internal
load-balancer: the
IPv4 CIDR block of
the VPC
Outbound
The security group rules for your instances must allow the load balancer to communicate with your
instances on both the listener port and the health check port.
Inbound
TCP 6 The health check The ID of the load Allow traffic from
port balancer security the load balancer
group on the health
check port.
For more information, see Configure Security Groups for Your Classic Load Balancer in the User Guide
for Classic Load Balancers, and Security Groups for Your Application Load Balancer in the User Guide for
Application Load Balancers.
621
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Network Access to Your Instance
resources without sharing your security credentials. You can use IAM to control how other users use
resources in your AWS account, and you can use security groups to control access to your Amazon EC2
instances. You can choose to allow full use or limited use of your Amazon EC2 resources.
Contents
• Network Access to Your Instance (p. 622)
• Amazon EC2 Permission Attributes (p. 622)
• IAM and Amazon EC2 (p. 622)
• IAM Policies for Amazon EC2 (p. 624)
• IAM Roles for Amazon EC2 (p. 696)
• Authorizing Inbound Traffic for Your Linux Instances (p. 704)
For more information, see Authorizing Inbound Traffic for Your Linux Instances (p. 704).
Each AMI has a LaunchPermission attribute that controls which AWS accounts can access the AMI. For
more information, see Making an AMI Public (p. 105).
Each Amazon EBS snapshot has a createVolumePermission attribute that controls which AWS
accounts can use the snapshot. For more information, see Sharing an Amazon EBS Snapshot (p. 878).
By using IAM with Amazon EC2, you can control whether users in your organization can perform a task
using specific Amazon EC2 API actions and whether they can use specific AWS resources.
622
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM and Amazon EC2
• PowerUserAccess
• ReadOnlyAccess
• AmazonEC2FullAccess
• AmazonEC2ReadOnlyAccess
5. Choose Create Group.
To create an IAM user, add the user to your group, and create a password for the user
• Autogenerated password. Each user gets a randomly generated password that meets the current
password policy in effect (if any). You can view or download the passwords when you get to the
Final page.
• Custom password. Each user is assigned the password that you type in the box.
5. Choose Next: Permissions.
6. On the Set permissions page, choose Add user to group. Select the check box next to the group
that you created earlier and choose Next: Review.
7. Choose Create user.
8. To view the users' access keys (access key IDs and secret access keys), choose Show next to each
password and secret access key to see. To save the access keys, choose Download .csv and then save
the file to a safe location.
Important
You cannot retrieve the secret access key after you complete this step; if you misplace it you
must create a new one.
9. Choose Close.
10. Give each user his or her credentials (access keys and password); this enables them to use services
based on the permissions you specified for the IAM group.
Related Topics
For more information about IAM, see the following:
623
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
When you attach a policy to a user or group of users, it allows or denies the users permission to perform
the specified tasks on the specified resources. For more general information about IAM policies, see
Permissions and Policies in the IAM User Guide. For more information about managing and creating
custom IAM policies, see Managing IAM Policies.
Getting Started
An IAM policy must grant or deny permissions to use one or more Amazon EC2 actions. It must also
specify the resources that can be used with the action, which can be all resources, or in some cases,
specific resources. The policy can also include conditions that you apply to the resource.
Amazon EC2 partially supports resource-level permissions. This means that for some EC2 API actions,
you cannot specify which resource a user is allowed to work with for that action; instead, you have to
allow users to work with all resources for that action.
Task Topic
Define actions in your policy Actions for Amazon EC2 (p. 625)
Define specific resources in your policy Amazon Resource Names for Amazon
EC2 (p. 626)
Apply conditions to the use of the resources Condition Keys for Amazon EC2 (p. 629)
Example policies for a CLI or SDK Example Policies for Working with the AWS CLI or
an AWS SDK (p. 661)
Example policies for the Amazon EC2 console Example Policies for Working in the Amazon EC2
Console (p. 688)
Policy Structure
The following topics explain the structure of an IAM policy.
Contents
624
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
Policy Syntax
An IAM policy is a JSON document that consists of one or more statements. Each statement is structured
as follows:
{
"Statement":[{
"Effect":"effect",
"Action":"action",
"Resource":"arn",
"Condition":{
"condition":{
"key":"value"
}
}
}
]
}
• Effect: The effect can be Allow or Deny. By default, IAM users don't have permission to use resources
and API actions, so all requests are denied. An explicit allow overrides the default. An explicit deny
overrides any allows.
• Action: The action is the specific API action for which you are granting or denying permission. To learn
about specifying action, see Actions for Amazon EC2 (p. 625).
• Resource: The resource that's affected by the action. Some Amazon EC2 API actions allow you to
include specific resources in your policy that can be created or modified by the action. To specify a
resource in the statement, you need to use its Amazon Resource Name (ARN). For more information
about specifying the ARN value, see Amazon Resource Names for Amazon EC2 (p. 626). For more
information about which API actions support which ARNs, see Supported Resource-Level Permissions
for Amazon EC2 API Actions (p. 633). If the API action does not support ARNs, use the * wildcard to
specify that all resources can be affected by the action.
• Condition: Conditions are optional. They can be used to control when your policy is in effect. For
more information about specifying conditions for Amazon EC2, see Condition Keys for Amazon
EC2 (p. 629).
For more information about example IAM policy statements for Amazon EC2, see Example Policies for
Working with the AWS CLI or an AWS SDK (p. 661).
To specify multiple actions in a single statement, separate them with commas as follows:
625
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
You can also specify multiple actions using wildcards. For example, you can specify all actions whose
name begins with the word "Describe" as follows:
"Action": "ec2:Describe*"
To specify all Amazon EC2 API actions, use the * wildcard as follows:
"Action": "ec2:*"
For a list of Amazon EC2 actions, see Actions in the Amazon EC2 API Reference.
arn:aws:[service]:[region]:[account]:resourceType/resourcePath
service
A path that identifies the resource. You can use the * wildcard in your paths.
For example, you can indicate a specific instance (i-1234567890abcdef0) in your statement using its
ARN as follows:
"Resource": "arn:aws:ec2:us-east-1:123456789012:instance/i-1234567890abcdef0"
You can also specify all instances that belong to a specific account by using the * wildcard as follows:
"Resource": "arn:aws:ec2:us-east-1:123456789012:instance/*"
To specify all resources, or if a specific API action does not support ARNs, use the * wildcard in the
Resource element as follows:
626
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
"Resource": "*"
The following table describes the ARNs for each type of resource used by the Amazon EC2 API actions.
Image arn:aws:ec2:region::image/image-id
Where image-id is the ID of the AMI, AKI, or ARI, and account isn't
used
Instance arn:aws:ec2:region:account:instance/instance-id
627
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
Snapshot arn:aws:ec2:region::snapshot/snapshot-id
Subnet arn:aws:ec2:region:account:subnet/subnet-id
Volume arn:aws:ec2:region:account:volume/volume-id
VPC arn:aws:ec2:region:account:vpc/vpc-id
Many Amazon EC2 API actions involve multiple resources. For example, AttachVolume attaches an
Amazon EBS volume to an instance, so an IAM user must have permissions to use the volume and the
instance. To specify multiple resources in a single statement, separate their ARNs with commas, as
follows:
628
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
For more general information about ARNs, see Amazon Resource Names (ARN) and AWS Service
Namespaces in the Amazon Web Services General Reference. For more information about the resources
that are created or modified by the Amazon EC2 actions, and the ARNs that you can use in your IAM
policy statements, see Granting IAM Users Required Permissions for Amazon EC2 Resources in the
Amazon EC2 API Reference.
If you specify multiple conditions, or multiple keys in a single condition, we evaluate them using a
logical AND operation. If you specify a single condition with multiple values for one key, we evaluate the
condition using a logical OR operation. For permissions to be granted, all conditions must be met.
You can also use placeholders when you specify conditions. For example, you can grant an IAM user
permission to use resources with a tag that specifies his or her IAM user name. For more information, see
Policy Variables in the IAM User Guide.
Important
Many condition keys are specific to a resource, and some API actions use multiple resources.
If you write a policy with a condition key, use the Resource element of the statement to
specify the resource to which the condition key applies. If not, the policy may prevent users
from performing the action at all, because the condition check fails for the resources to which
the condition key does not apply. If you do not want to specify a resource, or if you've written
the Action element of your policy to include multiple API actions, then you must use the
...IfExists condition type to ensure that the condition key is ignored for resources that do
not use it. For more information, see ...IfExists Conditions in the IAM User Guide.
Amazon EC2 implements the following service-specific condition keys. For information about which
condition keys you can use with which Amazon EC2 resources, on an action-by-action basis, see
Supported Resource-Level Permissions for Amazon EC2 API Actions (p. 633).
Where vpc-arn is the VPC ARN for the accepter VPC in a VPC
peering connection
"ec2:AuthorizedService":"service-principal"
ec2:AuthorizedService String, Null
"ec2:AuthorizedUser":"principal-arn"
ec2:AuthorizedUser ARN, Null
"ec2:AvailabilityZone":"az-api-name"
ec2:AvailabilityZone String, Null
629
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
"ec2:ElasticGpuType":"elastic-gpu-type"
ec2:ElasticGpuType String, Null
"ec2:InstanceMarketType":"market-type"
ec2:InstanceMarketType String, Null
"ec2:InstanceProfile":"instance-profile-arn"
ec2:InstanceProfile ARN, Null
"ec2:IsLaunchTemplateResource":"launch-template-resource-
ec2:IsLaunchTemplateResource Boolean, Null
flag"
"ec2:LaunchTemplate":"launch-template-arn"
ec2:LaunchTemplate ARN, Null
"ec2:ParentSnapshot":"snapshot-arn"
ec2:ParentSnapshot ARN, Null
630
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
"ec2:PlacementGroup":"placement-group-arn"
ec2:PlacementGroup ARN, Null
"ec2:PlacementGroupStrategy":"placement-group-strategy"
ec2:PlacementGroupStrategy String, Null
"ec2:ReservedInstancesOfferingType":"offering-type
ec2:ReservedInstancesOfferingType String, Null
"ec2:RootDeviceType":"root-device-type-name"
ec2:RootDeviceType String, Null
631
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
Amazon EC2 also implements the AWS-wide condition keys. For more information, see Information
Available in All Requests in the IAM User Guide.
All Amazon EC2 actions support the aws:RequestedRegion and ec2:Region condition keys. For more
information, see Example: Restricting Access to a Specific Region (p. 662).
The ec2:SourceInstanceARN key can be used for conditions that specify the ARN of the instance from
which a request is made. This condition key is available AWS-wide and is not service-specific. For policy
examples, see Allows an EC2 Instance to Attach or Detach Volumes and Example: Allowing a Specific
Instance to View Resources in Other AWS Services (p. 687). The ec2:SourceInstanceARN key cannot
be used as a variable to populate the ARN for the Resource element in a statement.
The following AWS condition keys were introduced for Amazon EC2 and are supported by a limited
number of additional services.
For example policy statements for Amazon EC2, see Example Policies for Working with the AWS CLI or an
AWS SDK (p. 661).
First, create an IAM user for testing purposes, and then attach the IAM policy that you created to the test
user. Then, make a request as the test user.
632
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
If the Amazon EC2 action that you are testing creates or modifies a resource, you should make the
request using the DryRun parameter (or run the AWS CLI command with the --dry-run option). In
this case, the call completes the authorization check, but does not complete the operation. For example,
you can check whether the user can terminate a particular instance without actually terminating it. If
the test user has the required permissions, the request returns DryRunOperation; otherwise, it returns
UnauthorizedOperation.
If the policy doesn't grant the user the permissions that you expected, or is overly permissive, you can
adjust the policy as needed and retest until you get the desired results.
Important
It can take several minutes for policy changes to propagate before they take effect. Therefore,
we recommend that you allow five minutes to pass before you test your policy updates.
If an authorization check fails, the request returns an encoded message with diagnostic information. You
can decode the message using the DecodeAuthorizationMessage action. For more information, see
DecodeAuthorizationMessage in the AWS Security Token Service API Reference, and decode-authorization-
message in the AWS CLI Command Reference.
The following table describes the Amazon EC2 API actions that currently support resource-level
permissions, as well as the supported resources (and their ARNs) and condition keys for each action.
When specifying an ARN, you can use the * wildcard in your paths; for example, when you cannot or do
not want to specify exact resource IDs. For examples of using wildcards, see Example Policies for Working
with the AWS CLI or an AWS SDK (p. 661).
Important
If an Amazon EC2 API action is not listed in this table, then it does not support resource-level
permissions. If an Amazon EC2 API action does not support resource-level permissions, you can
grant users permissions to use the action, but you have to specify a * for the resource element
of your policy statement. For an example, see Example: Read-Only Access (p. 661). For a
list of Amazon EC2 API actions that currently do not support resource-level permissions, see
Unsupported Resource-Level Permissions in the Amazon EC2 API Reference.
AcceptVpcPeeringConnection
VPC peering connection ec2:AccepterVpc
arn:aws:ec2:region:account:vpc-peering- ec2:Region
connection/*
ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:vpc-peering-
connection/vpc-peering-connection-id ec2:RequesterVpc
VPC ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:vpc/* ec2:Region
arn:aws:ec2:region:account:vpc/vpc-id ec2:Tenancy
633
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
AssociateIamInstanceProfile
Instance ec2:AvailabilityZone
arn:aws:ec2:region:account:instance/* ec2:EbsOptimized
arn:aws:ec2:region:account:instance/ ec2:InstanceProfile
instance-id
ec2:InstanceType
ec2:PlacementGroup
ec2:Region
ec2:ResourceTag/tag-key
ec2:RootDeviceType
ec2:Tenancy
arn:aws:ec2:region:account:instance/* ec2:EbsOptimized
arn:aws:ec2:region:account:instance/ ec2:InstanceProfile
instance-id
ec2:InstanceType
ec2:PlacementGroup
ec2:Region
ec2:ResourceTag/tag-key
ec2:RootDeviceType
ec2:Tenancy
arn:aws:ec2:region:account:security- ec2:ResourceTag/tag-key
group/*
ec2:Vpc
arn:aws:ec2:region:account:security-
group/security-group-id
VPC ec2:Region
arn:aws:ec2:region:account:vpc/* ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:vpc/vpc-id ec2:Tenancy
634
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
arn:aws:ec2:region:account:instance/* ec2:EbsOptimized
arn:aws:ec2:region:account:instance/ ec2:InstanceProfile
instance-id
ec2:InstanceType
ec2:PlacementGroup
ec2:Region
ec2:ResourceTag/tag-key
ec2:RootDeviceType
ec2:Tenancy
Volume ec2:AvailabilityZone
arn:aws:ec2:region:account:volume/* ec2:Encrypted
arn:aws:ec2:region:account:volume/ ec2:ParentSnapshot
volume-id
ec2:Region
ec2:ResourceTag/tag-key
ec2:VolumeIops
ec2:VolumeSize
ec2:VolumeType
AuthorizeSecurityGroupEgress
Security group ec2:Region
arn:aws:ec2:region:account:security- ec2:ResourceTag/tag-key
group/*
ec2:Vpc
arn:aws:ec2:region:account:security-
group/security-group-id
AuthorizeSecurityGroupIngress
Security group ec2:Region
arn:aws:ec2:region:account:security- ec2:ResourceTag/tag-key
group/*
ec2:Vpc
arn:aws:ec2:region:account:security-
group/security-group-id
CreateLaunchTemplateVersion
Launch template ec2:Region
arn:aws:ec2:region:account:launch- ec2:ResourceTag/tag-key
template/*
arn:aws:ec2:region:account:launch-
template/launch-template-id
635
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
CreateNetworkInterfacePermission
Network interface ec2:AuthorizedUser
arn:aws:ec2:region:account:network- ec2:AvailabilityZone
interface/*
ec2:Permission
arn:aws:ec2:region:account:network-
interface/eni-id ec2:Region
ec2:ResourceTag/tag-key
ec2:Subnet
ec2:Vpc
arn:aws:ec2:region:account:route-table/* ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:route- ec2:Vpc
table/route-table-id
arn:aws:ec2:region::snapshot/* ec2:Region
aws:RequestTag/tag-key
aws:TagKeys
Volume ec2:Encrypted
arn:aws:ec2:region:account:volume/* ec2:Region
arn:aws:ec2:region:account:volume/ ec2:VolumeIops
volume-id
ec2:VolumeSize
ec2:VolumeType
ec2:ResourceTag/tag-key
arn:aws:ec2:region::snapshot/* ec2:Region
aws:RequestTag/tag-key
aws:TagKeys
Volume ec2:Encrypted
arn:aws:ec2:region:account:volume/* ec2:Region
arn:aws:ec2:region:account:volume/ ec2:VolumeIops
volume-id
ec2:VolumeSize
ec2:VolumeType
ec2:ResourceTag/tag-key
636
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
Instance ec2:AvailabilityZone
arn:aws:ec2:region:account:instance/* ec2:EbsOptimized
arn:aws:ec2:region:account:volume/ ec2:PlacementGroup
instance-id
ec2:Region
ec2:ResourceTag/tag-key
ec2:RootDeviceType
ec2:Tenancy
arn:aws:ec2:region:account:fpga-image/* ec2:Region
arn:aws:ec2:region:account:fpga- ec2:ResourceTag/tag-key
image/afi-id
aws:RequestTag/tag-key
aws:TagKeys
arn:aws:ec2:region:account:dhcp- ec2:Region
options/*
ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:dhcp-
options/dhcp-options-id aws:RequestTag/tag-key
aws:TagKeys
Image ec2:CreateAction
arn:aws:ec2:region::image/* ec2:ImageType
arn:aws:ec2:region::image/image-id ec2:Owner
ec2:Public
ec2:Region
ec2:ResourceTag/tag-key
ec2:RootDeviceType
aws:RequestTag/tag-key
aws:TagKeys
637
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
Instance ec2:AvailabilityZone
arn:aws:ec2:region:account:instance/* ec2:CreateAction
arn:aws:ec2:region:account:instance/ ec2:EbsOptimized
instance-id
ec2:InstanceProfile
ec2:InstanceType
ec2:PlacementGroup
ec2:Region
ec2:ResourceTag/tag-key
ec2:RootDeviceType
ec2:Tenancy
aws:RequestTag/tag-key
aws:TagKeys
arn:aws:ec2:region:account:internet- ec2:Region
gateway/*
ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:internet-
gateway/igw-id aws:RequestTag/tag-key
aws:TagKeys
arn:aws:ec2:region:account:launch- ec2:Region
template/*
ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:launch-
template/launch-template-id aws:RequestTag/tag-key
aws:TagKeys
arn:aws:ec2:region:account:natgateway/* ec2:Region
arn:aws:ec2:region:account:natgateway/ ec2:ResourceTag/tag-key
natgateway-id
aws:RequestTag/tag-key
aws:TagKeys
638
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
arn:aws:ec2:region:account:network-acl/* ec2:Region
arn:aws:ec2:region:account:network- ec2:ResourceTag/tag-key
acl/nacl-id
ec2:Vpc
aws:RequestTag/tag-key
aws:TagKeys
arn:aws:ec2:region:account:network- ec2:CreateAction
interface/*
ec2:Region
arn:aws:ec2:region:account:network-
interface/eni-id ec2:Subnet
ec2:ResourceTag/tag-key
ec2:Vpc
aws:RequestTag/tag-key
aws:TagKeys
arn:aws:ec2:region:account:reserved- ec2:CreateAction
instances/*
ec2:InstanceType
arn:aws:ec2:region:account:reserved-
instances/reservation-id ec2:ReservedInstancesOfferingType
ec2:Region
ec2:ResourceTag/tag-key
ec2:Tenancy
aws:RequestTag/tag-key
aws:TagKeys
arn:aws:ec2:region:account:route-table/* ec2:Region
arn:aws:ec2:region:account:route- ec2:ResourceTag/tag-key
table/route-table-id
ec2:Vpc
aws:RequestTag/tag-key
aws:TagKeys
639
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
arn:aws:ec2:region:account:security- ec2:Region
group/*
ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:security-
group/security-group-id ec2:Vpc
aws:RequestTag/tag-key
aws:TagKeys
Snapshot ec2:CreateAction
arn:aws:ec2:region::snapshot/* ec2:Owner
arn:aws:ec2:region::snapshot/snapshot-id ec2:ParentVolume
ec2:Region
ec2:ResourceTag/tag-key
ec2:SnapshotTime
ec2:VolumeSize
aws:RequestTag/tag-key
aws:TagKeys
arn:aws:ec2:region:account:spot- ec2:Region
instances-request/*
ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:spot-
instances-request/spot-instance-request- aws:RequestTag/tag-key
id
aws:TagKeys
Subnet ec2:AvailabilityZone
arn:aws:ec2:region:account:subnet/* ec2:CreateAction
arn:aws:ec2:region:account:subnet/ ec2:Region
subnet-id
ec2:ResourceTag/tag-key
ec2:Vpc
aws:RequestTag/tag-key
aws:TagKeys
640
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
Volume ec2:AvailabilityZone
arn:aws:ec2:region:account:volume/* ec2:CreateAction
arn:aws:ec2:region:account:volume/ ec2:Encrypted
volume-id
ec2:ParentSnapshot
ec2:Region
ec2:ResourceTag/tag-key
ec2:VolumeIops
ec2:VolumeSize
ec2:VolumeType
aws:RequestTag/tag-key
aws:TagKeys
VPC ec2:CreateAction
arn:aws:ec2:region:account:vpc/* ec2:Region
arn:aws:ec2:region:account:vpc/vpc-id ec2:ResourceTag/tag-key
ec2:Tenancy
aws:RequestTag/tag-key
aws:TagKeys
arn:aws:ec2:region:account:vpn- ec2:Region
connection/*
ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:vpn-
connection/vpn-connection-id aws:RequestTag/tag-key
aws:TagKeys
arn:aws:ec2:region:account:vpn-gateway/ ec2:Region
*
ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:vpn-
gateway/vpn-gateway-id aws:RequestTag/tag-key
aws:TagKeys
641
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
arn:aws:ec2:region:account:volume/* ec2:Encrypted
ec2:ParentSnapshot
ec2:Region
ec2:VolumeIops
ec2:VolumeSize
ec2:VolumeType
aws:RequestTag/tag-key
aws:TagKeys
CreateVpcPeeringConnection
VPC ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:vpc/* ec2:Region
arn:aws:ec2:region:account:vpc/vpc-id ec2:Tenancy
arn:aws:ec2:region:account:vpc-peering- ec2:Region
connection/*
ec2:RequesterVpc
arn:aws:ec2:region:account:customer- ec2:ResourceTag/tag-key
gateway/*
arn:aws:ec2:region:account:customer-
gateway/cgw-id
arn:aws:ec2:region:account:dhcp- ec2:ResourceTag/tag-key
options/*
arn:aws:ec2:region:account:dhcp-
options/dhcp-options-id
arn:aws:ec2:region:account:internet- ec2:ResourceTag/tag-key
gateway/*
arn:aws:ec2:region:account:internet-
gateway/igw-id
642
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
arn:aws:ec2:region:account:launch- ec2:ResourceTag/tag-key
template/*
arn:aws:ec2:region:account:launch-
template/launch-template-id
DeleteLaunchTemplateVersions
Launch template ec2:Region
arn:aws:ec2:region:account:launch- ec2:ResourceTag/tag-key
template/*
arn:aws:ec2:region:account:launch-
template/launch-template-id
arn:aws:ec2:region:account:network-acl/* ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:network- ec2:Vpc
acl/nacl-id
arn:aws:ec2:region:account:network-acl/* ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:network- ec2:Vpc
acl/nacl-id
arn:aws:ec2:region:account:route-table/* ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:route- ec2:Vpc
table/route-table-id
arn:aws:ec2:region:account:route-table/* ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:route- ec2:Vpc
table/route-table-id
arn:aws:ec2:region:account:security- ec2:ResourceTag/tag-key
group/security-group-id
ec2:Vpc
643
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
arn:aws:ec2:region::snapshot/* ec2:ParentVolume
arn:aws:ec2:region::snapshot/snapshot-id ec2:Region
ec2:SnapshotTime
ec2:VolumeSize
ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:fpga-image/* ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:fpga- aws:RequestTag/tag-key
image/afi-id
aws:TagKeys
arn:aws:ec2:region:account:dhcp- ec2:ResourceTag/tag-key
options/*
aws:RequestTag/tag-key
arn:aws:ec2:region:account:dhcp-
options/dhcp-options-id aws:TagKeys
Image ec2:Region
arn:aws:ec2:region::image/* ec2:ResourceTag/tag-key
arn:aws:ec2:region::image/image-id aws:RequestTag/tag-key
aws:TagKeys
Instance ec2:Region
arn:aws:ec2:region:account:instance/* ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:instance/ aws:RequestTag/tag-key
instance-id
aws:TagKeys
arn:aws:ec2:region:account:internet- ec2:ResourceTag/tag-key
gateway/*
aws:RequestTag/tag-key
arn:aws:ec2:region:account:internet-
gateway/igw-id aws:TagKeys
arn:aws:ec2:region:account:launch- ec2:ResourceTag/tag-key
template/*
aws:RequestTag/tag-key
arn:aws:ec2:region:account:launch-
template/launch-template-id aws:TagKeys
644
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
arn:aws:ec2:region:account:natgateway/* ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:natgateway/ aws:RequestTag/tag-key
natgateway-id
aws:TagKeys
arn:aws:ec2:region:account:network-acl/* ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:network- aws:RequestTag/tag-key
acl/nacl-id
aws:TagKeys
arn:aws:ec2:region:account:network- ec2:ResourceTag/tag-key
interface/*
aws:RequestTag/tag-key
arn:aws:ec2:region:account:network-
interface/eni-id aws:TagKeys
arn:aws:ec2:region:account:reserved- ec2:ResourceTag/tag-key
instances/*
aws:RequestTag/tag-key
arn:aws:ec2:region:account:reserved-
instances/reservation-id aws:TagKeys
arn:aws:ec2:region:account:route-table/* ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:route- aws:RequestTag/tag-key
table/route-table-id
aws:TagKeys
arn:aws:ec2:region:account:security- ec2:ResourceTag/tag-key
group/*
aws:RequestTag/tag-key
arn:aws:ec2:region:account:security-
group/security-group-id aws:TagKeys
Snapshot ec2:Region
arn:aws:ec2:region::snapshot/* ec2:ResourceTag/tag-key
arn:aws:ec2:region::snapshot/snapshot-id aws:RequestTag/tag-key
aws:TagKeys
645
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
arn:aws:ec2:region:account:spot- ec2:ResourceTag/tag-key
instances-request/*
aws:RequestTag/tag-key
arn:aws:ec2:region:account:spot-
instances-request/spot-instance-request- aws:TagKeys
id
Subnet ec2:Region
arn:aws:ec2:region:account:subnet/* ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:subnet/ aws:RequestTag/tag-key
subnet-id
aws:TagKeys
Volume ec2:Region
arn:aws:ec2:region:account:volume/* ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:volume/ aws:RequestTag/tag-key
volume-id
aws:TagKeys
VPC ec2:Region
arn:aws:ec2:region:account:vpc/* ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:vpc/vpc-id aws:RequestTag/tag-key
aws:TagKeys
arn:aws:ec2:region:account:vpn- ec2:ResourceTag/tag-key
connection/*
aws:RequestTag/tag-key
arn:aws:ec2:region:account:vpn-
connection/vpn-connection-id aws:TagKeys
arn:aws:ec2:region:account:vpn-gateway/ ec2:ResourceTag/tag-key
*
aws:RequestTag/tag-key
arn:aws:ec2:region:account:vpn-
gateway/vpn-gateway-id aws:TagKeys
646
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
arn:aws:ec2:region:account:volume/* ec2:Encrypted
arn:aws:ec2:region:account:volume/ ec2:ParentSnapshot
volume-id
ec2:Region
ec2:ResourceTag/tag-key
ec2:VolumeIops
ec2:VolumeSize
ec2:VolumeType
DeleteVpcPeeringConnection
VPC peering connection ec2:AccepterVpc
arn:aws:ec2:region:account:vpc-peering- ec2:Region
connection/*
ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:vpc-peering-
connection/vpc-peering-connection-id ec2:RequesterVpc
arn:aws:ec2:region:account:instance/* ec2:EbsOptimized
arn:aws:ec2:region:account:instance/ ec2:InstanceProfile
instance-id
ec2:InstanceType
ec2:PlacementGroup
ec2:Region
ec2:ResourceTag/tag-key
ec2:RootDeviceType
ec2:Tenancy
VPC ec2:Region
arn:aws:ec2:region:account:vpc/* ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:vpc/vpc-id ec2:Tenancy
647
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
arn:aws:ec2:region:account:instance/* ec2:EbsOptimized
arn:aws:ec2:region:account:instance/ ec2:InstanceProfile
instance-id
ec2:InstanceType
ec2:PlacementGroup
ec2:Region
ec2:ResourceTag/tag-key
ec2:RootDeviceType
ec2:Tenancy
Volume ec2:AvailabilityZone
arn:aws:ec2:region:account:volume/* ec2:Encrypted
arn:aws:ec2:region:account:volume/ ec2:ParentSnapshot
volume-id
ec2:Region
ec2:ResourceTag/tag-key
ec2:VolumeIops
ec2:VolumeSize
ec2:VolumeType
arn:aws:ec2:region:account:vpc/* ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:vpc/vpc-id ec2:Tenancy
DisassociateIamInstanceProfile
Instance ec2:AvailabilityZone
arn:aws:ec2:region:account:instance/* ec2:EbsOptimized
arn:aws:ec2:region:account:instance/ ec2:InstanceProfile
instance-id
ec2:InstanceType
ec2:PlacementGroup
ec2:Region
ec2:ResourceTag/tag-key
ec2:RootDeviceType
ec2:Tenancy
648
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
arn:aws:ec2:region:account:vpc/* ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:vpc/vpc-id ec2:Tenancy
arn:aws:ec2:region:account:instance/* ec2:EbsOptimized
arn:aws:ec2:region:account:instance/ ec2:InstanceProfile
instance-id
ec2:InstanceType
ec2:PlacementGroup
ec2:Region
ec2:ResourceTag/tag-key
ec2:RootDeviceType
ec2:Tenancy
arn:aws:ec2:region:account:launch- ec2:ResourceTag/tag-key
template/*
arn:aws:ec2:region:account:launch-
template/launch-template-id
arn:aws:ec2:region::snapshot/* ec2:ParentVolume
arn:aws:ec2:region::snapshot/snapshot-id ec2:Region
ec2:SnapshotTime
ec2:VolumeSize
ec2:ResourceTag/tag-key
649
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
arn:aws:ec2:region:account:instance/* ec2:EbsOptimized
arn:aws:ec2:region:account:instance/ ec2:InstanceProfile
instance-id
ec2:InstanceType
ec2:PlacementGroup
ec2:Region
ec2:ResourceTag/tag-key
ec2:RootDeviceType
ec2:Tenancy
RejectVpcPeeringConnection
VPC peering connection ec2:AccepterVpc
arn:aws:ec2:region:account:vpc-peering- ec2:Region
connection/*
ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:vpc-peering-
connection/vpc-peering-connection-id ec2:RequesterVpc
ReplaceIamInstanceProfileAssociation
Instance ec2:AvailabilityZone
arn:aws:ec2:region:account:instance/* ec2:EbsOptimized
arn:aws:ec2:region:account:instance/ ec2:InstanceProfile
instance-id
ec2:InstanceType
ec2:PlacementGroup
ec2:Region
ec2:ResourceTag/tag-key
ec2:RootDeviceType
ec2:Tenancy
arn:aws:ec2:region:account:route-table/* ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:route- ec2:Vpc
table/route-table-id
arn:aws:ec2:region:account:security- ec2:ResourceTag/tag-key
group/*
ec2:Vpc
arn:aws:ec2:region:account:security-
group/security-group-id
650
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
RevokeSecurityGroupIngress
Security group ec2:Region
arn:aws:ec2:region:account:security- ec2:ResourceTag/tag-key
group/*
ec2:Vpc
arn:aws:ec2:region:account:security-
group/security-group-id
arn:aws:ec2:region:account:elastic-gpu/* ec2:IsLaunchTemplateResource
ec2:LaunchTemplate
ec2:Region
Image ec2:ImageType
arn:aws:ec2:region::image/* ec2:IsLaunchTemplateResource
arn:aws:ec2:region::image/image-id ec2:LaunchTemplate
ec2:Owner
ec2:Public
ec2:Region
ec2:RootDeviceType
ec2:ResourceTag/tag-key
Instance ec2:AvailabilityZone
arn:aws:ec2:region:account:instance/* ec2:EbsOptimized
ec2:InstanceMarketType
ec2:InstanceProfile
ec2:InstanceType
ec2:IsLaunchTemplateResource
ec2:LaunchTemplate
ec2:PlacementGroup
ec2:Region
ec2:RootDeviceType
ec2:Tenancy
aws:RequestTag/tag-key
aws:TagKeys
651
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
arn:aws:ec2:region:account:key-pair/* ec2:LaunchTemplate
arn:aws:ec2:region:account:key-pair/key- ec2:Region
pair-name
arn:aws:ec2:region:account:launch- ec2:LaunchTemplate
template/*
ec2:Region
arn:aws:ec2:region:account:launch-
template/launch-template-id
arn:aws:ec2:region:account:network- ec2:IsLaunchTemplateResource
interface/*
ec2:LaunchTemplate
arn:aws:ec2:region:account:network-
interface/eni-id ec2:Region
ec2:Subnet
ec2:ResourceTag/tag-key
ec2:Vpc
arn:aws:ec2:region:account:placement- ec2:LaunchTemplate
group/*
ec2:Region
arn:aws:ec2:region:account:placement-
group/placement-group-name ec2:PlacementGroupStrategy
arn:aws:ec2:region:account:security- ec2:LaunchTemplate
group/*
ec2:Region
arn:aws:ec2:region:account:security-
group/security-group-id ec2:ResourceTag/tag-key
ec2:Vpc
652
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
Snapshot ec2:IsLaunchTemplateResource
arn:aws:ec2:region::snapshot/* ec2:LaunchTemplate
arn:aws:ec2:region::snapshot/snapshot-id ec2:Owner
ec2:ParentVolume
ec2:Region
ec2:SnapshotTime
ec2:ResourceTag/tag-key
ec2:VolumeSize
Subnet ec2:AvailabilityZone
arn:aws:ec2:region:account:subnet/* ec2:IsLaunchTemplateResource
arn:aws:ec2:region:account:subnet/ ec2:LaunchTemplate
subnet-id
ec2:Region
ec2:ResourceTag/tag-key
ec2:Vpc
Volume ec2:AvailabilityZone
arn:aws:ec2:region:account:volume/* ec2:Encrypted
ec2:IsLaunchTemplateResource
ec2:LaunchTemplate
ec2:ParentSnapshot
ec2:Region
ec2:VolumeIops
ec2:VolumeSize
ec2:VolumeType
aws:RequestTag/tag-key
aws:TagKeys
653
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
arn:aws:ec2:region:account:instance/* ec2:EbsOptimized
arn:aws:ec2:region:account:instance/ ec2:InstanceProfile
instance-id
ec2:InstanceType
ec2:PlacementGroup
ec2:Region
ec2:ResourceTag/tag-key
ec2:RootDeviceType
ec2:Tenancy
arn:aws:ec2:region:account:instance/* ec2:EbsOptimized
arn:aws:ec2:region:account:instance/ ec2:InstanceProfile
instance-id
ec2:InstanceType
ec2:PlacementGroup
ec2:Region
ec2:ResourceTag/tag-key
ec2:RootDeviceType
ec2:Tenancy
arn:aws:ec2:region:account:instance/* ec2:EbsOptimized
arn:aws:ec2:region:account:instance/ ec2:InstanceProfile
instance-id
ec2:InstanceType
ec2:PlacementGroup
ec2:Region
ec2:ResourceTag/tag-key
ec2:RootDeviceType
ec2:Tenancy
654
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
UpdateSecurityGroupRuleDescriptionsEgress
Security group ec2:Region
arn:aws:ec2:region:account:security- ec2:ResourceTag/tag-key
group/*
ec2:Vpc
arn:aws:ec2:region:account:security-
group/security-group-id
UpdateSecurityGroupRuleDescriptionsIngress
Security group ec2:Region
arn:aws:ec2:region:account:security- ec2:ResourceTag/tag-key
group/*
ec2:Vpc
arn:aws:ec2:region:account:security-
group/security-group-id
If you are using resource-level permissions, the following table describes the minimum resources
required to use the ec2:RunInstances action.
ec2:InstanceMarketType
ec2:InstanceProfile
ec2:InstanceType
ec2:IsLaunchTemplateResource
ec2:LaunchTemplate
ec2:PlacementGroup
ec2:Region
ec2:RootDeviceType
ec2:Tenancy
655
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
ec2:Owner
ec2:Public
ec2:Region
ec2:RootDeviceType
ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:security-ec2:IsLaunchTemplateResource
group/* (or a specific security
group ID) ec2:LaunchTemplate
ec2:Region
ec2:ResourceTag/tag-key
ec2:Vpc
arn:aws:ec2:region:account:network-
ec2:AvailabilityZone
interface/* (or a specific network
interface ID) ec2:IsLaunchTemplateResource
ec2:LaunchTemplate
ec2:Region
ec2:Subnet
ec2:ResourceTag/tag-key
ec2:Vpc
arn:aws:ec2:region:account:subnet/ec2:AvailabilityZone
* (or a specific subnet ID)
ec2:IsLaunchTemplateResource
ec2:LaunchTemplate
ec2:Region
ec2:ResourceTag/tag-key
ec2:Vpc
656
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
ec2:InstanceMarketType
ec2:InstanceProfile
ec2:InstanceType
ec2:IsLaunchTemplateResource
ec2:LaunchTemplate
ec2:PlacementGroup
ec2:Region
ec2:RootDeviceType
ec2:Tenancy
ec2:LaunchTemplate
ec2:Owner
ec2:Public
ec2:Region
ec2:RootDeviceType
ec2:ResourceTag/tag-key
arn:aws:ec2:region:account:security-ec2:IsLaunchTemplateResource
group/* (or a specific security
group ID) ec2:LaunchTemplate
ec2:Region
ec2:ResourceTag/tag-key
ec2:Vpc
657
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
arn:aws:ec2:region:account:network-
ec2:AvailabilityZone
interface/* (or a specific network
interface ID) ec2:IsLaunchTemplateResource
ec2:LaunchTemplate
ec2:Region
ec2:Subnet
ec2:ResourceTag/tag-key
ec2:Vpc
arn:aws:ec2:region:account:volume/ec2:AvailabilityZone
*
ec2:Encrypted
ec2:IsLaunchTemplateResource
ec2:LaunchTemplate
ec2:ParentSnapshot
ec2:Region
ec2:VolumeIops
ec2:VolumeSize
ec2:VolumeType
arn:aws:ec2:region:account:subnet/ec2:AvailabilityZone
* (or a specific subnet ID)
ec2:IsLaunchTemplateResource
ec2:LaunchTemplate
ec2:Region
ec2:ResourceTag/tag-key
ec2:Vpc
We recommend that you also specify the key pair resource in your policy — even though it's not
required to launch an instance, you can't connect to your instance without a key pair. For examples
of using resource-level permissions with the ec2:RunInstances action, see Launching Instances
(RunInstances) (p. 673).
For additional information about resource-level permissions in Amazon EC2, see the following AWS
Security Blog post: Demystifying EC2 Resource-Level Permissions.
You can create a launch template (p. 403) that contains the parameters to launch an instance.
When users use the ec2:RunInstances action, they can specify the launch template to use to
launch instances. You can apply resource-level permissions for the launch template resource for the
ec2:RunInstances action. For example, you can specify that users can only launch instances using a
658
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
launch template, and that they must use a specific launch template. You can also control the parameters
that users can or cannot override in the launch template. This enables you to manage the parameters for
launching an instance in a launch template rather than an IAM policy. For example policies, see Launch
Templates (p. 681).
To enable users to tag resources on creation, they must have permissions to use the action that creates
the resource (for example, ec2:RunInstances or ec2:CreateVolume). If tags are specified in the
resource-creating action, Amazon performs additional authorization on the ec2:CreateTags action to
verify if users have permissions to create tags. Therefore, users must also have explicit permissions to use
the ec2:CreateTags action.
For the ec2:CreateTags action, you can use the ec2:CreateAction condition key to restrict tagging
permissions to the resource-creating actions only. For example, the following policy allows users to
launch instances and apply any tags to instances and volumes during launch. Users are not permitted to
tag any existing resources (they cannot call the ec2:CreateTags action directly).
{
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:RunInstances"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:region:account:*/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction" : "RunInstances"
}
}
}
]
}
Similarly, the following policy allows users to create volumes and apply any tags to the volumes
during volume creation. Users are not permitted to tag any existing resources (they cannot call the
ec2:CreateTags action directly).
{
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateVolume"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
659
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:region:account:*/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction" : "CreateVolume"
}
}
}
]
}
The ec2:CreateTags action is only evaluated if tags are applied during the resource-creating action.
Therefore, a user that has permissions to create a resource (assuming there are no tagging conditions)
does not require permissions to use the ec2:CreateTags action if no tags are specified in the request.
However, if the user attempts to create a resource with tags, the request fails if the user does not have
permissions to use the ec2:CreateTags action.
The ec2:CreateTags action is also evaluated if tags are provided in a launch template and the launch
template is specified in the ec2:RunInstances action. For an example policy, see Tags in a Launch
Template (p. 680).
You can control the tag keys and values that are applied to resources by using the following condition
keys:
• aws:RequestTag: To indicate that a particular tag key or tag key and value must be present in a
request. Other tags can also be specified in the request.
• Use with the StringEquals condition operator to enforce a specific tag key and value combination,
for example, to enforce the tag cost-center=cc123:
• Use with the StringLike condition operator to enforce a specific tag key in the request; for
example, to enforce the tag key purpose:
• aws:TagKeys: To enforce the tag keys that are used in the request.
• Use with the ForAllValues modifier to enforce specific tag keys if they are provided in the request
(if tags are specified in the request, only specific tag keys are allowed; no other tags are allowed). For
example, the tag keys environment or cost-center are allowed:
• Use with the ForAnyValue modifier to enforce the presence of at least one of the specified tag
keys in the request. For example, at least one of the tag keys environment or webserver must be
present in the request:
These condition keys can be applied to resource-creating actions that support tagging, as well as the
ec2:CreateTags and ec2:DeleteTags actions.
To force users to specify tags when they create a resource, you must use the aws:RequestTag condition
key or the aws:TagKeys condition key with the ForAnyValue modifier on the resource-creating action.
The ec2:CreateTags action is not evaluated if a user does not specify tags for the resource-creating
action.
660
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
For conditions, the condition key is not case-sensitive and the condition value is case-sensitive. Therefore,
to enforce the case-sensitivity of a tag key, use the aws:TagKeys condition key, where the tag key is
specified as a value in the condition.
For more information about multi-value conditions, see Creating a Condition That Tests Multiple Key
Values in the IAM User Guide. For example IAM policies, see Example Policies for Working with the AWS
CLI or an AWS SDK (p. 661).
Example Policies for Working with the AWS CLI or an AWS SDK
The following examples show policy statements that you could use to control the permissions that IAM
users have to Amazon EC2. These policies are designed for requests that are made with the AWS CLI
or an AWS SDK. For example policies for working in the Amazon EC2 console, see Example Policies for
Working in the Amazon EC2 Console (p. 688). For examples of IAM policies specific to Amazon VPC, see
Controlling Access to Amazon VPC Resources.
Examples
• Example: Read-Only Access (p. 661)
• Example: Restricting Access to a Specific Region (p. 662)
• Working with Instances (p. 662)
• Working with Volumes (p. 664)
• Working with Snapshots (p. 666)
• Launching Instances (RunInstances) (p. 673)
• Example: Working with Reserved Instances (p. 683)
• Example: Tagging Resources (p. 684)
• Example: Working with IAM Roles (p. 686)
• Example: Working with Route Tables (p. 687)
• Example: Allowing a Specific Instance to View Resources in Other AWS Services (p. 687)
• Example: Working with Launch Templates (p. 688)
Users don't have permission to perform any actions on the resources (unless another statement grants
them permission to do so) because they're denied permission to use API actions by default.
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "ec2:Describe*",
"Resource": "*"
}
]
}
661
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
{
"Version":"2012-10-17",
"Statement":[
{
"Effect": "Deny",
"Action": "ec2:*",
"Resource": "*",
"Condition": {
"StringNotEquals": {
"aws:RequestedRegion": "eu-central-1"
}
}
}
]
}
Alternatively, you can use the condition key ec2:Region, which is specific to Amazon EC2 and is
supported by all Amazon EC2 API actions.
{
"Version":"2012-10-17",
"Statement":[
{
"Effect": "Deny",
"Action": "ec2:*",
"Resource": "*",
"Condition": {
"StringNotEquals": {
"ec2:Region": "eu-central-1"
}
}
}
]
}
The users don't have permission to use any other API actions (unless another statement grants them
permission to do so) because users are denied permission to use API actions by default.
662
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"ec2:DescribeInstances", "ec2:DescribeImages",
"ec2:DescribeKeyPairs", "ec2:DescribeSecurityGroups",
"ec2:DescribeAvailabilityZones",
"ec2:RunInstances", "ec2:TerminateInstances",
"ec2:StopInstances", "ec2:StartInstances"
],
"Resource": "*"
}
]
}
Example: Describe All Instances, and Stop, Start, and Terminate Only Particular Instances
The following policy allows users to describe all instances, to start and stop only instances
i-1234567890abcdef0 and i-0598c7d356eba48d7, and to terminate only instances in the US East (N.
Virginia) Region (us-east-1) with the resource tag "purpose=test".
The first statement uses a * wildcard for the Resource element to indicate that users can
specify all resources with the action; in this case, they can list all instances. The * wildcard is also
necessary in cases where the API action does not support resource-level permissions (in this case,
ec2:DescribeInstances). For more information about which ARNs you can use with which Amazon
EC2 API actions, see Supported Resource-Level Permissions for Amazon EC2 API Actions (p. 633).
The second statement uses resource-level permissions for the StopInstances and StartInstances
actions. The specific instances are indicated by their ARNs in the Resource element.
The third statement allows users to terminate all instances in the US East (N. Virginia) Region
(us-east-1) that belong to the specified AWS account, but only where the instance has the tag
"purpose=test". The Condition element qualifies when the policy statement is in effect.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ec2:DescribeInstances",
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ec2:StopInstances",
"ec2:StartInstances"
],
"Resource": [
"arn:aws:ec2:us-east-1:123456789012:instance/i-1234567890abcdef0",
"arn:aws:ec2:us-east-1:123456789012:instance/i-0598c7d356eba48d7"
]
},
{
"Effect": "Allow",
"Action": "ec2:TerminateInstances",
"Resource": "arn:aws:ec2:us-east-1:123456789012:instance/*",
"Condition": {
"StringEquals": {
"ec2:ResourceTag/purpose": "test"
}
}
663
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
]
}
When an API action requires a caller to specify multiple resources, you must create a policy statement
that allows users to access all required resources. If you need to use a Condition element with one or
more of these resources, you must create multiple statements as shown in this example.
The following policy allows users to attach volumes with the tag "volume_user=iam-user-name" to
instances with the tag "department=dev", and to detach those volumes from those instances. If you
attach this policy to an IAM group, the aws:username policy variable gives each IAM user in the group
permission to attach or detach volumes from the instances with a tag named volume_user that has his
or her IAM user name as a value.
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"ec2:AttachVolume",
"ec2:DetachVolume"
],
"Resource": "arn:aws:ec2:us-east-1:123456789012:instance/*",
"Condition": {
"StringEquals": {
"ec2:ResourceTag/department": "dev"
}
}
},
{
"Effect": "Allow",
"Action": [
"ec2:AttachVolume",
"ec2:DetachVolume"
],
"Resource": "arn:aws:ec2:us-east-1:123456789012:volume/*",
"Condition": {
"StringEquals": {
"ec2:ResourceTag/volume_user": "${aws:username}"
}
}
}
]
}
The following policy allows users to use the CreateVolume API action. The user is allowed to create a
volume only if the volume is encrypted and only if the volume size is less than 20 GiB.
664
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateVolume"
],
"Resource": "arn:aws:ec2:us-east-1:123456789012:volume/*",
"Condition":{
"NumericLessThan": {
"ec2:VolumeSize" : "20"
},
"Bool":{
"ec2:Encrypted" : "true"
}
}
}
]
}
For resource-creating actions that apply tags, users must also have permissions to use the CreateTags
action. The second statement uses the ec2:CreateAction condition key to allow users to create tags
only in the context of CreateVolume. Users cannot tag existing volumes or any other resources. For
more information, see Resource-Level Permissions for Tagging (p. 659).
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowCreateTaggedVolumes",
"Effect": "Allow",
"Action": "ec2:CreateVolume",
"Resource": "arn:aws:ec2:us-east-1:123456789012:volume/*",
"Condition": {
"StringEquals": {
"aws:RequestTag/costcenter": "115",
"aws:RequestTag/stack": "prod"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": ["costcenter","stack"]
}
}
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:us-east-1:123456789012:volume/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction" : "CreateVolume"
}
}
665
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
}
]
}
The following policy allows users to create a volume without having to specify tags. The CreateTags
action is only evaluated if tags are specified in the CreateVolume request. If users do specify tags, the
tag must be purpose=test. No other tags are allowed in the request.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ec2:CreateVolume",
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:us-east-1:1234567890:volume/*",
"Condition": {
"StringEquals": {
"aws:RequestTag/purpose": "test",
"ec2:CreateAction" : "CreateVolume"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": "purpose"
}
}
}
]
}
Examples
• Example: Creating a Snapshot (p. 666)
• Example: Creating Snapshots (p. 667)
• Example: Creating a Snapshot with Tags (p. 667)
• Example: Creating Snapshots with Tags (p. 668)
• Example: Modifying Permission Settings for Snapshots (p. 673)
The following policy allows customers to use the CreateSnapshot API action. The customer can create
snapshots only if the volume is encrypted and only if the volume size is less than 20 GiB.
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":"ec2:CreateSnapshot",
666
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
"Resource":"arn:aws:ec2:us-east-1::snapshot/*"
},
{
"Effect":"Allow",
"Action":"ec2:CreateSnapshot",
"Resource":"arn:aws:ec2:us-east-1:123456789012:volume/*",
"Condition":{
"NumericLessThan":{
"ec2:VolumeSize":"20"
},
"Bool":{
"ec2:Encrypted":"true"
}
}
}
]
}
The following policy allows customers to use the CreateSnapshots API action. The customer can create
snapshots only if all of the volumes on the instance are type GP2.
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":"ec2:CreateSnapshots",
"Resource":[
"arn:aws:ec2:us-east-1::snapshot/*",
"arn:aws:ec2:*:*:instance/*"
]
},
{
"Effect":"Allow",
"Action":"ec2:CreateSnapshots",
"Resource":"arn:aws:ec2:us-east-1:*:volume/*",
"Condition":{
"StringLikeIfExists":{
"ec2:VolumeType":"gp2"
}
}
}
]
}
The following policy includes the aws:RequestTag condition key that requires the customer to apply
the tags costcenter=115 and stack=prod to any new snapshot. The aws:TagKeys condition
key uses the ForAllValues modifier to indicate that only the keys costcenter and stack can be
specified in the request. The request fails if either of these conditions is not met.
For resource-creating actions that apply tags, customers must also have permissions to use the
CreateTags action. The third statement uses the ec2:CreateAction condition key to allow
customers to create tags only in the context of CreateSnapshot. Customers cannot tag existing
volumes or any other resources. For more information, see Resource-Level Permissions for Tagging.
667
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":"ec2:CreateSnapshot",
"Resource":"arn:aws:ec2:us-east-1:123456789012:volume/*"
},
{
"Sid":"AllowCreateTaggedSnapshots",
"Effect":"Allow",
"Action":"ec2:CreateSnapshot",
"Resource":"arn:aws:ec2:us-east-1::snapshot/*",
"Condition":{
"StringEquals":{
"aws:RequestTag/costcenter":"115",
"aws:RequestTag/stack":"prod"
},
"ForAllValues:StringEquals":{
"aws:TagKeys":[
"costcenter",
"stack"
]
}
}
},
{
"Effect":"Allow",
"Action":"ec2:CreateTags",
"Resource":"arn:aws:ec2:us-east-1::snapshot/*",
"Condition":{
"StringEquals":{
"ec2:CreateAction":"CreateSnapshot"
}
}
}
]
}
The following policy includes the aws:RequestTag condition key that requires the customer to apply
the tags costcenter=115 and stack=prod to any new snapshot. The aws:TagKeys condition
key uses the ForAllValues modifier to indicate that only the keys costcenter and stack can be
specified in the request. The request fails if either of these conditions is not met.
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":"ec2:CreateSnapshots",
"Resource":[
"arn:aws:ec2:us-east-1::snapshot/*",
"arn:aws:ec2:*:*:instance/*",
"arn:aws:ec2:*:*:volume/*"
]
},
{
"Sid":"AllowCreateTaggedSnapshots",
"Effect":"Allow",
"Action":"ec2:CreateSnapshots",
"Resource":"arn:aws:ec2:us-east-1::snapshot/*",
"Condition":{
668
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
"StringEquals":{
"aws:RequestTag/costcenter":"115",
"aws:RequestTag/stack":"prod"
},
"ForAllValues:StringEquals":{
"aws:TagKeys":[
"costcenter",
"stack"
]
}
}
},
{
"Effect":"Allow",
"Action":"ec2:CreateTags",
"Resource":"arn:aws:ec2:us-east-1::snapshot/*",
"Condition":{
"StringEquals":{
"ec2:CreateAction":"CreateSnapshots"
}
}
}
]
}
The following policy allows customers to create a snapshot without having to specify tags.
The CreateTags action is evaluated only if tags are specified in the CreateSnapshot or
CreateSnapshots request. If a tag is specified, the tag must be purpose=test. No other tags are
allowed in the request.
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":"ec2:CreateSnapshot",
"Resource":"*"
},
{
"Effect":"Allow",
"Action":"ec2:CreateTags",
"Resource":"arn:aws:ec2:us-east-1::snapshot/*",
"Condition":{
"StringEquals":{
"aws:RequestTag/purpose":"test",
"ec2:CreateAction":"CreateSnapshot"
},
"ForAllValues:StringEquals":{
"aws:TagKeys":"purpose"
}
}
}
]
}
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":"ec2:CreateSnapshots",
"Resource":"*"
},
669
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
{
"Effect":"Allow",
"Action":"ec2:CreateTags",
"Resource":"arn:aws:ec2:us-east-1::snapshot/*",
"Condition":{
"StringEquals":{
"aws:RequestTag/purpose":"test",
"ec2:CreateAction":"CreateSnapshots"
},
"ForAllValues:StringEquals":{
"aws:TagKeys":"purpose"
}
}
}
]
}
The following policy allows snapshots to be created only if the source volume is tagged with
User:username for the customer, and the snapshot itself is tagged with Environment:Dev and
User:username. The customer can add additional tags to the snapshot.
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":"ec2:CreateSnapshot",
"Resource":"arn:aws:ec2:us-east-1:123456789012:volume/*",
"Condition":{
"StringEquals":{
"ec2:ResourceTag/User":"${aws:username}"
}
}
},
{
"Effect":"Allow",
"Action":"ec2:CreateSnapshot",
"Resource":"arn:aws:ec2:us-east-1::snapshot/*",
"Condition":{
"StringEquals":{
"aws:RequestTag/Environment":"Dev",
"aws:RequestTag/User":"${aws:username}"
}
}
},
{
"Effect":"Allow",
"Action":"ec2:CreateTags",
"Resource":"arn:aws:ec2:us-east-1::snapshot/*"
}
]
}
The following policy for CreateSnapshots allows snapshots to be created only if the source
volume is tagged with User:username for the customer, and the snapshot itself is tagged with
Environment:Dev and User:username.
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":"ec2:CreateSnapshots",
670
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
"Resource":"arn:aws:ec2:us-east-1:*:instance/*",
},
{
"Effect":"Allow",
"Action":"ec2:CreateSnapshots",
"Resource":"arn:aws:ec2:us-east-1:123456789012:volume/*",
"Condition":{
"StringEquals":{
"ec2:ResourceTag/User":"${aws:username}"
}
}
},
{
"Effect":"Allow",
"Action":"ec2:CreateSnapshots",
"Resource":"arn:aws:ec2:us-east-1::snapshot/*",
"Condition":{
"StringEquals":{
"aws:RequestTag/Environment":"Dev",
"aws:RequestTag/User":"${aws:username}"
}
}
},
{
"Effect":"Allow",
"Action":"ec2:CreateTags",
"Resource":"arn:aws:ec2:us-east-1::snapshot/*"
}
]
}
The following policy allows deletion of a snapshot only if the snapshot is tagged with User:username for
the customer.
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":"ec2:DeleteSnapshot",
"Resource":"arn:aws:ec2:us-east-1::snapshot/*",
"Condition":{
"StringEquals":{
"ec2:ResourceTag/User":"${aws:username}"
}
}
}
]
}
The following policy allows a customer to create a snapshot but denies the action if the snapshot being
created has a tag key value=stack.
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"ec2:CreateSnapshot",
"ec2:CreateTags"
],
"Resource":"*"
671
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
},
{
"Effect":"Deny",
"Action":"ec2:CreateSnapshot",
"Resource":"arn:aws:ec2:us-east-1::snapshot/*",
"Condition":{
"ForAnyValue:StringEquals":{
"aws:TagKeys":"stack"
}
}
}
]
}
The following policy allows a customer to create snapshots but denies the action if the snapshots being
created have a tag key value=stack.
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"ec2:CreateSnapshots",
"ec2:CreateTags"
],
"Resource":"*"
},
{
"Effect":"Deny",
"Action":"ec2:CreateSnapshots",
"Resource":"arn:aws:ec2:us-east-1::snapshot/*",
"Condition":{
"ForAnyValue:StringEquals":{
"aws:TagKeys":"stack"
}
}
}
]
}
The following policy allows you to combine multiple actions into a single policy. You can only create a
snapshot (in the context of CreateSnapshots) when the snapshot is created in Region us-east-1. You
can only create snapshots (in the context of CreateSnapshots) when the snapshots are being created
in the Region us-east-1 and when the instance type is t2*.
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"ec2:CreateSnapshots",
"ec2:CreateSnapshot",
"ec2:CreateTags"
],
"Resource": [
"arn:aws:ec2:*:*:instance/*",
"arn:aws:ec2:*:*:snapshot/*",
"arn:aws:ec2:*:*:volume/*"
],
"Condition":{
"StringEqualsIgnoreCase": {
672
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
"ec2:Region": "us-east-1"
},
"StringLikeIfExists": {
"ec2:InstanceType": [
"t2.*"
]
}
}
}
]
}
The following policy allows modification of a snapshot only if the snapshot is tagged with
User:username, where username is the customer's AWS account user name. The request fails if this
condition is not met.
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":"ec2: ModifySnapshotAttribute",
"Resource":"arn:aws:ec2:us-east-1::snapshot/*",
"Condition":{
"StringEquals":{
"ec2:ResourceTag/user-name":"${aws:username}"
}
}
}
]
}
For more information about the resource-level permissions that are required to launch an instance, see
Resource-Level Permissions for RunInstances (p. 655).
By default, users don't have permissions to describe, start, stop, or terminate the resulting instances. One
way to grant the users permission to manage the resulting instances is to create a specific tag for each
instance, and then create a statement that enables them to manage instances with that tag. For more
information, see Working with Instances (p. 662).
Resources
• AMIs (p. 674)
• Instance Types (p. 675)
• Subnets (p. 676)
• EBS Volumes (p. 677)
• Tags (p. 677)
673
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
AMIs
The following policy allows users to launch instances using only the specified AMIs, ami-9e1670f7 and
ami-45cf5c3c. The users can't launch an instance using other AMIs (unless another statement grants
the users permission to do so).
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "ec2:RunInstances",
"Resource": [
"arn:aws:ec2:region::image/ami-9e1670f7",
"arn:aws:ec2:region::image/ami-45cf5c3c",
"arn:aws:ec2:region:account:instance/*",
"arn:aws:ec2:region:account:volume/*",
"arn:aws:ec2:region:account:key-pair/*",
"arn:aws:ec2:region:account:security-group/*",
"arn:aws:ec2:region:account:subnet/*",
"arn:aws:ec2:region:account:network-interface/*"
]
}
]
}
Alternatively, the following policy allows users to launch instances from all AMIs owned by Amazon. The
Condition element of the first statement tests whether ec2:Owner is amazon. The users can't launch
an instance using other AMIs (unless another statement grants the users permission to do so).
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "ec2:RunInstances",
"Resource": [
"arn:aws:ec2:region::image/ami-*"
],
"Condition": {
"StringEquals": {
"ec2:Owner": "amazon"
}
}
},
{
"Effect": "Allow",
"Action": "ec2:RunInstances",
"Resource": [
"arn:aws:ec2:region:account:instance/*",
"arn:aws:ec2:region:account:subnet/*",
"arn:aws:ec2:region:account:volume/*",
"arn:aws:ec2:region:account:network-interface/*",
"arn:aws:ec2:region:account:key-pair/*",
"arn:aws:ec2:region:account:security-group/*"
]
}
]
}
674
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
Instance Types
The following policy allows users to launch instances using only the t2.micro or t2.small instance
type, which you might do to control costs. The users can't launch larger instances because the
Condition element of the first statement tests whether ec2:InstanceType is either t2.micro or
t2.small.
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "ec2:RunInstances",
"Resource": [
"arn:aws:ec2:region:account:instance/*"
],
"Condition": {
"StringEquals": {
"ec2:InstanceType": ["t2.micro", "t2.small"]
}
}
},
{
"Effect": "Allow",
"Action": "ec2:RunInstances",
"Resource": [
"arn:aws:ec2:region::image/ami-*",
"arn:aws:ec2:region:account:subnet/*",
"arn:aws:ec2:region:account:network-interface/*",
"arn:aws:ec2:region:account:volume/*",
"arn:aws:ec2:region:account:key-pair/*",
"arn:aws:ec2:region:account:security-group/*"
]
}
]
}
Alternatively, you can create a policy that denies users permissions to launch any instances except
t2.micro and t2.small instance types.
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Deny",
"Action": "ec2:RunInstances",
"Resource": [
"arn:aws:ec2:region:account:instance/*"
],
"Condition": {
"StringNotEquals": {
"ec2:InstanceType": ["t2.micro", "t2.small"]
}
}
},
{
"Effect": "Allow",
"Action": "ec2:RunInstances",
"Resource": [
"arn:aws:ec2:region::image/ami-*",
"arn:aws:ec2:region:account:network-interface/*",
"arn:aws:ec2:region:account:instance/*",
"arn:aws:ec2:region:account:subnet/*",
"arn:aws:ec2:region:account:volume/*",
"arn:aws:ec2:region:account:key-pair/*",
675
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
"arn:aws:ec2:region:account:security-group/*"
]
}
]
}
Subnets
The following policy allows users to launch instances using only the specified subnet,
subnet-12345678. The group can't launch instances into any another subnet (unless another statement
grants the users permission to do so).
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "ec2:RunInstances",
"Resource": [
"arn:aws:ec2:region:account:subnet/subnet-12345678",
"arn:aws:ec2:region:account:network-interface/*",
"arn:aws:ec2:region:account:instance/*",
"arn:aws:ec2:region:account:volume/*",
"arn:aws:ec2:region::image/ami-*",
"arn:aws:ec2:region:account:key-pair/*",
"arn:aws:ec2:region:account:security-group/*"
]
}
]
}
Alternatively, you could create a policy that denies users permissions to launch an instance into any other
subnet. The statement does this by denying permission to create a network interface, except where
subnet subnet-12345678 is specified. This denial overrides any other policies that are created to allow
launching instances into other subnets.
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Deny",
"Action": "ec2:RunInstances",
"Resource": [
"arn:aws:ec2:region:account:network-interface/*"
],
"Condition": {
"ArnNotEquals": {
"ec2:Subnet": "arn:aws:ec2:region:account:subnet/subnet-12345678"
}
}
},
{
"Effect": "Allow",
"Action": "ec2:RunInstances",
"Resource": [
"arn:aws:ec2:region::image/ami-*",
"arn:aws:ec2:region:account:network-interface/*",
"arn:aws:ec2:region:account:instance/*",
"arn:aws:ec2:region:account:subnet/*",
"arn:aws:ec2:region:account:volume/*",
"arn:aws:ec2:region:account:key-pair/*",
"arn:aws:ec2:region:account:security-group/*"
]
}
676
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
]
}
EBS Volumes
The following policy allows users to launch instances only if the EBS volumes for the instance are
encrypted. The user must launch an instance from an AMI that was created with encrypted snapshots, to
ensure that the root volume is encrypted. Any additional volume that the user attaches to the instance
during launch must also be encrypted.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ec2:RunInstances",
"Resource": [
"arn:aws:ec2:*:*:volume/*"
],
"Condition": {
"Bool": {
"ec2:Encrypted": "true"
}
}
},
{
"Effect": "Allow",
"Action": "ec2:RunInstances",
"Resource": [
"arn:aws:ec2:*::image/ami-*",
"arn:aws:ec2:*:*:network-interface/*",
"arn:aws:ec2:*:*:instance/*",
"arn:aws:ec2:*:*:subnet/*",
"arn:aws:ec2:*:*:key-pair/*",
"arn:aws:ec2:*:*:security-group/*"
]
}
]
}
Tags
The following policy allows users to launch instances and tag the instances during creation. For resource-
creating actions that apply tags, users must have permissions to use the CreateTags action. The second
statement uses the ec2:CreateAction condition key to allow users to create tags only in the context
of RunInstances, and only for instances. Users cannot tag existing resources, and users cannot tag
volumes using the RunInstances request.
For more information, see Resource-Level Permissions for Tagging (p. 659).
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:RunInstances"
],
"Resource": "*"
},
{
677
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:us-east-1:123456789012:instance/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction" : "RunInstances"
}
}
}
]
}
The following policy includes the aws:RequestTag condition key that requires users to tag any
instances and volumes that are created by RunInstances with the tags environment=production
and purpose=webserver. The aws:TagKeys condition key uses the ForAllValues modifier to
indicate that only the keys environment and purpose are allowed in the request (no other tags can be
specified). If no tags are specified in the request, the request fails.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:RunInstances"
],
"Resource": [
"arn:aws:ec2:region::image/*",
"arn:aws:ec2:region:account:subnet/*",
"arn:aws:ec2:region:account:network-interface/*",
"arn:aws:ec2:region:account:security-group/*",
"arn:aws:ec2:region:account:key-pair/*"
]
},
{
"Effect": "Allow",
"Action": [
"ec2:RunInstances"
],
"Resource": [
"arn:aws:ec2:region:account:volume/*",
"arn:aws:ec2:region:account:instance/*"
],
"Condition": {
"StringEquals": {
"aws:RequestTag/environment": "production" ,
"aws:RequestTag/purpose": "webserver"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": ["environment","purpose"]
}
}
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:region:account:*/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction" : "RunInstances"
678
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
}
}
}
]
}
The following policy uses the ForAnyValue modifier on the aws:TagKeys condition to indicate that at
least one tag must be specified in the request, and it must contain the key environment or webserver.
The tag must be applied to both instances and volumes. Any tag values can be specified in the request.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:RunInstances"
],
"Resource": [
"arn:aws:ec2:region::image/*",
"arn:aws:ec2:region:account:subnet/*",
"arn:aws:ec2:region:account:network-interface/*",
"arn:aws:ec2:region:account:security-group/*",
"arn:aws:ec2:region:account:key-pair/*"
]
},
{
"Effect": "Allow",
"Action": [
"ec2:RunInstances"
],
"Resource": [
"arn:aws:ec2:region:account:volume/*",
"arn:aws:ec2:region:account:instance/*"
],
"Condition": {
"ForAnyValue:StringEquals": {
"aws:TagKeys": ["environment","webserver"]
}
}
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:region:account:*/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction" : "RunInstances"
}
}
}
]
}
In the following policy, users do not have to specify tags in the request, but if they do, the tag must be
purpose=test. No other tags are allowed. Users can apply the tags to any taggable resource in the
RunInstances request.
{
"Version": "2012-10-17",
"Statement": [
679
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
{
"Effect": "Allow",
"Action": [
"ec2:RunInstances"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:region:account:*/*",
"Condition": {
"StringEquals": {
"aws:RequestTag/purpose": "test",
"ec2:CreateAction" : "RunInstances"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": "purpose"
}
}
}
]
}
In the following example, users can launch instances, but only if they use a specific launch template
(lt-09477bcd97b0d310e). The ec2:IsLaunchTemplateResource condition key prevents users from
overriding any of the resources specified in the launch template. The second part of the statement allows
users to tag instances on creation—this part of the statement is necessary if tags are specified for the
instance in the launch template.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ec2:RunInstances",
"Resource": "*",
"Condition": {
"ArnLike": {
"ec2:LaunchTemplate": "arn:aws:ec2:region:account:launch-template/
lt-09477bcd97b0d310e"
},
"Bool": {
"ec2:IsLaunchTemplateResource": "true"
}
}
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:region:account:instance/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction" : "RunInstances"
}
}
}
]
680
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
Elastic GPUs
In the following policy, users can launch an instance and specify an elastic GPU to attach to the instance.
Users can launch instances in any region, but they can only attach an elastic GPU during a launch in the
us-east-2 region.
The ec2:ElasticGpuType condition key uses the ForAnyValue modifier to indicate that only the
elastic GPU types eg1.medium and eg1.large are allowed in the request.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:RunInstances"
],
"Resource": [
"arn:aws:ec2:*:account:elastic-gpu/*"
],
"Condition": {
"StringEquals": {
"ec2:Region": "us-east-2"
},
"ForAnyValue:StringLike": {
"ec2:ElasticGpuType": [
"eg1.medium",
"eg1.large"
]
}
}
},
{
"Effect": "Allow",
"Action": "ec2:RunInstances",
"Resource": [
"arn:aws:ec2:*::image/ami-*",
"arn:aws:ec2:*:account:network-interface/*",
"arn:aws:ec2:*:account:instance/*",
"arn:aws:ec2:*:account:subnet/*",
"arn:aws:ec2:*:account:volume/*",
"arn:aws:ec2:*:account:key-pair/*",
"arn:aws:ec2:*:account:security-group/*"
]
}
]
}
Launch Templates
In the following example, users can launch instances, but only if they use a specific launch template
(lt-09477bcd97b0d310e). Users can override any parameters in the launch template by specifying the
parameters in the RunInstances action.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ec2:RunInstances",
681
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
"Resource": "*",
"Condition": {
"ArnLike": {
"ec2:LaunchTemplate": "arn:aws:ec2:region:account:launch-template/
lt-09477bcd97b0d310e"
}
}
}
]
}
In this example, users can launch instances only if they use a launch template. The policy uses the
ec2:IsLaunchTemplateResource condition key to prevent users from overriding any of the launch
template resources in the RunInstances request.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ec2:RunInstances",
"Resource": "*",
"Condition": {
"ArnLike": {
"ec2:LaunchTemplate": "arn:aws:ec2:region:account:launch-template/*"
},
"Bool": {
"ec2:IsLaunchTemplateResource": "true"
}
}
}
]
}
The following example policy allows user to launch instances, but only if they use a launch template.
Users cannot override the subnet and network interface parameters in the request; these parameters
can only be specified in the launch template. The first part of the statement uses the NotResource
element to allow all other resources except subnets and network interfaces. The second part of the
statement allows the subnet and network interface resources, but only if they are sourced from the
launch template.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ec2:RunInstances",
"NotResource": ["arn:aws:ec2:region:account:subnet/*",
"arn:aws:ec2:region:account:network-interface/*" ],
"Condition": {
"ArnLike": {
"ec2:LaunchTemplate": "arn:aws:ec2:region:account:launch-template/*"
}
}
},
{
"Effect": "Allow",
"Action": "ec2:RunInstances",
"Resource": ["arn:aws:ec2:region:account:subnet/*",
"arn:aws:ec2:region:account:network-interface/*" ],
"Condition": {
"ArnLike": {
682
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
"ec2:LaunchTemplate": "arn:aws:ec2:region:account:launch-template/*"
},
"Bool": {
"ec2:IsLaunchTemplateResource": "true"
}
}
}
]
}
The following example allows users to launch instances only if they use a launch template, and only
if the launch template has the tag Purpose=Webservers. Users cannot override any of the launch
template parameters in the RunInstances action.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ec2:RunInstances",
"NotResource": "arn:aws:ec2:region:account:launch-template/*",
"Condition": {
"ArnLike": {
"ec2:LaunchTemplate": "arn:aws:ec2:region:account:launch-template/*"
},
"Bool": {
"ec2:IsLaunchTemplateResource": "true"
}
}
},
{
"Effect": "Allow",
"Action": "ec2:RunInstances",
"Resource": "arn:aws:ec2:region:account:launch-template/*",
"Condition": {
"StringEquals": {
"ec2:ResourceTag/Purpose": "Webservers"
}
}
}
]
}
It is not possible to set resource-level permissions for individual Reserved Instances. This policy means
that users have access to all the Reserved Instances in the account.
The Resource element uses a * wildcard to indicate that users can specify all resources with the action;
in this case, they can list and modify all Reserved Instances in the account. They can also purchase
Reserved Instances using the account credentials. The * wildcard is also necessary in cases where the API
action does not support resource-level permissions.
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"ec2:DescribeReservedInstances", "ec2:ModifyReservedInstances",
683
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
"ec2:PurchaseReservedInstancesOffering", "ec2:DescribeAvailabilityZones",
"ec2:DescribeReservedInstancesOfferings"
],
"Resource": "*"
}
]
}
To allow users to view and modify the Reserved Instances in your account, but not purchase new
Reserved Instances.
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"ec2:DescribeReservedInstances", "ec2:ModifyReservedInstances",
"ec2:DescribeAvailabilityZones"
],
"Resource": "*"
}
]
}
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:region:account:instance/*",
"Condition": {
"StringEquals": {
"aws:RequestTag/environment": "production"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"environment"
]
}
}
}
]
}
The following policy allows users to tag any taggable resource that already has a tag with a key of owner
and a value of the IAM username. In addition, users must specify a tag with a key of environment and a
value of either test or prod in the request. Users can specify additional tags in the request.
{
"Version": "2012-10-17",
684
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:region:account:*/*",
"Condition": {
"StringEquals": {
"aws:RequestTag/environment": ["test","prod"],
"ec2:ResourceTag/owner": "${aws:username}"
}
}
}
]
}
You can create an IAM policy that allows users to delete specific tags for a resource. For example, the
following policy allows users to delete tags for a volume if the tag keys specified in the request are
environment or cost-center. Any value can be specified for the tag but the tag key must match
either of the specified keys.
Note
If you delete a resource, all tags associated with the resource are also deleted. Users do not need
permissions to use the ec2:DeleteTags action to delete a resource that has tags; they only
need permissions to perform the deleting action.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ec2:DeleteTags",
"Resource": "arn:aws:ec2:us-east-1:123456789012:volume/*",
"Condition": {
"ForAllValues:StringEquals": {
"aws:TagKeys": ["environment","cost-center"]
}
}
}
]
}
This policy allows users to delete only the environment=prod tag on any resource, and only if the
resource is already tagged with a key of owner and a value of the IAM username. Users cannot delete
any other tags for a resource.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:DeleteTags"
],
"Resource": "arn:aws:ec2:region:account:*/*",
"Condition": {
"StringEquals": {
"aws:RequestTag/environment": "prod",
"ec2:ResourceTag/owner": "${aws:username}"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": ["environment"]
685
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
}
}
}
]
}
IAM users must have permission to use the iam:PassRole action in order to pass the role to the
instance.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:AssociateIamInstanceProfile",
"ec2:ReplaceIamInstanceProfileAssociation",
"ec2:DisassociateIamInstanceProfile"
],
"Resource": "arn:aws:ec2:region:account:instance/*",
"Condition": {
"StringEquals": {
"ec2:ResourceTag/department":"test"
}
}
},
{
"Effect": "Allow",
"Action": "ec2:DescribeIamInstanceProfileAssociations",
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "*"
}
]
}
The following policy allows users to attach or replace an IAM role for any instance. Users can only attach
or replace IAM roles with names that begin with TestRole-. For the iam:PassRole action, ensure that
you specify the name of the IAM role and not the instance profile (if the names are different). For more
information, see Instance Profiles (p. 697).
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:AssociateIamInstanceProfile",
"ec2:ReplaceIamInstanceProfileAssociation"
],
"Resource": "*"
},
686
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
{
"Effect": "Allow",
"Action": "ec2:DescribeIamInstanceProfileAssociations",
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::account:role/TestRole-*"
}
]
}
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:DeleteRoute",
"ec2:CreateRoute",
"ec2:ReplaceRoute"
],
"Resource": [
"arn:aws:ec2:region:account:route-table/*"
],
"Condition": {
"StringEquals": {
"ec2:Vpc": "arn:aws:ec2:region:account:vpc/vpc-ec43eb89"
}
}
}
]
}
The ec2:SourceInstanceARN key is an AWS-wide condition key, therefore it can be used for other
service actions, not just Amazon EC2.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:DescribeVolumes",
"s3:ListAllMyBuckets",
"dynamodb:ListTables",
687
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
"rds:DescribeDBInstances"
],
"Resource": [
"*"
],
"Condition": {
"ArnEquals": {
"ec2:SourceInstanceARN": "arn:aws:ec2:region:account:instance/
i-093452212644b0dd6"
}
}
}
]
}
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"ec2:CreateLaunchTemplateVersion",
"ec2:ModifyLaunchTemplate"
],
"Effect": "Allow",
"Resource": "arn:aws:ec2:region:account:launch-template/lt-09477bcd97b0d3abc"
}
]
}
The following policy allows users to delete any launch template and launch template version, provided
that the launch template has the tag Purpose=Testing.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"ec2:DeleteLaunchTemplate",
"ec2:DeleteLaunchTemplateVersions"
],
"Effect": "Allow",
"Resource": "arn:aws:ec2:region:account:launch-template/*",
"Condition": {
"StringEquals": {
"ec2:ResourceTag/Purpose": "Testing"
}
}
}
]
}
688
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
designed for requests that are made with the AWS CLI or an AWS SDK. The console uses additional
API actions for its features, so these policies may not work as expected. For example, a user that has
permission to use only the DescribeVolumes API action will encounter errors when trying to view
volumes in the console. This section demonstrates policies that enable users to work with specific parts
of the console.
Tip
To help you work out which API actions are required to perform tasks in the console, you can
use a service such as AWS CloudTrail. For more information, see the AWS CloudTrail User Guide.
If your policy does not grant permission to create or modify a specific resource, the console
displays an encoded message with diagnostic information. You can decode the message using
the DecodeAuthorizationMessage API action for AWS STS, or the decode-authorization-message
command in the AWS CLI.
Examples
• Example: Read-Only Access (p. 689)
• Example: Using the EC2 Launch Wizard (p. 690)
• Example: Working with Volumes (p. 692)
• Example: Working with Security Groups (p. 693)
• Example: Working with Elastic IP Addresses (p. 695)
• Example: Working with Reserved Instances (p. 695)
For additional information about creating policies for the Amazon EC2 console, see the following AWS
Security Blog post: Granting Users Permission to Work in the Amazon EC2 Console.
Alternatively, you can provide read-only access to a subset of resources. To do this, replace the *
wildcard in the ec2:Describe API action with specific ec2:Describe actions for each resource. The
following policy allows users to view all instances, AMIs, and snapshots in the Amazon EC2 console.
The ec2:DescribeTags action allows users to view public AMIs. The console requires the tagging
information to display public AMIs; however, you can remove this action to allow users to view only
private AMIs.
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"ec2:DescribeInstances", "ec2:DescribeImages",
"ec2:DescribeTags", "ec2:DescribeSnapshots"
],
"Resource": "*"
}
]
}
Note
The Amazon EC2 ec2:Describe* API actions do not support resource-level permissions, so
you cannot control which individual resources users can view in the console. Therefore, the *
689
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
wildcard is necessary in the Resource element of the above statement. For more information
about which ARNs you can use with which Amazon EC2 API actions, see Supported Resource-
Level Permissions for Amazon EC2 API Actions (p. 633).
The following policy allows users to view instances in the Amazon EC2 console, as well as CloudWatch
alarms and metrics in the Monitoring tab of the Instances page. The Amazon EC2 console uses the
CloudWatch API to display the alarms and metrics, so you must grant users permission to use the
cloudwatch:DescribeAlarms and cloudwatch:GetMetricStatistics actions.
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"ec2:DescribeInstances",
"cloudwatch:DescribeAlarms",
"cloudwatch:GetMetricStatistics"
],
"Resource": "*"
}
]
}
To complete a launch successfully, users must be given permission to use the ec2:RunInstances API
action, and at least the following API actions:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"ec2:DescribeInstances", "ec2:DescribeImages",
"ec2:DescribeKeyPairs","ec2:DescribeVpcs", "ec2:DescribeSubnets",
"ec2:DescribeSecurityGroups"
],
"Resource": "*"
},
{
"Effect": "Allow",
690
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
"Action": "ec2:RunInstances",
"Resource": "*"
}
]
}
You can add API actions to your policy to provide more options for users, for example:
Currently, the Amazon EC2 Describe* API actions do not support resource-level permissions, so you
cannot restrict which individual resources users can view in the launch wizard. However, you can apply
resource-level permissions on the ec2:RunInstances API action to restrict which resources users can
use to launch an instance. The launch fails if users select options that they are not authorized to use.
The following policy allows users to launch m1.small instances using AMIs owned by Amazon, and only
into a specific subnet (subnet-1a2b3c4d). Users can only launch in the sa-east-1 region. If users select
a different region, or select a different instance type, AMI, or subnet in the launch wizard, the launch
fails.
The first statement grants users permission to view the options in the launch wizard, as demonstrated in
the example above. The second statement grants users permission to use the network interface, volume,
key pair, security group, and subnet resources for the ec2:RunInstances action, which are required to
launch an instance into a VPC. For more information about using the ec2:RunInstances action, see
Launching Instances (RunInstances) (p. 673). The third and fourth statements grant users permission
to use the instance and AMI resources respectively, but only if the instance is an m1.small instance, and
only if the AMI is owned by Amazon.
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"ec2:DescribeInstances", "ec2:DescribeImages",
"ec2:DescribeKeyPairs","ec2:DescribeVpcs", "ec2:DescribeSubnets",
"ec2:DescribeSecurityGroups"
],
"Resource": "*"
},
691
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
{
"Effect": "Allow",
"Action":"ec2:RunInstances",
"Resource": [
"arn:aws:ec2:sa-east-1:111122223333:network-interface/*",
"arn:aws:ec2:sa-east-1:111122223333:volume/*",
"arn:aws:ec2:sa-east-1:111122223333:key-pair/*",
"arn:aws:ec2:sa-east-1:111122223333:security-group/*",
"arn:aws:ec2:sa-east-1:111122223333:subnet/subnet-1a2b3c4d"
]
},
{
"Effect": "Allow",
"Action": "ec2:RunInstances",
"Resource": [
"arn:aws:ec2:sa-east-1:111122223333:instance/*"
],
"Condition": {
"StringEquals": {
"ec2:InstanceType": "m1.small"
}
}
},
{
"Effect": "Allow",
"Action": "ec2:RunInstances",
"Resource": [
"arn:aws:ec2:sa-east-1::image/ami-*"
],
"Condition": {
"StringEquals": {
"ec2:Owner": "amazon"
}
}
}
]
}
Users can attach any volume to instances that have the tag "purpose=test", and also detach volumes
from those instances. To attach a volume using the Amazon EC2 console, it is helpful for users to have
permission to use the ec2:DescribeInstances action, as this allows them to select an instance from a
pre-populated list in the Attach Volume dialog box. However, this also allows users to view all instances
on the Instances page in the console, so you can omit this action.
In the first statement, the ec2:DescribeAvailabilityZones action is necessary to ensure that a user
can select an Availability Zone when creating a volume.
Users cannot tag the volumes that they create (either during or after volume creation).
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"ec2:DescribeVolumes",
"ec2:DescribeAvailabilityZones",
"ec2:CreateVolume",
"ec2:DescribeInstances"
692
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ec2:AttachVolume",
"ec2:DetachVolume"
],
"Resource": "arn:aws:ec2:region:111122223333:instance/*",
"Condition": {
"StringEquals": {
"ec2:ResourceTag/purpose": "test"
}
}
},
{
"Effect": "Allow",
"Action": [
"ec2:AttachVolume",
"ec2:DetachVolume"
],
"Resource": "arn:aws:ec2:region:111122223333:volume/*"
}
]
}
The following policy grants users permission to view security groups in the Amazon EC2 console,
and to add and remove inbound and outbound rules for existing security groups that have the tag
Department=Test.
In the first statement, the ec2:DescribeTags action allows users to view tags in the console, which
makes it easier for users to identify the security groups that they are allowed to modify.
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"ec2:DescribeSecurityGroups", "ec2:DescribeTags"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ec2:AuthorizeSecurityGroupIngress", "ec2:RevokeSecurityGroupIngress",
"ec2:AuthorizeSecurityGroupEgress", "ec2:RevokeSecurityGroupEgress"
],
"Resource": [
"arn:aws:ec2:region:111122223333:security-group/*"
],
"Condition": {
"StringEquals": {
"ec2:ResourceTag/Department": "Test"
}
}
}
]
693
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
You can create a policy that allows users to work with the Create Security Group dialog box in the
Amazon EC2 console. To use this dialog box, users must be granted permission to use at the least the
following API actions:
With these permissions, users can create a new security group successfully, but they cannot add any rules
to it. To work with rules in the Create Security Group dialog box, you can add the following API actions
to your policy:
Currently, the ec2:CreateSecurityGroup API action does not support resource-level permissions;
however, you can apply resource-level permissions to the ec2:AuthorizeSecurityGroupIngress
and ec2:AuthorizeSecurityGroupEgress actions to control how users can create rules.
The following policy grants users permission to use the Create Security Group dialog box, and to create
inbound and outbound rules for security groups that are associated with a specific VPC (vpc-1a2b3c4d).
Users can create security groups for EC2-Classic or another VPC, but they cannot add any rules to them.
Similarly, users cannot add any rules to any existing security group that's not associated with VPC
vpc-1a2b3c4d. Users are also granted permission to view all security groups in the console. This makes
it easier for users to identify the security groups to which they can add inbound rules. This policy also
grants users permission to delete security groups that are associated with VPC vpc-1a2b3c4d.
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"ec2:DescribeSecurityGroups", "ec2:CreateSecurityGroup", "ec2:DescribeVpcs"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ec2:DeleteSecurityGroup", "ec2:AuthorizeSecurityGroupIngress",
"ec2:AuthorizeSecurityGroupEgress"
694
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Policies
],
"Resource": "arn:aws:ec2:region:111122223333:security-group/*",
"Condition":{
"ArnEquals": {
"ec2:Vpc": "arn:aws:ec2:region:111122223333:vpc/vpc-1a2b3c4d"
}
}
}
]
}
To allow users to work with Elastic IP addresses, you can add the following actions to your policy.
The following policy allows users to view, allocate, and associate Elastic IP addresses with instances.
Users cannot associate Elastic IP addresses with network interfaces, disassociate Elastic IP addresses, or
release them.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:DescribeAddresses",
"ec2:AllocateAddress",
"ec2:DescribeInstances",
"ec2:AssociateAddress"
],
"Resource": "*"
}
]
}
This policy allows users to view all the Reserved Instances, as well as On-Demand Instances, in the
account. It's not possible to set resource-level permissions for individual Reserved Instances.
{
"Version": "2012-10-17",
"Statement": [{
695
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Roles
"Effect": "Allow",
"Action": [
"ec2:DescribeReservedInstances", "ec2:ModifyReservedInstances",
"ec2:PurchaseReservedInstancesOffering", "ec2:DescribeInstances",
"ec2:DescribeAvailabilityZones", "ec2:DescribeReservedInstancesOfferings"
],
"Resource": "*"
}
]
}
The ec2:DescribeAvailabilityZones action is necessary to ensure that the Amazon EC2 console
can display information about the Availability Zones in which you can purchase Reserved Instances. The
ec2:DescribeInstances action is not required, but ensures that the user can view the instances in the
account and purchase reservations to match the correct specifications.
You can adjust the API actions to limit user access, for example removing ec2:DescribeInstances
and ec2:DescribeAvailabilityZones means the user has read-only access.
We designed IAM roles so that your applications can securely make API requests from your instances,
without requiring you to manage the security credentials that the applications use. Instead of creating
and distributing your AWS credentials, you can delegate permission to make API requests using IAM roles
as follows:
For example, you can use IAM roles to grant permissions to applications running on your instances that
need to use a bucket in Amazon S3. You can specify permissions for IAM roles by creating a policy in
JSON format. These are similar to the policies that you create for IAM users. If you change a role, the
change is propagated to all instances.
You cannot attach multiple IAM roles to a single instance, but you can attach a single IAM role to
multiple instances. For more information about creating and using IAM roles, see Roles in the IAM User
Guide.
You can apply resource-level permissions to your IAM policies to control the users' ability to attach,
replace, or detach IAM roles for an instance. For more information, see Supported Resource-Level
Permissions for Amazon EC2 API Actions (p. 633) and the following example: Example: Working with
IAM Roles (p. 686).
Topics
• Instance Profiles (p. 697)
696
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Roles
Instance Profiles
Amazon EC2 uses an instance profile as a container for an IAM role. When you create an IAM role using
the IAM console, the console creates an instance profile automatically and gives it the same name as the
role to which it corresponds. If you use the Amazon EC2 console to launch an instance with an IAM role
or to attach an IAM role to an instance, you choose the role based on a list of instance profile names.
If you use the AWS CLI, API, or an AWS SDK to create a role, you create the role and instance profile as
separate actions, with potentially different names. If you then use the AWS CLI, API, or an AWS SDK to
launch an instance with an IAM role or to attach an IAM role to an instance, specify the instance profile
name.
An instance profile can contain only one IAM role. This limit cannot be increased.
For more information, see Instance Profiles in the IAM User Guide.
The following command retrieves the security credentials for an IAM role named s3access.
curl http://169.254.169.254/latest/meta-data/iam/security-credentials/s3access
{
"Code" : "Success",
"LastUpdated" : "2012-04-26T16:39:16Z",
"Type" : "AWS-HMAC",
"AccessKeyId" : "ASIAIOSFODNN7EXAMPLE",
"SecretAccessKey" : "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"Token" : "token",
"Expiration" : "2017-05-17T15:09:54Z"
}
For applications, AWS CLI, and Tools for Windows PowerShell commands that run on the instance, you
do not have to explicitly get the temporary security credentials — the AWS SDKs, AWS CLI, and Tools for
Windows PowerShell automatically get the credentials from the EC2 instance metadata service and use
them. To make a call outside of the instance using temporary security credentials (for example, to test
IAM policies), you must provide the access key, secret key, and the session token. For more information,
see Using Temporary Security Credentials to Request Access to AWS Resources in the IAM User Guide.
697
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Roles
For more information about instance metadata, see Instance Metadata and User Data (p. 526).
The following IAM policy grants users permission to launch instances (ec2:RunInstances)
with an IAM role, or to attach or replace an IAM role for an existing instance
(ec2:AssociateIamInstanceProfile and ec2:ReplaceIamInstanceProfileAssociation).
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:RunInstances",
"ec2:AssociateIamInstanceProfile",
"ec2:ReplaceIamInstanceProfileAssociation"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "*"
}
]
}
This policy grants IAM users access to all your roles by specifying the resource as "*" in the policy.
However, consider whether users who launch instances with your roles (ones that exist or that you create
later on) might be granted permissions that they don't need or shouldn't have.
Contents
• Creating an IAM Role (p. 698)
• Launching an Instance with an IAM Role (p. 700)
• Attaching an IAM Role to an Instance (p. 701)
• Replacing an IAM Role (p. 702)
• Detaching an IAM Role (p. 703)
698
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Roles
3. On the Select role type page, choose EC2 and the EC2 use case. Choose Next: Permissions.
4. On the Attach permissions policy page, select an AWS managed policy that grants your instances
access to the resources that they need.
5. On the Review page, type a name for the role and choose Create role.
Alternatively, you can use the AWS CLI to create an IAM role.
• Create an IAM role with a policy that allows the role to use an Amazon S3 bucket.
a. Create the following trust policy and save it in a text file named ec2-role-trust-
policy.json.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": { "Service": "ec2.amazonaws.com"},
"Action": "sts:AssumeRole"
}
]
}
b. Create the s3access role and specify the trust policy that you created.
c. Create an access policy and save it in a text file named ec2-role-access-policy.json. For
example, this policy grants administrative permissions for Amazon S3 to applications running
on the instance.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:*"],
699
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Roles
"Resource": ["*"]
}
]
}
For more information about these commands, see create-role, put-role-policy, and create-instance-
profile in the AWS CLI Command Reference.
Alternatively, you can use the following AWS Tools for Windows PowerShell commands:
• New-IAMRole
• Register-IAMRolePolicy
• New-IAMInstanceProfile
700
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Roles
was created for you and given the same name as the role. If you created your IAM role using
the AWS CLI, API, or an AWS SDK, you may have named your instance profile differently.
5. Configure any other details, then follow the instructions through the rest of the wizard, or choose
Review and Launch to accept default settings and go directly to the Review Instance Launch page.
6. Review your settings, then choose Launch to choose a key pair and launch your instance.
7. If you are using the Amazon EC2 API actions in your application, retrieve the AWS security
credentials made available on the instance and use them to sign the requests. The AWS SDK does
this for you.
curl http://169.254.169.254/latest/meta-data/iam/security-credentials/role_name
Alternatively, you can use the AWS CLI to associate a role with an instance during launch. You must
specify the instance profile in the command.
1. Use the run-instances command to launch an instance using the instance profile. The following
example shows how to launch an instance with the instance profile.
curl http://169.254.169.254/latest/meta-data/iam/security-credentials/role_name
1. If required, describe your instances to get the ID of the instance to which to attach the role.
2. Use the associate-iam-instance-profile command to attach the IAM role to the instance by specifying
the instance profile. You can use the Amazon Resource Name (ARN) of the instance profile, or you
can use its name.
701
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Roles
{
"IamInstanceProfileAssociation": {
"InstanceId": "i-1234567890abcdef0",
"State": "associating",
"AssociationId": "iip-assoc-0dbd8529a48294120",
"IamInstanceProfile": {
"Id": "AIPAJLNLDX3AMYZNWYYAY",
"Arn": "arn:aws:iam::123456789012:instance-profile/TestRole-1"
}
}
}
• Get-EC2Instance
• Register-EC2IamInstanceProfile
1. If required, describe your IAM instance profile associations to get the association ID for the IAM
instance profile to replace.
{
"IamInstanceProfileAssociation": {
"InstanceId": "i-087711ddaf98f9489",
"State": "associating",
"AssociationId": "iip-assoc-09654be48e33b91e0",
"IamInstanceProfile": {
"Id": "AIPAJCJEDKX7QYHWYK7GS",
702
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IAM Roles
"Arn": "arn:aws:iam::123456789012:instance-profile/TestRole-2"
}
}
}
• Get-EC2IamInstanceProfileAssociation
• Set-EC2IamInstanceProfileAssociation
{
"IamInstanceProfileAssociations": [
{
"InstanceId": "i-088ce778fbfeb4361",
"State": "associated",
"AssociationId": "iip-assoc-0044d817db6c0a4ba",
"IamInstanceProfile": {
"Id": "AIPAJEDNCAA64SSD265D6",
"Arn": "arn:aws:iam::123456789012:instance-profile/TestRole-2"
}
}
]
}
2. Use the disassociate-iam-instance-profile command to detach the IAM instance profile using its
association ID.
{
"IamInstanceProfileAssociation": {
"InstanceId": "i-087711ddaf98f9489",
"State": "disassociating",
"AssociationId": "iip-assoc-0044d817db6c0a4ba",
"IamInstanceProfile": {
"Id": "AIPAJEDNCAA64SSD265D6",
"Arn": "arn:aws:iam::123456789012:instance-profile/TestRole-2"
}
703
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Network Access
}
}
• Get-EC2IamInstanceProfileAssociation
• Unregister-EC2IamInstanceProfile
Your default security groups and newly created security groups include default rules that do not
enable you to access your instance from the Internet. For more information, see Default Security
Groups (p. 611) and Custom Security Groups (p. 611). To enable network access to your instance, you
must allow inbound traffic to your instance. To open a port for inbound traffic, add a rule to a security
group that you associated with your instance when you launched it.
To connect to your instance, you must set up a rule to authorize SSH traffic from your computer's public
IPv4 address. To allow SSH traffic from additional IP address ranges, add another rule for each range you
need to authorize.
If you've enabled your VPC for IPv6 and launched your instance with an IPv6 address, you can connect to
your instance using its IPv6 address instead of a public IPv4 address. Your local computer must have an
IPv6 address and must be configured to use IPv6.
If you need to enable network access to a Windows instance, see Authorizing Inbound Traffic for Your
Windows Instances in the Amazon EC2 User Guide for Windows Instances.
For more information about security groups, see Amazon EC2 Security Groups for Linux
Instances (p. 607).
704
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Network Access
To add a rule to a security group for inbound SSH traffic over IPv4 (console)
1. In the navigation pane of the Amazon EC2 console, choose Instances. Select your instance and
look at the Description tab; Security groups lists the security groups that are associated with the
instance. Choose view inbound rules to display a list of the rules that are in effect for the instance.
2. In the navigation pane, choose Security Groups. Select one of the security groups associated with
your instance.
3. In the details pane, on the Inbound tab, choose Edit. In the dialog, choose Add Rule, and then
choose SSH from the Type list.
4. In the Source field, choose My IP to automatically populate the field with the public IPv4 address
of your local computer. Alternatively, choose Custom and specify the public IPv4 address of your
computer or network in CIDR notation. For example, if your IPv4 address is 203.0.113.25, specify
203.0.113.25/32 to list this single IPv4 address in CIDR notation. If your company allocates
addresses from a range, specify the entire range, such as 203.0.113.0/24.
For information about finding your IP address, see Before You Start (p. 704).
5. Choose Save.
If you launched an instance with an IPv6 address and want to connect to your instance using its IPv6
address, you must add rules that allow inbound IPv6 traffic over SSH.
To add a rule to a security group for inbound SSH traffic over IPv6 (console)
Note
Be sure to run the following commands on your local system, not on the instance itself. For
more information about these command line interfaces, see Accessing Amazon EC2 (p. 3).
1. Find the security group that is associated with your instance using one of the following commands:
Both commands return a security group ID, which you use in the next step.
2. Add the rule to the security group using one of the following commands:
705
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance IP Addressing
After you launch an instance, you can change its security groups. For more information, see Changing an
Instance's Security Groups in the Amazon VPC User Guide.
Contents
• Private IPv4 Addresses and Internal DNS Hostnames (p. 706)
• Public IPv4 Addresses and External DNS Hostnames (p. 707)
• Elastic IP Addresses (IPv4) (p. 708)
• Amazon DNS Server (p. 708)
• IPv6 Addresses (p. 708)
• Working with IP Addresses for Your Instance (p. 709)
• Multiple IP Addresses (p. 713)
706
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Public IPv4 Addresses and External DNS Hostnames
Note
You can create a VPC with a publicly routable CIDR block that falls outside of the private IPv4
address ranges specified in RFC 1918. However, for the purposes of this documentation, we refer
to private IPv4 addresses (or 'private IP addresses') as the IP addresses that are within the IPv4
CIDR range of your VPC.
When you launch an instance, we allocate a primary private IPv4 address for the instance. Each instance
is also given an internal DNS hostname that resolves to the primary private IPv4 address; for example,
ip-10-251-50-12.ec2.internal. You can use the internal DNS hostname for communication
between instances in the same network, but we can't resolve the DNS hostname outside the network
that the instance is in.
An instance receives a primary private IP address from the IPv4 address range of the subnet. For more
information, see VPC and Subnet Sizing in the Amazon VPC User Guide. If you don't specify a primary
private IP address when you launch the instance, we select an available IP address in the subnet's IPv4
range for you. Each instance has a default network interface (eth0) that is assigned the primary private
IPv4 address. You can also specify additional private IPv4 addresses, known as secondary private IPv4
addresses. Unlike primary private IP addresses, secondary private IP addresses can be reassigned from
one instance to another. For more information, see Multiple IP Addresses (p. 713).
A private IPv4 address remains associated with the network interface when the instance is stopped and
restarted, and is released when the instance is terminated.
Each instance that receives a public IP address is also given an external DNS hostname; for example,
ec2-203-0-113-25.compute-1.amazonaws.com. We resolve an external DNS hostname to the
public IP address of the instance outside the network of the instance, and to the private IPv4 address of
the instance from within the network of the instance. The public IP address is mapped to the primary
private IP address through network address translation (NAT). For more information about NAT, see RFC
1631: The IP Network Address Translator (NAT).
When you launch an instance in a default VPC, we assign it a public IP address by default. When you
launch an instance into a nondefault VPC, the subnet has an attribute that determines whether instances
launched into that subnet receive a public IP address from the public IPv4 address pool. By default, we
don't assign a public IP address to instances launched in a nondefault subnet.
You can control whether your instance receives a public IP address as follows:
• Modifying the public IP addressing attribute of your subnet. For more information, see Modifying the
Public IPv4 Addressing Attribute for Your Subnet in the Amazon VPC User Guide.
• Enabling or disabling the public IP addressing feature during launch, which overrides the subnet's
public IP addressing attribute. For more information, see Assigning a Public IPv4 Address During
Instance Launch (p. 711).
A public IP address is assigned to your instance from Amazon's pool of public IPv4 addresses, and is not
associated with your AWS account. When a public IP address is disassociated from your instance, it is
released back into the public IPv4 address pool, and you cannot reuse it.
You cannot manually associate or disassociate a public IP address from your instance. Instead, in certain
cases, we release the public IP address from your instance, or assign it a new one:
• We release your instance's public IP address when it is stopped or terminated. Your stopped instance
receives a new public IP address when it is restarted.
707
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Elastic IP Addresses (IPv4)
• We release your instance's public IP address when you associate an Elastic IP address with it. When you
disassociate the Elastic IP address from your instance, it receives a new public IP address.
• If the public IP address of your instance in a VPC has been released, it will not receive a new one if
there is more than one network interface attached to your instance.
• If your instance's public IP address is released while it has a secondary private IP address that is
associated with an Elastic IP address, the instance does not receive a new public IP address.
If you require a persistent public IP address that can be associated to and from instances as you require,
use an Elastic IP address instead.
If you use dynamic DNS to map an existing DNS name to a new instance's public IP address, it might take
up to 24 hours for the IP address to propagate through the Internet. As a result, new instances might
not receive traffic while terminated instances continue to receive requests. To solve this problem, use an
Elastic IP address. You can allocate your own Elastic IP address, and associate it with your instance. For
more information, see Elastic IP Addresses (p. 724).
If you assign an Elastic IP address to an instance, it receives an IPv4 DNS hostname if DNS hostnames are
enabled. For more information, see Using DNS with Your VPC in the Amazon VPC User Guide.
Note
Instances that access other instances through their public NAT IP address are charged for
regional or Internet data transfer, depending on whether the instances are in the same region.
IPv6 Addresses
You can optionally associate an IPv6 CIDR block with your VPC, and associate IPv6 CIDR blocks with
your subnets. The IPv6 CIDR block for your VPC is automatically assigned from Amazon's pool of IPv6
addresses; you cannot choose the range yourself. For more information, see the following topics in the
Amazon VPC User Guide:
IPv6 addresses are globally unique, and therefore reachable over the Internet. Your instance receives an
IPv6 address if an IPv6 CIDR block is associated with your VPC and subnet, and if one of the following is
true:
• Your subnet is configured to automatically assign an IPv6 address to an instance during launch. For
more information, see Modifying the IPv6 Addressing Attribute for Your Subnet.
708
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with IP Addresses for Your Instance
When your instance receives an IPv6 address during launch, the address is associated with the primary
network interface (eth0) of the instance. You can disassociate the IPv6 address from the network
interface. We do not support IPv6 DNS hostnames for your instance.
An IPv6 address persists when you stop and start your instance, and is released when you terminate your
instance. You cannot reassign an IPv6 address while it's assigned to another network interface—you must
first unassign it.
You can assign additional IPv6 addresses to your instance by assigning them to a network interface
attached to your instance. The number of IPv6 addresses you can assign to a network interface and
the number of network interfaces you can attach to an instance varies per instance type. For more
information, see IP Addresses Per Network Interface Per Instance Type (p. 731).
Contents
• Determining Your Public, Private, and Elastic IP Addresses (p. 709)
• Determining Your IPv6 Addresses (p. 710)
• Assigning a Public IPv4 Address During Instance Launch (p. 711)
• Assigning an IPv6 Address to an Instance (p. 712)
• Unassigning an IPv6 Address From an Instance (p. 712)
709
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with IP Addresses for Your Instance
Note that if an Elastic IP address is associated with the instance, the value returned is that of the
Elastic IP address.
710
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with IP Addresses for Your Instance
2. Use the following command to view the IPv6 address (you can get the MAC address from
http://169.254.169.254/latest/meta-data/network/interfaces/macs/):
The public IP addressing feature is only available during launch. However, whether you assign a public
IP address to your instance during launch or not, you can associate an Elastic IP address with your
instance after it's launched. For more information, see Elastic IP Addresses (p. 724). You can also
modify your subnet's public IPv4 addressing behavior. For more information, see Modifying the Public
IPv4 Addressing Attribute for Your Subnet.
To enable or disable the public IP addressing feature using the command line
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
711
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with IP Addresses for Your Instance
• Use the -AssociatePublicIp parameter with the New-EC2Instance command (AWS Tools for
Windows PowerShell)
IPv6 is supported on all current generation instance types and the C3, R3, and I2 previous generation
instance types.
Alternatively, you can assign an IPv6 address to your instance after launch.
Note
If you launched your instance using Amazon Linux 2016.09.0 or later, or Windows Server 2008
R2 or later, your instance is configured for IPv6, and no additional steps are needed to ensure
that the IPv6 address is recognized on the instance. If you launched your instance from an older
AMI, you may have to configure your instance manually. For more information, see Configure
IPv6 on Your Instances in the Amazon VPC User Guide.
• Use the --ipv6-addresses option with the run-instances command (AWS CLI)
• Use the Ipv6Addresses property for -NetworkInterface in the New-EC2Instance command (AWS
Tools for Windows PowerShell)
• assign-ipv6-addresses (AWS CLI)
• Register-EC2Ipv6AddressList (AWS Tools for Windows PowerShell)
712
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Multiple IP Addresses
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
Multiple IP Addresses
You can specify multiple private IPv4 and IPv6 addresses for your instances. The number of network
interfaces and private IPv4 and IPv6 addresses that you can specify for an instance depends on the
instance type. For more information, see IP Addresses Per Network Interface Per Instance Type (p. 731).
It can be useful to assign multiple IP addresses to an instance in your VPC to do the following:
• Host multiple websites on a single server by using multiple SSL certificates on a single server and
associating each certificate with a specific IP address.
• Operate network appliances, such as firewalls or load balancers, that have multiple IP addresses for
each network interface.
• Redirect internal traffic to a standby instance in case your instance fails, by reassigning the secondary
IP address to the standby instance.
Contents
• How Multiple IP Addresses Work (p. 713)
• Working with Multiple IPv4 Addresses (p. 714)
• Working with Multiple IPv6 Addresses (p. 718)
• You can assign a secondary private IPv4 address to any network interface. The network interface can
be attached to or detached from the instance.
• You can assign multiple IPv6 addresses to a network interface that's in a subnet that has an associated
IPv6 CIDR block.
• You must choose the secondary IPv4 from the IPv4 CIDR block range of the subnet for the network
interface.
• You must choose IPv6 addresses from the IPv6 CIDR block range of the subnet for the network
interface.
• You associate security groups with network interfaces, not the individual IP addresses. Therefore, each
IP address you specify in a network interface is subject to the security group of its network interface.
713
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Multiple IP Addresses
The following list explains how multiple IP addresses work with Elastic IP addresses (IPv4 only):
• Each private IPv4 address can be associated with a single Elastic IP address, and vice versa.
• When a secondary private IPv4 address is reassigned to another interface, the secondary private IPv4
address retains its association with an Elastic IP address.
• When a secondary private IPv4 address is unassigned from an interface, an associated Elastic IP
address is automatically disassociated from the secondary private IPv4 address.
Contents
• Assigning a Secondary Private IPv4 Address (p. 714)
• Configuring the Operating System on Your Instance to Recognize the Secondary Private IPv4 Address
(p. 716)
• Associating an Elastic IP Address with the Secondary Private IPv4 Address (p. 716)
• Viewing Your Secondary Private IPv4 Addresses (p. 717)
• Unassigning a Secondary Private IPv4 Address (p. 717)
• To assign a secondary private IPv4 address when launching an instance (p. 714)
• To assign a secondary IPv4 address during launch using the command line (p. 715)
• To assign a secondary private IPv4 address to a network interface (p. 715)
• To assign a secondary private IPv4 to an existing instance using the command line (p. 716)
714
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Multiple IP Addresses
3. Select an AMI, then choose an instance type and choose Next: Configure Instance Details.
4. On the Configure Instance Details page, for Network, select a VPC and for Subnet, select a subnet.
5. In the Network Interfaces section, do the following, and then choose Next: Add Storage:
• To add another network interface, choose Add Device. The console enables you to specify up
to two network interfaces when you launch an instance. After you launch the instance, choose
Network Interfaces in the navigation pane to add additional network interfaces. The total
number of network interfaces that you can attach varies by instance type. For more information,
see IP Addresses Per Network Interface Per Instance Type (p. 731).
Important
When you add a second network interface, the system can no longer auto-assign a public
IPv4 address. You will not be able to connect to the instance over IPv4 unless you assign
an Elastic IP address to the primary network interface (eth0). You can assign the Elastic IP
address after you complete the Launch wizard. For more information, see Working with
Elastic IP Addresses (p. 724).
• For each network interface, under Secondary IP addresses, choose Add IP, and then enter a
private IP address from the subnet range, or accept the default Auto-assign value to let Amazon
select an address.
6. On the next Add Storage page, you can specify volumes to attach to the instance besides the
volumes specified by the AMI (such as the root device volume), and then choose Next: Add Tags.
7. On the Add Tags page, specify tags for the instance, such as a user-friendly name, and then choose
Next: Configure Security Group.
8. On the Configure Security Group page, select an existing security group or create a new one.
Choose Review and Launch.
9. On the Review Instance Launch page, review your settings, and then choose Launch to choose a key
pair and launch your instance. If you're new to Amazon EC2 and haven't created any key pairs, the
wizard prompts you to create one.
Important
After you have added a secondary private IP address to a network interface, you must connect
to the instance and configure the secondary private IP address on the instance itself. For
more information, see Configuring the Operating System on Your Instance to Recognize the
Secondary Private IPv4 Address (p. 716).
To assign a secondary IPv4 address during launch using the command line
• You can use one of the following commands. For more information about these command line
interfaces, see Accessing Amazon EC2 (p. 3).
715
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Multiple IP Addresses
6. (Optional) Choose Allow reassignment to allow the secondary private IP address to be reassigned if
it is already assigned to another network interface.
7. Choose Yes, Update.
Alternatively, you can assign a secondary private IPv4 address to an instance. Choose Instances in the
navigation pane, select the instance, and then choose Actions, Networking, Manage IP Addresses. You
can configure the same information as you did in the steps above. The IP address is assigned to the
primary network interface (eth0) for the instance.
To assign a secondary private IPv4 to an existing instance using the command line
• You can use one of the following commands. For more information about these command line
interfaces, see Accessing Amazon EC2 (p. 3).
• If you are using Amazon Linux, the ec2-net-utils package can take care of this step for you. It
configures additional network interfaces that you attach while the instance is running, refreshes
secondary IPv4 addresses during DHCP lease renewal, and updates the related routing rules. You can
immediately refresh the list of interfaces by using the command sudo service network restart
and then view the up-to-date list using ip addr li. If you require manual control over your network
configuration, you can remove the ec2-net-utils package. For more information, see Configuring Your
Network Interface Using ec2-net-utils (p. 740).
• If you are using another Linux distribution, see the documentation for your Linux distribution. Search
for information about configuring additional network interfaces and secondary IPv4 addresses. If the
instance has two or more interfaces on the same subnet, search for information about using routing
rules to work around asymmetric routing.
For information about configuring a Windows instance, see Configuring a Secondary Private IP Address
for Your Windows Instance in a VPC in the Amazon EC2 User Guide for Windows Instances.
716
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Multiple IP Addresses
To associate an Elastic IP address with a secondary private IPv4 address using the command
line
• You can use one of the following commands. For more information about these command line
interfaces, see Accessing Amazon EC2 (p. 3).
717
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Multiple IP Addresses
• You can use one of the following commands. For more information about these command line
interfaces, see Accessing Amazon EC2 (p. 3).
Contents
• Assigning Multiple IPv6 Addresses (p. 718)
• Viewing Your IPv6 Addresses (p. 719)
• Unassigning an IPv6 Address (p. 720)
• To assign a single IPv6 address to the primary network interface (eth0), under IPv6 IPs, choose
Add IP. To add a secondary IPv6 address, choose Add IP again. You can enter an IPv6 address from
the range of the subnet, or leave the default Auto-assign value to let Amazon choose an IPv6
address from the subnet for you.
• Choose Add Device to add another network interface and repeat the steps above to add one
or more IPv6 addresses to the network interface. The console enables you to specify up to two
network interfaces when you launch an instance. After you launch the instance, choose Network
Interfaces in the navigation pane to add additional network interfaces. The total number of
network interfaces that you can attach varies by instance type. For more information, see IP
Addresses Per Network Interface Per Instance Type (p. 731).
6. Follow the next steps in the wizard to attach volumes and tag your instance.
7. On the Configure Security Group page, select an existing security group or create a new one. If you
want your instance to be reachable over IPv6, ensure that your security group has rules that allow
access from IPv6 addresses. For more information, see Security Group Rules Reference (p. 616).
Choose Review and Launch.
8. On the Review Instance Launch page, review your settings, and then choose Launch to choose a key
pair and launch your instance. If you're new to Amazon EC2 and haven't created any key pairs, the
wizard prompts you to create one.
718
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Multiple IP Addresses
You can use the Instances screen Amazon EC2 console to assign multiple IPv6 addresses to an existing
instance. This assigns the IPv6 addresses to the primary network interface (eth0) for the instance. To
assign a specific IPv6 address to the instance, ensure that the IPv6 address is not already assigned to
another instance or network interface.
Alternatively, you can assign multiple IPv6 addresses to an existing network interface. The network
interface must have been created in a subnet that has an associated IPv6 CIDR block. To assign a specific
IPv6 address to the network interface, ensure that the IPv6 address is not already assigned to another
network interface.
CLI Overview
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
719
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Multiple IP Addresses
CLI Overview
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
CLI Overview
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
720
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Bring Your Own IP Addresses
Requirements
• The address range must be registered with your regional internet registry (RIR), such as the American
Registry for Internet Numbers (ARIN) or Réseaux IP Européens Network Coordination Centre (RIPE).
It must be registered to a business or institutional entity and may not be registered to an individual
person.
• For ARIN, the supported network types are "Direct Allocation" and "Direct Assignment".
• For RIPE, the supported allocation statuses are "ALLOCATED PA", "LEGACY", and "ASSIGNED PI".
• The most specific address range that you can specify is /24.
• You can bring each address range to one region at a time.
• You can bring 5 address ranges per region to your AWS account.
• The addresses in the IP address range must have a clean history. We may investigate the reputation of
the IP address range and reserve the right to reject an IP address range if it contains an IP address that
has poor reputation or is associated with malicious behavior.
A Route Origin Authorization (ROA) is a document that you can create through your RIR. It contains the
address range, the ASNs that are allowed to advertise the address range, and an expiration date. An
ROA authorizes Amazon to advertise an address range under a specific AS number. However, it does not
authorize your AWS account to bring the address range to AWS. To authorize your AWS account to bring
an address range to AWS, you must publish a self-signed X509 certificate in the RDAP remarks for the
address range. The certificate contains a public key, which AWS uses to verify the authorization-context
signature that you provide. You should keep your private key secure and use it to sign the authorization-
context message.
The commands in the following procedure require OpenSSL version 1.0.2 or later.
1. Create an ROA to authorize Amazon ASNs 16509 and 14618 to advertise your address range, plus
the ASNs that are currently authorized to advertise the address range. You must set the maximum
length to the size of the smallest prefix that you want to bring (for example, /24). It might take up
to 24 hours for the ROA to become available to Amazon. For more information, see the following:
721
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Provision the Address Range for use with AWS
3. Create a public X509 certificate from the key pair using the following command. In this example, the
certificate expires in 365 days, after which time it cannot be trusted. Therefore, be sure to set the
expiration appropriately. When prompted for information, you can accept the default values.
openssl req -new -x509 -key private.key -days 365 | tr -d "\n" > publickey.cer
4. Create a signed authorization message for the prefix and AWS account. The format of the message is
as follows, where the date is the expiry date of the message:
1|aws|account|cidr|YYYYMMDD|SHA256|RSAPSS
The following command creates a plain-text authorization message using an example account
number, address range, and expiry date, and stores it in a variable named text_message.
text_message="1|aws|123456789012|198.51.100.0/24|20191201|SHA256|RSAPSS"
The following command signs the authorization message in text_message using the key pair that
you created, and stores it in a variable named signed_message:
5. Update the RDAP record for your RIR with the X509 certificate. Be sure to copy the -----BEGIN
CERTIFICATE----- and -----END CERTIFICATE----- from the certificate. Be sure that you
have removed newline characters, if you haven't already done so using the tr -d "\n" commands in
the previous steps. To view your certificate, run the following command:
cat publickey.cer
For ARIN, add the certificate in the "Public Comments" section for your address range.
For RIPE, add the certificate as a new "desc" field for your address range.
To provision the address range, use the following provision-byoip-cidr command. The --cidr-
authorization-context parameter uses the variables that you created in the previous section, not
the ROA message.
Provisioning an address range is an asynchronous operation, so the call returns immediately, but the
address range is not ready to use until its status changes from pending-provision to provisioned.
722
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Advertise the Address Range through AWS
It can take up to five days to complete the provisioning process. To monitor the status of the address
ranges that you've provisioned, use the following describe-byoip-cidrs command:
We recommend that you stop advertising the address range from other locations before you advertise
it through AWS. If you keep advertising your IP address range from other locations, we can't reliably
support it or troubleshoot issues. Specifically, we can't guarantee that traffic to the address range will
enter our network.
To minimize down time, you can configure your AWS resources to use an address from your address
pool before it is advertised, and then simultaneously stop advertising it from the current location and
start advertising it through AWS. For more information about allocating an Elastic IP address from your
address pool, see Allocating an Elastic IP Address (p. 725).
Important
You can run the advertise-byoip-cidr command at most once every 10 seconds, even if you
specify different address ranges each time.
To stop advertising the address range, use the following withdraw-byoip-cidr command:
Important
You can run the withdraw-byoip-cidr command at most once every 10 seconds, even if you
specify different address ranges each time.
To stop advertising the address range, use the following withdraw-byoip-cidr command:
723
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Elastic IP Addresses
Elastic IP Addresses
An Elastic IP address is a static IPv4 address designed for dynamic cloud computing. An Elastic IP address
is associated with your AWS account. With an Elastic IP address, you can mask the failure of an instance
or software by rapidly remapping the address to another instance in your account.
An Elastic IP address is a public IPv4 address, which is reachable from the internet. If your instance does
not have a public IPv4 address, you can associate an Elastic IP address with your instance to enable
communication with the internet; for example, to connect to your instance from your local computer.
Contents
• Elastic IP Address Basics (p. 724)
• Working with Elastic IP Addresses (p. 724)
• Using Reverse DNS for Email Applications (p. 729)
• Elastic IP Address Limit (p. 729)
• To use an Elastic IP address, you first allocate one to your account, and then associate it with your
instance or a network interface.
• When you associate an Elastic IP address with an instance or its primary network interface, the
instance's public IPv4 address (if it had one) is released back into Amazon's pool of public IPv4
addresses. You cannot reuse a public IPv4 address, and you cannot convert a public IPv4 address
to an Elastic IP address. For more information, see Public IPv4 Addresses and External DNS
Hostnames (p. 707).
• You can disassociate an Elastic IP address from a resource, and reassociate it with a different resource.
Any open connections to an instance continue to work for a time even after you disassociate its Elastic
IP address and reassociate it with another instance. We recommend that you reopen these connections
using the reassociated Elastic IP address.
• A disassociated Elastic IP address remains allocated to your account until you explicitly release it.
• To ensure efficient use of Elastic IP addresses, we impose a small hourly charge if an Elastic IP address
is not associated with a running instance, or if it is associated with a stopped instance or an unattached
network interface. While your instance is running, you are not charged for one Elastic IP address
associated with the instance, but you are charged for any additional Elastic IP addresses associated
with the instance. For more information, see Amazon EC2 Pricing.
• An Elastic IP address is for use in a specific region only.
• When you associate an Elastic IP address with an instance that previously had a public IPv4 address,
the public DNS hostname of the instance changes to match the Elastic IP address.
• We resolve a public DNS hostname to the public IPv4 address or the Elastic IP address of the instance
outside the network of the instance, and to the private IPv4 address of the instance from within the
network of the instance.
• When you allocate an Elastic IP address from an IP address pool that you have brought to your AWS
account, it does not count toward your Elastic IP address limits.
724
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with Elastic IP Addresses
Tasks
• Allocating an Elastic IP Address (p. 725)
• Describing Your Elastic IP Addresses (p. 726)
• Tagging an Elastic IP Address (p. 726)
• Associating an Elastic IP Address with a Running Instance (p. 727)
• Disassociating an Elastic IP Address and Reassociating with a Different Instance (p. 727)
• Releasing an Elastic IP Address (p. 728)
• Recovering an Elastic IP Address (p. 728)
You can allocate an Elastic IP address using the Amazon EC2 console or the command line.
To allocate an Elastic IP address from Amazon's pool of public IPv4 addresses using the
console
To allocate an Elastic IP address from an IP address pool that you own using the console
To see the IP address range of the selected address pool and the number of IP addresses already
allocated from the address pool, see Address ranges.
5. For IPv4 address, do one of the following:
• To let Amazon EC2 select an IP address from the address pool, choose No preference.
• To select a specific IP address from the address pool, choose Select an address and then type the
IP address.
6. Choose Allocate, and close the confirmation screen.
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
725
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with Elastic IP Addresses
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
The New-EC2Tag command needs a Tag parameter, which specifies the key and value pair to be used
for the Elastic IP address tag. The following commands create the Tag parameter:
726
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with Elastic IP Addresses
If you're associating an Elastic IP address with your instance to enable communication with the internet,
you must also ensure that your instance is in a public subnet. For more information, see Internet
Gateways in the Amazon VPC User Guide.
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
727
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with Elastic IP Addresses
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
• You cannot recover an Elastic IP address if it has been allocated to another AWS account, or if it will
result in your exceeding your Elastic IP address limit.
• You cannot recover tags associated with an Elastic IP address.
• You can recover an Elastic IP address using the Amazon EC2 API or a command line tool only.
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
• allocate-address (AWS CLI) — Specify the IP address using the --address parameter as follows.
• New-EC2Address (AWS Tools for Windows PowerShell) — Specify the IP address using the -Address
parameter as follows.
728
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Using Reverse DNS for Email Applications
In addition, assigning a static reverse DNS record to your Elastic IP address used to send email can
help avoid having email flagged as spam by some anti-spam organizations. Note that a corresponding
forward DNS record (record type A) pointing to your Elastic IP address must exist before we can create
your reverse DNS record.
If a reverse DNS record is associated with an Elastic IP address, the Elastic IP address is locked to your
account and cannot be released from your account until the record is removed.
To remove email sending limits, or to provide us with your Elastic IP addresses and reverse DNS records,
go to the Request to Remove Email Sending Limitations page.
If you feel your architecture warrants additional Elastic IP addresses, complete the Amazon EC2 Elastic
IP Address Request Form. Describe your use case so that we can understand your need for additional
addresses.
• A primary private IPv4 address from the IPv4 address range of your VPC
• One or more secondary private IPv4 addresses from the IPv4 address range of your VPC
• One Elastic IP address (IPv4) per private IPv4 address
• One public IPv4 address
• One or more IPv6 addresses
• One or more security groups
• A MAC address
• A source/destination check flag
• A description
You can create and configure network interfaces in your account and attach them to instances in
your VPC. Your account might also have requester-managed network interfaces, which are created
and managed by AWS services to enable you to use other resources and services. You cannot
manage these network interfaces yourself. For more information, see Requester-Managed Network
Interfaces (p. 749).
729
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Network Interface Basics
Important
The term 'elastic network interface' is sometimes shortened to 'ENI'. This is not the same as the
Elastic Network Adapter (ENA), which is a custom interface that optimizes network performance
on some instance types. For more information, see Enhanced Networking on Linux (p. 750).
Contents
• Network Interface Basics (p. 730)
• IP Addresses Per Network Interface Per Instance Type (p. 731)
• Scenarios for Network Interfaces (p. 738)
• Best Practices for Configuring Network Interfaces (p. 740)
• Working with Network Interfaces (p. 741)
• Requester-Managed Network Interfaces (p. 749)
You can also modify the attributes of your network interface, including changing its security groups and
managing its IP addresses.
Every instance in a VPC has a default network interface, called the primary network interface (eth0).
You cannot detach a primary network interface from an instance. You can create and attach additional
network interfaces. The maximum number of network interfaces that you can use varies by instance
type. For more information, see IP Addresses Per Network Interface Per Instance Type (p. 731).
In a VPC, all subnets have a modifiable attribute that determines whether network interfaces created in
that subnet (and therefore instances launched into that subnet) are assigned a public IPv4 address. For
more information, see IP Addressing Behavior for Your Subnet in the Amazon VPC User Guide. The public
IPv4 address is assigned from Amazon's pool of public IPv4 addresses. When you launch an instance, the
IP address is assigned to the primary network interface (eth0) that's created.
When you create a network interface, it inherits the public IPv4 addressing attribute from the subnet.
If you later modify the public IPv4 addressing attribute of the subnet, the network interface keeps the
setting that was in effect when it was created. If you launch an instance and specify an existing network
interface for eth0, the public IPv4 addressing attribute is determined by the network interface.
For more information, see Public IPv4 Addresses and External DNS Hostnames (p. 707).
You can associate an IPv6 CIDR block with your VPC and subnet, and assign one or more IPv6 addresses
from the subnet range to a network interface.
All subnets have a modifiable attribute that determines whether network interfaces created in that
subnet (and therefore instances launched into that subnet) are automatically assigned an IPv6 address
from the range of the subnet. For more information, see IP Addressing Behavior for Your Subnet in
the Amazon VPC User Guide. When you launch an instance, the IPv6 address is assigned to the primary
network interface (eth0) that's created.
Monitoring IP Traffic
730
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IP Addresses Per Network Interface Per Instance Type
You can enable a VPC flow log on your network interface to capture information about the IP traffic
going to and from a network interface. After you've created a flow log, you can view and retrieve its data
in Amazon CloudWatch Logs. For more information, see VPC Flow Logs in the Amazon VPC User Guide.
Instance Type Maximum Network IPv4 Addresses per IPv6 Addresses per
Interfaces Interface Interface
a1.medium 2 4 4
a1.large 3 10 10
a1.xlarge 4 15 15
a1.2xlarge 4 15 15
a1.4xlarge 8 30 30
c3.large 3 10 10
c3.xlarge 4 15 15
c3.2xlarge 4 15 15
c3.4xlarge 8 30 30
c3.8xlarge 8 30 30
c4.large 3 10 10
c4.xlarge 4 15 15
c4.2xlarge 4 15 15
c4.4xlarge 8 30 30
c4.8xlarge 8 30 30
c5.large 3 10 10
c5.xlarge 4 15 15
c5.2xlarge 4 15 15
c5.4xlarge 8 30 30
c5.9xlarge 8 30 30
731
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IP Addresses Per Network Interface Per Instance Type
Instance Type Maximum Network IPv4 Addresses per IPv6 Addresses per
Interfaces Interface Interface
c5.12xlarge 8 30 30
c5.18xlarge 15 50 50
c5.24xlarge 15 50 50
c5.metal 15 50 50
c5d.large 3 10 10
c5d.xlarge 4 15 15
c5d.2xlarge 4 15 15
c5d.4xlarge 8 30 30
c5d.9xlarge 8 30 30
c5d.18xlarge 15 50 50
c5n.large 3 10 10
c5n.xlarge 4 15 15
c5n.2xlarge 4 15 15
c5n.4xlarge 8 30 30
c5n.9xlarge 8 30 30
c5n.18xlarge 15 50 50
d2.xlarge 4 15 15
d2.2xlarge 4 15 15
d2.4xlarge 8 30 30
d2.8xlarge 8 30 30
f1.2xlarge 4 15 15
f1.4xlarge 8 30 30
f1.16xlarge 8 50 50
g3s.xlarge 4 15 15
g3.4xlarge 8 30 30
g3.8xlarge 8 30 30
732
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IP Addresses Per Network Interface Per Instance Type
Instance Type Maximum Network IPv4 Addresses per IPv6 Addresses per
Interfaces Interface Interface
g3.16xlarge 15 50 50
h1.2xlarge 4 15 15
h1.4xlarge 8 30 30
h1.8xlarge 8 30 30
h1.16xlarge 15 50 50
i2.xlarge 4 15 15
i2.2xlarge 4 15 15
i2.4xlarge 8 30 30
i2.8xlarge 8 30 30
i3.large 3 10 10
i3.xlarge 4 15 15
i3.2xlarge 4 15 15
i3.4xlarge 8 30 30
i3.8xlarge 8 30 30
i3.16xlarge 15 50 50
i3.metal 15 50 50
i3en.large 3 10 10
i3en.xlarge 4 15 15
i3en.2xlarge 4 15 15
i3en.3xlarge 4 15 15
i3en.6xlarge 8 30 30
i3en.12xlarge 8 30 30
i3en.24xlarge 15 50 50
733
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IP Addresses Per Network Interface Per Instance Type
Instance Type Maximum Network IPv4 Addresses per IPv6 Addresses per
Interfaces Interface Interface
m4.large 2 10 10
m4.xlarge 4 15 15
m4.2xlarge 4 15 15
m4.4xlarge 8 30 30
m4.10xlarge 8 30 30
m4.16xlarge 8 30 30
m5.large 3 10 10
m5.xlarge 4 15 15
m5.2xlarge 4 15 15
m5.4xlarge 8 30 30
m5.8xlarge 8 30 30
m5.12xlarge 8 30 30
m5.16xlarge 15 50 50
m5.24xlarge 15 50 50
m5.metal 15 50 50
m5a.large 3 10 10
m5a.xlarge 4 15 15
m5a.2xlarge 4 15 15
m5a.4xlarge 8 30 30
m5a.8xlarge 8 30 30
m5a.12xlarge 8 30 30
m5a.16xlarge 15 50 50
m5a.24xlarge 15 50 50
m5ad.large 3 10 10
m5ad.xlarge 4 15 15
734
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IP Addresses Per Network Interface Per Instance Type
Instance Type Maximum Network IPv4 Addresses per IPv6 Addresses per
Interfaces Interface Interface
m5ad.2xlarge 4 15 15
m5ad.4xlarge 8 30 30
m5ad.12xlarge 8 30 30
m5ad.24xlarge 15 50 50
m5d.large 3 10 10
m5d.xlarge 4 15 15
m5d.2xlarge 4 15 15
m5d.4xlarge 8 30 30
m5d.8xlarge 8 30 30
m5d.12xlarge 8 30 30
m5d.16xlarge 15 50 50
m5d.24xlarge 15 50 50
m5d.metal 15 50 50
p2.xlarge 4 15 15
p2.8xlarge 8 30 30
p2.16xlarge 8 30 30
p3.2xlarge 4 15 15
p3.8xlarge 8 30 30
p3.16xlarge 8 30 30
p3dn.24xlarge 15 50 50
r3.large 3 10 10
r3.xlarge 4 15 15
r3.2xlarge 4 15 15
r3.4xlarge 8 30 30
r3.8xlarge 8 30 30
r4.large 3 10 10
r4.xlarge 4 15 15
r4.2xlarge 4 15 15
r4.4xlarge 8 30 30
r4.8xlarge 8 30 30
735
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IP Addresses Per Network Interface Per Instance Type
Instance Type Maximum Network IPv4 Addresses per IPv6 Addresses per
Interfaces Interface Interface
r4.16xlarge 15 50 50
r5.large 3 10 10
r5.xlarge 4 15 15
r5.2xlarge 4 15 15
r5.4xlarge 8 30 30
r5.8xlarge 8 30 30
r5.12xlarge 8 30 30
r5.16xlarge 15 50 50
r5.24xlarge 15 50 50
r5.metal 15 50 50
r5a.large 3 10 10
r5a.xlarge 4 15 15
r5a.2xlarge 4 15 15
r5a.4xlarge 8 30 30
r5a.8xlarge 8 30 30
r5a.12xlarge 8 30 30
r5a.16xlarge 15 50 50
r5a.24xlarge 15 50 50
r5ad.large 3 10 10
r5ad.xlarge 4 15 15
r5ad.2xlarge 4 15 15
r5ad.4xlarge 8 30 30
r5ad.12xlarge 8 30 30
r5ad.24xlarge 15 50 50
r5d.large 3 10 10
r5d.xlarge 4 15 15
r5d.2xlarge 4 15 15
r5d.4xlarge 8 30 30
r5d.8xlarge 8 30 30
r5d.12xlarge 8 30 30
736
Amazon Elastic Compute Cloud
User Guide for Linux Instances
IP Addresses Per Network Interface Per Instance Type
Instance Type Maximum Network IPv4 Addresses per IPv6 Addresses per
Interfaces Interface Interface
r5d.16xlarge 15 50 50
r5d.24xlarge 15 50 50
r5d.metal 15 50 50
t2.nano 2 2 2
t2.micro 2 2 2
t2.small 3 4 4
t2.medium 3 6 6
t2.large 3 12 12
t2.xlarge 3 15 15
t2.2xlarge 3 15 15
t3.nano 2 2 2
t3.micro 2 2 2
t3.small 3 4 4
t3.medium 3 6 6
t3.large 3 12 12
t3.xlarge 4 15 15
t3.2xlarge 4 15 15
t3a.nano 2 2 2
t3a.micro 2 2 2
t3a.small 2 4 4
t3a.medium 3 6 6
t3a.large 3 12 12
t3a.xlarge 4 15 15
t3a.2xlarge 4 15 15
u-6tb1.metal 5 30 30
u-9tb1.metal 5 30 30
u-12tb1.metal 5 30 30
x1.16xlarge 8 30 30
x1.32xlarge 8 30 30
737
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Scenarios for Network Interfaces
Instance Type Maximum Network IPv4 Addresses per IPv6 Addresses per
Interfaces Interface Interface
x1e.xlarge 3 10 10
x1e.2xlarge 4 15 15
x1e.4xlarge 4 15 15
x1e.8xlarge 4 15 15
x1e.16xlarge 8 30 30
x1e.32xlarge 8 30 30
z1d.large 3 10 10
z1d.xlarge 4 15 15
z1d.2xlarge 4 15 15
z1d.3xlarge 8 30 30
z1d.6xlarge 8 30 30
z1d.12xlarge 15 50 50
z1d.metal 15 50 50
Note
If f1.16xlarge, g3.16xlarge, h1.16xlarge, i3.16xlarge, and r4.16xlarge instances
use more than 31 IPv4 or IPv6 addresses per interface, they cannot access the instance
metadata, VPC DNS, and Time Sync services from the 32nd IP address onwards. If access
to these services is needed from all IP addresses on the interface, we recommend using a
maximum of 31 IP addresses per interface.
738
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Scenarios for Network Interfaces
To ensure failover capabilities, consider using a secondary private IPv4 for incoming traffic on a network
interface. In the event of an instance failure, you can move the interface and/or secondary private IPv4
address to a standby instance.
739
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Best Practices for Configuring Network Interfaces
that the network interface is attached to the standby instance, but no changes to the VPC route table or
your DNS server are required.
Use the following command to install the package on Amazon Linux if it's not already installed, or
update it if it's installed and additional updates are available:
Identifies network interfaces when they are attached, detached, or reattached to a running instance,
and ensures that the hotplug script runs (53-ec2-network-interfaces.rules). Maps the
MAC address to a device name (75-persistent-net-generator.rules, which generates 70-
persistent-net.rules).
hotplug script
Generates an interface configuration file suitable for use with DHCP (/etc/sysconfig/network-
scripts/ifcfg-ethN). Also generates a route configuration file (/etc/sysconfig/network-
scripts/route-ethN).
740
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with Network Interfaces
DHCP script
Whenever the network interface receives a new DHCP lease, this script queries the instance
metadata for Elastic IP addresses. For each Elastic IP address, it adds a rule to the routing policy
database to ensure that outbound traffic from that address uses the correct network interface. It
also adds each private IP address to the network interface as a secondary address.
ec2ifup ethN
Extends the functionality of the standard ifup. After this script rewrites the configuration files
ifcfg-ethN and route-ethN, it runs ifup.
ec2ifdown ethN
Extends the functionality of the standard ifdown. After this script removes any rules for the network
interface from the routing policy database, it runs ifdown.
ec2ifscan
Checks for network interfaces that have not been configured and configures them.
To list any configuration files that were generated by ec2-net-utils, use the following command:
$ ls -l /etc/sysconfig/network-scripts/*-eth?
To disable the automation on a per-instance basis, you can add EC2SYNC=no to the corresponding
ifcfg-ethN file. For example, use the following command to disable the automation for the eth1
interface:
To disable the automation completely, you can remove the package using the following command:
Contents
• Creating a Network Interface (p. 742)
• Deleting a Network Interface (p. 742)
• Viewing Details about a Network Interface (p. 743)
• Attaching a Network Interface When Launching an Instance (p. 743)
• Attaching a Network Interface to a Stopped or Running Instance (p. 744)
• Detaching a Network Interface from an Instance (p. 745)
• Changing the Security Group (p. 745)
• Changing the Source or Destination Checking (p. 746)
• Associating an Elastic IP Address (IPv4) (p. 746)
• Disassociating an Elastic IP Address (IPv4) (p. 747)
• Assigning an IPv6 Address (p. 747)
• Unassigning an IPv6 Address (p. 748)
• Changing Termination Behavior (p. 748)
741
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with Network Interfaces
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
742
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with Network Interfaces
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
You can add additional network interfaces to the instance after you launch it. The total number
of network interfaces that you can attach varies by instance type. For more information, see IP
Addresses Per Network Interface Per Instance Type (p. 731).
Note
If you specify more than one network interface, you cannot auto-assign a public IPv4
address to your instance.
743
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with Network Interfaces
6. (IPv6 only) If you're launching an instance into a subnet that has an associated IPv6 CIDR block, you
can specify IPv6 addresses for any network interfaces that you attach. Under IPv6 IPs, choose Add
IP. To add a secondary IPv6 address, choose Add IP again. You can enter an IPv6 address from the
range of the subnet, or leave the default Auto-assign value to let Amazon choose an IPv6 address
from the subnet for you.
7. Choose Next: Add Storage.
8. On the Add Storage page, you can specify volumes to attach to the instance besides the volumes
specified by the AMI (such as the root device volume), and then choose Next: Add Tags.
9. On the Add Tags page, specify tags for the instance, such as a user-friendly name, and then choose
Next: Configure Security Group.
10. On the Configure Security Group page, you can select a security group or create a new one. Choose
Review and Launch.
Note
If you specified an existing network interface in step 5, the instance is associated with the
security group for that network interface, regardless of any option that you select in this
step.
11. On the Review Instance Launch page, details about the primary and additional network interface
are displayed. Review the settings, and then choose Launch to choose a key pair and launch your
instance. If you're new to Amazon EC2 and haven't created any key pairs, the wizard prompts you to
create one.
To attach a network interface when launching an instance using the command line
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
744
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with Network Interfaces
4. In the Attach Network Interface dialog box, select the instance and choose Attach.
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
To detach a network interface from an instance using the Network Interfaces page
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
745
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with Network Interfaces
3. Select the network interface and choose Actions, Change Security Groups.
4. In the Change Security Groups dialog box, select the security groups to use, and choose Save.
To change the security group of a network interface using the command line
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
To change source/destination checking for a network interface using the command line
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
You can associate an Elastic IP address using the Amazon EC2 console or the command line.
746
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with Network Interfaces
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
You can disassociate an Elastic IP address using the Amazon EC2 console or the command line.
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
• You can use one of the following commands. For more information about these command line
interfaces, see Accessing Amazon EC2 (p. 3).
747
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with Network Interfaces
To unassign an IPv6 address from a network interface using the command line
• You can use one of the following commands. For more information about these command line
interfaces, see Accessing Amazon EC2 (p. 3).
You can change the terminating behavior for a network interface using the Amazon EC2 console or the
command line.
To change the termination behavior for a network interface using the console
To change the termination behavior for a network interface using the command line
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
748
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Requester-Managed Network Interfaces
To change the description for a network interface using the command line
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
To add or edit tags for a network interface using the command line
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
You cannot modify or detach a requester-managed network interface. If you delete the resource that
the network interface represents, the AWS service detaches and deletes the network interface for
you. To change the security groups for a requester-managed network interface, you might have to
use the console or command line tools for that service. For more information, see the service-specific
documentation.
You can tag a requester-managed network interface. For more information, see Adding or Editing
Tags (p. 749).
You can view the requester-managed network interfaces that are in your account.
749
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Enhanced Networking
• Attachment owner: If you created the network interface, this field displays your AWS account ID.
Otherwise, it displays an alias or ID for the principal or service that created the network interface.
• Description: Provides information about the purpose of the network interface; for example, "VPC
Endpoint Interface".
1. Use the describe-network-interfaces AWS CLI command to describe the network interfaces in your
account.
2. In the output, the RequesterManaged field displays true if the network interface is managed by
another AWS service.
{
"Status": "in-use",
...
"Description": "VPC Endpoint Interface vpce-089f2123488812123",
"NetworkInterfaceId": "eni-c8fbc27e",
"VpcId": "vpc-1a2b3c4d",
"PrivateIpAddresses": [
{
"PrivateDnsName": "ip-10-0-2-227.ec2.internal",
"Primary": true,
"PrivateIpAddress": "10.0.2.227"
}
],
"RequesterManaged": true,
...
}
Contents
• Enhanced Networking Types (p. 751)
• Enabling Enhanced Networking on Your Instance (p. 751)
• Enabling Enhanced Networking with the Elastic Network Adapter (ENA) on Linux Instances (p. 751)
• Enabling Enhanced Networking with the Intel 82599 VF Interface on Linux Instances (p. 763)
• Troubleshooting the Elastic Network Adapter (ENA) (p. 769)
750
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Enhanced Networking Types
The Elastic Network Adapter (ENA) supports network speeds of up to 100 Gbps for supported
instance types.
A1, C5, C5d, C5n, F1, G3, H1, I3, I3en, m4.16xlarge, M5, M5a, M5ad, M5d, P2, P3, R4, R5, R5a,
R5ad, R5d, T3, T3a, u-6tb1.metal, u-9tb1.metal, u-12tb1.metal, X1, X1e, and z1d instances
use the Elastic Network Adapter for enhanced networking.
Intel 82599 Virtual Function (VF) interface
The Intel 82599 Virtual Function interface supports network speeds of up to 10 Gbps for supported
instance types.
C3, C4, D2, I2, M4 (excluding m4.16xlarge), and R3 instances use the Intel 82599 VF interface for
enhanced networking.
For information about the supported network speed for each instance type, see Amazon EC2 Instance
Types.
If your instance type supports the Intel 82599 VF interface for enhanced networking, follow
the procedures in Enabling Enhanced Networking with the Intel 82599 VF Interface on Linux
Instances (p. 763).
Contents
• Requirements (p. 751)
• Data Encryption (p. 752)
• Testing Whether Enhanced Networking Is Enabled (p. 752)
• Enabling Enhanced Networking on the Amazon Linux AMI (p. 754)
• Enabling Enhanced Networking on Ubuntu (p. 755)
• Enabling Enhanced Networking on Linux (p. 756)
• Enabling Enhanced Networking on Ubuntu with DKMS (p. 758)
• Troubleshooting (p. 760)
• Operating System Optimizations (p. 760)
Requirements
To prepare for enhanced networking using the ENA, set up your instance as follows:
751
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Enhanced Networking: ENA
• Select from the following supported instance types: A1, C5, C5d, C5n, F1, G3, H1, I3, I3en,
m4.16xlarge, M5, M5a, M5ad, M5d, P2, P3, R4, R5, R5a, R5ad, R5d, T3, T3a, u-6tb1.metal,
u-9tb1.metal, u-12tb1.metal, X1, X1e, and z1d.
• Launch the instance using a supported version of the Linux kernel and a supported distribution, so that
ENA enhanced networking is enabled for your instance automatically. For more information, see ENA
Linux Kernel Driver Release Notes.
• Ensure that the instance has internet connectivity.
• Install and configure the AWS CLI or the AWS Tools for Windows PowerShell on any computer
you choose, preferably your local desktop or laptop. For more information, see Accessing Amazon
EC2 (p. 3). Enhanced networking cannot be managed from the Amazon EC2 console.
• If you have important data on the instance that you want to preserve, you should back that data up
now by creating an AMI from your instance. Updating kernels and kernel modules, as well as enabling
the enaSupport attribute, might render incompatible instances or operating systems unreachable; if
you have a recent backup, your data will still be retained if this happens.
Data Encryption
AWS provides secure and private connectivity between EC2 instances. In addition, we automatically
encrypt in-transit traffic between C5n, I3en, and P3dn instances in the same VPC or in peered VPCs,
using AEAD algorithms with 256-bit encryption. This encryption feature uses the offload capabilities of
the underlying hardware, and there is no impact on network performance.
To verify that the ena module is installed, use the modinfo command as follows:
In the above Ubuntu instance, the module is not installed, so you must first install it. For more
information, see Enabling Enhanced Networking on Ubuntu (p. 755).
752
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Enhanced Networking: ENA
To check whether an AMI has the enhanced networking enaSupport attribute set, use one of the
following commands. If the attribute is set, the response is true.
Use the following command to verify that the ena module is being used on a particular interface,
substituting the interface name that you wish to check. If you are using a single interface (default), it will
be eth0.
In the above case, the ena module is not loaded, because the listed driver is vif.
753
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Enhanced Networking: ENA
In this case, the ena module is loaded and at the minimum recommended version. This instance has
enhanced networking properly configured.
If you launched your instance using an older Amazon Linux AMI and it does not have enhanced
networking enabled already, use the following procedure to enable enhanced networking.
3. From your local computer, reboot your instance using the Amazon EC2 console or one of the
following commands: reboot-instances (AWS CLI), Restart-EC2Instance (AWS Tools for Windows
PowerShell).
4. Connect to your instance again and verify that the ena module is installed and at the minimum
recommended version using the modinfo ena command from Testing Whether Enhanced
Networking Is Enabled (p. 752).
5. [EBS-backed instance] From your local computer, stop the instance using the Amazon EC2 console
or one of the following commands: stop-instances (AWS CLI), Stop-EC2Instance (AWS Tools for
Windows PowerShell). If your instance is managed by AWS OpsWorks, you should stop the instance
in the AWS OpsWorks console so that the instance state remains in sync.
[Instance store-backed instance] You can't stop the instance to modify the attribute. Instead,
proceed to this procedure: To enable enhanced networking on Amazon Linux AMI (instance store-
backed instances) (p. 755).
6. From your local computer, enable the enhanced networking attribute using one of the following
commands:
7. (Optional) Create an AMI from the instance, as described in Creating an Amazon EBS-Backed Linux
AMI (p. 116). The AMI inherits the enhanced networking enaSupport attribute from the instance.
Therefore, you can use this AMI to launch another instance with enhanced networking enabled by
default.
8. From your local computer, start the instance using the Amazon EC2 console or one of the following
commands: start-instances (AWS CLI), Start-EC2Instance (AWS Tools for Windows PowerShell). If
your instance is managed by AWS OpsWorks, you should start the instance in the AWS OpsWorks
console so that the instance state remains in sync.
754
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Enhanced Networking: ENA
9. Connect to your instance and verify that the ena module is installed and loaded on your network
interface using the ethtool -i ethn command from Testing Whether Enhanced Networking Is
Enabled (p. 752).
If you are unable to connect to your instance after enabling enhanced networking, see
Troubleshooting the Elastic Network Adapter (ENA) (p. 769).
Follow the previous procedure until the step where you stop the instance. Create a new AMI as described
in Creating an Instance Store-Backed Linux AMI (p. 119), making sure to enable the enhanced networking
attribute when you register the AMI.
If you launched your instance using an older AMI and it does not have enhanced networking enabled
already, you can install the linux-aws kernel package to get the latest enhanced networking drivers
and update the required attribute.
Ubuntu 16.04 and 18.04 ship with the Ubuntu custom kernel (linux-aws kernel package). To use a
different kernel, contact AWS Support.
Important
If during the update process you are prompted to install grub, use /dev/xvda to install
grub onto, and then choose to keep the current version of /boot/grub/menu.lst.
3. [EBS-backed instance] From your local computer, stop the instance using the Amazon EC2 console
or one of the following commands: stop-instances (AWS CLI), Stop-EC2Instance (AWS Tools for
Windows PowerShell). If your instance is managed by AWS OpsWorks, you should stop the instance
in the AWS OpsWorks console so that the instance state remains in sync.
[Instance store-backed instance] You can't stop the instance to modify the attribute. Instead,
proceed to this procedure: To enable enhanced networking on Ubuntu (instance store-backed
instances) (p. 756).
755
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Enhanced Networking: ENA
4. From your local computer, enable the enhanced networking attribute using one of the following
commands:
5. (Optional) Create an AMI from the instance, as described in Creating an Amazon EBS-Backed Linux
AMI (p. 116). The AMI inherits the enhanced networking enaSupport attribute from the instance.
Therefore, you can use this AMI to launch another instance with enhanced networking enabled by
default.
6. From your local computer, start the instance using the Amazon EC2 console or one of the following
commands: start-instances (AWS CLI), Start-EC2Instance (AWS Tools for Windows PowerShell). If
your instance is managed by AWS OpsWorks, you should start the instance in the AWS OpsWorks
console so that the instance state remains in sync.
Follow the previous procedure until the step where you stop the instance. Create a new AMI as described
in Creating an Instance Store-Backed Linux AMI (p. 119), making sure to enable the enhanced networking
attribute when you register the AMI.
756
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Enhanced Networking: ENA
dracut -f -v
6. Determine if your system uses predictable network interface names by default. Systems that use
systemd or udev versions 197 or greater can rename Ethernet devices and they do not guarantee
that a single network interface will be named eth0. This behavior can cause problems connecting to
your instance. For more information and to see other configuration options, see Predictable Network
Interface Names on the freedesktop.org website.
a. You can check the systemd or udev versions on RPM-based systems with the following
command:
In the above Red Hat Enterprise Linux 7 example, the systemd version is 208, so predictable
network interface names must be disabled.
b. Disable predictable network interface names by adding the net.ifnames=0 option to the
GRUB_CMDLINE_LINUX line in /etc/default/grub.
7. [EBS-backed instance] From your local computer, stop the instance using the Amazon EC2 console
or one of the following commands: stop-instances (AWS CLI), Stop-EC2Instance (AWS Tools for
Windows PowerShell). If your instance is managed by AWS OpsWorks, you should stop the instance
in the AWS OpsWorks console so that the instance state remains in sync.
[Instance store-backed instance] You can't stop the instance to modify the attribute. Instead,
proceed to this procedure: To enable enhanced networking on Linux (instance store–backed
instances) (p. 758).
8. From your local computer, enable the enhanced networking enaSupport attribute using one of the
following commands:
9. (Optional) Create an AMI from the instance, as described in Creating an Amazon EBS-Backed Linux
AMI (p. 116) . The AMI inherits the enhanced networking enaSupport attribute from the instance.
Therefore, you can use this AMI to launch another instance with enhanced networking enabled by
default.
Important
If your instance operating system contains an /etc/udev/rules.d/70-persistent-
net.rules file, you must delete it before creating the AMI. This file contains the MAC
address for the Ethernet adapter of the original instance. If another instance boots with
757
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Enhanced Networking: ENA
this file, the operating system will be unable to find the device and eth0 might fail, causing
boot issues. This file is regenerated at the next boot cycle, and any instances launched from
the AMI create their own version of the file.
10. From your local computer, start the instance using the Amazon EC2 console or one of the following
commands: start-instances (AWS CLI), Start-EC2Instance (AWS Tools for Windows PowerShell). If
your instance is managed by AWS OpsWorks, you should start the instance in the AWS OpsWorks
console so that the instance state remains in sync.
11. (Optional) Connect to your instance and verify that the module is installed.
If you are unable to connect to your instance after enabling enhanced networking, see
Troubleshooting the Elastic Network Adapter (ENA) (p. 769).
Follow the previous procedure until the step where you stop the instance. Create a new AMI as described
in Creating an Instance Store-Backed Linux AMI (p. 119), making sure to enable the enhanced networking
attribute when you register the AMI.
3. Clone the source for the ena module on your instance from GitHub at https://github.com/amzn/
amzn-drivers.
4. Move the amzn-drivers package to the /usr/src/ directory so dkms can find it and build it for
each kernel update. Append the version number (you can find the current version number in the
release notes) of the source code to the directory name. For example, version 1.0.0 is shown in the
example below.
758
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Enhanced Networking: ENA
5. Create the dkms configuration file with the following values, substituting your version of ena.
6. Add, build, and install the ena module on your instance using dkms.
8. Verify that the ena module is installed using the modinfo ena command from Testing Whether
Enhanced Networking Is Enabled (p. 752).
759
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Enhanced Networking: ENA
Troubleshooting
For additional information about troubleshooting your ENA adapter, see Troubleshooting the Elastic
Network Adapter (ENA) (p. 769).
In addition to these operating system optimizations, you should also consider the maximum transmission
unit (MTU) of your network traffic, and adjust according to your workload and network architecture. For
more information, see Network Maximum Transmission Unit (MTU) for Your EC2 Instance (p. 793).
AWS regularly measures average round trip latencies between instances launched in a cluster placement
group of 50us and tail latencies of 200us at the 99.9 percentile. If your applications require consistently
low latencies, we recommend using the latest version of the ENA drivers on fixed performance Nitro-
based instances.
These procedures were written for Amazon Linux 2 and Amazon Linux AMI. However, they may also work
for other Linux distributions with kernel version 3.9 or newer. For more information, see your system-
specific documentation.
cat /sys/devices/system/clocksource/clocksource0/current_clocksource
2. If the clock source is xen, complete the following substeps. Otherwise, skip to Step 3 (p. 761).
a. Edit the GRUB configuration and add xen_nopvspin=1 and clocksource=tsc to the kernel
boot options.
• For Amazon Linux 2, edit the /etc/default/grub file and add these options to the
GRUB_CMDLINE_LINUX_DEFAULT line, as shown below:
• For Amazon Linux AMI, edit the /boot/grub/grub.conf file and add these options to the
kernel line, as shown below:
760
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Enhanced Networking: ENA
b. (Amazon Linux 2 only) Rebuild your GRUB configuration file to pick up these changes:
3. If your instance type is listed as supported on Processor State Control for Your EC2 Instance (p. 494),
prevent the system from using deeper C-states to ensure low-latency system performance. For more
information, see High Performance and Low Latency by Limiting Deeper C-states (p. 496).
a. Edit the GRUB configuration and add intel_idle.max_cstate=1 to the kernel boot options.
• For Amazon Linux 2, edit the /etc/default/grub file and add this option to the
GRUB_CMDLINE_LINUX_DEFAULT line, as shown below:
GRUB_CMDLINE_LINUX_DEFAULT="console=tty0 console=ttyS0,115200n8
net.ifnames=0 biosdevname=0 nvme_core.io_timeout=4294967295 xen_nopvspin=1
clocksource=tsc intel_idle.max_cstate=1"
GRUB_TIMEOUT=0
• For Amazon Linux AMI, edit the /boot/grub/grub.conf file and add this option to the
kernel line, as shown below:
b. (Amazon Linux 2 only) Rebuild your GRUB configuration file to pick up these changes:
4. Ensure that your reserved kernel memory is sufficient to sustain a high rate of packet buffer
allocations (the default value may be too small).
a. Open (as root or with sudo) the /etc/sysctl.conf file with the editor of your choice.
b. Add the vm.min_free_kbytes line to the file with the reserved kernel memory value (in
kilobytes) for your instance type. As a rule of thumb, you should set this value to between
1-3% of available system memory, and adjust this value up or down to meet the needs of your
application.
vm.min_free_kbytes = 1048576
sudo sysctl -p
d. Verify that the setting was applied with the following command:
sudo reboot
6. (Optional) Manually distribute packet receive interrupts so that they are associated with different
CPUs that all belong to the same NUMA node. Use this carefully, however, because irqbalancer is
disabled globally.
Note
The configuration change in this step does not survive a reboot.
761
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Enhanced Networking: ENA
a. Create a file called smp_affinity.sh and paste the following code block into it:
✔/bin/sh
service irqbalance stop
affinity_values=(00000001 00000002 00000004 00000008 00000010 00000020 00000040
00000080)
irqs=($(grep eth /proc/interrupts|awk '{print $1}'|cut -d : -f 1))
irqLen=${✔irqs[@]}
for (( i=0; i<${irqLen}; i++ ));
do
echo $(printf "0000,00000000,00000000,00000000,${affinity_values[$i]}") > /proc/
irq/${irqs[$i]}/smp_affinity;
echo "IRQ ${irqs[$i]} =" $(cat /proc/irq/${irqs[$i]}/smp_affinity);
done
7. (Optional) If the vCPUs that handle receive IRQs are overloaded, or if your application network
processing is demanding on CPU, you can offload part of the network processing to other cores
with receive packet steering (RPS). Ensure that cores used for RPS belong to the same NUMA node
to avoid inter-NUMA node locks. For example, to use cores 8-15 for packet processing, use the
following command.
Note
The configuration change in this step does not survive a reboot.
a. Install numactl:
b. When you run your network processing program, bind it to a single NUMA node. For example,
the following command binds the shell script, run.sh, to NUMA node 0:
c. If you have hyperthreading enabled, you can configure your application to only use a single
hardware thread per CPU core.
• You can view which CPU cores map to a NUMA node with the lscpu command:
Output:
NUMA node(s): 2
NUMA node0 CPU(s): 0-15,32-47
NUMA node1 CPU(s): 16-31,48-63
• You can view which hardware threads belong to a physical CPU with the following command:
762
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Enhanced Networking: Intel 82599 VF
cat /sys/devices/system/cpu/cpu0/topology/thread_siblings_list
Output:
0,32
9. Use multiple elastic network interfaces for different classes of traffic. For example, if you are running
a web server that uses a backend database, use one elastic network interfaces for the web server
front end, and another for the database connection.
Contents
• Requirements (p. 763)
• Testing Whether Enhanced Networking is Enabled (p. 764)
• Enabling Enhanced Networking on Amazon Linux (p. 765)
• Enabling Enhanced Networking on Ubuntu (p. 766)
• Enabling Enhanced Networking on Other Linux Distributions (p. 767)
• Troubleshooting Connectivity Issues (p. 769)
Requirements
To prepare for enhanced networking using the Intel 82599 VF interface, set up your instance as follows:
• Select from the following supported instance types: C3, C4, D2, I2, M4 (excluding m4.16xlarge), and
R3.
• Launch the instance from an HVM AMI using Linux kernel version of 2.6.32 or later. The latest Amazon
Linux HVM AMIs have the modules required for enhanced networking installed and have the required
attributes set. Therefore, if you launch an Amazon EBS–backed, enhanced networking–supported
instance using a current Amazon Linux HVM AMI, enhanced networking is already enabled for your
instance.
Warning
Enhanced networking is supported only for HVM instances. Enabling enhanced networking
with a PV instance can make it unreachable. Setting this attribute without the proper module
or module version can also make your instance unreachable.
• Ensure that the instance has internet connectivity.
• Install and configure the AWS CLI or the AWS Tools for Windows PowerShell on any computer
you choose, preferably your local desktop or laptop. For more information, see Accessing Amazon
EC2 (p. 3). Enhanced networking cannot be managed from the Amazon EC2 console.
763
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Enhanced Networking: Intel 82599 VF
• If you have important data on the instance that you want to preserve, you should back that data
up now by creating an AMI from your instance. Updating kernels and kernel modules, as well as
enabling the sriovNetSupport attribute, might render incompatible instances or operating systems
unreachable; if you have a recent backup, your data will still be retained if this happens.
To check whether an instance has the enhanced networking sriovNetSupport attribute set, use one of
the following commands:
"SriovNetSupport": {
"Value": "simple"
},
To check whether an AMI already has the enhanced networking sriovNetSupport attribute set, use
one of the following commands:
Note that this command only works for images that you own. You receive an AuthFailure error for
images that do not belong to your account.
• Get-EC2ImageAttribute (AWS Tools for Windows PowerShell)
"SriovNetSupport": {
"Value": "simple"
},
764
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Enhanced Networking: Intel 82599 VF
Use the following command to verify that the module is being used on a particular interface,
substituting the interface name that you wish to check. If you are using a single interface (default), it will
be eth0.
In the above case, the ixgbevf module is not loaded, because the listed driver is vif.
In this case, the ixgbevf module is loaded. This instance has enhanced networking properly configured.
If you launched your instance using an older Amazon Linux AMI and it does not have enhanced
networking enabled already, use the following procedure to enable enhanced networking.
Warning
There is no way to disable the enhanced networking attribute after you've enabled it.
3. From your local computer, reboot your instance using the Amazon EC2 console or one of the
following commands: reboot-instances (AWS CLI), Restart-EC2Instance (AWS Tools for Windows
PowerShell).
4. Connect to your instance again and verify that the ixgbevf module is installed and at the minimum
recommended version using the modinfo ixgbevf command from Testing Whether Enhanced
Networking is Enabled (p. 764).
765
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Enhanced Networking: Intel 82599 VF
5. [EBS-backed instance] From your local computer, stop the instance using the Amazon EC2 console
or one of the following commands: stop-instances (AWS CLI), Stop-EC2Instance (AWS Tools for
Windows PowerShell). If your instance is managed by AWS OpsWorks, you should stop the instance
in the AWS OpsWorks console so that the instance state remains in sync.
[Instance store-backed instance] You can't stop the instance to modify the attribute.
Instead, proceed to this procedure: To enable enhanced networking (instance store-backed
instances) (p. 766).
6. From your local computer, enable the enhanced networking attribute using one of the following
commands:
7. (Optional) Create an AMI from the instance, as described in Creating an Amazon EBS-Backed Linux
AMI (p. 116) . The AMI inherits the enhanced networking attribute from the instance. Therefore, you
can use this AMI to launch another instance with enhanced networking enabled by default.
8. From your local computer, start the instance using the Amazon EC2 console or one of the following
commands: start-instances (AWS CLI), Start-EC2Instance (AWS Tools for Windows PowerShell). If
your instance is managed by AWS OpsWorks, you should start the instance in the AWS OpsWorks
console so that the instance state remains in sync.
9. Connect to your instance and verify that the ixgbevf module is installed and loaded on your
network interface using the ethtool -i ethn command from Testing Whether Enhanced Networking
is Enabled (p. 764).
Follow the previous procedure until the step where you stop the instance. Create a new AMI as described
in Creating an Instance Store-Backed Linux AMI (p. 119), making sure to enable the enhanced networking
attribute when you register the AMI.
The Quick Start Ubuntu HVM AMIs include the necessary drivers for enhanced networking. If you have a
version of ixgbevf earlier than 2.16.4, you can install the linux-aws kernel package to get the latest
enhanced networking drivers.
The following procedure provides the general steps for compiling the ixgbevf module on an Ubuntu
instance.
766
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Enhanced Networking: Intel 82599 VF
Important
If during the update process, you are prompted to install grub, use /dev/xvda to install
grub, and then choose to keep the current version of /boot/grub/menu.lst.
The following procedure provides the general steps if you need to enable enhanced networking with
the Intel 82599 VF interface on a Linux distribution other than Amazon Linux or Ubuntu. For more
information, such as detailed syntax for commands, file locations, or package and tool support, see the
specific documentation for your Linux distribution.
Versions of ixgbevf earlier than 2.16.4, including version 2.14.2, do not build properly on some
Linux distributions, including certain versions of Ubuntu.
3. Compile and install the ixgbevf module on your instance.
Warning
If you compile the ixgbevf module for your current kernel and then upgrade your
kernel without rebuilding the driver for the new kernel, your system might revert to the
distribution-specific ixgbevf module at the next reboot, which could make your system
unreachable if the distribution-specific version is incompatible with enhanced networking.
4. Run the sudo depmod command to update module dependencies.
5. Update initramfs on your instance to ensure that the new module loads at boot time.
6. Determine if your system uses predictable network interface names by default. Systems that use
systemd or udev versions 197 or greater can rename Ethernet devices and they do not guarantee
that a single network interface will be named eth0. This behavior can cause problems connecting to
your instance. For more information and to see other configuration options, see Predictable Network
Interface Names on the freedesktop.org website.
a. You can check the systemd or udev versions on RPM-based systems with the following
command:
In the above Red Hat Enterprise Linux 7 example, the systemd version is 208, so predictable
network interface names must be disabled.
b. Disable predictable network interface names by adding the net.ifnames=0 option to the
GRUB_CMDLINE_LINUX line in /etc/default/grub.
767
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Enhanced Networking: Intel 82599 VF
7. [EBS-backed instance] From your local computer, stop the instance using the Amazon EC2 console
or one of the following commands: stop-instances (AWS CLI), Stop-EC2Instance (AWS Tools for
Windows PowerShell). If your instance is managed by AWS OpsWorks, you should stop the instance
in the AWS OpsWorks console so that the instance state remains in sync.
[Instance store-backed instance] You can't stop the instance to modify the attribute.
Instead, proceed to this procedure: To enable enhanced networking (instance store–backed
instances) (p. 768).
8. From your local computer, enable the enhanced networking attribute using one of the following
commands:
9. (Optional) Create an AMI from the instance, as described in Creating an Amazon EBS-Backed Linux
AMI (p. 116) . The AMI inherits the enhanced networking attribute from the instance. Therefore, you
can use this AMI to launch another instance with enhanced networking enabled by default.
Important
If your instance operating system contains an /etc/udev/rules.d/70-persistent-
net.rules file, you must delete it before creating the AMI. This file contains the MAC
address for the Ethernet adapter of the original instance. If another instance boots with
this file, the operating system will be unable to find the device and eth0 might fail, causing
boot issues. This file is regenerated at the next boot cycle, and any instances launched from
the AMI create their own version of the file.
10. From your local computer, start the instance using the Amazon EC2 console or one of the following
commands: start-instances (AWS CLI), Start-EC2Instance (AWS Tools for Windows PowerShell). If
your instance is managed by AWS OpsWorks, you should start the instance in the AWS OpsWorks
console so that the instance state remains in sync.
11. (Optional) Connect to your instance and verify that the module is installed.
Follow the previous procedure until the step where you stop the instance. Create a new AMI as described
in Creating an Instance Store-Backed Linux AMI (p. 119), making sure to enable the enhanced networking
attribute when you register the AMI.
768
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Troubleshooting ENA
If you enable enhanced networking for a PV instance or AMI, this can make your instance unreachable.
For more information, see How do I enable and configure enhanced networking on my EC2 instances?.
If you are unable to connect to your instance, start with the Troubleshooting Connectivity
Issues (p. 769) section.
If you are able to connect to your instance, you can gather diagnostic information by using the failure
detection and recovery mechanisms that are covered in the later sections of this topic.
Contents
• Troubleshooting Connectivity Issues (p. 769)
• Keep-Alive Mechanism (p. 770)
• Register Read Timeout (p. 771)
• Statistics (p. 771)
• Driver Error Logs in syslog (p. 774)
If you enable enhanced networking for a PV instance or AMI, this can also make your instance
unreachable.
If your instance becomes unreachable after enabling enhanced networking with ENA, you can disable the
enaSupport attribute for your instance and it will fall back to the stock network adapter.
1. From your local computer, stop the instance using the Amazon EC2 console or one of the following
commands: stop-instances (AWS CLI), Stop-EC2Instance (AWS Tools for Windows PowerShell). If your
instance is managed by AWS OpsWorks, you should stop the instance in the AWS OpsWorks console
so that the instance state remains in sync.
769
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Troubleshooting ENA
Important
If you are using an instance store-backed instance, you can't stop the instance.
Instead, proceed to To disable enhanced networking with ENA (instance store-backed
instances) (p. 770).
2. From your local computer, disable the enhanced networking attribute using the following command.
3. From your local computer, start the instance using the Amazon EC2 console or one of the following
commands: start-instances (AWS CLI), Start-EC2Instance (AWS Tools for Windows PowerShell). If
your instance is managed by AWS OpsWorks, you should start the instance in the AWS OpsWorks
console so that the instance state remains in sync.
4. (Optional) Connect to your instance and try reinstalling the ena module with your current kernel
version by following the steps in Enabling Enhanced Networking with the Elastic Network Adapter
(ENA) on Linux Instances (p. 751).
If your instance is an instance store-backed instance, create a new AMI as described in Creating an
Instance Store-Backed Linux AMI (p. 119). Be sure to disable the enhanced networking enaSupport
attribute when you register the AMI.
Keep-Alive Mechanism
The ENA device posts keep-alive events at a fixed rate (usually once every second). The ENA driver
implements a watchdog mechanism, which checks for the presence of these keep-alive messages. If a
message or messages are present, the watchdog is rearmed, otherwise the driver concludes that the
device experienced a failure and then does the following:
The above reset procedure may result in some traffic loss for a short period of time (TCP connections
should be able to recover), but should not otherwise affect the user.
The ENA device may also indirectly request a device reset procedure, by not sending a keep-alive
notification, for example, if the ENA device reaches an unknown state after loading an irrecoverable
configuration.
[18509.800135] ena 0000:00:07.0 eth1: Keep alive watchdog timeout. // The watchdog process
initiates a reset
770
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Troubleshooting ENA
If the driver logs (available in dmesg output) indicate failures of read operations, this may be caused by
an incompatible or incorrectly compiled driver, a busy hardware device, or hardware failure.
Intermittent log entries that indicate failures on read operations should not be considered an issue; the
driver will retry them in this case. However, a sequence of log entries containing read failures indicate a
driver or hardware problem.
Below is an example of driver log entry indicating a read operation failure due to a timeout:
Statistics
If you experience insufficient network performance or latency issues, you should retrieve the device
statistics and examine them. These statistics can be obtained using ethtool, as shown below:
771
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Troubleshooting ENA
tx_timeout: N
The number of times that the driver did not receive the keep-alive event in the preceding 3 seconds.
interface_up: N
The number of times that the ENA interface was brought up.
interface_down: N
The number of times that the ENA interface was brought down.
admin_q_pause: N
The admin queue is in an unstable state. This value should always be zero.
queue_N_tx_cnt: N
Direct memory access error count. If this value is not 0, it indicates low system resources.
queue_N_tx_napi_comp: N
The number of times the napi handler called napi_complete for queue N.
772
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Troubleshooting ENA
queue_N_tx_poll: N
The number of times the napi handler was scheduled for queue N.
queue_N_tx_doorbells: N
The number of times ena_com_prepare_tx failed for queue N. This value should always be zero; if
not, see the driver logs.
queue_N_tx_missing_tx_comp: codeN
The number of packets that were left uncompleted for queue N. This value should always be zero.
queue_N_tx_bad_req_id: N
Invalid req_id for queue N. The valid req_id is zero, minus the queue_size, minus 1.
queue_N_rx_cnt: N
The number of times the driver did not succeed in refilling the empty portion of the rx queue with
the buffers for queue N. If this value is not zero, it indicates low memory resources.
queue_N_rx_bad_csum: N
The number of times the rx queue had a bad checksum for queue N (only if rx checksum offload is
supported).
queue_N_rx_page_alloc_fail: N
The number of time that page allocation failed for queue N. If this value is not zero, it indicates low
memory resources.
queue_N_rx_skb_alloc_fail: N
The number of time that SKB allocation failed for queue N. If this value is not zero, it indicates low
system resources.
queue_N_rx_dma_mapping_err: N
Direct memory access error count. If this value is not 0, it indicates low system resources.
queue_N_rx_bad_desc_num: N
Too many buffers per packet. If this value is not 0, it indicates usage of very small buffers.
queue_N_rx_small_copy_len_pkt: N
Optimization: For packets smaller that this threshold, which is set by sysfs, the packet is copied
directly to the stack to avoid allocation of a new page.
773
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Troubleshooting ENA
ena_admin_q_aborted_cmd: N
The number of admin commands that were aborted. This usually happens during the auto-recovery
procedure.
ena_admin_q_submitted_cmd: N
The number of times that the driver tried to submit new admin command, but the queue was full.
ena_admin_q_no_completion: N
The number of times that the driver did not get an admin completion for a command.
The following warnings that may appear in your system's error logs can be ignored for the Elastic
Network Adapter:
774
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Elastic Fabric Adapter
This is a recoverable error, and it indicates that there may have been a memory pressure issue when
the error was thrown.
Feature X isn't supported
The referenced feature is not supported by the Elastic Network Adapter. Possible values for X
include:
• 10: RSS Hash function configuration is not supported for this device.
• 12: RSS Indirection table configuration is not supported for this device.
• 18: RSS Hash Input configuration is not supported for this device.
• 20: Interrupt moderation is not supported for this device.
• 27: The Elastic Network Adapter driver does not support polling the Ethernet capabilities from
snmpd.
Failed to config AENQ
This error indicates an attempt to set an AENQ events group that is not supported by the Elastic
Network Adapter.
EFA provides lower and more consistent latency and higher throughput than the TCP transport
traditionally used in cloud-based HPC systems. It enhances the performance of inter-instance
communication that is critical for scaling HPC applications.
EFA is optimized to work on the existing AWS network infrastructure and it can scale depending on
application requirements.
Note
The OS-bypass capabilities of EFAs are not supported on Windows instances. If you attach an
EFA to a Windows instance, the instance functions as an Elastic Network Adapter, without the
added EFA capabilities.
Contents
• EFA Basics (p. 776)
• Differences between EFAs and ENAs (p. 776)
• Supported Instance Types (p. 776)
• Supported AMIs (p. 777)
• EFA limitations (p. 777)
• Getting Started with EFAs (p. 777)
• Working with EFA (p. 781)
• Monitoring an EFA (p. 784)
775
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EFA Basics
EFA Basics
An EFA is an Elastic Network Adapter (ENA) with added capabilities. It provides all of the functionality
of an ENA, with an additional OS-bypass functionality. OS-bypass is an access model that allows HPC
applications to communicate directly with the network interface hardware to provide low-latency,
reliable transport functionality.
Traditionally, HPC applications use the Message Passing Interface (MPI) to interface with the system’s
network transport. In the AWS Cloud, this has meant that applications interface with MPI, which
then uses the operating system's TCP/IP stack and the ENA device driver in order to enable network
communication between instances.
With an EFA, HPC applications use MPI to interface with the libfabric API. The libfabric API bypasses the
operating system kernel and communicates directly with the EFA device to put packets on the network.
This reduces overhead and enables the HPC application to run more efficiently.
Note
Libfabric is a core component of the OpenFabrics Interfaces (OFI) framework, which defines and
exports the user-space API of OFI. For more information, see the Libfabric OpenFabrics website.
776
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Supported AMIs
Note
EFA requires an instance type that has at least 8GB of memory.
Supported AMIs
The following AMIs support EFAs: Amazon Linux, Amazon Linux 2, Red Hat Enterprise Linux 7.6, CentOS
7.6, Ubuntu 16.04, Ubuntu 18.04
EFA limitations
EFA has the following limitations:
Contents
• Step 1: Prepare an EFA-enabled Security Group (p. 777)
• Step 2: Launch a Temporary Instance (p. 778)
• Step 3: Install EFA Software Components (p. 778)
• Step 4: Install your HPC Application (p. 779)
• Step 5: Create an EFA-enabled AMI (p. 780)
• Step 6: Launch EFA-enabled Instances into a Cluster Placement Group (p. 780)
• Step 7: Terminate the Temporary Instance (p. 781)
a. For Security group name, enter a descriptive name for the security group, such as EFA-
enabled security group.
b. (Optional) For Description, enter a brief description of the security group.
c. For VPC, select the VPC into which you intend to launch your EFA-enabled instances.
d. Choose Create.
4. Select the security group that you created, and on the Description tab, copy the Group ID.
777
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Getting Started with EFAs
a. Choose Edit.
b. For Type, choose All traffic.
c. For Source, choose Custom.
d. Paste the security group ID that you copied into the field.
e. Choose Save.
1. Connect to the instance you launched in Step 2. For more information, see Connect to Your Linux
Instance (p. 446).
2. Update the instance software.
3. Download the EFA software installation files. The software installation files are packaged into a
compressed .tar.gz file.
778
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Getting Started with EFAs
$ wget https://s3-us-west-2.amazonaws.com/aws-efa-installer/aws-efa-installer-
latest.tar.gz
4. Extract the EFA software installation files from the compressed .tar.gz file. The files are extracted
into a directory named aws-efa-installer.
$ cd aws-efa-installer
6. Run the EFA software installation script. You can specify the -y option to run an unattended
installation.
$ sudo ./efa_installer.sh -y
$ fi_info -p efa
The command should return information about the libfabric EFA interfaces. The following is
example output of the command:
provider: efa
fabric: EFA-fe80::1a:feff:feef:82a6
domain: efa_0-rdm
version: 3.0
type: FI_EP_RDM
protocol: FI_PROTO_EFA
provider: efa
fabric: EFA-fe80::1a:feff:feef:82a6
domain: efa_0-dgrm
version: 3.0
type: FI_EP_DGRAM
protocol: FI_PROTO_EFA
provider: efa;ofi_rxd
fabric: EFA-fe80::1a:feff:feef:82a6
domain: efa_0-dgrm
version: 1.0
type: FI_EP_RDM
protocol: FI_PROTO_RXD
provider: efa;ofi_rxr
fabric: EFA-fe80::1a:feff:feef:82a6
domain: efa_0-rdm
version: 1.0
type: FI_EP_RDM
protocol: FI_PROTO_RXR
779
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Getting Started with EFAs
Note
You might need to refer to your HPC application’s documentation for installation instructions.
a. For Image name, enter a descriptive name for the AMI, such as EFA-enabled AMI.
b. (Optional) For Image description, enter a brief description of the AMI.
c. Choose Create Image and then choose Close.
5. In the navigation pane, choose AMIs.
6. Locate the AMI you created in the list. Wait for the Status to transition from pending to available
before continuing to the next step.
a. For Number of instances, enter the number of EFA-enabled instances that you want to launch.
b. For Network and Subnet, select the VPC and subnet into which to launch the instances.
c. For Placement group, select Add instance to placement group.
d. For Placement group name, select Add to a new placement group, enter a descriptive name
for the placement group, and then for Placement group strategy, select cluster.
e. For EFA, choose Enable.
f. In the Network Interfaces section, for device eth0, choose New network interface. You can
optionally specify a primary IPv4 address and one or more secondary IPv4 addresses. If you're
780
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with EFA
launching the instance into a subnet that has an associated IPv6 CIDR block, you can optionally
specify a primary IPv6 address and one or more secondary IPv6 addresses.
g. Choose Next: Add Storage.
6. On the Add Storage page, specify the volumes to attach to the instances in addition to the volumes
specified by the AMI (such as the root device volume), and then choose Next: Add Tags.
7. On the Add Tags page, specify tags for the instances, such as a user-friendly name, and then choose
Next: Configure Security Group.
8. On the Configure Security Group page, for Assign a security group, select Select an existing
security group, and then select the security group that you created in Step 1.
9. Choose Review and Launch.
10. On the Review Instance Launch page, review the settings, and then choose Launch to choose a key
pair and to launch your instances.
EFA Requirements
To use an EFA, you must do the following:
• Use one of the following supported instance types: c5n.18xlarge, i3en.24xlarge, p3dn.24xlarge
• Use one of the following supported AMIs: Amazon Linux, Amazon Linux 2, Red Hat Enterprise Linux
7.6, CentOS 7.6, Ubuntu 16.04, Ubuntu 18.04
• Install the EFA software components.
• Use a security group that allows all inbound and outbound traffic to and from the security group itself.
Contents
• Creating an EFA (p. 782)
• Attaching an EFA to a Stopped Instance (p. 782)
• Attaching an EFA When Launching an Instance (p. 782)
• Adding an EFA to a Launch Template (p. 783)
• Assigning an IP Address to an EFA (p. 783)
• Unassigning an IP Address from an EFA (p. 783)
• Changing the Security Group (p. 783)
781
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with EFA
Creating an EFA
You can create an EFA in a subnet in a VPC. You can't move the EFA to another subnet after it's created,
and you can only attach it to stopped instances in the same Availability Zone.
Use the create-network-interface command and for interface-type, specify efa. For example:
You attach an EFA to an instance in the same way that you attach an ENI to an instance. For more
information, see Attaching a Network Interface to a Stopped or Running Instance (p. 744).
Use the run-instances command and for NetworkInterfaceId, specify the ID of the EFA. For example:
782
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with EFA
Use the run-instances command and for InterfaceType, specify efa. For example:
You can leverage launch templates to launch EFA-enabled instances with other AWS services, such as
AWS Batch.
For more information about creating launch templates, see Creating a Launch Template (p. 405).
You assign an Elastic IP (IPv4) and IPv6 address to an EFA in the same way that you assign an IP address
to an ENI. For more information, see:
You change the security group that is associated with an EFA in the same way that you change
the security group that is associated with an ENI. For more information, see Changing the Security
Group (p. 745).
Detaching an EFA
To detach an EFA from an instance, you must first stop the instance. You cannot detach an EFA from an
instance that is in the running state.
783
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Monitoring an EFA
You detach an EFA from an instance in the same way that you detach an ENI from an instance. For more
information, see Detaching a Network Interface from an Instance (p. 745).
Viewing EFAs
You can view all of the EFAs in your account.
You view EFAs in the same way that you view ENIs. For more information, see Viewing Details about a
Network Interface (p. 743).
Deleting an EFA
To delete an EFA, you must first detach it from the instance. You cannot delete an EFA while it is
attached to an instance.
You delete EFAs in the same way that you delete ENIs. For more information, see Deleting a Network
Interface (p. 742).
Monitoring an EFA
You can use the following features to monitor the performance of your Elastic Fabric Adapters.
You create a flow log for an EFA in the same way that you create a flow log for an ENI. For more
information, see Creating a Flow Log in the Amazon VPC User Guide.
In the flow log entries, EFA traffic is identified by the srcAddress and destAddress, which are both
formatted as MAC addresses. For example:
Amazon CloudWatch
Amazon CloudWatch provides metrics that enable you to monitor your EFAs in real time. You can collect
and track metrics, create customized dashboards, and set alarms that notify you or take actions when
a specified metric reaches a threshold that you specify. For more information, see Monitoring Your
Instances Using CloudWatch (p. 558).
Placement Groups
When you launch a new EC2 instance, the EC2 service attempts to place the instance in such a way that
all of your instances are spread out across underlying hardware to minimize correlated failures. You can
use placement groups to influence the placement of a group of interdependent instances to meet the
784
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Cluster Placement Groups
needs of your workload. Depending on the type of workload, you can create a placement group using
one of the following placement strategies:
• Cluster – packs instances close together inside an Availability Zone. This strategy enables workloads
to achieve the low-latency network performance necessary for tightly-coupled node-to-node
communication that is typical of HPC applications.
• Partition – spreads your instances across logical partitions such that groups of instances in one
partition do not share the underlying hardware with groups of instances in different partitions. This
strategy is typically used by large distributed and replicated workloads, such as Hadoop, Cassandra,
and Kafka.
• Spread – strictly places a small group of instances across distinct underlying hardware to reduce
correlated failures.
Contents
• Cluster Placement Groups (p. 785)
• Partition Placement Groups (p. 786)
• Spread Placement Groups (p. 787)
• Placement Group Rules and Limitations (p. 787)
• Creating a Placement Group (p. 788)
• Launching Instances in a Placement Group (p. 789)
• Describing Instances in a Placement Group (p. 790)
• Changing the Placement Group for an Instance (p. 791)
• Deleting a Placement Group (p. 792)
The following image shows instances that are placed into a cluster placement group.
Cluster placement groups are recommended for applications that benefit from low network latency, high
network throughput, or both, and if the majority of the network traffic is between the instances in the
group. To provide the lowest latency and the highest packet-per-second network performance for your
placement group, choose an instance type that supports enhanced networking. For more information,
see Enhanced Networking (p. 750).
785
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Partition Placement Groups
We recommend that you launch the number of instances that you need in the placement group in a
single launch request and that you use the same instance type for all instances in the placement group.
If you try to add more instances to the placement group later, or if you try to launch more than one
instance type in the placement group, you increase your chances of getting an insufficient capacity error.
If you stop an instance in a placement group and then start it again, it still runs in the placement group.
However, the start fails if there isn't enough capacity for the instance.
If you receive a capacity error when launching an instance in a placement group that already has running
instances, stop and start all of the instances in the placement group, and try the launch again. Restarting
the instances may migrate them to hardware that has capacity for all the requested instances.
The following image is a simple visual representation of a partition placement group in a single
Availability Zone. It shows instances that are placed into a partition placement group with three
partitions—Partition 1, Partition 2, and Partition 3. Each partition comprises multiple instances. The
instances in a partition do not share racks with the instances in the other partitions, allowing you to
contain the impact of a single hardware failure to only the associated partition.
Partition placement groups can be used to deploy large distributed and replicated workloads, such as
HDFS, HBase, and Cassandra, across distinct racks. When you launch instances into a partition placement
group, Amazon EC2 tries to distribute the instances evenly across the number of partitions that you
specify. You can also launch instances into a specific partition to have more control over where the
instances are placed.
A partition placement group can have partitions in multiple Availability Zones in the same Region. A
partition placement group can have a maximum of seven partitions per Availability Zone. The number
of instances that can be launched into a partition placement group is limited only by the limits of your
account.
In addition, partition placement groups offer visibility into the partitions—you can see which instances
are in which partitions. You can share this information with topology-aware applications, such as HDFS,
HBase, and Cassandra. These applications use this information to make intelligent data replication
decisions for increasing data availability and durability.
If you start or launch an instance in a partition placement group and there is insufficient unique
hardware to fulfill the request, the request fails. Amazon EC2 makes more distinct hardware available
over time, so you can try your request again later.
786
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spread Placement Groups
The following image shows seven instances in a single Availability Zone that are placed into a spread
placement group. The seven instances are placed on seven different racks.
Spread placement groups are recommended for applications that have a small number of critical
instances that should be kept separate from each other. Launching instances in a spread placement
group reduces the risk of simultaneous failures that might occur when instances share the same racks.
Spread placement groups provide access to distinct racks, and are therefore suitable for mixing instance
types or launching instances over time.
A spread placement group can span multiple Availability Zones in the same Region. You can have a
maximum of seven running instances per Availability Zone per group.
If you start or launch an instance in a spread placement group and there is insufficient unique hardware
to fulfill the request, the request fails. Amazon EC2 makes more distinct hardware available over time, so
you can try your request again later.
• The name you specify for a placement group must be unique within your AWS account for the Region.
• You can't merge placement groups.
• An instance can be launched in one placement group at a time; it cannot span multiple placement
groups.
• On-Demand Capacity Reservation (p. 383) and zonal Reserved Instances (p. 258) provide a capacity
reservation for EC2 instances in a specific Availability Zone. The capacity reservation can be used
by instances in a placement group. However, it is not possible to explicitly reserve capacity for a
placement group.
• Instances with a tenancy of host cannot be launched in placement groups.
• For instances that are enabled for enhanced networking, traffic between instances within the same
Region that is addressed using IPv4 or IPv6 addresses can use up to 5 Gbps for single-flow traffic and
up to 25 Gbps for multi-flow traffic. A flow represents a single, point-to-point network connection.
• The following are the only instance types that you can use when you launch an instance into a cluster
placement group:
• General purpose: A1, M4, M5, M5a, M5ad, and M5d
• Compute optimized: C3, C4, C5, C5d, C5n, and cc2.8xlarge
787
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Creating a Placement Group
• Memory optimized: cr1.8xlarge, R3, R4, R5, R5a, R5ad, R5d, X1, X1e, and z1d
• Storage optimized: D2, H1, hs1.8xlarge, I2, I3, and I3en
• Accelerated computing: F1, G2, G3, P2, and P3
• A cluster placement group can't span multiple Availability Zones.
• The maximum network throughput speed of traffic between two instances in a cluster placement
group is limited by the slower of the two instances. For applications with high-throughput
requirements, choose an instance type with network connectivity that meets your requirements.
• For instances that are enabled for enhanced networking, the following rules apply:
• Instances within a cluster placement group can use up to 10 Gbps for single-flow traffic.
• Traffic to and from Amazon S3 buckets within the same Region over the public IP address space or
through a VPC endpoint can use all available instance aggregate bandwidth.
• You can launch multiple instance types into a cluster placement group. However, this reduces the
likelihood that the required capacity will be available for your launch to succeed. We recommend using
the same instance type for all instances in a cluster placement group.
• Network traffic to the internet and over an AWS Direct Connect connection to on-premises resources is
limited to 5 Gbps.
• A partition placement group supports a maximum of seven partitions per Availability Zone. The
number of instances that you can launch in a partition placement group is limited only by your account
limits.
• When instances are launched into a partition placement group, Amazon EC2 tries to evenly distribute
the instances across all partitions. Amazon EC2 doesn’t guarantee an even distribution of instances
across all partitions.
• A partition placement group with Dedicated Instances can have a maximum of two partitions.
• Partition placement groups are not supported for Dedicated Hosts.
• A spread placement group supports a maximum of seven running instances per Availability Zone. For
example, in a Region with three Availability Zones, you can run a total of 21 instances in the group
(seven per zone). If you try to start an eighth instance in the same Availability Zone and in the same
spread placement group, the instance will not launch. If you need to have more than seven instances in
an Availability Zone, then the recommendation is to use multiple spread placement groups. This does
not provide guarantees about the spread of instances between groups, but does ensure the spread for
each group to limit impact from certain classes of failures.
• Spread placement groups are not supported for Dedicated Instances or Dedicated Hosts.
788
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launching Instances in a Placement Group
• Use the create-placement-group command and specify the --strategy parameter with the value
partition and the --partition-count parameter. In this example, the partition placement
group is named HDFS-Group-A and is created with five partitions.
• On the Choose an Amazon Machine Image (AMI) page, select an AMI. To select an AMI you
created, choose My AMIs.
• On the Choose an Instance Type page, select an instance type that can be launched into a
placement group.
• On the Configure Instance Details page, the following fields are applicable to placement groups:
• For Number of instances, enter the total number of instances that you need in this placement
group, because you might not be able to add instances to the placement group later.
• For Placement group, select the Add instance to placement group check box. If you do not
see Placement group on this page, verify that you have selected an instance type that can be
launched into a placement group; otherwise, this option is not available.
• For Placement group name, you can choose to add the instances to an existing placement
group or to a new placement group that you create.
• For Placement group strategy, choose the appropriate strategy. If you choose partition, for
Target partition, choose Auto distribution to have Amazon EC2 do a best effort to distribute
the instances evenly across all the partitions in the group; or, specify the partition in which to
launch the instances.
1. Create an AMI for your instances using one of the following commands:
789
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Describing Instances in a Placement Group
To launch instances into a specific partition of a partition placement group (AWS CLI)
• Use the run-instances command and specify the placement group name and partition using the
--placement "GroupName = HDFS-Group-A, PartitionNumber = 3" parameter. In this
example, the placement group is named HDFS-Group-A and the partition number is 3.
To view the partition number for an instance in a partition placement group (AWS CLI)
The response contains the placement information, which includes the placement group name and
the partition number for the instance.
"Placement": {
"AvailabilityZone": "us-east-1c",
"GroupName": "HDFS-Group-A",
"PartitionNumber": 3,
"Tenancy": "default"
}
To filter instances for a specific partition placement group and partition number (AWS CLI)
• Use the describe-instances command and specify the --filters parameter with the placement-
group-name and placement-partition-number filters. In this example, the placement group is
named HDFS-Group-A and the partition number is 7.
790
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Changing the Placement Group for an Instance
The response lists all the instances that are in the specified partition within the specified placement
group. The following is example output showing only the instance ID, instance type, and placement
information for the returned instances.
"Instances": [
{
"InstanceId": "i-0a1bc23d4567e8f90",
"InstanceType": "r4.large",
},
"Placement": {
"AvailabilityZone": "us-east-1c",
"GroupName": "HDFS-Group-A",
"PartitionNumber": 7,
"Tenancy": "default"
}
{
"InstanceId": "i-0a9b876cd5d4ef321",
"InstanceType": "r4.large",
},
"Placement": {
"AvailabilityZone": "us-east-1c",
"GroupName": "HDFS-Group-A",
"PartitionNumber": 7,
"Tenancy": "default"
}
],
You can change the placement group for an instance using the command line or an AWS SDK.
Alternatively, use the Edit-EC2InstancePlacement command (AWS Tools for Windows PowerShell).
3. Restart the instance using one of the following commands:
791
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Deleting a Placement Group
Alternatively, use the Edit-EC2InstancePlacement command (AWS Tools for Windows PowerShell).
3. Restart the instance using one of the following commands:
Alternatively, follow the steps in Changing the Placement Group for an Instance (p. 791) to move
the instances to a different placement group.
4. In the navigation pane, choose Placement Groups.
5. Select the placement group and choose Delete Placement Group.
6. When prompted for confirmation, choose Delete.
You can use one of the following sets of commands. For more information about these command line
interfaces, see Accessing Amazon EC2 (p. 3).
792
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Network MTU
Ethernet frames can come in different formats, and the most common format is the standard Ethernet
v2 frame format. It supports 1500 MTU, which is the largest Ethernet packet size supported over most of
the Internet. The maximum supported MTU for an instance depends on its instance type. All Amazon EC2
instance types support 1500 MTU, and many current instance sizes support 9001 MTU, or jumbo frames.
Contents
• Jumbo Frames (9001 MTU) (p. 793)
• Path MTU Discovery (p. 794)
• Check the Path MTU Between Two Hosts (p. 794)
• Check and Set the MTU on Your Linux Instance (p. 794)
• Troubleshooting (p. 795)
Jumbo frames should be used with caution for Internet-bound traffic or any traffic that leaves a VPC.
Packets are fragmented by intermediate systems, which slows down this traffic. To use jumbo frames
inside a VPC and not slow traffic that's bound for outside the VPC, you can configure the MTU size by
route, or use multiple elastic network interfaces with different MTU sizes and different routes.
For instances that are collocated inside a cluster placement group, jumbo frames help to achieve the
maximum network throughput possible, and they are recommended in this case. For more information,
see Placement Groups (p. 784).
You can use jumbo frames for traffic between your VPCs and your on-premises networks over AWS Direct
Connect. For more information, and for how to verify Jumbo Frame capability, see Setting Network MTU
in the AWS Direct Connect User Guide.
• General purpose: A1, M3, M4, M5, M5a, M5ad, M5d, T2, T3, and T3a
• Compute optimized: C3, C4, C5, C5d, C5n, and CC2
• Memory optimized: CR1, R3, R4, R5, R5a, R5ad, R5d, X1, and z1d
• Storage optimized: D2, H1, HS1, I2, I3, and I3en
• Accelerated computing: F1, G2, G3, P2, and P3
• Bare metal: c5.metal, i3.metal, m5.metal, m5d.metal, r5.metal, r5d.metal, u-6tb1.metal,
u-9tb1.metal, u-12tb1.metal, and z1d.metal
793
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Path MTU Discovery
By default, security groups do not allow any inbound ICMP traffic. To ensure that your instance can
receive this message and the packet does not get dropped, you must add a Custom ICMP Rule with
the Destination Unreachable protocol to the inbound security group rules for your instance. For more
information, see Rules for Path MTU Discovery (p. 619).
Important
Modifying your instance's security group to allow path MTU discovery does not guarantee
that jumbo frames will not be dropped by some routers. An Internet gateway in your VPC will
forward packets up to 1500 bytes only. 1500 MTU packets are recommended for Internet traffic.
Use the following command to check the path MTU between your EC2 instance and another host. You
can use a DNS name or an IP address as the destination. If the destination is another EC2 instance, verify
that the security group allows inbound UDP traffic. This example checks the path MTU between an EC2
instance and amazon.com.
794
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Troubleshooting
You can check the current MTU value using the following ip command. Note that in the example output,
mtu 9001 indicates that this instance uses jumbo frames.
1. You can set the MTU value using the ip command. The following command sets the desired MTU
value to 1500, but you could use 9001 instead.
2. (Optional) To persist your network MTU setting after a reboot, modify the following configuration
files, based on your operating system type.
MTU=1500
• For Amazon Linux, add the following lines to your /etc/dhcp/dhclient-eth0.conf file.
interface "eth0" {
supersede interface-mtu 1500;
}
Troubleshooting
If you experience connectivity issues between your EC2 instance and an Amazon Redshift cluster when
using jumbo frames, see Queries Appear to Hang in the Amazon Redshift Cluster Management Guide
795
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Amazon VPC Documentation
When you create your AWS account, we create a default VPC for you in each region. A default VPC is a
VPC that is already configured and ready for you to use. You can launch instances into your default VPC
immediately. Alternatively, you can create your own nondefault VPC and configure it as you need.
If you created your AWS account before 2013-12-04, you might have support for the EC2-Classic
platform in some regions. If you created your AWS account after 2013-12-04, it does not support EC2-
Classic, so you must launch your resources in a VPC. For more information, see EC2-Classic (p. 796).
Guide Description
Amazon VPC User Guide Describes key concepts and provides instructions
for using the features of Amazon VPC.
Amazon VPC Peering Guide Describes VPC peering connections and provides
instructions for using them.
Amazon VPC Network Administrator Guide Helps network administrators configure customer
gateways.
EC2-Classic
With EC2-Classic, your instances run in a single, flat network that you share with other customers. With
Amazon VPC, your instances run in a virtual private cloud (VPC) that's logically isolated to your AWS
account.
The EC2-Classic platform was introduced in the original release of Amazon EC2. If you created your
AWS account after 2013-12-04, it does not support EC2-Classic, so you must launch your Amazon EC2
instances in a VPC.
If your account does not support EC2-Classic, we create a default VPC for you. By default, when you
launch an instance, we launch it into your default VPC. Alternatively, you can create a nondefault VPC
and specify it when you launch an instance.
Verify that the region you'll use is selected in the navigation bar. On the Amazon EC2 console dashboard,
look for Supported Platforms under Account Attributes.
796
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Types Available in EC2-Classic
The output of the describe-account-attributes command includes both the EC2 and VPC values for the
supported-platforms attribute.
The output of the describe-account-attributes command includes only the VPC value for the
supported-platforms attribute.
797
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Differences Between Instances in EC2-Classic and a VPC
If your account supports EC2-Classic but you have not created a nondefault VPC, you can do one of the
following to launch instances that require a VPC:
• Create a nondefault VPC and launch your VPC-only instance into it by specifying a subnet ID or a
network interface ID in the request. Note that you must create a nondefault VPC if you do not have
a default VPC and you are using the AWS CLI, Amazon EC2 API, or AWS SDK to launch a VPC-only
instance. For more information, see Create a Virtual Private Cloud (VPC) (p. 24).
• Launch your VPC-only instance using the Amazon EC2 console. The Amazon EC2 console creates a
nondefault VPC in your account and launches the instance into the subnet in the first Availability Zone.
The console creates the VPC with the following attributes:
• One subnet in each Availability Zone, with the public IPv4 addressing attribute set to true so that
instances receive a public IPv4 address. For more information, see IP Addressing in Your VPC in the
Amazon VPC User Guide.
• An Internet gateway, and a main route table that routes traffic in the VPC to the Internet gateway.
This enables the instances you launch in the VPC to communicate over the Internet. For more
information, see Internet Gateways in the Amazon VPC User Guide.
• A default security group for the VPC and a default network ACL that is associated with each subnet.
For more information, see Security in Your VPC in the Amazon VPC User Guide.
If you have other resources in EC2-Classic, you can take steps to migrate them to a VPC. For more
information, see Migrating from a Linux Instance in EC2-Classic to a Linux Instance in a VPC (p. 816).
Public IPv4 Your instance receives a Your instance launched in Your instance doesn't
address (from public IPv4 address from a default subnet receives receive a public IPv4
Amazon's the EC2-Classic public IPv4 a public IPv4 address address by default, unless
public IP address pool. by default, unless you you specify otherwise
address pool) specify otherwise during during launch, or you
launch, or you modify modify the subnet's public
the subnet's public IPv4 IPv4 address attribute.
address attribute.
Private IPv4 Your instance receives a Your instance receives a Your instance receives a
address private IPv4 address from static private IPv4 address static private IPv4 address
the EC2-Classic range each from the address range of from the address range of
time it's started. your default VPC. your VPC.
Multiple We select a single You can assign multiple You can assign multiple
private IPv4 private IP address for private IPv4 addresses to private IPv4 addresses to
addresses your instance; multiple your instance. your instance.
IP addresses are not
supported.
798
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Differences Between Instances in EC2-Classic and a VPC
Reassociating If the Elastic IP address is If the Elastic IP address is If the Elastic IP address
an Elastic IP already associated with already associated with is already associated
address another instance, the another instance, the with another instance,
address is automatically address is automatically it succeeds only if you
associated with the new associated with the new allowed reassociation.
instance. instance.
Tagging Elastic You cannot apply tags to You can apply tags to an You can apply tags to an
IP addresses an Elastic IP address. Elastic IP address. Elastic IP address.
DNS DNS hostnames are DNS hostnames are DNS hostnames are
hostnames enabled by default. enabled by default. disabled by default.
Security group A security group can A security group can A security group can
reference security groups reference security groups reference security groups
that belong to other AWS for your VPC only. for your VPC only.
accounts.
Security group You can assign an You can assign up to 5 You can assign up to 5
association unlimited number of security groups to an security groups to an
security groups to an instance. instance.
instance when you launch
it. You can assign security You can assign security
groups to your instance groups to your instance
You can't change the when you launch it and when you launch it and
security groups of your while it's running. while it's running.
running instance. You can
either modify the rules
of the assigned security
groups, or replace the
instance with a new one
(create an AMI from the
instance, launch a new
instance from this AMI
with the security groups
that you need, disassociate
any Elastic IP address
from the original instance
and associate it with the
new instance, and then
terminate the original
instance).
799
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Differences Between Instances in EC2-Classic and a VPC
Security group You can add rules for You can add rules for You can add rules for
rules inbound traffic only. inbound and outbound inbound and outbound
traffic. traffic.
Tenancy Your instance runs on You can run your instance You can run your instance
shared hardware. on shared hardware or on shared hardware or
single-tenant hardware. single-tenant hardware.
Accessing the Your instance can access By default, your instance By default, your instance
Internet the Internet. Your instance can access the Internet. cannot access the Internet.
automatically receives a Your instance receives Your instance doesn't
public IP address, and can a public IP address by receive a public IP address
access the Internet directly default. An Internet by default. Your VPC may
through the AWS network gateway is attached to have an Internet gateway,
edge. your default VPC, and your depending on how it was
default subnet has a route created.
to the Internet gateway.
IPv6 IPv6 addressing is not You can optionally You can optionally
addressing supported. You cannot associate an IPv6 CIDR associate an IPv6 CIDR
assign IPv6 addresses to block with your VPC, and block with your VPC, and
your instances. assign IPv6 addresses to assign IPv6 addresses to
instances in your VPC. instances in your VPC.
After you launch an instance in EC2-Classic, you can't change its security groups. However, you can
add rules to or remove rules from a security group, and those changes are automatically applied to all
instances that are associated with the security group after a short period.
Your AWS account automatically has a default security group per region for EC2-Classic. If you try to
delete the default security group, you'll get the following error: Client.InvalidGroup.Reserved: The
security group 'default' is reserved.
You can create custom security groups. The security group name must be unique within your account for
the region. To create a security group for use in EC2-Classic, choose No VPC for the VPC.
You can add inbound rules to your default and custom security groups. You can't change the outbound
rules for an EC2-Classic security group. When you create a security group rule, you can use a different
security group for EC2-Classic in the same region as the source or destination. To specify a security
group for another AWS account, add the AWS account ID as a prefix; for example, 111122223333/sg-
edcd9784.
In EC2-Classic, you can have up to 500 security groups in each region for each account. You can associate
an instance with up to 500 security groups and add up to 100 rules to a security group.
800
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Differences Between Instances in EC2-Classic and a VPC
If you create a custom firewall configuration in EC2-Classic, you must create a rule in your firewall that
allows inbound traffic from port 53 (DNS)—with a destination port from the ephemeral range—from
the address of the Amazon DNS server; otherwise, internal DNS resolution from your instances fails. If
your firewall doesn't automatically allow DNS query responses, then you need to allow traffic from the
IP address of the Amazon DNS server. To get the IP address of the Amazon DNS server, use the following
command from within your instance:
Elastic IP Addresses
If your account supports EC2-Classic, there's one pool of Elastic IP addresses for use with the EC2-Classic
platform and another for use with your VPCs. You can't associate an Elastic IP address that you allocated
for use with a VPC with an instance in EC2-Classic, and vice- versa. However, you can migrate an Elastic
IP address you've allocated for use in the EC2-Classic platform for use with a VPC. You cannot migrate an
Elastic IP address to another region.
After you've migrated an Elastic IP address to a VPC, you cannot use it with EC2-Classic. However, if
required, you can restore it to EC2-Classic. You cannot migrate an Elastic IP address that was originally
allocated for use with a VPC to EC2-Classic.
To migrate an Elastic IP address, it must not be associated with an instance. For more information
about disassociating an Elastic IP address from an instance, see Disassociating an Elastic IP Address and
Reassociating with a Different Instance (p. 727).
You can migrate as many EC2-Classic Elastic IP addresses as you can have in your account. However,
when you migrate an Elastic IP address, it counts against your Elastic IP address limit for VPCs. You
cannot migrate an Elastic IP address if it will result in your exceeding your limit. Similarly, when you
restore an Elastic IP address to EC2-Classic, it counts against your Elastic IP address limit for EC2-Classic.
For more information, see Elastic IP Address Limit (p. 729).
You cannot migrate an Elastic IP address that has been allocated to your account for less than 24 hours.
You can migrate an Elastic IP address from EC2-Classic using the Amazon EC2 console or the Amazon
VPC console. This option is only available if your account supports EC2-Classic.
801
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Sharing and Accessing Resources
Between EC2-Classic and a VPC
3. Select the Elastic IP address, and choose Actions, Move to VPC scope.
4. In the confirmation dialog box, choose Move Elastic IP.
You can restore an Elastic IP address to EC2-Classic using the Amazon EC2 console or the Amazon VPC
console.
After you've performed the command to move or restore your Elastic IP address, the process of
migrating the Elastic IP address can take a few minutes. Use the describe-moving-addresses command to
check whether your Elastic IP address is still moving, or has completed moving.
After you've moved your Elastic IP address, you can view its allocation ID on the Elastic IPs page in the
Allocation ID field.
If the Elastic IP address is in a moving state for longer than 5 minutes, contact Premium Support.
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
To describe the status of your moving addresses using the command line
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
802
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Sharing and Accessing Resources
Between EC2-Classic and a VPC
If your account supports EC2-Classic, you might have set up resources for use in EC2-Classic. If you
want to migrate from EC2-Classic to a VPC, you must recreate those resources in your VPC. For more
information about migrating from EC2-Classic to a VPC, see Migrating from a Linux Instance in EC2-
Classic to a Linux Instance in a VPC (p. 816).
The following resources can be shared or accessed between EC2-Classic and a VPC.
Resource Notes
AMI
Bundle task
EBS volume
Elastic IP address (IPv4) You can migrate an Elastic IP address from EC2-
Classic to a VPC. You can't migrate an Elastic
IP address that was originally allocated for use
in a VPC to EC2-Classic. For more information,
see Migrating an Elastic IP Address from EC2-
Classic (p. 801).
Key pair
Placement group
Reserved Instance You can change the network platform for your
Reserved Instances from EC2-Classic to a VPC.
For more information, see Modifying Reserved
Instances (p. 281).
803
Amazon Elastic Compute Cloud
User Guide for Linux Instances
ClassicLink
Resource Notes
security group for EC2-Classic to a security group
for a VPC. For more information, see Creating a
Security Group (p. 612).
Snapshot
The following resources can't be shared or moved between EC2-Classic and a VPC:
• Spot Instances
ClassicLink
ClassicLink allows you to link EC2-Classic instances to a VPC in your account, within the same region. If
you associate the VPC security groups with a EC2-Classic instance, this enables communication between
your EC2-Classic instance and instances in your VPC using private IPv4 addresses. ClassicLink removes
the need to make use of public IPv4 addresses or Elastic IP addresses to enable communication between
instances in these platforms.
ClassicLink is available to all users with accounts that support the EC2-Classic platform, and can be
used with any EC2-Classic instance. For more information about migrating your resources to a VPC, see
Migrating from a Linux Instance in EC2-Classic to a Linux Instance in a VPC (p. 816).
There is no additional charge for using ClassicLink. Standard charges for data transfer and instance usage
apply.
Contents
• ClassicLink Basics (p. 804)
• ClassicLink Limitations (p. 807)
• Working with ClassicLink (p. 807)
• Example IAM Policies for ClassicLink (p. 811)
• API and CLI Overview (p. 813)
• Example: ClassicLink Security Group Configuration for a Three-Tier Web Application (p. 814)
ClassicLink Basics
There are two steps to linking an EC2-Classic instance to a VPC using ClassicLink. First, you must enable
the VPC for ClassicLink. By default, all VPCs in your account are not enabled for ClassicLink, to maintain
their isolation. After you've enabled the VPC for ClassicLink, you can then link any running EC2-Classic
instance in the same region in your account to that VPC. Linking your instance includes selecting security
groups from the VPC to associate with your EC2-Classic instance. After you've linked the instance, it
can communicate with instances in your VPC using their private IP addresses, provided the VPC security
groups allow it. Your EC2-Classic instance does not lose its private IP address when linked to the VPC.
Note
Linking your instance to a VPC is sometimes referred to as attaching your instance.
A linked EC2-Classic instance can communicate with instances in a VPC, but it does not form part of the
VPC. If you list your instances and filter by VPC, for example, through the DescribeInstances API
request, or by using the Instances screen in the Amazon EC2 console, the results do not return any EC2-
Classic instances that are linked to the VPC. For more information about viewing your linked EC2-Classic
instances, see Viewing Your ClassicLink-Enabled VPCs and Linked EC2-Classic Instances (p. 809).
804
Amazon Elastic Compute Cloud
User Guide for Linux Instances
ClassicLink
By default, if you use a public DNS hostname to address an instance in a VPC from a linked EC2-Classic
instance, the hostname resolves to the instance's public IP address. The same occurs if you use a public
DNS hostname to address a linked EC2-Classic instance from an instance in the VPC. If you want the
public DNS hostname to resolve to the private IP address, you can enable ClassicLink DNS support for
the VPC. For more information, see Enabling ClassicLink DNS Support (p. 809).
If you no longer require a ClassicLink connection between your instance and the VPC, you can unlink
the EC2-Classic instance from the VPC. This disassociates the VPC security groups from the EC2-Classic
instance. A linked EC2-Classic instance is automatically unlinked from a VPC when it's stopped. After
you've unlinked all linked EC2-Classic instances from the VPC, you can disable ClassicLink for the VPC.
If you use Elastic Load Balancing, you can register your linked EC2-Classic instances with the load
balancer. You must create your load balancer in the ClassicLink-enabled VPC and enable the Availability
Zone in which the instance runs. If you terminate the linked EC2-Classic instance, the load balancer
deregisters the instance.
If you use Amazon EC2 Auto Scaling, you can create an Amazon EC2 Auto Scaling group with instances
that are automatically linked to a specified ClassicLink-enabled VPC at launch. For more information, see
Linking EC2-Classic Instances to a VPC in the Amazon EC2 Auto Scaling User Guide.
If you use Amazon RDS instances or Amazon Redshift clusters in your VPC, and they are publicly
accessible (accessible from the Internet), the endpoint you use to address those resources from a linked
EC2-Classic instance by default resolves to a public IP address. If those resources are not publicly
accessible, the endpoint resolves to a private IP address. To address a publicly accessible RDS instance
or Redshift cluster over private IP using ClassicLink, you must use their private IP address or private DNS
hostname, or you must enable ClassicLink DNS support for the VPC.
If you use a private DNS hostname or a private IP address to address an RDS instance, the linked EC2-
Classic instance cannot use the failover support available for Multi-AZ deployments.
You can use the Amazon EC2 console to find the private IP addresses of your Amazon Redshift, Amazon
ElastiCache, or Amazon RDS resources.
805
Amazon Elastic Compute Cloud
User Guide for Linux Instances
ClassicLink
For more information about policies for working with ClassicLink, see the following example: Example
IAM Policies for ClassicLink (p. 811).
After you've linked your instance to a VPC, you cannot change which VPC security groups are associated
with the instance. To associate different security groups with your instance, you must first unlink the
instance, and then link it to the VPC again, choosing the required security groups.
VPCs that are in the 10.0.0.0/16 and 10.1.0.0/16 IP address ranges can be enabled for ClassicLink
only if they do not have any existing static routes in route tables in the 10.0.0.0/8 IP address range,
excluding the local routes that were automatically added when the VPC was created. Similarly, if you've
enabled a VPC for ClassicLink, you may not be able to add any more specific routes to your route tables
within the 10.0.0.0/8 IP address range.
Important
If your VPC CIDR block is a publicly routable IP address range, consider the security implications
before you link an EC2-Classic instance to your VPC. For example, if your linked EC2-Classic
instance receives an incoming Denial of Service (DoS) request flood attack from a source IP
address that falls within the VPC’s IP address range, the response traffic is sent into your VPC.
We strongly recommend that you create your VPC using a private IP address range as specified
in RFC 1918.
For more information about route tables and routing in your VPC, see Route Tables in the Amazon VPC
User Guide.
If you enable a local VPC to communicate with a linked EC2-Classic instance in a peer VPC, a static route
is automatically added to your route tables with a destination of 10.0.0.0/8 and a target of local.
For more information and examples, see Configurations With ClassicLink in the Amazon VPC Peering
Guide.
806
Amazon Elastic Compute Cloud
User Guide for Linux Instances
ClassicLink
ClassicLink Limitations
To use the ClassicLink feature, you need to be aware of the following limitations:
Tasks
• Enabling a VPC for ClassicLink (p. 808)
• Linking an Instance to a VPC (p. 808)
• Creating a VPC with ClassicLink Enabled (p. 808)
• Linking an EC2-Classic Instance to a VPC at Launch (p. 809)
807
Amazon Elastic Compute Cloud
User Guide for Linux Instances
ClassicLink
• Viewing Your ClassicLink-Enabled VPCs and Linked EC2-Classic Instances (p. 809)
• Enabling ClassicLink DNS Support (p. 809)
• Disabling ClassicLink DNS Support (p. 810)
• Unlinking a EC2-Classic Instance from a VPC (p. 810)
• Disabling ClassicLink for a VPC (p. 810)
808
Amazon Elastic Compute Cloud
User Guide for Linux Instances
ClassicLink
809
Amazon Elastic Compute Cloud
User Guide for Linux Instances
ClassicLink
Note
If you enable ClassicLink DNS support for your VPC, your linked EC2-Classic instance can access
any private hosted zone associated with the VPC. For more information, see Working with
Private Hosted Zones in the Amazon Route 53 Developer Guide.
810
Amazon Elastic Compute Cloud
User Guide for Linux Instances
ClassicLink
Examples
• Full Permissions to Work with ClassicLink (p. 811)
• Enable and Disable a VPC for ClassicLink (p. 811)
• Link Instances (p. 812)
• Unlink Instances (p. 812)
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"ec2:DescribeClassicLinkInstances", "ec2:DescribeVpcClassicLink",
"ec2:EnableVpcClassicLink", "ec2:DisableVpcClassicLink",
"ec2:AttachClassicLinkVpc", "ec2:DetachClassicLinkVpc"
],
"Resource": "*"
}
]
}
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ec2:*VpcClassicLink",
"Resource": "arn:aws:ec2:region:account:vpc/*",
"Condition": {
"StringEquals": {
"ec2:ResourceTag/purpose":"classiclink"
}
}
}
]
811
Amazon Elastic Compute Cloud
User Guide for Linux Instances
ClassicLink
Link Instances
The following policy grants users permissions to link instances to a VPC only if the instance is an
m3.large instance type. The second statement allows users to use the VPC and security group
resources, which are required to link an instance to a VPC.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ec2:AttachClassicLinkVpc",
"Resource": "arn:aws:ec2:region:account:instance/*",
"Condition": {
"StringEquals": {
"ec2:InstanceType":"m3.large"
}
}
},
{
"Effect": "Allow",
"Action": "ec2:AttachClassicLinkVpc",
"Resource": [
"arn:aws:ec2:region:account:vpc/*",
"arn:aws:ec2:region:account:security-group/*"
]
}
]
}
The following policy grants users permissions to link instances to a specific VPC (vpc-1a2b3c4d) only,
and to associate only specific security groups from the VPC to the instance (sg-1122aabb and sg-
aabb2233). Users cannot link an instance to any other VPC, and they cannot specify any other of the
VPC security groups to associate with the instance in the request.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ec2:AttachClassicLinkVpc",
"Resource": [
"arn:aws:ec2:region:account:vpc/vpc-1a2b3c4d",
"arn:aws:ec2:region:account:instance/*",
"arn:aws:ec2:region:account:security-group/sg-1122aabb",
"arn:aws:ec2:region:account:security-group/sg-aabb2233"
]
}
]
}
Unlink Instances
The following grants users permission to unlink any linked EC2-Classic instance from a VPC, but only if
the instance has the tag "unlink=true". The second statement grants users permissions to use the VPC
resource, which is required to unlink an instance from a VPC.
{
"Version": "2012-10-17",
812
Amazon Elastic Compute Cloud
User Guide for Linux Instances
ClassicLink
"Statement": [{
"Effect": "Allow",
"Action": "ec2:DetachClassicLinkVpc",
"Resource": [
"arn:aws:ec2:region:account:instance/*"
],
"Condition": {
"StringEquals": {
"ec2:ResourceTag/unlink":"true"
}
}
},
{
"Effect": "Allow",
"Action": "ec2:DetachClassicLinkVpc",
"Resource": [
"arn:aws:ec2:region:account:vpc/*"
]
}
]
}
813
Amazon Elastic Compute Cloud
User Guide for Linux Instances
ClassicLink
You want a security group configuration that allows traffic to flow only between these instances. You
have four security groups: two for your web server (sg-1a1a1a1a and sg-2b2b2b2b), one for your
application server (sg-3c3c3c3c), and one for your database server (sg-4d4d4d4d).
The following diagram displays the architecture of your instances, and their security group configuration.
814
Amazon Elastic Compute Cloud
User Guide for Linux Instances
ClassicLink
You have one security group in EC2-Classic, and the other in your VPC. You associated the VPC security
group with your web server instance when you linked the instance to your VPC via ClassicLink. The VPC
security group enables you to control the outbound traffic from your web server to your application
server.
The following are the security group rules for the EC2-Classic security group (sg-1a1a1a1a).
Inbound
0.0.0.0/0 HTTPS 443 Allows Internet traffic to reach your web server.
The following are the security group rules for the VPC security group (sg-2b2b2b2b).
Outbound
815
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Migrating from EC2-Classic to a VPC
sg-3c3c3c3c TCP 6001 Allows outbound traffic from your web server
to your application server in your VPC (or to any
other instance associated with sg-3c3c3c3c).
The following are the security group rules for the VPC security group that's associated with your
application server.
Inbound
sg-2b2b2b2b TCP 6001 Allows the specified type of traffic from your
web server (or any other instance associated with
sg-2b2b2b2b) to reach your application server.
Outbound
The following are the security group rules for the VPC security group that's associated with your
database server.
Inbound
sg-3c3c3c3c TCP 6004 Allows the specified type of traffic from your
application server (or any other instance
associated with sg-3c3c3c3c) to reach your
database server.
816
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Migrating from EC2-Classic to a VPC
If your account supports EC2-Classic, you might have set up resources for use in EC2-Classic. If you want
to migrate from EC2-Classic to a VPC, you must recreate those resources in your VPC.
There are two ways of migrating to a VPC. You can do a full migration, or you can do an incremental
migration over time. The method you choose depends on the size and complexity of your application in
EC2-Classic. For example, if your application consists of one or two instances running a static website,
and you can afford a short period of downtime, you can do a full migration. If you have a multi-tier
application with processes that cannot be interrupted, you can do an incremental migration using
ClassicLink. This allows you to transfer functionality one component at a time until your application is
running fully in your VPC.
If you need to migrate a Windows instance, see Migrating a Windows Instance from EC2-Classic to a VPC
in the Amazon EC2 User Guide for Windows Instances.
Contents
• Full Migration to a VPC (p. 817)
• Incremental Migration to a VPC Using ClassicLink (p. 823)
Tasks
• Step 1: Create a VPC (p. 817)
• Step 2: Configure Your Security Group (p. 817)
• Step 3: Create an AMI from Your EC2-Classic Instance (p. 818)
• Step 4: Launch an Instance Into Your VPC (p. 819)
• Example: Migrating a Simple Web Application (p. 820)
• Your AWS account comes with a default VPC in each region, which is ready for you to use. Instances
that you launch are by default launched into this VPC, unless you specify otherwise. For more
information about your default VPC, see Your Default VPC and Subnets. Use this option if you'd prefer
not to set up a VPC yourself, or if you do not need specific requirements for your VPC configuration.
• In your existing AWS account, open the Amazon VPC console and use the VPC wizard to create a new
VPC. For more information, see Scenarios for Amazon VPC. Use this option if you want to set up a VPC
quickly in your existing EC2-Classic account, using one of the available configuration sets in the wizard.
You'll specify this VPC each time you launch an instance.
• In your existing AWS account, open the Amazon VPC console and set up the components of a VPC
according to your requirements. For more information, see Your VPC and Subnets. Use this option if
you have specific requirements for your VPC, such as a particular number of subnets. You'll specify this
VPC each time you launch an instance.
817
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Migrating from EC2-Classic to a VPC
Important
You can only copy security group rules to a new security group in the same AWS account in the
same region. If you've created a new AWS account, you cannot use this method to copy your
existing security group rules to your new account. You'll have to create a new security group,
and add the rules yourself. For more information about creating a new security group, see
Amazon EC2 Security Groups for Linux Instances (p. 607).
The method you use to create your AMI depends on the root device type of your instance, and the
operating system platform on which your instance runs. To find out the root device type of your instance,
go to the Instances page, select your instance, and look at the information in the Root device type field
in the Description tab. If the value is ebs, then your instance is EBS-backed. If the value is instance-
store, then your instance is instance store-backed. You can also use the describe-instances AWS CLI
command to find out the root device type.
The following table provides options for you to create your AMI based on the root device type of your
instance, and the software platform.
Important
Some instance types support both PV and HVM virtualization, while others support only
one or the other. If you plan to use your AMI to launch a different instance type than your
current instance type, check that the instance type supports the type of virtualization that your
AMI offers. If your AMI supports PV virtualization, and you want to use an instance type that
supports HVM virtualization, you may have to reinstall your software on a base HVM AMI. For
more information about PV and HVM virtualization, see Linux AMI Virtualization Types (p. 99).
EBS Create an EBS-backed AMI from your instance. For more information, see
Creating an Amazon EBS-Backed Linux AMI (p. 116).
818
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Migrating from EC2-Classic to a VPC
Instance store Create an instance store-backed AMI from your instance using the AMI
tools. For more information, see Creating an Instance Store-Backed Linux
AMI (p. 119).
For more information about Amazon EBS volumes, see the following topics:
To back up the data on your Amazon EBS volume, you can take periodic snapshots of your volume. If
you need to, you can restore an Amazon EBS volume from your snapshot. For more information about
Amazon EBS snapshots, see the following topics:
You can either launch your instance into a VPC that you've created in your existing account, or into a new,
VPC-only AWS account.
819
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Migrating from EC2-Classic to a VPC
6. Select Select an existing group, and select the security group you created earlier. Choose Review
and Launch.
7. Review your instance details, then choose Launch to specify a key pair and launch your instance.
For more information about the parameters you can configure in each step of the wizard, see Launching
an Instance Using the Launch Instance Wizard (p. 395).
To launch an instance in your new AWS account, you'll first have to share the AMI you created with your
new account. You can then use the Amazon EC2 launch wizard to launch an instance into your default
VPC.
For more information about the parameters you can configure in each step of the wizard, see Launching
an Instance Using the Launch Instance Wizard (p. 395).
820
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Migrating from EC2-Classic to a VPC
The first part of migrating to a VPC is deciding what kind of VPC architecture will suit your needs. In this
case, you've decided on the following: one public subnet for your web servers, and one private subnet
for your database server. As your website grows, you can add more web servers and database servers to
your subnets. By default, instances in the private subnet cannot access the Internet; however, you can
enable Internet access through a Network Address Translation (NAT) device in the public subnet. You may
want to set up a NAT device to support periodic updates and patches from the Internet for your database
server. You'll migrate your Elastic IP addresses to a VPC, and create a load balancer in your public subnet
to load balance the traffic between your web servers.
821
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Migrating from EC2-Classic to a VPC
To migrate your web application to a VPC, you can follow these steps:
• Create a VPC: In this case, you can use the VPC wizard in the Amazon VPC console to create your VPC
and subnets. The second wizard configuration creates a VPC with one private and one public subnet,
and launches and configures a NAT device in your public subnet for you. For more information, see
Scenario 2: VPC with Public and Private Subnets in the Amazon VPC User Guide.
• Create AMIs from your instances: Create an AMI from one of your web servers, and a second AMI
from your database server. For more information, see Step 3: Create an AMI from Your EC2-Classic
Instance (p. 818).
• Configure your security groups: In your EC2-Classic environment, you have one security group for
your web servers, and another security group for your database server. You can use the Amazon EC2
console to copy the rules from each security group into new security groups for your VPC. For more
information, see Step 2: Configure Your Security Group (p. 817).
Tip
Create the security groups that are referenced by other security groups first.
• Launch an instance into your new VPC: Launch replacement web servers into your public subnet, and
launch your replacement database server into your private subnet. For more information, see Step 4:
Launch an Instance Into Your VPC (p. 819).
• Configure your NAT device: If you are using a NAT instance, you must create security group for it that
allows HTTP and HTTPS traffic from your private subnet. For more information, see NAT Instances. If
you are using a NAT gateway, traffic from your private subnet is automatically allowed.
822
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Migrating from EC2-Classic to a VPC
• Configure your database: When you created an AMI from your database server in EC2-Classic, all
the configuration information that was stored in that instance was copied to the AMI. You may have
to connect to your new database server and update the configuration details; for example, if you
configured your database to grant full read, write, and modification permissions to your web servers
in EC2-Classic, you'll have to update the configuration files to grant the same permissions to your new
VPC web servers instead.
• Configure your web servers: Your web servers will have the same configuration settings as your
instances in EC2-Classic. For example, if you configured your web servers to use the database in EC2-
Classic, update your web servers' configuration settings to point to your new database instance.
Note
By default, instances launched into a nondefault subnet are not assigned a public IP address,
unless you specify otherwise at launch. Your new database server may not have a public IP
address. In this case, you can update your web servers' configuration file to use your new
database server's private DNS name. Instances in the same VPC can communicate with each
other via private IP address.
• Migrate your Elastic IP addresses: Disassociate your Elastic IP addresses from your web servers in EC2-
Classic, and then migrate them to a VPC. After you've migrated them, you can associate them with
your new web servers in your VPC. For more information, see Migrating an Elastic IP Address from EC2-
Classic (p. 801).
• Create a new load balancer: To continue using Elastic Load Balancing to load balance the traffic to
your instances, make sure you understand the various ways you can configure your load balancer in
VPC. For more information, see Elastic Load Balancing in Amazon VPC.
• Update your DNS records: After you've set up your load balancer in your public subnet, ensure that
your www.garden.example.com domain points to your new load balancer. To do this, you'll need to
update your DNS records and update your alias record set in Route 53. For more information about
using Route 53, see Getting Started with Route 53.
• Shut down your EC2-Classic resources: After you've verified that your web application is working from
within the VPC architecture, you can shut down your EC2-Classic resources to stop incurring charges
for them. Terminate your EC2-Classic instances, and release your EC2-Classic Elastic IP addresses.
Topics
• Step 1: Prepare Your Migration Sequence (p. 824)
• Step 2: Create a VPC (p. 824)
• Step 3: Enable Your VPC for ClassicLink (p. 824)
• Step 4: Create an AMI from Your EC2-Classic Instance (p. 824)
• Step 5: Launch an Instance Into Your VPC (p. 825)
• Step 6: Link Your EC2-Classic Instances to Your VPC (p. 826)
• Step 7: Complete the VPC Migration (p. 826)
823
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Migrating from EC2-Classic to a VPC
For example, you have an application that relies on a presentation web server, a backend database
server, and authentication logic for transactions. You may decide to start the migration process with the
authentication logic, then the database server, and finally, the web server.
• In your existing AWS account, open the Amazon VPC console and use the VPC wizard to create a new
VPC. For more information, see Scenarios for Amazon VPC. Use this option if you want to set up a VPC
quickly in your existing EC2-Classic account, using one of the available configuration sets in the wizard.
You'll specify this VPC each time you launch an instance.
• In your existing AWS account, open the Amazon VPC console and set up the components of a VPC
according to your requirements. For more information, see Your VPC and Subnets. Use this option if
you have specific requirements for your VPC, such as a particular number of subnets. You'll specify this
VPC each time you launch an instance.
The method you use to create your AMI depends on the root device type of your instance, and the
operating system platform on which your instance runs. To find out the root device type of your instance,
go to the Instances page, select your instance, and look at the information in the Root device type field
in the Description tab. If the value is ebs, then your instance is EBS-backed. If the value is instance-
store, then your instance is instance store-backed. You can also use the describe-instances AWS CLI
command to find out the root device type.
The following table provides options for you to create your AMI based on the root device type of your
instance, and the software platform.
Important
Some instance types support both PV and HVM virtualization, while others support only
one or the other. If you plan to use your AMI to launch a different instance type than your
current instance type, check that the instance type supports the type of virtualization that your
AMI offers. If your AMI supports PV virtualization, and you want to use an instance type that
824
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Migrating from EC2-Classic to a VPC
supports HVM virtualization, you may have to reinstall your software on a base HVM AMI. For
more information about PV and HVM virtualization, see Linux AMI Virtualization Types (p. 99).
EBS Create an EBS-backed AMI from your instance. For more information, see
Creating an Amazon EBS-Backed Linux AMI (p. 116).
Instance store Create an instance store-backed AMI from your instance using the AMI
tools. For more information, see Creating an Instance Store-Backed Linux
AMI (p. 119).
Instance store Convert your instance store-backed instance to an EBS-backed instance. For
more information, see Converting your Instance Store-Backed AMI to an
Amazon EBS-Backed AMI (p. 130).
You can create an Amazon EBS volume and use it to back up and store the data on your instance—
like you would use a physical hard drive. Amazon EBS volumes can be attached and detached from any
instance in the same Availability Zone. You can detach a volume from your instance in EC2-Classic, and
attach it to a new instance that you launch into your VPC in the same Availability Zone.
For more information about Amazon EBS volumes, see the following topics:
To back up the data on your Amazon EBS volume, you can take periodic snapshots of your volume. If
you need to, you can restore an Amazon EBS volume from your snapshot. For more information about
Amazon EBS snapshots, see the following topics:
825
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Migrating from EC2-Classic to a VPC
5. On the Configure Instance Details page, select your VPC from the Network list. Select the required
subnet from the Subnet list. Configure any other details you require, then go through the next
pages of the wizard until you reach the Configure Security Group page.
6. Select Select an existing group, and select the security group you created earlier. Choose Review
and Launch.
7. Review your instance details, then choose Launch to specify a key pair and launch your instance.
For more information about the parameters you can configure in each step of the wizard, see Launching
an Instance Using the Launch Instance Wizard (p. 395).
After you've launched your instance and it's in the running state, you can connect to it and configure it
as required.
After you've enabled internal communication between the EC2-Classic and VPC instances, you must
update your application to point to your migrated service in your VPC, instead of your service in the EC2-
Classic platform. The exact steps for this depend on your application’s design. Generally, this includes
updating your destination IP addresses to point to the IP addresses of your VPC instances instead of
your EC2-Classic instances. You can migrate your Elastic IP addresses that you are currently using in
the EC2-Classic platform to a VPC. For more information, see Migrating an Elastic IP Address from EC2-
Classic (p. 801).
After you've completed this step and you've tested that the application is functioning from your VPC,
you can terminate your EC2-Classic instances, and disable ClassicLink for your VPC. You can also clean up
any EC2-Classic resources that you may no longer need to avoid incurring charges for them; for example,
you can release Elastic IP addresses, and delete the volumes that were associated with your EC2-Classic
instances.
826
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Storage
Amazon EC2 provides you with flexible, cost effective, and easy-to-use data storage options for your
instances. Each option has a unique combination of performance and durability. These storage options
can be used independently or in combination to suit your requirements.
After reading this section, you should have a good understanding about how you can use the data
storage options supported by Amazon EC2 to meet your specific requirements. These storage options
include the following:
The following figure shows the relationship between these storage options and your instance.
Amazon EBS
Amazon EBS provides durable, block-level storage volumes that you can attach to a running instance.
You can use Amazon EBS as a primary storage device for data that requires frequent and granular
updates. For example, Amazon EBS is the recommended storage option when you run a database on an
instance.
An EBS volume behaves like a raw, unformatted, external block device that you can attach to a single
instance. The volume persists independently from the running life of an instance. After an EBS volume
is attached to an instance, you can use it like any other physical hard drive. As illustrated in the previous
figure, multiple volumes can be attached to an instance. You can also detach an EBS volume from one
instance and attach it to another instance. You can dynamically change the configuration of a volume
attached to an instance. EBS volumes can also be created as encrypted volumes using the Amazon EBS
encryption feature. For more information, see Amazon EBS Encryption (p. 903).
To keep a backup copy of your data, you can create a snapshot of an EBS volume, which is stored in
Amazon S3. You can create an EBS volume from a snapshot, and attach it to another instance. For more
information, see Amazon Elastic Block Store (p. 828).
827
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Amazon EBS
Many instances can access storage from disks that are physically attached to the host computer. This
disk storage is referred to as instance store. Instance store provides temporary block-level storage for
instances. The data on an instance store volume persists only during the life of the associated instance; if
you stop or terminate an instance, any data on instance store volumes is lost. For more information, see
Amazon EC2 Instance Store (p. 956).
Amazon EFS provides scalable file storage for use with Amazon EC2. You can create an EFS file system
and configure your instances to mount the file system. You can use an EFS file system as a common data
source for workloads and applications running on multiple instances. For more information, see Amazon
Elastic File System (Amazon EFS) (p. 968).
Amazon S3
Amazon S3 provides access to reliable and inexpensive data storage infrastructure. It is designed to
make web-scale computing easier by enabling you to store and retrieve any amount of data, at any time,
from within Amazon EC2 or anywhere on the web. For example, you can use Amazon S3 to store backup
copies of your data and applications. Amazon EC2 uses Amazon S3 to store EBS snapshots and instance
store-backed AMIs. For more information, see Amazon Simple Storage Service (Amazon S3) (p. 972).
Adding Storage
Every time you launch an instance from an AMI, a root storage device is created for that instance. The
root storage device contains all the information necessary to boot the instance. You can specify storage
volumes in addition to the root device volume when you create an AMI or launch an instance using block
device mapping. For more information, see Block Device Mapping (p. 977).
You can also attach EBS volumes to a running instance. For more information, see Attaching an Amazon
EBS Volume to an Instance (p. 851).
EBS volumes are highly available and reliable storage volumes that can be attached to any running
instance that is in the same Availability Zone. EBS volumes that are attached to an EC2 instance are
exposed as storage volumes that persist independently from the life of the instance. With Amazon EBS,
you pay only for what you use. For more information about Amazon EBS pricing, see the Projecting Costs
section of the Amazon Elastic Block Store page.
You can attach multiple volumes to the same instance within the limits specified by your AWS account.
Your account has a limit on the number of EBS volumes that you can use, and the total storage available
to you. For more information about these limits, and how to request an increase in your limits, see
Request to Increase the Amazon EBS Volume Limit.
Amazon EBS is recommended when data must be quickly accessible and requires long-term persistence.
EBS volumes are particularly well-suited for use as the primary storage for file systems, databases, or for
any applications that require fine granular updates and access to raw, unformatted, block-level storage.
828
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Features of Amazon EBS
Amazon EBS is well suited to both database-style applications that rely on random reads and writes, and
to throughput-intensive applications that perform long, continuous reads and writes.
Contents
• Features of Amazon EBS (p. 829)
• Amazon EBS Volumes (p. 830)
• Amazon EBS Snapshots (p. 866)
• Amazon EBS Data Services (p. 892)
• Amazon EBS and NVMe on Linux Instances (p. 912)
• Amazon EBS–Optimized Instances (p. 915)
• Amazon EBS Volume Performance on Linux Instances (p. 925)
• Amazon CloudWatch Metrics for Amazon EBS (p. 942)
• Amazon CloudWatch Events for Amazon EBS (p. 947)
829
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
monitor the performance of your volumes to make sure that you are providing enough performance
for your applications without paying for resources you don't need. For more information, see Amazon
EBS Volume Performance on Linux Instances (p. 925).
After a volume is attached to an instance, you can use it like any other physical hard drive. EBS volumes
are flexible. For current-generation volumes attached to current-generation instance types, you can
dynamically increase size, modify the provisioned IOPS capacity, and change volume type on live
production volumes.
Amazon EBS provides the following volume types: General Purpose SSD (gp2), Provisioned IOPS SSD
(io1), Throughput Optimized HDD (st1), Cold HDD (sc1), and Magnetic (standard, a previous-
generation type). They differ in performance characteristics and price, allowing you to tailor your storage
performance and cost to the needs of your applications. For more information, see Amazon EBS Volume
Types (p. 832).
Contents
• Benefits of Using EBS Volumes (p. 830)
• Amazon EBS Volume Types (p. 832)
• Constraints on the Size and Configuration of an EBS Volume (p. 845)
• Creating an Amazon EBS Volume (p. 847)
• Restoring an Amazon EBS Volume from a Snapshot (p. 848)
• Attaching an Amazon EBS Volume to an Instance (p. 851)
• Making an Amazon EBS Volume Available for Use on Linux (p. 852)
• Viewing Information about an Amazon EBS Volume (p. 855)
• Monitoring the Status of Your Volumes (p. 856)
• Detaching an Amazon EBS Volume from an Instance (p. 864)
• Deleting an Amazon EBS Volume (p. 866)
• Data availability
When you create an EBS volume in an Availability Zone, it is automatically replicated within that zone
to prevent data loss due to failure of any single hardware component. After you create a volume, you
can attach it to any EC2 instance in the same Availability Zone. After you attach a volume, it appears
as a native block device similar to a hard drive or other physical device. At that point, the instance can
interact with the volume just as it would with a local drive. The instance can format the EBS volume
with a file system, such as ext3, and then install applications.
An EBS volume can be attached to only one instance at a time, but multiple volumes can be attached
to a single instance. If you attach multiple volumes to a device that you have named, you can stripe
data across the volumes for increased I/O and throughput performance.
830
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
An EBS volume and the instance to which it attaches must be in the same Availability Zone.
You can get monitoring data for your EBS volumes, including root device volumes for EBS-backed
instances, at no additional charge. For more information about monitoring metrics, see Amazon
CloudWatch Metrics for Amazon EBS (p. 942). For information about tracking the status of your
volumes, see Amazon CloudWatch Events for Amazon EBS (p. 947).
• Data persistence
An EBS volume is off-instance storage that can persist independently from the life of an instance. You
continue to pay for the volume usage as long as the data persists.
EBS volumes that are attached to a running instance can automatically detach from the instance
with their data intact when the instance is terminated if you uncheck the Delete on Termination
checkbox when you configure EBS volumes for your instance on the EC2 console. The volume can then
be reattached to a new instance, enabling quick recovery. If the checkbox for Delete on Termination
is checked, the volume(s) will delete upon termination of the EC2 instance. If you are using an EBS-
backed instance, you can stop and restart that instance without affecting the data stored in the
attached volume. The volume remains attached throughout the stop-start cycle. This enables you
to process and store the data on your volume indefinitely, only using the processing and storage
resources when required. The data persists on the volume until the volume is deleted explicitly. The
physical block storage used by deleted EBS volumes is overwritten with zeroes before it is allocated
to another account. If you are dealing with sensitive data, you should consider encrypting your data
manually or storing the data on a volume protected by Amazon EBS encryption. For more information,
see Amazon EBS Encryption (p. 903).
By default, the root EBS volume that is created and attached to an instance at launch is deleted
when that instance is terminated. You can modify this behavior by changing the value of the flag
DeleteOnTermination to false when you launch the instance. This modified value causes the
volume to persist even after the instance is terminated, and enables you to attach the volume to
another instance.
By default, additional EBS volumes that are created and attached to an instance at launch are not
deleted when that instance is terminated. You can modify this behavior by changing the value of the
flag DeleteOnTermination to true when you launch the instance. This modified value causes the
volumes to be deleted when the instance is terminated.
• Data encryption
For simplified data encryption, you can create encrypted EBS volumes with the Amazon EBS
encryption feature. All EBS volume types support encryption. You can use encrypted EBS volumes
to meet a wide range of data-at-rest encryption requirements for regulated/audited data and
applications. Amazon EBS encryption uses 256-bit Advanced Encryption Standard algorithms
(AES-256) and an Amazon-managed key infrastructure. The encryption occurs on the server that
hosts the EC2 instance, providing encryption of data-in-transit from the EC2 instance to Amazon EBS
storage. For more information, see Amazon EBS Encryption (p. 903).
Amazon EBS encryption uses AWS Key Management Service (AWS KMS) master keys when creating
encrypted volumes and any snapshots created from your encrypted volumes. The first time you create
an encrypted EBS volume in a region, a default master key is created for you automatically. This key
is used for Amazon EBS encryption unless you select a customer master key (CMK) that you created
separately using AWS KMS. Creating your own CMK gives you more flexibility, including the ability to
create, rotate, disable, define access controls, and audit the encryption keys used to protect your data.
For more information, see the AWS Key Management Service Developer Guide.
• Snapshots
Amazon EBS provides the ability to create snapshots (backups) of any EBS volume and write a copy
of the data in the volume to Amazon S3, where it is stored redundantly in multiple Availability Zones.
The volume does not need to be attached to a running instance in order to take a snapshot. As you
831
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
continue to write data to a volume, you can periodically create a snapshot of the volume to use as a
baseline for new volumes. These snapshots can be used to create multiple new EBS volumes or move
volumes across Availability Zones. Snapshots of encrypted EBS volumes are automatically encrypted.
When you create a new volume from a snapshot, it's an exact copy of the original volume at the time
the snapshot was taken. EBS volumes that are restored from encrypted snapshots are automatically
encrypted. By optionally specifying a different Availability Zone, you can use this functionality to
create a duplicate volume in that zone. The snapshots can be shared with specific AWS accounts or
made public. When you create snapshots, you incur charges in Amazon S3 based on the volume's total
size. For a successive snapshot of the volume, you are only charged for any additional data beyond the
volume's original size.
Snapshots are incremental backups, meaning that only the blocks on the volume that have changed
after your most recent snapshot are saved. If you have a volume with 100 GiB of data, but only 5 GiB
of data have changed since your last snapshot, only the 5 GiB of modified data is written to Amazon
S3. Even though snapshots are saved incrementally, the snapshot deletion process is designed so that
you need to retain only the most recent snapshot in order to restore the volume.
To help categorize and manage your volumes and snapshots, you can tag them with metadata of your
choice. For more information, see Tagging Your Amazon EC2 Resources (p. 995).
• Flexibility
EBS volumes support live configuration changes while in production. You can modify volume type,
volume size, and IOPS capacity without service interruptions.
• SSD-backed volumes optimized for transactional workloads involving frequent read/write operations
with small I/O size, where the dominant performance attribute is IOPS
• HDD-backed volumes optimized for large streaming workloads where throughput (measured in MiB/s)
is a better performance measure than IOPS
The following table describes the use cases and performance characteristics for each volume type.
Note
AWS updates to the performance of EBS volume types may not immediately take effect on your
existing volumes. To see full performance on an older volume, you may first need to perform a
ModifyVolume action on it. For more information, see Modifying the Size, IOPS, or Type of an
EBS Volume on Linux.
Volume Type General Purpose Provisioned IOPS SSD Throughput Cold HDD (sc1)
SSD (gp2)* (io1) Optimized
HDD (st1)
832
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
Volume Size 1 GiB - 16 TiB 4 GiB - 16 TiB 500 GiB - 16 500 GiB - 16 TiB
TiB
* Default volume type for EBS volumes created from the console is gp2. Volumes created using the
CreateVolume API without a volume-type argument default to either gp2 or standard according to
region:
** gp2/io1 based on 16 KiB I/O size, st1/sc1 based on 1 MiB I/O size
833
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
*** General Purpose SSD (gp2) volumes have a throughput limit between 128 MiB/s and 250
MiB/s depending on volume size. Volumes greater than 170 GiB and below 334 GiB deliver a
maximum throughput of 250 MiB/s if burst credits are available. Volumes with 334 GiB and above
deliver 250 MiB/s irrespective of burst credits. An older gp2 volume may not see full performance
unless a ModifyVolume action is performed on it. For more information, see Amazon EBS Elastic
Volumes (p. 892).
**** Maximum IOPS of 64,000 is guaranteed only on Nitro-based Instances (p. 181). Other instances
guarantee performance up to 32,000 IOPS.
† Maximum throughput of 1,000 MiB/s is guaranteed only on Nitro-based Instances (p. 181).
Other instances guarantee up to 500 MiB/s. An older io1 volume may not see full performance
unless a ModifyVolume action is performed on it. For more information, see Amazon EBS Elastic
Volumes (p. 892).
†† To achieve this throughput, you must have an instance that supports it. For more information, see
Amazon EBS–Optimized Instances (p. 915).
The following table describes previous-generation EBS volume types. If you need higher performance
or performance consistency than previous-generation volumes can provide, we recommend that you
consider using General Purpose SSD (gp2) or other current volume types. For more information, see
Previous Generation Volumes.
Note
Linux AMIs require GPT partition tables and GRUB 2 for boot volumes 2 TiB (2048 GiB) or larger.
Many Linux AMIs today use the MBR partitioning scheme, which only supports up to 2047 GiB
boot volumes. If your instance does not boot with a boot volume that is 2 TiB or larger, the AMI
you are using may be limited to a 2047 GiB boot volume size. Non-boot volumes do not have
this limitation on Linux instances.
There are several factors that can affect the performance of EBS volumes, such as instance configuration,
I/O characteristics, and workload demand. For more information about getting the most out of your EBS
volumes, see Amazon EBS Volume Performance on Linux Instances (p. 925).
For more information about pricing for these volume types, see Amazon EBS Pricing.
834
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
The performance of gp2 volumes is tied to volume size, which determines the baseline performance
level of the volume and how quickly it accumulates I/O credits; larger volumes have higher baseline
performance levels and accumulate I/O credits faster. I/O credits represent the available bandwidth
that your gp2 volume can use to burst large amounts of I/O when more than the baseline performance
is needed. The more credits your volume has for I/O, the more time it can burst beyond its baseline
performance level and the better it performs when more performance is needed. The following diagram
shows the burst-bucket behavior for gp2.
Each volume receives an initial I/O credit balance of 5.4 million I/O credits, which is enough to sustain
the maximum burst performance of 3,000 IOPS for 30 minutes. This initial credit balance is designed
to provide a fast initial boot cycle for boot volumes and to provide a good bootstrapping experience
for other applications. Volumes earn I/O credits at the baseline performance rate of 3 IOPS per GiB of
volume size. For example, a 100 GiB gp2 volume has a baseline performance of 300 IOPS.
835
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
When your volume requires more than the baseline performance I/O level, it draws on I/O credits in the
credit balance to burst to the required performance level, up to a maximum of 3,000 IOPS. Volumes
larger than 1,000 GiB have a baseline performance that is equal or greater than the maximum burst
performance, and their I/O credit balance never depletes. When your volume uses fewer I/O credits than
it earns in a second, unused I/O credits are added to the I/O credit balance. The maximum I/O credit
balance for a volume is equal to the initial credit balance (5.4 million I/O credits).
Note
For a volume 1 TiB or larger, baseline performance is higher than maximum burst performance,
so I/O credits are never spent. If the volume is attached to a Nitro-based instance, the reported
burst balance is 0%. For a non-Nitro-based instance, the reported burst balance is 100%.
The following table lists several volume sizes and the associated baseline performance of the volume
(which is also the rate at which it accumulates I/O credits), the burst duration at the 3,000 IOPS
maximum (when starting with a full credit balance), and the time in seconds that the volume would take
to refill an empty credit balance.
Volume size (GiB) Baseline performance Burst duration when Seconds to fill empty
(IOPS) driving sustained credit balance when
3,000 IOPS (second) driving no IO
836
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
* Bursting and I/O credits are only relevant to volumes under 1,000 GiB, where burst performance
exceeds baseline performance.
The burst duration of a volume is dependent on the size of the volume, the burst IOPS required, and the
credit balance when the burst begins. This is shown in the following equation:
(Credit balance)
Burst duration = ------------------------------------
(Burst IOPS) - 3(Volume size in GiB)
If your gp2 volume uses all of its I/O credit balance, the maximum IOPS performance of the volume
remains at the baseline IOPS performance level (the rate at which your volume earns credits) and the
volume's maximum throughput is reduced to the baseline IOPS multiplied by the maximum I/O size.
Throughput can never exceed 250 MiB/s. When I/O demand drops below the baseline level and unused
credits are added to the I/O credit balance, the maximum IOPS performance of the volume again
exceeds the baseline. For example, a 100 GiB gp2 volume with an empty credit balance has a baseline
performance of 300 IOPS and a throughput limit of 75 MiB/s (300 I/O operations per second * 256 KiB
per I/O operation = 75 MiB/s). The larger a volume is, the greater the baseline performance is and the
faster it replenishes the credit balance. For more information about how IOPS are measured, see I/O
Characteristics and Monitoring (p. 929).
If you notice that your volume performance is frequently limited to the baseline level (due to an empty
I/O credit balance), you should consider using a larger gp2 volume (with a higher baseline performance
level) or switching to an io1 volume for workloads that require sustained IOPS performance greater
than 16,000 IOPS.
For information about using CloudWatch metrics and alarms to monitor your burst bucket balance, see
Monitoring the Burst Bucket Balance for gp2, st1, and sc1 Volumes (p. 845).
Throughput Performance
Throughput for a gp2 volume can be calculated using the following formula, up to the throughput limit
of 250 MiB/s:
Throughput in MiB/s = ((Volume size in GiB) × (IOPS per GiB) × (I/O size in KiB))
Assuming V = volume size, I = I/O size, R = I/O rate, and T = throughput, this can be simplified to:
T = VIR
The smallest volume size that achieves the maximum throughput is given by:
T
V = -----
I R
250 MiB/s
= ---------------------
(256 KiB)(3 IOPS/GiB)
[(250)(2^20)(Bytes)]/s
= ------------------------------------------
(256)(2^10)(Bytes)([3 IOP/s]/[(2^30)(Bytes)])
(250)(2^20)(2^30)(Bytes)
837
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
= ------------------------
(256)(2^10)(3)
= 357,913,941,333 Bytes
= 333✔ GiB (334 GiB in practice because volumes are provisioned in whole gibibytes)
An io1 volume can range in size from 4 GiB to 16 TiB. You can provision from 100 IOPS up to 64,000
IOPS per volume on Nitro-based Instances (p. 181) instances and up to 32,000 on other instances. The
maximum ratio of provisioned IOPS to requested volume size (in GiB) is 50:1. For example, a 100 GiB
volume can be provisioned with up to 5,000 IOPS. On a supported instance type, any volume 1,280 GiB
in size or greater allows provisioning up to the 64,000 IOPS maximum (50 × 1,280 GiB = 64,000).
An io1 volume provisioned with up to 32,000 IOPS supports a maximum I/O size of 256 KiB and yields
as much as 500 MiB/s of throughput. With the I/O size at the maximum, peak throughput is reached at
2,000 IOPS. A volume provisioned with more than 32,000 IOPS (up to the cap of 64,000 IOPS) supports
a maximum I/O size of 16 KiB and yields as much as 1,000 MiB/s of throughput. The following graph
illustrates these performance characteristics:
Your per-I/O latency experience depends on the IOPS provisioned and your workload pattern. For the
best per-I/O latency experience, we recommend that you provision an IOPS-to-GiB ratio greater than 2:1.
For example, a 2,000 IOPS volume should be smaller than 1,000 GiB.
Note
Some AWS accounts created before 2012 might have access to Availability Zones in us-west-1
or ap-northeast-1 that do not support Provisioned IOPS SSD (io1) volumes. If you are unable
to create an io1 volume (or launch an instance with an io1 volume in its block device mapping)
in one of these Regions, try a different Availability Zone in the Region. You can verify that an
Availability Zone supports io1 volumes by creating a 4 GiB io1 volume in that zone.
838
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
Throughput Optimized HDD (st1) volumes, though similar to Cold HDD (sc1) volumes, are designed to
support frequently accessed data.
This volume type is optimized for workloads involving large, sequential I/O, and we recommend that
customers with workloads performing small, random I/O use gp2. For more information, see Inefficiency
of Small Read/Writes on HDD (p. 844).
Like gp2, st1 uses a burst-bucket model for performance. Volume size determines the baseline
throughput of your volume, which is the rate at which the volume accumulates throughput credits.
Volume size also determines the burst throughput of your volume, which is the rate at which you can
spend credits when they are available. Larger volumes have higher baseline and burst throughput. The
more credits your volume has, the longer it can drive I/O at the burst level.
Subject to throughput and throughput-credit caps, the available throughput of an st1 volume is
expressed by the following formula:
For a 1-TiB st1 volume, burst throughput is limited to 250 MiB/s, the bucket fills with credits at 40 MiB/
s, and it can hold up to 1 TiB-worth of credits.
Larger volumes scale these limits linearly, with throughput capped at a maximum of 500 MiB/s. After the
bucket is depleted, throughput is limited to the baseline rate of 40 MiB/s per TiB.
On volume sizes ranging from 0.5 to 16 TiB, baseline throughput varies from 20 to a cap of 500 MiB/s,
which is reached at 12.5 TiB as follows:
40 MiB/s
12.5 TiB x ---------- = 500 MiB/s
1 TiB
Burst throughput varies from 125 MiB/s to a cap of 500 MiB/s, which is reached at 2 TiB as follows:
250 MiB/s
2 TiB x ---------- = 500 MiB/s
1 TiB
The following table states the full range of base and burst throughput values for st1:
839
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
Volume Size (TiB) ST1 Base Throughput (MiB/s) ST1 Burst Throughput (MiB/s)
0.5 20 125
1 40 250
2 80 500
3 120 500
4 160 500
5 200 500
6 240 500
7 280 500
8 320 500
9 360 500
10 400 500
11 440 500
12 480 500
13 500 500
14 500 500
15 500 500
16 500 500
Note
When you create a snapshot of a Throughput Optimized HDD (st1) volume, performance may
drop as far as the volume's baseline value while the snapshot is in progress.
For information about using CloudWatch metrics and alarms to monitor your burst bucket balance, see
Monitoring the Burst Bucket Balance for gp2, st1, and sc1 Volumes (p. 845).
840
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
Cold HDD (sc1) volumes, though similar to Throughput Optimized HDD (st1) volumes, are designed to
support infrequently accessed data.
Note
This volume type is optimized for workloads involving large, sequential I/O, and we recommend
that customers with workloads performing small, random I/O use gp2. For more information,
see Inefficiency of Small Read/Writes on HDD (p. 844).
Like gp2, sc1 uses a burst-bucket model for performance. Volume size determines the baseline
throughput of your volume, which is the rate at which the volume accumulates throughput credits.
Volume size also determines the burst throughput of your volume, which is the rate at which you can
spend credits when they are available. Larger volumes have higher baseline and burst throughput. The
more credits your volume has, the longer it can drive I/O at the burst level.
Subject to throughput and throughput-credit caps, the available throughput of an sc1 volume is
expressed by the following formula:
For a 1-TiB sc1 volume, burst throughput is limited to 80 MiB/s, the bucket fills with credits at 12 MiB/s,
and it can hold up to 1 TiB-worth of credits.
Larger volumes scale these limits linearly, with throughput capped at a maximum of 250 MiB/s. After the
bucket is depleted, throughput is limited to the baseline rate of 12 MiB/s per TiB.
On volume sizes ranging from 0.5 to 16 TiB, baseline throughput varies from 6 MiB/s to a maximum of
192 MiB/s, which is reached at 16 TiB as follows:
12 MiB/s
16 TiB x ---------- = 192 MiB/s
1 TiB
Burst throughput varies from 40 MiB/s to a cap of 250 MiB/s, which is reached at 3.125 TiB as follows:
80 MiB/s
3.125 TiB x ----------- = 250 MiB/s
841
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
1 TiB
The following table states the full range of base and burst throughput values for sc1:
Volume Size (TiB) SC1 Base Throughput (MiB/s) SC1 Burst Throughput (MiB/s)
0.5 6 40
1 12 80
2 24 160
3 36 240
4 48 250
5 60 250
6 72 250
7 84 250
8 96 250
9 108 250
10 120 250
11 132 250
12 144 250
13 156 250
14 168 250
15 180 250
16 192 250
Note
When you create a snapshot of a Cold HDD (sc1) volume, performance may drop as far as the
volume's baseline value while the snapshot is in progress.
For information about using CloudWatch metrics and alarms to monitor your burst bucket balance, see
Monitoring the Burst Bucket Balance for gp2, st1, and sc1 Volumes (p. 845).
842
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
Magnetic (standard)
Magnetic volumes are backed by magnetic drives and are suited for workloads where data is accessed
infrequently, and scenarios where low-cost storage for small volume sizes is important. These volumes
deliver approximately 100 IOPS on average, with burst capability of up to hundreds of IOPS, and they
can range in size from 1 GiB to 1 TiB.
Note
Magnetic is a Previous Generation Volume. For new applications, we recommend using one of
the newer volume types. For more information, see Previous Generation Volumes.
For information about using CloudWatch metrics and alarms to monitor your burst bucket balance, see
Monitoring the Burst Bucket Balance for gp2, st1, and sc1 Volumes (p. 845).
Both st1 and sc1 are designed for performance consistency of 90% of burst throughput 99% of the
time. Non-compliant periods are approximately uniformly distributed, targeting 99% of expected total
throughput each hour.
The following table shows ideal scan times for volumes of various size, assuming full buckets and
sufficient instance throughput.
Volume size
------------- = Scan time
Throughput
For example, taking the performance consistency guarantees and other optimizations into account, an
st1 customer with a 5-TiB volume can expect to complete a full volume scan in 2.91 to 3.27 hours.
5 TiB 5 TiB
----------- = ------------------- = 10,486 s = 2.91 hours (optimal)
500 MiB/s 0.00047684 TiB/s
2.91 hours
2.91 hours + -------------- = 3.27 hours (minimum expected)
(0.90)(0.99) <-- From expected performance of 90% of burst 99% of the time
Similarly, an sc1 customer with a 5-TiB volume can expect to complete a full volume scan in 5.83 to 6.54
hours.
5 TiB
------------------- = 20972 s = 5.83 hours (optimal)
0.000238418 TiB/s
5.83 hours
-------------- = 6.54 hours (minimum expected)
843
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
(0.90)(0.99)
Volume Size (TiB) ST1 Scan Time with Burst SC1 Scan Time with Burst
(Hours)* (Hours)*
1 1.17 3.64
2 1.17 3.64
3 1.75 3.64
4 2.33 4.66
5 2.91 5.83
6 3.50 6.99
7 4.08 8.16
8 4.66 9.32
9 5.24 10.49
10 5.83 11.65
11 6.41 12.82
12 6.99 13.98
13 7.57 15.15
14 8.16 16.31
15 8.74 17.48
16 9.32 18.64
* These scan times assume an average queue depth (rounded to the nearest whole number) of four or
more when performing 1 MiB of sequential I/O.
Therefore if you have a throughput-oriented workload that needs to complete scans quickly (up to 500
MiB/s), or requires several full volume scans a day, use st1. If you are optimizing for cost, your data is
relatively infrequently accessed, and you don’t need more than 250 MiB/s of scanning performance, then
use sc1.
For example, an I/O request of 1 MiB or less counts as a 1 MiB I/O credit. However, if the I/Os are
sequential, they are merged into 1 MiB I/O blocks and count only as a 1 MiB I/O credit.
844
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
As for all Amazon EBS volumes, we recommend that you select an appropriate EBS-optimized EC2
instance in order to avoid network bottlenecks. For more information, see Amazon EBS–Optimized
Instances (p. 915).
Monitoring the Burst Bucket Balance for gp2, st1, and sc1 Volumes
You can monitor the burst-bucket level for gp2, st1, and sc1 volumes using the EBS BurstBalance
metric available in Amazon CloudWatch. This metric shows the percentage of I/O credits (for gp2)
or throughput credits (for st1 and sc1) remaining in the burst bucket. For more information
about the BurstBalance metric and other metrics related to I/O, see I/O Characteristics and
Monitoring (p. 929). CloudWatch also allows you to set an alarm that notifies you when the
BurstBalance value falls to a certain level. For more information, see Creating Amazon CloudWatch
Alarms.
The following table summarizes the theoretical and implemented storage capacities for the most
commonly used file systems on Amazon EBS, assuming a 4,096 byte block size.
** https://access.redhat.com/solutions/1532
The following sections describe the most important factors that limit the usable size of an EBS volume
and offer recommendations for configuring your EBS volumes.
Content
• Service Limitations (p. 845)
• Partitioning Schemes (p. 846)
• Data Block Sizes (p. 846)
Service Limitations
Amazon EBS abstracts the massively distributed storage of a data center into virtual hard disk drives. To
an operating system installed on an EC2 instance, an attached EBS volume appears to be a physical hard
disk drive containing 512-byte disk sectors. The OS manages the allocation of data blocks (or clusters)
onto those virtual sectors through its storage management utilities. The allocation is in conformity with
845
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
a volume partitioning scheme, such as master boot record (MBR) or GUID partition table (GPT), and
within the capabilities of the installed file system (ext4, NTFS, and so on).
EBS is not aware of the data contained in its virtual disk sectors; it only ensures the integrity of the
sectors. This means that AWS actions and OS actions are independent of each other. When you are
selecting a volume size, be aware of the capabilities and limits of both, as in the following cases:
• EBS currently supports a maximum volume size of 16 TiB. This means that you can create an EBS
volume as large as 16 TiB, but whether the OS recognizes all of that capacity depends on its own
design characteristics and on how the volume is partitioned.
• Amazon EC2 requires Windows boot volumes to use MBR partitioning. As discussed in Partitioning
Schemes (p. 846), this means that boot volumes cannot be bigger than 2 TiB. Windows data volumes
are not subject to this limitation and may be GPT-partitioned.
• Linux boot volumes may be either MBR or GPT, and Linux GPT boot volumes are not subject to the 2-
TiB limit.
Partitioning Schemes
Among other impacts, the partitioning scheme determines how many logical data blocks can be uniquely
addressed in a single volume. For more information, see Data Block Sizes (p. 846). The common
partitioning schemes in use are master boot record (MBR) and GUID partition table (GPT). The important
differences between these schemes can be summarized as follows.
MBR
MBR uses a 32-bit data structure to store block addresses. This means that each data block is mapped
32
with one of 2 possible integers. The maximum addressable size of a volume is given by:
The block size for MBR volumes is conventionally limited to 512 bytes. Therefore:
Engineering workarounds to increase this 2-TiB limit for MBR volumes have not met with widespread
industry adoption. Consequently, Linux and Windows never detect an MBR volume as being larger than 2
TiB even if AWS shows its size to be larger.
GPT
GPT uses a 64-bit data structure to store block addresses. This means that each data block is mapped
64
with one of 2 possible integers. The maximum addressable size of a volume is given by:
The block size for GPT volumes is commonly 4,096 bytes. Therefore:
(264 - 1) × 4,096 bytes = 8 ZiB - 4,096 bytes = 8 billion TiB - 4,096 bytes
Real-world computer systems don't support anything close to this theoretical maximum. Implemented
file-system size is currently limited to 50 TiB for ext4 and 256 TiB for NTFS—both of which exceed the
16-TiB limit imposed by AWS.
846
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
the underlying hardware. The OS relies on the storage device to map the blocks to its physical sectors.
EBS advertises 512-byte sectors to the operating system, which reads and writes data to disk using data
blocks that are a multiple of the sector size.
The industry default size for logical data blocks is currently 4,096 bytes (4 KiB). Because certain
workloads benefit from a smaller or larger block size, file systems support non-default block sizes
that can be specified during formatting. Scenarios in which non-default block sizes should be used are
outside the scope of this topic, but the choice of block size has consequences for the storage capacity of
the volume. The following table shows storage capacity as a function of block size:
8 KiB 32 TiB
16 KiB 64 TiB
The EBS-imposed limit on volume size (16 TiB) is currently equal to the maximum size enabled by 4-KiB
data blocks.
You can also create and attach EBS volumes when you launch instances by specifying a block device
mapping. For more information, see Launching an Instance Using the Launch Instance Wizard (p. 395)
and Block Device Mapping (p. 977). You can restore volumes from previously created snapshots. For
more information, see Restoring an Amazon EBS Volume from a Snapshot (p. 848).
You can apply tags to EBS volumes at the time of creation. With tagging, you can simplify tracking of
your Amazon EC2 resource inventory. Tagging on creation can be combined with an IAM policy to enforce
tagging on new volumes. For more information, see Tagging Your Amazon EC2 Resources (p. 995).
If you are creating a volume for a high-performance storage scenario, you should make sure to use a
Provisioned IOPS SSD (io1) volume and attach it to an instance with enough bandwidth to support your
application, such as an EBS-optimized instance or an instance with 10-Gigabit network connectivity.
The same advice holds for Throughput Optimized HDD (st1) and Cold HDD (sc1) volumes. For more
information, see Amazon EC2 Instance Configuration (p. 928).
New EBS volumes receive their maximum performance the moment that they are available and do not
require initialization (formerly known as pre-warming). However, storage blocks on volumes that were
restored from snapshots must be initialized (pulled down from Amazon S3 and written to the volume)
before you can access the block. This preliminary action takes time and can cause a significant increase
in the latency of an I/O operation the first time each block is accessed. For most applications, amortizing
this cost over the lifetime of the volume is acceptable. Performance is restored after the data is accessed
once. For more information, see Initializing Amazon EBS Volumes (p. 931).
847
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
2. From the navigation bar, select the region in which you would like to create your volume. This choice
is important because some Amazon EC2 resources can be shared between regions, while others
can't. For more information, see Resource Locations (p. 986).
3. In the navigation pane, choose ELASTIC BLOCK STORE, Volumes.
4. Choose Create Volume.
5. For Volume Type, choose a volume type. For more information, see Amazon EBS Volume
Types (p. 832).
Note
Some AWS accounts created before 2012 might have access to Availability Zones in us-
west-1 or ap-northeast-1 that do not support Provisioned IOPS SSD (io1) volumes. If you
are unable to create an io1 volume (or launch an instance with an io1 volume in its block
device mapping) in one of these Regions, try a different Availability Zone in the Region. You
can verify that an Availability Zone supports io1 volumes by creating a 4 GiB io1 volume in
that zone.
6. For Size (GiB), type the size of the volume.
7. With a Provisioned IOPS SSD volume, for IOPS, type the maximum number of input/output
operations per second (IOPS) that the volume should support.
8. For Availability Zone, choose the Availability Zone in which to create the volume. EBS volumes can
only be attached to EC2 instances within the same Availability Zone.
9. (Optional) To create an encrypted volume, select the Encrypted box and choose the Customer
Master Key (CMK) you want to use when encrypting the volume. You can accept the default, which is
the default CMK for your account, or you can choose any CMK that you have previously created using
the AWS Key Management Service. Choose an available key from the Master Key menu or paste the
full ARN of any key that you have access to. For more information, see the AWS Key Management
Service Developer Guide.
Note
Encrypted volumes can only be attached to selected instance types. For more information,
see Supported Instance Types (p. 904).
10. (Optional) Choose Create additional tags to add tags to the volume. For each tag, provide a tag key
and a tag value.
11. Choose Create Volume.
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
EBS snapshots are the preferred backup tool on Amazon EC2 due to their speed, convenience, and cost.
When restoring a volume from a snapshot, you recreate its state at a specific point in the past with all
data intact. By attaching a restored volume to an instance, you can duplicate data across regions, create
test environments, replace a damaged or corrupted production volume in its entirety, or retrieve specific
files and directories and transfer them to another attached volume. For more information, see Amazon
EBS Snapshots (p. 866).
848
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
New volumes created from existing EBS snapshots load lazily in the background. This means that
after a volume is created from a snapshot, there is no need to wait for all of the data to transfer from
Amazon S3 to your EBS volume before your attached instance can start accessing the volume and all
its data. If your instance accesses data that hasn't yet been loaded, the volume immediately downloads
the requested data from Amazon S3, and then continues loading the rest of the volume data in the
background.
EBS Performance
New EBS volumes receive their maximum performance the moment that they are available and do not
require initialization (formerly known as pre-warming). However, storage blocks on volumes that were
restored from snapshots must be initialized (pulled down from Amazon S3 and written to the volume)
before you can access the block. This preliminary action takes time and can cause a significant increase
in the latency of an I/O operation the first time each block is accessed. Performance is restored after the
data is accessed once.
For most applications, amortizing the initialization cost over the lifetime of the volume is acceptable.
To ensure that your restored volume always functions at peak capacity in production, you can force
the immediate initialization of the entire volume using dd or fio. For more information, see Initializing
Amazon EBS Volumes (p. 931).
EBS Encryption
New EBS volumes that are restored from encrypted snapshots are automatically encrypted. You can also
encrypt a volume on-the-fly while restoring it from an unencrypted snapshot. Encrypted volumes can
only be attached to instance types that support EBS encryption. For more information, see Supported
Instance Types (p. 904).
Because of security constraints, you cannot directly restore an EBS volume from a shared encrypted
snapshot that you do not own. You must first create a copy of the snapshot, which you will own. You can
then restore a volume from that copy. For more information, see Amazon EBS Encryption (p. 903).
The following table describes the encryption outcome for each possible combination of settings.
Encryption Outcomes
849
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
* This is the default CMK used for EBS encryption for the AWS account and Region. By default this is a
unique AWS managed CMK for EBS, or you can specify a customer managed CMK. For more information,
see Encryption Key Management (p. 905).
** This is a customer managed CMK specified for the volume at launch time. This CMK is used instead of
the default CMK for the AWS account and Region.
850
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
To restore the snapshot to a volume in a different region, you can copy your snapshot to the new
region and then restore it to a volume in that region. For more information, see Copying an Amazon
EBS Snapshot (p. 874).
3. In the navigation pane, choose ELASTIC BLOCK STORE, Volumes.
4. Choose Create Volume.
5. For Volume Type, choose a volume type. For more information, see Amazon EBS Volume
Types (p. 832).
6. For Snapshot ID, start typing the ID or description of the snapshot from which you are restoring the
volume, and choose it from the list of suggested options.
7. (Optional) Select Encrypt this volume to change the encryption state of your volume. This is
optional if encryption by default (p. 904) is enabled. Select a CMK from Master Key to specify a
CMK other than the default CMK for EBS encryption.
8. For Size (GiB), type the size of the volume, or verify that the default size of the snapshot is
adequate.
If you specify both a volume size and a snapshot, the size must be equal to or greater than the
snapshot size. When you select a volume type and a snapshot, the minimum and maximum sizes
for the volume are shown next to Size. Any AWS Marketplace product codes from the snapshot are
propagated to the volume.
9. With a Provisioned IOPS SSD volume, for IOPS, type the maximum number of input/output
operations per second (IOPS) that the volume should support.
10. For Availability Zone, choose the Availability Zone in which to create the volume. EBS volumes can
only be attached to EC2 instances in the same Availability Zone.
11. (Optional) Choose Create additional tags to add tags to the volume. For each tag, provide a tag key
and a tag value.
12. Choose Create Volume.
13. After you've restored a volume from a snapshot, you can attach it to an instance to begin using it.
For more information, see Attaching an Amazon EBS Volume to an Instance (p. 851).
14. If you restored a snapshot to a larger volume than the default for that snapshot, you must extend
the file system on the volume to take advantage of the extra space. For more information, see
Amazon EBS Elastic Volumes (p. 892).
Prerequisites
• Determine how many volumes you can attach to your instance. For more information, see Instance
Volume Limits (p. 974).
• If a volume is encrypted, it can only be attached to an instance that supports Amazon EBS encryption.
For more information, see Supported Instance Types (p. 904).
• If a volume has an AWS Marketplace product code:
851
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
You can take snapshots of your EBS volume for backup purposes or to use as a baseline when you create
another volume. For more information, see Amazon EBS Snapshots (p. 866).
You can get directions for volumes on a Windows instance from Making a Volume Available for Use on
Windows in the Amazon EC2 User Guide for Windows Instances.
1. Connect to your instance using SSH. For more information, see Connect to Your Linux
Instance (p. 446).
2. The device could be attached to the instance with a different device name than you specified in the
block device mapping. For more information, see Device Naming on Linux Instances (p. 975). Use
852
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
the lsblk command to view your available disk devices and their mount points (if applicable) to help
you determine the correct device name to use. The output of lsblk removes the /dev/ prefix from
full device paths.
The following is example output for a Nitro-based instance (p. 181), which exposes EBS volumes as
NVMe block devices. The root device is /dev/nvme0n1. The attached volume is /dev/nvme1n1,
which is not yet mounted.
The following is example output for a T2 instance. The root device is /dev/xvda. The attached
volume is /dev/xvdf, which is not yet mounted.
3. Determine whether there is a file system on the volume. New volumes are raw block devices, and
you must create a file system on them before you can mount and use them. Volumes that have been
restored from snapshots likely have a file system on them already; if you create a new file system on
top of an existing file system, the operation overwrites your data.
Use the file -s command to get information about a device, such as its file system type. If the output
shows simply data, as in the following example output, there is no file system on the device and
you must create one.
If the device has a file system, the command shows information about the file system type. For
example, the following output shows a root device with the XFS file system.
4. (Conditional) If you discovered that there is a file system on the device in the previous step, skip this
step. If you have an empty volume, use the mkfs -t command to create a file system on the volume.
Warning
Do not use this command if you're mounting a volume that already has data on it (for
example, a volume that was restored from a snapshot). Otherwise, you'll format the volume
and delete the existing data.
If you get an error that mkfs.xfs is not found, use the following command to install the XFS tools
and then repeat the previous command:
853
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
5. Use the mkdir command to create a mount point directory for the volume. The mount point is
where the volume is located in the file system tree and where you read and write files to after you
mount the volume. The following example creates a directory named /data.
6. Use the following command to mount the volume at the directory you created in the previous step.
7. Review the file permissions of your new volume mount to make sure that your users and
applications can write to the volume. For more information about file permissions, see File security
at The Linux Documentation Project.
8. The mount point is not automatically preserved after rebooting your instance. To automatically
mount this EBS volume after reboot, see Automatically Mount an Attached Volume After
Reboot (p. 854).
You can use the device name, such as /dev/xvdf, in /etc/fstab, but we recommend using the
device's 128-bit universally unique identifier (UUID) instead. Device names can change, but the UUID
persists throughout the life of the partition. By using the UUID, you reduce the chances that the system
becomes unbootable after a hardware reconfiguration. For more information, see Identifying the EBS
Device (p. 913).
1. (Optional) Create a backup of your /etc/fstab file that you can use if you accidentally destroy or
delete this file while editing it.
3. Open the /etc/fstab file using any text editor, such as nano or vim.
4. Add the following entry to /etc/fstab to mount the device at the specified mount point. The
fields are the UUID value returned by blkid (or lsblk for Ubuntu 18.04), the mount point, the file
system, and the recommended file system mount options. For more information, see the manual
page for fstab (run man fstab).
854
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
Note
If you ever boot your instance without this volume attached (for example, after moving the
volume to another instance), the nofail mount option enables the instance to boot even if
there are errors mounting the volume. Debian derivatives, including Ubuntu versions earlier
than 16.04, must also add the nobootwait mount option.
5. To verify that your entry works, run the following commands to unmount the device and then
mount all file systems in /etc/fstab. If there are no errors, the /etc/fstab file is OK and your
file system will mount automatically after it is rebooted.
If you are unsure how to correct errors in /etc/fstab and you created a backup file in the first step
of this procedure, you can restore from your backup file using the following command.
You can get additional information about your EBS volumes, such as how much disk space is available,
from the operating system on the instance.
855
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
You can use one of the following commands to view volume attributes. For more information, see
Accessing Amazon EC2 (p. 3).
Contents
• EBS Volume Status Checks (p. 856)
• EBS Volume Events (p. 858)
• Working with an Impaired Volume (p. 860)
• Working with the Auto-Enabled IO Volume Attribute (p. 863)
For additional monitoring information, see Amazon CloudWatch Metrics for Amazon EBS (p. 942) and
Amazon CloudWatch Events for Amazon EBS (p. 947).
Volume status checks are automated tests that run every 5 minutes and return a pass or fail status. If
all checks pass, the status of the volume is ok. If a check fails, the status of the volume is impaired. If
the status is insufficient-data, the checks may still be in progress on the volume. You can view the
results of volume status checks to identify any impaired volumes and take any necessary actions.
When Amazon EBS determines that a volume's data is potentially inconsistent, the default is that it
disables I/O to the volume from any attached EC2 instances, which helps to prevent data corruption.
After I/O is disabled, the next volume status check fails, and the volume status is impaired. In addition,
you'll see an event that lets you know that I/O is disabled, and that you can resolve the impaired status
of the volume by enabling I/O to the volume. We wait until you enable I/O to give you the opportunity
to decide whether to continue to let your instances use the volume, or to run a consistency check using a
command, such as fsck, before doing so.
Note
Volume status is based on the volume status checks, and does not reflect the volume state.
Therefore, volume status does not indicate volumes in the error state (for example, when a
volume is incapable of accepting I/O.)
856
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
If the consistency of a particular volume is not a concern, and you'd prefer that the volume be made
available immediately if it's impaired, you can override the default behavior by configuring the volume
to automatically enable I/O. If you enable the Auto-Enable IO volume attribute (autoEnableIO in the
API), the volume status check continues to pass. In addition, you'll see an event that lets you know that
the volume was determined to be potentially inconsistent, but that its I/O was automatically enabled.
This enables you to check the volume's consistency or replace it at a later time.
The I/O performance status check compares actual volume performance to the expected performance
of a volume and alerts you if the volume is performing below expectations. This status check is only
available for io1 volumes that are attached to an instance and is not valid for General Purpose SSD
(gp2), Throughput Optimized HDD (st1), Cold HDD (sc1), or Magnetic (standard) volumes. The I/O
performance status check is performed once every minute and CloudWatch collects this data every 5
minutes, so it may take up to 5 minutes from the moment you attach a io1 volume to an instance for
this check to report the I/O performance status.
Important
While initializing io1 volumes that were restored from snapshots, the performance of the
volume may drop below 50 percent of its expected level, which causes the volume to display
a warning state in the I/O Performance status check. This is expected, and you can ignore
the warning state on io1 volumes while you are initializing them. For more information, see
Initializing Amazon EBS Volumes (p. 931).
Insufficient Data
To view and work with status checks, you can use the Amazon EC2 console, the API, or the command line
interface.
857
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
3. To view the status details of a volume, select the volume and choose Status Checks.
4. If you have a volume with a failed status check (status is impaired), see Working with an Impaired
Volume (p. 860).
Alternatively, you can choose Events in the navigator to view all the events for your instances and
volumes. For more information, see EBS Volume Events (p. 858).
To automatically enable I/O on a volume with potential data inconsistencies, change the setting of the
Auto-Enabled IO volume attribute (autoEnableIO in the API). For more information about changing
this attribute, see Working with an Impaired Volume (p. 860).
Each event includes a start time that indicates the time at which the event occurred, and a duration that
indicates how long I/O for the volume was disabled. The end time is added to the event when I/O for the
volume is enabled.
Volume data is potentially inconsistent. I/O is disabled for the volume until you explicitly enable it.
The event description changes to IO Enabled after you explicitly enable I/O.
858
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
IO Enabled
I/O operations were automatically enabled on this volume after an event occurred. We recommend
that you check for data inconsistencies before continuing to use the data.
Normal
You can view events for your volumes using the Amazon EC2 console, the API, or the command line
interface.
859
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
If you have a volume where I/O is disabled, see Working with an Impaired Volume (p. 860). If you have
a volume where I/O performance is below normal, this might be a temporary condition due to an action
you have taken (for example, creating a snapshot of a volume during peak usage, running the volume on
an instance that cannot support the I/O bandwidth required, accessing data on the volume for the first
time, etc.).
Options
• Option 1: Perform a Consistency Check on the Volume Attached to its Instance (p. 861)
• Option 2: Perform a Consistency Check on the Volume Using Another Instance (p. 861)
860
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
The simplest option is to enable I/O and then perform a data consistency check on the volume while the
volume is still attached to its Amazon EC2 instance.
You can use one of the following commands to view event information for your Amazon EBS volumes.
For more information about these command line interfaces, see Accessing Amazon EC2 (p. 3).
Use the following procedure to check the volume outside your production environment.
861
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
Important
This procedure may cause the loss of write I/Os that were suspended when volume I/O was
disabled.
4. Attach the volume to another instance. For more information, see Launch Your Instance (p. 395) and
Attaching an Amazon EBS Volume to an Instance (p. 851).
5. Check the data on the volume.
You can use one of the following commands to view event information for your Amazon EBS volumes.
For more information about these command line interfaces, see Accessing Amazon EC2 (p. 3).
862
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
If you have a recent snapshot that backs up the data on the volume, you can create a new volume from
the snapshot. For information about creating a volume from a snapshot, see Restoring an Amazon EBS
Volume from a Snapshot (p. 848).
This procedure explains how to view and modify the Auto-Enabled IO attribute of a volume.
863
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
3. Select the volume and choose Actions, Change Auto-Enable IO Setting. Alternatively, choose the
Status Checks tab, and for Auto-Enabled IO, choose Edit.
4. Select the Auto-Enable Volume IO check box to automatically enable I/O for an impaired volume.
To disable the feature, clear the check box.
5. Choose Save.
To view or modify the autoEnableIO attribute of a volume with the command line
You can use one of the following commands to view the autoEnableIO attribute of your Amazon EBS
volumes. For more information about these command line interfaces, see Accessing Amazon EC2 (p. 3).
To modify the autoEnableIO attribute of a volume, you can use one of the commands below.
If an EBS volume is the root device of an instance, you must stop the instance before you can detach the
volume.
When a volume with an AWS Marketplace product code is detached from an instance, the product code is
no longer associated with the instance.
864
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes
Important
After you detach a volume, you are still charged for volume storage as long as the storage
amount exceeds the limit of the AWS Free Tier. You must delete a volume to avoid incurring
further charges. For more information, see Deleting an Amazon EBS Volume (p. 866).
This example unmounts the volume and then explicitly detaches it from the instance. This is useful when
you want to terminate an instance or attach a volume to a different instance. To verify that the volume is
no longer attached to the instance, see Viewing Information about an Amazon EBS Volume (p. 855).
You can reattach a volume that you detached (without unmounting it), but it might not get the same
mount point. If there were writes to the volume in progress when it was detached, the data on the
volume might be out of sync.
Troubleshooting
The following are common problems encountered when detaching volumes, and how to resolve them.
Note
To guard against the possibility of data loss, take a snapshot of your volume before attempting
to unmount it. Forced detachment of a stuck volume can cause damage to the file system or the
data it contains or an inability to attach a new volume using the same device name, unless you
reboot the instance.
• If you encounter problems while detaching a volume through the Amazon EC2 console, it may be
helpful to use the describe-volumes CLI command to diagnose the issue. For more information, see
describe-volumes.
• If your volume stays in the detaching state, you can force the detachment by choosing Force Detach.
Use this option only as a last resort to detach a volume from a failed instance, or if you are detaching
a volume with the intention of deleting it. The instance doesn't get an opportunity to flush file system
caches or file system metadata. If you use this option, you must perform the file system check and
repair procedures.
• If you've tried to force the volume to detach multiple times over several minutes and it stays in the
detaching state, you can post a request for help to the Amazon EC2 forum. To help expedite a
resolution, include the volume ID and describe the steps that you've already taken.
• When you attempt to detach a volume that is still mounted, the volume can become stuck in the busy
state while it is trying to detach. The following output from describe-volumes shows an example of
this condition:
865
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Snapshots
When you encounter this state, detachment can be delayed indefinitely until you unmount the volume,
force detachment, reboot the instance, or all three.
To delete a volume, it must be in the available state (not attached to an instance). For more
information, see Detaching an Amazon EBS Volume from an Instance (p. 864).
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
When you create an EBS volume based on a snapshot, the new volume begins as an exact replica of
the original volume that was used to create the snapshot. The replicated volume loads data in the
866
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Snapshots
background so that you can begin using it immediately. If you access data that hasn't been loaded yet,
the volume immediately downloads the requested data from Amazon S3, and then continues loading
the rest of the volume's data in the background. For more information, see Creating Amazon EBS
Snapshots (p. 869).
Multi-Volume Snapshots
Snapshots can be used to create a backup of critical workloads, such as a large database or a file system
that spans across multiple EBS volumes. Multi-volume snapshots allow you to take exact point-in-
time, data coordinated, and crash-consistent snapshots across multiple EBS volumes attached to an
EC2 instance. You are no longer required to stop your instance or to coordinate between volumes to
ensure crash consistency, because snapshots are automatically taken across multiple EBS volumes. For
more information, see the steps for creating a multi-volume EBS snapshot under Creating Amazon EBS
Snapshots (p. 869).
You can track the status of your EBS snapshots through CloudWatch Events. For more information, see
Amazon CloudWatch Events for Amazon EBS (p. 947).
Contents
• How Incremental Snapshots Work (p. 867)
• Copying and Sharing Snapshots (p. 869)
• Encryption Support for Snapshots (p. 869)
• Creating Amazon EBS Snapshots (p. 869)
• Deleting an Amazon EBS Snapshot (p. 872)
• Copying an Amazon EBS Snapshot (p. 874)
• Viewing Amazon EBS Snapshot Information (p. 878)
• Sharing an Amazon EBS Snapshot (p. 878)
• Automating the Amazon EBS Snapshot Lifecycle (p. 881)
In the diagram below, Volume 1 is shown at three points in time. A snapshot is taken of each of these
three volume states.
• In State 1, the volume has 10 GiB of data. Because Snap A is the first snapshot taken of the volume,
the entire 10 GiB of data must be copied.
• In State 2, the volume still contains 10 GiB of data, but 4 GiB have changed. Snap B needs to copy and
store only the 4 GiB that changed after Snap A was taken. The other 6 GiB of unchanged data, which
are already copied and stored in Snap A, are referenced by Snap B rather than (again) copied. This is
indicated by the dashed arrow.
• In State 3, 2 GiB of data have been added to the volume, for a total of 12 GiB. Snap C needs to copy
the 2 GiB that were added after Snap B was taken. As shown by the dashed arrows, Snap C also
references 4 GiB of data stored in Snap B, and 6 GiB of data stored in Snap A.
• The total storage required for the three snapshots is 16 GiB.
867
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Snapshots
Note
If you copy a snapshot and encrypt it to a new CMK, a complete (non-incremental) copy is
always created, resulting in additional delay and storage costs.
868
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Snapshots
For more information about how data is managed when you delete a snapshot, see Deleting an Amazon
EBS Snapshot (p. 872).
A snapshot is constrained to the AWS Region where it was created. After you create a snapshot of an EBS
volume, you can use it to create new volumes in the same Region. For more information, see Restoring
an Amazon EBS Volume from a Snapshot (p. 848). You can also copy snapshots across Regions, making
it possible to use multiple Regions for geographical expansion, data center migration, and disaster
recovery. You can copy any accessible snapshot that has a completed status. For more information, see
Copying an Amazon EBS Snapshot (p. 874).
Note
If you copy a snapshot and encrypt it to a new CMK, a complete (non-incremental) copy is
always created, resulting in additional delay and storage costs.
Complete documentation of possible snapshot encryption scenarios is provided in Creating Amazon EBS
Snapshots (p. 869) and in Copying an Amazon EBS Snapshot (p. 874).
Snapshots occur asynchronously; the point-in-time snapshot is created immediately, but the status of
the snapshot is pending until the snapshot is complete (when all of the modified blocks have been
transferred to Amazon S3), which can take several hours for large initial snapshots or subsequent
snapshots where many blocks have changed. While it is completing, an in-progress snapshot is not
affected by ongoing reads and writes to the volume.
869
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Snapshots
Important
Although you can take a snapshot of a volume while a previous snapshot of that volume is in
the pending status, having multiple pending snapshots of a volume can result in reduced
volume performance until the snapshots complete.
There is a limit of five pending snapshots for a single gp2, io1, or Magnetic
volume, and one pending snapshot for a single st1 or sc1 volume. If you receive a
ConcurrentSnapshotLimitExceeded error while trying to create multiple concurrent
snapshots of the same volume, wait for one or more of the pending snapshots to complete
before creating another snapshot of that volume.
Snapshots that are taken from encrypted volumes are automatically encrypted. Volumes that are created
from encrypted snapshots are also automatically encrypted. The data in your encrypted volumes and
any associated snapshots is protected both at rest and in motion. For more information, see Amazon EBS
Encryption (p. 903).
By default, only you can create volumes from snapshots that you own. However, you can share
your unencrypted snapshots with specific AWS accounts, or you can share them with the entire
AWS community by making them public. For more information, see Sharing an Amazon EBS
Snapshot (p. 878).
You can share an encrypted snapshot only with specific AWS accounts. For others to use your shared,
encrypted snapshot, you must also share the CMK key that was used to encrypt it. Users with access to
your encrypted snapshot must create their own personal copy of it and then use that copy to restore the
volume. Your copy of a shared, encrypted snapshot can also be re-encrypted with a different key. For
more information, see Sharing an Amazon EBS Snapshot (p. 878).
Note
If you copy a snapshot and encrypt it to a new CMK, a complete (non-incremental) copy is
always created, resulting in additional delay and storage costs.
When a snapshot is created from a volume with an AWS Marketplace product code, the product code is
propagated to the snapshot.
You can take a snapshot of an attached volume that is in use. However, snapshots only capture data
that has been written to your Amazon EBS volume at the time the snapshot command is issued. This
might exclude any data that has been cached by any applications or the operating system. If you can
pause any file writes to the volume long enough to take a snapshot, your snapshot should be complete.
However, if you can't pause all file writes to the volume, you should unmount the volume from within
the instance, issue the snapshot command, and then remount the volume to ensure a consistent and
complete snapshot. You can remount and use your volume while the snapshot status is pending.
Multi-volume snapshots, or point-in-time snapshots for all EBS volumes attached to a single EC2
instance, can be created using the AWS Console, AWS CLI, or AWS SDK. You can also create lifecycle
policies to automate the creation and retention of multi-volume snapshots. For more information about
creating EBS lifecycle policies, see Automating the Amazon EBS Snapshot Lifecycle (p. 881).
To create a snapshot for an Amazon EBS volume that serves as a root device, you should stop the
instance before taking the snapshot.
To unmount the volume in Linux, use the following command, where device_name is the device name
(for example, /dev/sdh).
umount -d device_name
To make snapshot management easier, you can tag your snapshots during creation or add tags
afterward. For example, you can apply tags describing the original volume from which the snapshot
was created, or the device name that was used to attach the original volume to an instance. For more
information, see Tagging Your Amazon EC2 Resources (p. 995).
870
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Snapshots
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
During snapshot creation, the snapshots are managed together. If one of the snapshots in the
volume set fails, the other snapshots are moved to error status for the volume set. You can
monitor the progress of your snapshots with CloudWatch Events. After the snapshot creation
process completes, CloudWatch generates an event that contains the status and all of the relevant
snapshots details for the affected instance.
After the snapshots are created, each snapshot is treated as an individual snapshot. You can perform
all snapshot operations, such as restore, delete, and cross-region/account copy, just as you would
with a single volume snapshot. You can also tag your multi-volume snapshots as you would a
single volume snapshot. We recommend you tag your multiple volume snapshots to manage them
collectively during restore, copy, or retention.
Multi-volume, crash-consistent snapshots are typically restored as a set. It is helpflul to identify the
snapshots that are in a crash-consistent set by tagging your set with instance-id, name, or other
relevant details. You can also set the Copy tags from volume flag to automatically copy tags from
the source volume to the corresponding snapshots. This helps you to set the snapshot metadata,
such as access policies, attachment information, and cost allocation, to match the source volume.
After it's created, a multi-volume snapshot behaves like a normal snapshot. You can perform all
operations, such as restore, delete, and copy across Regions and accounts. You can also tag your
snapshots. We recommend that you tag your multi-volume snapshots to collectively manage them
during restore, copy, or retention.
871
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Snapshots
After creating your snapshots, they will appear in your EC2 console created at the exact point-in-
time. The snapshots are collectively managed and, therefore, if any one snapshot for the volume set
fails, all of the other snapshots will display an error status.
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
Deleting a snapshot of a volume has no effect on the volume. Deleting a volume has no effect on the
snapshots made from it.
If you make periodic snapshots of a volume, the snapshots are incremental. This means that only the
blocks on the device that have changed after your last snapshot are saved in the new snapshot. Even
though snapshots are saved incrementally, the snapshot deletion process is designed so that you need to
retain only the most recent snapshot in order to restore the volume.
Deleting a snapshot might not reduce your organization's data storage costs. Other snapshots might
reference that snapshot's data, and referenced data is always preserved. If you delete a snapshot
containing data being used by a later snapshot, costs associated with the referenced data are allocated
to the later snapshot. For more information about how snapshots store data, see How Incremental
Snapshots Work (p. 867) and the example below.
To delete multi-volume snapshots, retrieve all of the snapshots for your multi-volume group using the
tag you applied to the group when you created the snapshots. Then, delete the snapshots individually.
You will not be prevented from deleting individual snapshots in the multi-volume snapshots group.
In the following diagram, Volume 1 is shown at three points in time. A snapshot has captured each of the
first two states, and in the third, a snapshot has been deleted.
• In State 1, the volume has 10 GiB of data. Because Snap A is the first snapshot taken of the volume,
the entire 10 GiB of data must be copied.
• In State 2, the volume still contains 10 GiB of data, but 4 GiB have changed. Snap B needs to copy and
store only the 4 GiB that changed after Snap A was taken. The other 6 GiB of unchanged data, which
are already copied and stored in Snap A, are referenced by Snap B rather than (again) copied. This is
indicated by the dashed arrow.
• In state 3, the volume has not changed since State 2, but Snapshot A has been deleted. The 6 GiB of
data stored in Snapshot A that were referenced by Snapshot B have now been moved to Snapshot
B, as shown by the heavy arrow. As a result, you are still charged for storing 10 GiB of data; 6 GiB of
unchanged data preserved from Snap A and 4 GiB of changed data from Snap B.
Example 1: Deleting a Snapshot with Some of its Data Referenced by Another Snapshot
872
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Snapshots
Note that you can't delete a snapshot of the root device of an EBS volume used by a registered AMI.
You must first deregister the AMI before you can delete the snapshot. For more information, see
Deregistering Your Linux AMI (p. 159).
873
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Snapshots
Note
Although you can delete a snapshot that is still in progress, the snapshot must complete before
the deletion takes effect. This may take a long time. If you are also at your concurrent snapshot
limit (five snapshots in progress), and you attempt to take an additional snapshot, you may get
the ConcurrentSnapshotLimitExceeded error.
To copy multi-volume snapshots to another AWS Region, retrieve the snapshots using the tag you
applied to the multi-volume snapshots group when you created it. Then individually copy the snapshots
to another Region.
For information about copying an Amazon RDS snapshot, see Copying a DB Snapshot in the Amazon RDS
User Guide.
If you would like another account to be able to copy your snapshot, you must either modify the snapshot
permissions to allow access to that account or make the snapshot public so that all AWS accounts can
copy it. For more information, see Sharing an Amazon EBS Snapshot (p. 878).
For pricing information about copying snapshots across AWS Regions and accounts, see Amazon EBS
Pricing. Note that snapshot copy operations within a single account and Region do not copy any actual
data and therefore are cost-free as long as the encryption status of the snapshot copy does not change.
Note
If you copy a snapshot to a new Region, a complete (non-incremental) copy is always created,
resulting in additional delay and storage costs.
Note
If you copy a snapshot and encrypt it to a new CMK, a complete (non-incremental) copy is
always created, resulting in additional delay and storage costs.
Use Cases
874
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Snapshots
Prerequisites
• You can copy any accessible snapshots that have a completed status, including shared snapshots and
snapshots that you have created.
• You can copy AWS Marketplace, VM Import/Export, and AWS Storage Gateway snapshots, but you
must verify that the snapshot is supported in the destination Region.
Limits
• Each account can have up to five concurrent snapshot copy requests to a single destination Region.
• User-defined tags are not copied from the source snapshot to the new snapshot. After the copy
operation is complete, you can apply user-defined tags to the new snapshot. For more information, see
Tagging Your Amazon EC2 Resources (p. 995).
• Snapshots created by the CopySnapshot action have an arbitrary volume ID that should not be used
for any purpose.
In the case of encrypted snapshots, you must encrypt to the same CMK that was used for previous copies
to get incremental copies. The following examples illustrate how this works:
• If you copy an unencrypted snapshot from the US East (N. Virginia) Region to the US West (Oregon)
Region, the first snapshot copy is a full copy and subsequent snapshot copies of the same volume
transferred between the same Regions are incremental.
• If you copy an encrypted snapshot from the US East (N. Virginia) Region to the US West (Oregon)
Region, the first snapshot copy of the volume is a full copy.
• If you encrypt to the same CMK in a subsequent snapshot copy for the same volume between the
same Regions, the copy is incremental.
• If you encrypt to a different CMK in a subsequent snapshot copy for the same volume between the
same Regions, the copy is a new full copy of the snapshot.
To copy an encrypted snapshot shared from another AWS account, you must have permissions to use
the snapshot and the customer master key (CMK) that was used to encrypt the snapshot. When using
an encrypted snapshot that was shared with you, we recommend that you re-encrypt the snapshot by
copying it using a CMK that you own. This protects you if the original CMK is compromised, or if the
owner revokes it, which could cause you to lose access to any encrypted volumes that you created using
the snapshot. For more information, see Sharing an Amazon EBS Snapshot (p. 878).
You apply encryption to EBS snapshot copies by setting the Encrypted parameter to true. (The
Encrypted parameter is optional if encryption by default (p. 904) is enabled).
875
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Snapshots
Optionally, you can use KmsKeyId to specify a custom key to use to encrypt the snapshot copy. (The
Encrypted parameter must also be set to true, even if encryption by default is enabled.) If KmsKeyId
is not specified, the key that is used for encryption depends on the encryption state of the source
snapshot and its ownership.
The following table describes the encryption outcome for each possible combination of settings.
No No Unencrypted Unencrypted
snapshot that is
shared with you
876
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Snapshots
* This is the default CMK used for EBS encryption for the AWS account and Region. By default this is a
unique AWS managed CMK for EBS, or you can specify a customer managed CMK. For more information,
see Encryption Key Management (p. 905).
** This is a customer managed CMK specified for the copy action. This CMK is used instead of the default
CMK for the AWS account and Region.
Copy a Snapshot
Use the following procedure to copy a snapshot using the Amazon EC2 console.
• Destination region: Select the Region where you want to write the copy of the snapshot.
• Description: By default, the description includes information about the source snapshot so that
you can identify a copy from the original. You can change this description as necessary.
• Encryption: If the source snapshot is not encrypted, you can choose to encrypt the copy. If you
have enabled encryption by default (p. 904), the Encryption option is set and cannot be unset
from the snapshot console. If the Encryption option is set, you can choose to encrypt it to a
customer managed CMK by selecting one in the field, described below.
877
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Snapshots
6. In the Copy Snapshot confirmation dialog box, choose Snapshots to go to the Snapshots page in
the Region specified, or choose Close.
To view the progress of the copy process, switch to the destination Region, and then refresh the
Snapshots page. Copies in progress are listed at the top of the page.
If you attempt to copy an encrypted snapshot without having permissions to use the encryption key, the
operation fails silently. The error state is not displayed in the console until you refresh the page. You can
also check the state of the snapshot from the command line, as in the following example.
If the copy failed because of insufficient key permissions, you see the following message:
"StateMessage": "Given key ID is not accessible".
When copying an encrypted snapshot, you must have DescribeKey permissions on the default CMK.
Explicitly denying these permissions results in copy failure. For information about managing CMK keys,
see Controlling Access to Customer Master Keys.
878
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Snapshots
EBS volumes, while your original snapshot remains unaffected. If you choose, you can make your
unencrypted snapshots available publicly to all AWS users. You can't make your encrypted snapshots
available publicly.
When you share an encrypted snapshot, you must also share the customer managed CMK used to
encrypt the snapshot. You can apply cross-account permissions to a customer managed CMK either when
it is created or at a later time.
Important
When you share a snapshot, you are giving others access to all of the data on the snapshot.
Share snapshots only with people with whom you want to share all of your snapshot data.
Considerations
The following considerations apply to sharing snapshots:
• Snapshots are constrained to the Region in which they were created. To share a snapshot with
another Region, copy the snapshot to that Region. For more information, see Copying an Amazon EBS
Snapshot (p. 874).
• If your snapshot uses the longer resource ID format, you can only share it with another account that
also supports longer IDs. For more information, see Resource IDs (p. 987).
• AWS prevents you from sharing snapshots that were encrypted with your default CMK. Snapshots that
you intend to share must instead be encrypted with a customer managed CMK. For more information,
see Creating Keys in the AWS Key Management Service Developer Guide.
• Users of your shared CMK who are accessing encrypted snapshots must be granted permissions
to perform the following actions on the key: kms:DescribeKey, kms:CreateGrant,
GenerateDataKey, and kms:ReEncrypt. For more information, see Controlling Access to Customer
Master Keys in the AWS Key Management Service Developer Guide.
This option is not valid for encrypted snapshots or snapshots with an AWS Marketplace product
code.
• To share the snapshot with one or more AWS accounts, choose Private, enter the AWS account
ID (without hyphens) in AWS Account Number, and choose Add Permission. Repeat for any
additional AWS accounts.
5. Choose Save.
879
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Snapshots
For more information about these command line interfaces, see Accessing Amazon EC2 (p. 3).
880
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Snapshots
Combined with the monitoring features of Amazon CloudWatch Events and AWS CloudTrail, Amazon
DLM provides a complete backup solution for EBS volumes at no additional cost.
Contents
• Understanding Amazon DLM (p. 881)
• Permissions for Amazon DLM (p. 882)
• Permissions for IAM Users (p. 883)
• Limits (p. 884)
• Working with Amazon DLM Using the Console (p. 884)
• Working with Amazon DLM Using the Command Line (p. 886)
• Working with Amazon DLM Using the API (p. 889)
• Working with Amazon DLM to Create and Maintain Multi-Volume Snapshots Using the
Console (p. 889)
• Working with Amazon DLM to Create and Maintain Multi-Volume Snapshots Using the CLI (p. 889)
• Monitoring the Snapshot Lifecycle (p. 891)
Snapshots
Snapshots are the primary means to back up data from your EBS volumes. To save storage costs,
successive snapshots are incremental, containing only the volume data that changed since the previous
snapshot. When you delete one snapshot in a series of snapshots for a volume, only the data unique to
that snapshot is removed. The rest of the captured history of the volume is preserved.
For more information, see Tagging Your Amazon EC2 Resources (p. 995).
Snapshot Tags
Amazon DLM applies the following tags to all snapshots created by a policy, to distinguish them from
snapshots created by any other means:
881
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Snapshots
• aws:dlm:lifecycle-policy-id
• aws:dlm:lifecycle-schedule-name
The target tags that Amazon DLM uses to associate volumes with a policy can optionally be applied to
snapshots created by the policy.
Lifecycle Policies
• Policy type—Defines valid target resource types and actions a policy can manage. Defaults to
EBS_SNAPSHOT_MANAGEMENT if not present.
• Resource type—The AWS resource managed by the policy. Supported values are EBS volumes and EC2
instances.
• Target tag—The tag that must be associated with an EBS volume or an EC2 instance for it to be
managed by the policy.
• Schedule—Defines how often to create snapshots and the maximum number of snapshots to keep.
Snapshot creation starts within an hour of the specified start time. If creating a new snapshot exceeds
the maximum number of snapshots to keep for the volume, the oldest snapshot is deleted.
• A policy does not begin creating snapshots until you set its activation status to enabled. You can
configure a policy to be enabled upon creation.
• Snapshots begin to be created by a policy within one hour following the specified start time.
• If you modify a policy by removing or changing its target tag, the EBS volumes with that tag are no
longer affected by the policy.
• If you modify the schedule name for a policy, the snapshots created under the old schedule name are
no longer affected by the policy.
• If you delete the resource to which a policy applies, the policy no longer manages the previously
created snapshots. You must manually delete the snapshots if they are no longer needed.
• You can create multiple policies to back up an EBS volume or an EC2 instance. For example, if an EBS
volume has two tags, where tag A is the target for policy A to create a snapshot every 12 hours, and
tag B is the target for policy B to create a snapshot every 24 hours, Amazon DLM creates snapshots
according to the schedules for both policies.
• When you copy a snapshot created by a policy, the retention schedule is not carried over to the copy.
This ensures that Amazon DLM does not delete snapshots that should be retained for a longer period
of time.
For example, you could create a policy that manages all EBS volumes with the tag account=Finance,
creates snapshots every 24 hours at 0900, and retains the five most recent snapshots. Snapshot creation
could start as late as 0959.
882
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Snapshots
Alternatively, you can create a custom IAM role with the required permissions and select it when you
create a lifecycle policy.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateSnapshot",
"ec2:CreateSnapshots",
"ec2:DeleteSnapshot",
"ec2:DescribeVolumes",
"ec2:DescribeInstances",
"ec2:DescribeSnapshots"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:*::snapshot/*"
}
]
}
For more information, see Creating a Role in the IAM User Guide.
2. Add a trust relationship to the role.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "dlm.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
883
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Snapshots
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["iam:PassRole", "iam:ListRoles"],
"Resource": "arn:aws:iam::123456789012:role/AWSDataLifecycleManagerDefaultRole"
},
{
"Effect": "Allow",
"Action": "dlm:*",
"Resource": "*"
}
]
}
For more information, see Changing Permissions for an IAM User in the IAM User Guide.
Limits
Your AWS account has the following limits related to Amazon DLM:
884
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Snapshots
• IAM role—An IAM role that has permissions to create, delete, and describe snapshots, and to
describe volumes. AWS provides a default role, AWSDataLifecycleManagerDefaultRole, or you
can create a custom IAM role.
• Policy status after creation—Choose Enable policy to start the policy runs at the next scheduled
time or Disable policy to prevent the policy from running.
4. Choose Create Policy.
• Policy ID
• Resource type
• Policy type
• Date created
• Date modified
• Target resource tags
• Rule summary
• Description
• Policy state
• Tags added to snapshots
885
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Snapshots
• IAM role—An IAM role that has permissions to create, delete, and describe snapshots, and to
describe volumes. AWS provides a default role, AWSDataLifecycleManagerDefaultRole, or you
can create a custom IAM role.
• Policy status after creation—Choose Enable policy to start the policy runs at the next scheduled
time or Disable policy to prevent the policy from running.
Use the create-lifecycle-policy command to create a lifecycle policy. To simplify the syntax, this example
references a JSON file, policyDetails.json, that includes the policy details.
{
"ResourceTypes": [
"VOLUME"
],
"TargetTags": [
{
"Key": "costcenter",
"Value": "115"
}
],
"Schedules":[
{
"Name": "DailySnapshots",
"TagsToAdd": [
{
"Key": "type",
"Value": "myDailySnapshot"
}
],
"CreateRule": {
"Interval": 24,
"IntervalUnit": "HOURS",
"Times": [
"03:00"
]
},
"RetainRule": {
"Count":5
},
886
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Snapshots
"CopyTags": false
}
]
}
Upon success, the command returns the ID of the newly created policy. The following is example output.
{
"PolicyId": "policy-0123456789abcdef0"
}
The following is example output. It includes the information that you specified, plus metadata inserted
by AWS.
{
"Policy":{
"Description": "My first policy",
"DateCreated": "2018-05-15T00:16:21+0000",
"State": "ENABLED",
"ExecutionRoleArn":
"arn:aws:iam::210774411744:role/AWSDataLifecycleManagerDefaultRole",
"PolicyId": "policy-0123456789abcdef0",
"DateModified": "2018-05-15T00:16:22+0000",
"PolicyDetails": {
"PolicyType":"EBS_SNAPSHOT_MANAGEMENT",
"ResourceTypes": [
"VOLUME"
],
"TargetTags": [
{
"Value": "115",
"Key": "costcenter"
}
],
"Schedules": [
{
"TagsToAdd": [
{
"Value": "myDailySnapshot",
"Key": "type"
}
],
"RetainRule": {
"Count": 5
},
"CopyTags": false,
"CreateRule": {
"Interval": 24,
"IntervalUnit": "HOURS",
"Times": [
"03:00"
]
},
"Name": "DailySnapshots"
}
887
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Snapshots
]
}
}
}
Use the update-lifecycle-policy command to modify the information in a lifecycle policy. To simplify the
syntax, this example references a JSON file, policyDetailsUpdated.json, that includes the policy
details.
{
"ResourceTypes":[
"VOLUME"
],
"TargetTags":[
{
"Key": "costcenter",
"Value": "120"
}
],
"Schedules":[
{
"Name": "DailySnapshots",
"TagsToAdd": [
{
"Key": "type",
"Value": "myDailySnapshot"
}
],
"CreateRule": {
"Interval": 12,
"IntervalUnit": "HOURS",
"Times": [
"15:00"
]
},
"RetainRule": {
"Count" :5
},
"CopyTags": false
}
]
}
To view the updated policy, use the get-lifecycle-policy command. You can see that the state, the
value of the tag, the snapshot interval, and the snapshot start time were changed.
Use the delete-lifecycle-policy command to delete a lifecycle policy and free up the target tags specified
in the policy for reuse.
888
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Snapshots
Alternatively, you can use one of the AWS SDKs to access an API that's tailored to the programming
language or platform that you're using. For more information, see AWS SDKs.
1. Sign in to the AWS Management Console and open the Amazon EC2 console at https://
console.aws.amazon.com/ec2/.
2. In the navigation pane, choose Elastic Block Store. Then choose Lifecycle Manager and Create
snapshot lifecycle policy.
3. Provide the following information for your policy, as needed:
889
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Snapshots
Use the create-lifecycle-policy command to create a lifecycle policy. To simplify the syntax, this example
references a JSON file, policyDetails.json, which includes the policy details.
{
"ResourceTypes": [
"INSTANCE"
],
"TargetTags": [
{
"Key": "costcenter",
"Value": "115"
}
],
"Schedules":[
{
"Name": "DailySnapshots",
"TagsToAdd": [
{
"Key": "type",
"Value": "Daily-Multi-Volume Snapshots"
}
],
"VariableTags":[
{
"Key": "timestamp",
"Value": "$(timestamp)"
},
{
"Key": "instance-id",
"Value": "$(instance-id)"
},
],
"Interval": 24,
"IntervalUnit": "HOURS",
"Times": [
"03:00"
]
},
"RetainRule": {
"Count":5
},
"CopyTags": false
}
]
"Parameters": {
"ExcludeBootVolume": true
}
}
Upon success, the command returns the ID of the newly created policy. The following is example output.
{
"PolicyId": "policy-0123456789abcdef0"
890
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Snapshots
You can view your lifecycle policies using the Amazon EC2 console or the AWS CLI. Each snapshot created
by a policy has a timestamp and policy-related tags. You can filter snapshots using tags to verify that
your backups are being created as you intend. For information about viewing lifecycle policies using the
console, see To display a lifecycle policy (p. 885). For information about displaying information about
lifecycle policies using the CLI, see Example: Display a lifecycle policy (p. 887).
CloudWatch Events
Amazon EBS and Amazon DLM emit events related to lifecycle policy actions. You can use AWS Lambda
and Amazon CloudWatch Events to handle event notifications programmatically. For more information,
see the Amazon CloudWatch Events User Guide.
• createSnapshot—An Amazon EBS event emitted when a CreateSnapshot action succeeds or fails.
For more information, see Amazon CloudWatch Events for Amazon EBS (p. 947).
• DLM Policy State Change—A Amazon DLM event emitted when a lifecycle policy enters an error
state. The event contains a description of what caused the error. The following is an example of an
event when the permissions granted by the IAM role are insufficient:
{
"version": "0",
"id": "01234567-0123-0123-0123-0123456789ab",
"detail-type": "DLM Policy State Change",
"source": "aws.dlm",
"account": "123456789012",
"time": "2018-05-25T13:12:22Z",
"region": "us-east-1",
"resources": [
"arn:aws:dlm:us-east-1:123456789012:policy/policy-0123456789abcdef"
],
"detail": {
"state": "ERROR",
"cause": "Role provided does not have sufficient permissions",
"policy_id": "arn:aws:dlm:us-east-1:123456789012:policy/policy-0123456789abcdef"
}
}
{
"version": "0",
"id": "01234567-0123-0123-0123-0123456789ab",
"detail-type": "DLM Policy State Change",
"source": "aws.dlm",
"account": "123456789012",
"time": "2018-05-25T13:12:22Z",
"region": "us-east-1",
"resources": [
"arn:aws:dlm:us-east-1:123456789012:policy/policy-0123456789abcdef"
],
"detail":{
891
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Data Services
"state": "ERROR",
"cause": "Maximum allowed active snapshot limit exceeded",
"policy_id": "arn:aws:dlm:us-east-1:123456789012:policy/policy-0123456789abcdef"
}
}
AWS CloudTrail
With AWS CloudTrail, you can track user activity and API usage to demonstrate compliance with internal
policies and regulatory standards. For more information, see the AWS CloudTrail User Guide.
AWS CloudFormation
When deploying resource stacks with AWS CloudFormation, you can include Amazon DLM policies in your
AWS CloudFormation templates. For more information, see Amazon Data Lifecycle Manager Resource
Types Reference.
Data Services
• Amazon EBS Elastic Volumes (p. 892)
• Amazon EBS Encryption (p. 903)
There is no charge to modify the configuration of a volume. You are charged for the new volume
configuration after volume modification starts. For more information, see the Amazon EBS Pricing page.
Contents
• Requirements When Modifying Volumes (p. 892)
• Requesting Modifications to Your EBS Volumes (p. 894)
• Monitoring the Progress of Volume Modifications (p. 897)
• Extending a Linux File System After Resizing a Volume (p. 900)
892
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Data Services
If your instance type does not support Elastic Volumes, see Modifying an EBS Volume If Elastic Volumes
Is Unsupported (p. 896).
Linux AMIs require a GUID partition table (GPT) and GRUB 2 for boot volumes that are 2 TiB (2,048
GiB) or larger. Many Linux AMIs today still use the MBR partitioning scheme, which only supports boot
volume sizes up to 2 TiB. If your instance does not boot with a boot volume larger than 2 TiB, the AMI
you are using may be limited to a boot volume size of less than 2 TiB. Non-boot volumes do not have
this limitation on Linux instances. For requirements affecting Windows volumes, see Requirements for
Windows Volumes in the Amazon EC2 User Guide for Windows Instances.
Before attempting to resize a boot volume beyond 2 TiB, you can determine whether the volume is using
MBR or GPT partitioning by running the following command on your instance:
An Amazon Linux instance with GPT partitioning returns the following information:
Limitations
• The new volume size cannot exceed the supported volume capacity. For more information, see
Constraints on the Size and Configuration of an EBS Volume (p. 845).
• If the volume was attached before November 2, 2016, you must initialize Elastic Volumes support. For
more information, see Initializing Elastic Volumes Support (p. 895).
• If you are using an unsupported previous-generation instance type, or if you encounter an error
while attempting a volume modification, see Modifying an EBS Volume If Elastic Volumes Is
Unsupported (p. 896).
• A gp2 volume that is attached to an instance as a root volume cannot be modified to an st1 or sc1
volume. If detached and modified to st1 or sc1, it cannot be attached to an instance as the root
volume.
• A gp2 volume cannot be modified to an st1 or sc1 volume if the requested volume size is below the
minimum size for st1 and sc1 volumes.
• In some cases, you must detach the volume or stop the instance for modification to proceed. If you
encounter an error message while attempting to modify an EBS volume, or if you are modifying an
EBS volume attached to a previous-generation instance type, take one of the following steps:
893
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Data Services
• For a non-root volume, detach the volume from the instance, apply the modifications, and then re-
attach the volume.
• For a root (boot) volume, stop the instance, apply the modifications, and then restart the instance.
• After provisioning over 32,000 IOPS on an existing io1 volume, you may need to do one of the
following to see the full performance improvements:
• Detach and attach the volume.
• Restart the instance.
• Decreasing the size of an EBS volume is not supported. However, you can create a smaller volume and
then migrate your data to it using an application-level tool such as rsync.
• Modification time is increased if you modify a volume that has not been fully initialized. For more
information see Initializing Amazon EBS Volumes (p. 931).
• After modifying a volume, wait at least six hours and ensure that the volume is in the in-use or
available state before making additional modifications to the same volume.
• While m3.medium instances fully support volume modification, m3.large, m3.xlarge, and
m3.2xlarge instances might not support all volume modification features.
1. (Optional) Before modifying a volume that contains valuable data, it is a best practice to create
a snapshot of the volume in case you need to roll back your changes. For more information, see
Creating Amazon EBS Snapshots (p. 869).
2. Request the volume modification.
3. Monitor the progress of the volume modification. For more information, see Monitoring the Progress
of Volume Modifications (p. 897).
4. If the size of the volume was modified, extend the volume's file system to take advantage of the
increased storage capacity. For more information, see Extending a Linux File System After Resizing a
Volume (p. 900).
Contents
• Modifying an EBS Volume Using Elastic Volumes (Console) (p. 894)
• Modifying an EBS Volume Using Elastic Volumes (AWS CLI) (p. 895)
• Initializing Elastic Volumes Support (If Needed) (p. 895)
• Modifying an EBS Volume If Elastic Volumes Is Unsupported (p. 896)
894
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Data Services
Use the modify-volume command modify one or more configuration settings for a volume. For
example, if you have a volume of type gp2 with a size of 100 GiB, the following command changes its
configuration to a volume of type io1 with 10,000 IOPS and a size of 200 GiB.
aws ec2 modify-volume --volume-type io1 --iops 10000 --size 200 --volume-
id vol-11111111111111111
{
"VolumeModification": {
"TargetSize": 200,
"TargetVolumeType": "io1",
"ModificationState": "modifying",
"VolumeId": "vol-11111111111111111",
"TargetIops": 10000,
"StartTime": "2017-01-19T22:21:02.959Z",
"Progress": 0,
"OriginalVolumeType": "gp2",
"OriginalIops": 300,
"OriginalSize": 100
}
}
Modifying volume size has no practical effect until you also extend the volume's file system to make use
of the new storage capacity. For more information, see Extending a Linux File System After Resizing a
Volume (p. 900).
Before you can modify a volume that was attached to an instance before November 1, 2016, you must
initialize volume modification support using one of the following actions:
Use one of the following procedures to determine whether your instances are ready for volume
modification.
895
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Data Services
Use the following describe-instances command to determine whether the volume was attached before
November 1, 2016.
The first line of the output for each instance shows its ID and whether it was started before the cutoff
date (True or False). The first line is followed by one or more lines that show whether each EBS volume
was attached before the cutoff date (True or False). In the following example output, you must initialize
volume modification for the first instance because it was started before the cutoff date and its root
volume was attached before the cutoff date. The other instances are ready because they were started
after the cutoff date.
i-e905622e True
True
i-719f99a8 False
True
i-006b02c1b78381e57 False
False
False
i-e3d172ed False
True
If you are using a supported instance type, you can use Elastic Volumes to dynamically modify the size,
performance, and volume type of your Amazon EBS volumes without detaching them.
If you cannot use Elastic Volumes but you need to modify the root (boot) volume, you must stop the
instance, modify the volume, and then restart the instance.
After the instance has started, you can check the file system size to see if your instance recognizes the
larger volume space. On Linux, use the df -h command to check the file system size.
896
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Data Services
[ec2-user ~]$ df -h
Filesystem Size Used Avail Use% Mounted on
/dev/xvda1 7.9G 943M 6.9G 12% /
tmpfs 1.9G 0 1.9G 0% /dev/shm
If the size does not reflect your newly expanded volume, you must extend the file system of your device
so that your instance can use the new space. For more information, see Extending a Linux File System
After Resizing a Volume (p. 900).
While the volume is in the optimizing state, your volume performance is in between the source and
target configuration specifications. Transitional volume performance will be no less than the source
volume performance. If you are downgrading IOPS, transitional volume performance is no less than the
target volume performance.
• Size changes usually take a few seconds to complete and take effect after a volume is in the
Optimizing state.
• Performance (IOPS) changes can take from a few minutes to a few hours to complete and are
dependent on the configuration change being made.
• It may take up to 24 hours for a new configuration to take effect, and in some cases more, such as
when the volume has not been fully initialized. Typically, a fully used 1-TiB volume takes about 6 hours
to migrate to a new performance configuration.
Use one of the following methods to monitor the progress of a volume modification.
Contents
• Monitoring the Progress of a Volume Modification (Console) (p. 897)
• Monitoring the Progress of a Volume Modification (AWS CLI) (p. 898)
• Monitoring the Progress of a Volume Modification (CloudWatch Events) (p. 899)
Use the following procedure to view the progress of one or more volume modifications.
897
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Data Services
Use the describe-volumes-modifications command to view the progress of one or more volume
modifications. The following example describes the volume modifications for two volumes.
In the following example output, the volume modifications are still in the modifying state.
{
"VolumesModifications": [
{
"TargetSize": 200,
"TargetVolumeType": "io1",
"ModificationState": "modifying",
"VolumeId": "vol-11111111111111111",
"TargetIops": 10000,
"StartTime": "2017-01-19T22:21:02.959Z",
"Progress": 0,
898
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Data Services
"OriginalVolumeType": "gp2",
"OriginalIops": 300,
"OriginalSize": 100
},
{
"TargetSize": 2000,
"TargetVolumeType": "sc1",
"ModificationState": "modifying",
"VolumeId": "vol-22222222222222222",
"StartTime": "2017-01-19T22:23:22.158Z",
"Progress": 0,
"OriginalVolumeType": "gp2",
"OriginalIops": 300,
"OriginalSize": 1000
}
]
}
The next example describes all volumes with a modification state of either optimizing or completed,
and then filters and formats the results to show only modifications that were initiated on or after
February 1, 2017:
[
{
"STATE": "optimizing",
"ID": "vol-06397e7a0eEXAMPLE"
},
{
"STATE": "completed",
"ID": "vol-ba74e18c2aEXAMPLE"
}
]
With CloudWatch Events, you can create a notification rule for volume modification events. You can
use your rule to generate a notification message using Amazon SNS or to invoke a Lambda function in
response to matching events.
{
"source": [
"aws.ec2"
],
"detail-type": [
"EBS Volume Notification"
],
899
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Data Services
"detail": {
"event": [
"modifyVolume"
]
}
}
{
"version": "0",
"id": "01234567-0123-0123-0123-012345678901",
"detail-type": "EBS Volume Notification",
"source": "aws.ec2",
"account": "012345678901",
"time": "2017-01-12T21:09:07Z",
"region": "us-east-1",
"resources": [
"arn:aws:ec2:us-east-1:012345678901:volume/vol-03a55cf56513fa1b6"
],
"detail": {
"result": "optimizing",
"cause": "",
"event": "modifyVolume",
"request-id": "01234567-0123-0123-0123-0123456789ab"
}
}
For information about extending a Windows file system, see Extending a Windows File System after
Resizing a Volume in the Amazon EC2 User Guide for Windows Instances.
For the following tasks, suppose that you have resized the boot volume of an instance from 8 GB to 16
GB and an additional volume from 8 GB to 30 GB.
Tasks
• Identifying the File System for a Volume (p. 900)
• Extending a Partition (If Needed) (p. 901)
• Extending the File System (p. 902)
To verify the file system in use for each volume on your instance, connect to your instance (p. 446) and
run the file -s command.
900
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Data Services
The following example shows a Nitro-based instance (p. 181) that has a boot volume with an XFS file
system and an additional volume with an XFS file system.
The following example shows a T2 instance that has a boot volume with an ext4 file system and an
additional volume with an XFS file system.
Your EBS volume might have a partition that contains the file system and data. Increasing the size of
a volume does not increase the size of the partition. Before you extend the file system on a resized
volume, check whether the volume has a partition that must be extended to the new size of the volume.
Use the lsblk command to display information about the block devices attached to your instance. If a
resized volume has a partition and the partition does not reflect the new size of the volume, use the
growpart command to extend the partition. For information about extending an LVM partition, see
Extending a logical volume.
• The root volume, /dev/nvme0n1, has a partition, /dev/nvme0n1p1. While the size of the root
volume reflects the new size, 16 GB, the size of the partition reflects the original size, 8 GB, and must
be extended before you can extend the file system.
• The volume /dev/nvme1n1 has no partitions. The size of the volume reflects the new size, 30 GB.
To extend the partition on the root volume, use the following growpart command. Notice that there is a
space between the device name and the partition number.
You can verify that the partition reflects the increased volume size by using the lsblk command again.
901
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Data Services
• The root volume, /dev/xvda, has a partition, /dev/xvda1. While the size of the volume is 16 GB, the
size of the partition is still 8 GB and must be extended.
• The volume /dev/xvdf has a partition, /dev/xvdf1. While the size of the volume is 30G, the size of
the partition is still 8 GB and must be extended.
To extend the partition on each volume, use the following growpart commands. Note that there is a
space between the device name and the partition number.
You can verify that the partitions reflect the increased volume size by using the lsblk command again.
[ec2-user ~]$ df -h
Filesystem Size Used Avail Use% Mounted on
/dev/xvda1 8.0G 1.9G 6.2G 24% /
/dev/xvdf1 8.0G 45M 8.0G 1% /data
...
Use the resize2fs command to extend the file system on each volume.
902
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Data Services
You can verify that each file system reflects the increased volume size by using the df -h command
again.
[ec2-user ~]$ df -h
Filesystem Size Used Avail Use% Mounted on
/dev/xvda1 16G 1.9G 6.2G 12% /
/dev/xvdf1 30G 45M 8.0G 1% /data
...
Use the df -h command to verify the size of the file system for each volume. In this example, each file
system reflects the original volume size, 8 GB.
[ec2-user ~]$ df -h
Filesystem Size Used Avail Use% Mounted on
/dev/nvme0n1p1 8.0G 1.6G 6.5G 20% /
/dev/nvme1n1 8.0G 33M 8.0G 1% /data
...
To extend the XFS file system, install the XFS tools as follows, if they are not already installed.
Use the xfs_growfs command to extend the file system on each volume. In this example, / and /data
are the volume mount points shown in the output for df -h.
You can verify that each file system reflects the increased volume size by using the df -h command
again.
[ec2-user ~]$ df -h
Filesystem Size Used Avail Use% Mounted on
/dev/nvme0n1p1 16G 1.6G 15G 10% /
/dev/nvme1n1 30G 33M 30G 1% /data
...
When you create an encrypted EBS volume and attach it to a supported instance type, the following
types of data are encrypted:
903
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Data Services
You can encrypt both the boot and data volumes of an EC2 instance.
Encryption operations occur on the servers that host EC2 instances, ensuring the security of both data-
at-rest and data-in-transit between an instance and its attached EBS storage.
Public snapshots of encrypted volumes are not supported, but you can share an encrypted snapshot with
specific accounts. For more information, see Sharing an Amazon EBS Snapshot (p. 878).
Contents
• Supported Volume Types (p. 904)
• Supported Instance Types (p. 904)
• Encryption by Default (p. 904)
• Encryption Key Management (p. 905)
• Encryption Parameters for EBS Volumes (p. 906)
• Examples of Encryption Outcomes (p. 908)
• Setting Encryption and Key Defaults Using the API and CLI (p. 911)
• General purpose: A1, M3, M4, M5, M5a, M5ad, M5d, T2, T3, and T3a
• Compute optimized: C3, C4, C5, C5d, and C5n
• Memory optimized: cr1.8xlarge, R3, R4, R5, R5a, R5ad, R5d, X1, X1e, and z1d
• Storage optimized: D2, h1.2xlarge, h1.4xlarge, I2, and I3
• Accelerated computing: F1, G2, G3, P2, and P3
• Bare metal: c5.metal, i3.metal, m5.metal, m5d.metal, r5.metal, r5d.metal, u-6tb1.metal,
u-9tb1.metal, u-12tb1.metal, and z1d.metal
Encryption by Default
You can configure your AWS account to enforce the encryption of your EBS volumes and snapshots.
Activating encryption by default has two effects:
Encryption by default is a Region-specific setting. If you enable it for a Region, you cannot disable it for
individual volumes or snapshots in that Region.
904
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Data Services
Newly created EBS resources are encrypted by your account's default customer master key (CMK) unless
you specify a customer managed CMK in the EC2 settings or at launch. For more information, see
Encryption Key Management (p. 905).
Encryption by default has no effect on existing EBS volumes or snapshots, but when you copy
unencrypted snapshots, or restore unencrypted volumes, the resulting snapshots or volumes are
encrypted. For examples of transitioning from unencrypted to encrypted EBS resources, see Encrypting
Unencrypted Resources (p. 907).
When you enable encryption by default, you can launch an Amazon EC2 instance only if the instance type
supports EBS encryption. For more information, see Supported Instance Types (p. 904).
You cannot change the CMK that is associated with an existing snapshot or encrypted volume. However,
you can associate a different CMK during a snapshot copy operation so that the resulting copied
snapshot is encrypted by the new CMK.
EBS encrypts your volume with a data key using the industry-standard AES-256 algorithm. Your
data key is stored on-disk with your encrypted data, but not before EBS encrypts it with your CMK; it
never appears on disk in plaintext. The same data key is shared by snapshots of the volume and any
subsequent volumes created from those snapshots. For more information, see Data Keys in the AWS Key
Management Service Developer Guide.
Prerequisite
When you configure a CMK as the default for EBS encryption, you must also give your users access to
a KMS key policy that allows the CMK to be used to launch instances, create volumes, copy snapshots,
and copy images. These permissions include the following: GenerateDataKeyWithoutPlainText,
Reencrypt*, CreateGrant, DescribeKey, and Decrypt. For more information, see Authentication
and Access Control for AWS KMS and How Amazon Elastic Block Store (Amazon EBS) Uses AWS KMS.
905
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Data Services
5. Choose Update.
For more information about key management and key access permissions, see How Amazon Elastic Block
Store (Amazon EBS) Uses AWS KMS and Authentication and Access Control for AWS KMS in the AWS Key
Management Service Developer Guide.
Optionally, you can use KmsKeyId to specify a custom key to use to encrypt the volume. (The
Encrypted parameter must also be set to true, even if encryption by default is enabled.) If KmsKeyId
is not specified, the key that is used for encryption depends on the encryption state of the source
snapshot and its ownership.
The following table describes the encryption outcome for each possible combination of settings.
Encryption Outcomes
906
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Data Services
* This is the default CMK used for EBS encryption for the AWS account and Region. By default this is a
unique AWS managed CMK for EBS, or you can specify a customer managed CMK. For more information,
see Encryption Key Management (p. 905).
** This is a customer managed CMK specified for the volume at launch time. This CMK is used instead of
the default CMK for the AWS account and Region.
When you create a new, empty EBS volume, you can encrypt it to your default CMK by setting the
Encrypted flag. To encrypt the volume to a customer managed CMK, you must provide a value for
KmsKeyId as well. The volume is encrypted from the time it is first available, so your data is always
secured. For detailed procedures, see Creating an Amazon EBS Volume (p. 847).
By default, the same CMK that you selected when creating the volume encrypts the snapshots that you
make from it and the volumes that you restore from those snapshots. You cannot remove encryption
from an encrypted volume or snapshot, which means that a volume restored from an encrypted
snapshot, or a copy of an encrypted snapshot, is always encrypted.
Although there is no direct way to encrypt an existing unencrypted volume or snapshot, you can encrypt
existing unencrypted data by using either the CreateVolume or CopySnapshot action. If you have
enabled encryption by default, AWS enforces encryption of the resulting new volume or snapshot
using your default CMK. Even if you have not enabled encryption by default, you can supply encryption
parameters with CreateVolume or CopySnapshot to encrypt resources individually. In either case, you
can override encryption defaults to apply a customer managed CMK. All of the actions shown can be
performed with the EC2 console, AWS CLI, or AWS API. For more information, see Creating an Amazon
EBS Volume (p. 847) and Copying an Amazon EBS Snapshot (p. 874).
907
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Data Services
To encrypt the snapshot copy to a customer managed CMK, you must supply both the Encrypted
and KmsKeyId parameters as shown in Copy an Unencrypted Snapshot (Encryption by Default Not
Enabled) (p. 909).
You can also apply new encryption states when launching an instance from an EBS-backed AMI. This is
because EBS-backed AMIs include snapshots of EBS volumes that can be manipulated as described. For
more information about encryption options while launching an instance from an EBS-backed AMI, see
Using Encryption with EBS-Backed AMIs (p. 149).
Examples
• Restore an Unencrypted Volume (Encryption by Default Not Enabled) (p. 908)
• Restore an Unencrypted Volume (Encryption by Default Enabled) (p. 908)
• Copy an Unencrypted Snapshot (Encryption by Default Not Enabled) (p. 909)
• Copy an Unencrypted Snapshot (Encryption by Default Enabled) (p. 909)
• Re-Encrypt an Encrypted Volume (p. 910)
• Re-Encrypt an Encrypted Snapshot (p. 910)
• Migrate Data between Encrypted and Unencrypted Volumes (p. 911)
Without encryption by default enabled, a volume restored from an unencrypted snapshot is unencrypted
by default. However, you can encrypt the resulting volume by setting the Encrypted parameter and,
optionally, the KmsKeyId parameter. The following diagram illustrates the process.
If you leave out the KmsKeyId parameter, the resulting volume is encrypted your default CMK. You must
supply a key ID to encrypt the volume to a different CMK.
For more information, see Restoring an Amazon EBS Volume from a Snapshot (p. 848).
When you have enabled encryption by default, encryption is mandatory for volumes restored from
unencrypted snapshots, and no encryption parameters are required for your default CMK to be used. The
following diagram shows this simple default case:
908
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Data Services
If you want to encrypt the restored volume to a customer managed CMK, you must supply both the
Encrypted and KmsKeyId parameters as shown in Restore an Unencrypted Volume (Encryption by
Default Not Enabled) (p. 908).
Note
If you copy a snapshot and encrypt it to a new CMK, a complete (non-incremental) copy is
always created, resulting in additional delay and storage costs.
You can encrypt an EBS volume by copying an unexpected snapshot to an encrypted snapshot and then
creating a volume from the encrypted snapshot. For more information, see Copying an Amazon EBS
Snapshot (p. 874).
When you have enabled encryption by default, encryption is mandatory for copies of unencrypted
snapshots, and no encryption parameters are required if your default CMK is used. The following
diagram illustrates this default case:
909
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Data Services
Note
If you copy a snapshot and encrypt it to a new CMK, a complete (non-incremental) copy is
always created, resulting in additional delay and storage costs.
When the CreateVolume action operates on an encrypted snapshot, you have the option of re-
encrypting it with a different CMK. The following diagram illustrates the process. You own two CMKs,
CMK A and CMK B. The source snapshot is encrypted by CMK A. During volume creation, with the key ID
of CMK B supplied as a parameter, the source data is automatically decrypted, then re-encrypted by CMK
B.
Note
If you copy a snapshot and encrypt it to a new CMK, a complete (non-incremental) copy is
always created, resulting in additional delay and storage costs.
For more information, see Restoring an Amazon EBS Volume from a Snapshot (p. 848).
The ability to encrypt a snapshot during copying allows you to apply a new CMK to an already-encrypted
snapshot that you own. Volumes restored from the resulting copy are only accessible using the new
CMK. The following diagram illustrates the process. You own two CMKs, CMK A and CMK B. The source
snapshot is encrypted by CMK A. During copy, with the key ID of CMK B supplied as a parameter, the
source data is automatically re-encrypted by CMK B.
910
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Data Services
Note
If you copy a snapshot and encrypt it to a new CMK, a complete (non-incremental) copy is
always created, resulting in additional delay and storage costs.
In a related scenario, you can choose to apply new encryption parameters to a copy of a snapshot that
has been shared with you. By default, the copy is encrypted with a CMK shared by the snapshot's owner.
However, we recommend that you create a copy of the shared snapshot using a different CMK that you
control. This protects your access to the volume if the original CMK is compromised, or if the owner
revokes the CMK for any reason. For more information, see Encryption and Snapshot Copying (p. 875).
For example, use the rsync command to copy the data. In the following command, the source data is
located in /mnt/source and the destination volume is mounted at /mnt/destination.
Setting Encryption and Key Defaults Using the API and CLI
You can manage encryption by default and the default customer master key (CMK) using the following
API actions and CLI commands.
911
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes and NVMe
Contents
• Install or Upgrade the NVMe Driver (p. 912)
• Identifying the EBS Device (p. 913)
• Working with NVMe EBS Volumes (p. 914)
• I/O Operation Timeout (p. 914)
• Amazon Linux 2
• Amazon Linux AMI 2018.03
• Ubuntu 14.04 or later
• Red Hat Enterprise Linux 7.4 or later
• SUSE Linux Enterprise Server 12 SP2 or later
• CentOS 7 or later
• FreeBSD 11.1 or later
For more information about NVMe drivers on Windows instances, see Amazon EBS and NVMe on
Windows Instances in the Amazon EC2 User Guide for Windows Instances.
If you are using an AMI that does not include the NVMe driver, you can install the driver on your instance
using the following procedure.
912
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes and NVMe
• For Amazon Linux 2, Amazon Linux, CentOS, and Red Hat Enterprise Linux:
3. Ubuntu 16.04 and later include the linux-aws package, which contains the NVMe and ENA drivers
required by Nitro-based instances. Upgrade the linux-aws package to receive the latest version as
follows:
For Ubuntu 14.04, you can install the latest linux-aws package as follows:
sudo reboot
We recommend that you use stable identifiers for your EBS volumes within your instance, such as one of
the following:
• For Nitro-based instances, the block device mappings that are specified in the Amazon EC2 console
when you are attaching an EBS volume or during AttachVolume or RunInstances API calls are
captured in the vendor-specific data field of the NVMe controller identification. With Amazon Linux
AMIs later than version 2017.09.01, we provide a udev rule that reads this data and creates a symbolic
link to the block-device mapping.
• NVMe-attached EBS volumes have the EBS volume ID set as the serial number in the device
identification.
• When a device is formatted, a UUID is generated that persists for the life of the filesystem. A device
label can be specified at the same time. For more information, see Making an Amazon EBS Volume
Available for Use on Linux (p. 852) and Booting from the Wrong Volume (p. 1054).
With Amazon Linux AMI 2017.09.01 or later (including Amazon Linux 2), you can run the ebsnvme-id
command as follows to map the NVMe device name to a volume ID and device name:
913
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Volumes and NVMe
Amazon Linux also creates a symbolic link from the device name in the block device mapping (for
example, /dev/sdf), to the NVMe device name.
With a kernel version of 4.2 or later, you can run the nvme id-ctrl command as follows to map an NVMe
device to a volume ID. First, install the NVMe command line package, nvme-cli, using the package
management tools for your Linux distribution.
The following example gets the volume ID and device name. The device name is available through the
NVMe controller vendor-specific extension (bytes 384:4095 of the controller identification):
The lsblk command lists available devices and their mount points (if applicable). This helps you
determine the correct device name to use. In this example, /dev/nvme0n1p1 is mounted as the root
device and /dev/nvme1n1 is attached but not mounted.
If you are using Linux kernel 4.2 or later, any change you make to the volume size of an NVMe EBS
volume is automatically reflected in the instance. For older Linux kernels, you might need to detach and
attach the EBS volume or reboot the instance for the size change to be reflected. With Linux kernel 3.19
or later, you can use the hdparm command as follows to force a rescan of the NVMe device:
When you detach an NVMe EBS volume, the instance does not have an opportunity to flush the file
system caches or metadata before detaching the volume. Therefore, before you detach an NVMe EBS
volume, you should first sync and unmount it. If the volume fails to detach, you can attempt a force-
detach command as described in Detaching an Amazon EBS Volume from an Instance (p. 864).
914
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Optimization
latency exceeds the value of this parameter, the Linux NVMe driver fails the I/O and return an error to
the filesystem or application. Depending on the I/O operation, your filesystem or application can retry
the error. In some cases, your filesystem may be remounted as read-only.
For an experience similar to EBS volumes attached to Xen instances, we recommend setting
nvme.io_timeout to the highest value possible. For current kernels, the maximum is 4294967295,
while for earlier kernels the maximum is 255. Depending on the version of Linux, the timeout might
already be set to the supported maximum value. For example, the timeout is set to 4294967295 by
default for Amazon Linux AMI 2017.09.01 and later.
You can verify the maximum value for your Linux distribution by writing a value higher than the
suggested maximum to /sys/module/nvme_core/parameters/io_timeout and checking for the
Numerical result out of range error when attempting to save the file.
EBS–optimized instances deliver dedicated bandwidth to Amazon EBS, with options between 425
Mbps and 14,000 Mbps, depending on the instance type you use. When attached to an EBS–optimized
instance, General Purpose SSD (gp2) volumes are designed to deliver within 10% of their baseline
and burst performance 99% of the time in a given year, and Provisioned IOPS SSD (io1) volumes are
designed to deliver within 10% of their provisioned performance 99.9% of the time in a given year. Both
Throughput Optimized HDD (st1) and Cold HDD (sc1) guarantee performance consistency of 90% of
burst throughput 99% of the time in a given year. Non-compliant periods are approximately uniformly
distributed, targeting 99% of expected total throughput each hour. For more information, see Amazon
EBS Volume Types (p. 832).
Contents
• Instance Types that Support EBS Optimization (p. 915)
• Enabling Amazon EBS Optimization at Launch (p. 924)
• Modifying Amazon EBS Optimization for a Running Instance (p. 925)
For instance types that are EBS–optimized by default, there is no need to enable EBS optimization
and no effect if you disable EBS optimization. For instances that are not EBS–optimized by default,
you can enable EBS optimization when you launch the instances, or enable EBS optimization after the
instances are running. Instances must have EBS optimization enabled to achieve the level of performance
described in the table below.
When you enable EBS optimization for an instance that is not EBS-optimized by default, you pay
an additional low, hourly fee for the dedicated capacity. For pricing information, see EBS-optimized
Instances on the Amazon EC2 Pricing page for On-Demand instances.
The i2.8xlarge, c3.8xlarge, and r3.8xlarge instances do not have dedicated EBS bandwidth and
therefore do not offer EBS optimization. On these instances, network traffic and Amazon EBS traffic
share the same 10-gigabit network interface.
915
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Optimization
916
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Optimization
917
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Optimization
918
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Optimization
919
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Optimization
920
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Optimization
* These instance types can support maximum performance for 30 minutes at least once every 24 hours.
For example, c5.large instances can deliver 437.5 MB/s for 30 minutes at least once every 24 hours. If
you have a workload that requires sustained maximum performance for longer than 30 minutes, select
an instance type according to baseline performance as shown in the following table:
921
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Optimization
922
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Optimization
t3.nano 32 4 250
t3.micro 64 8 500
t3a.nano 32 4 250
t3a.micro 64 8 500
The EBSIOBalance% and EBSByteBalance% metrics can help you determine if your instances are sized
correctly. You can view these metrics in the CloudWatch console and set an alarm that is triggered based
on a threshold you specify. These metrics are expressed as a percentage. Instances with a consistently
low balance percentage are candidates for upsizing. Instances where the balance percentage never drops
below 100% are candidates for downsizing. For more information, see Monitoring Your Instances Using
CloudWatch (p. 558).
923
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Optimization
To enable Amazon EBS optimization when launching an instance using the console
924
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Performance
To enable EBS optimization when launching an instance using the command line
You can use one of the following options with the corresponding command. For more information about
these command line interfaces, see Accessing Amazon EC2 (p. 3).
To enable EBS optimization for a running instance using the command line
You can use one of the following options with the corresponding command. For more information about
these command line interfaces, see Accessing Amazon EC2 (p. 3).
925
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Performance
workload, in addition to benchmarking, to determine your optimal configuration. After you learn the
basics of working with EBS volumes, it's a good idea to look at the I/O performance you require and at
your options for increasing Amazon EBS performance to meet those requirements.
Note
AWS updates to the performance of EBS volume types may not immediately take effect on your
existing volumes. To see full performance on an older volume, you may first need to perform a
ModifyVolume action on it. For more information, see Modifying the Size, IOPS, or Type of an
EBS Volume on Linux.
Contents
• Amazon EBS Performance Tips (p. 926)
• Amazon EC2 Instance Configuration (p. 928)
• I/O Characteristics and Monitoring (p. 929)
• Initializing Amazon EBS Volumes (p. 931)
• RAID Configuration on Linux (p. 933)
• Benchmark EBS Volumes (p. 937)
926
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Performance
more throughput than the instance can support, the performance penalty encountered while initializing
volumes restored from a snapshot, and excessive amounts of small, random I/O on the volume. For more
information about calculating throughput for HDD volumes, see Amazon EBS Volume Types (p. 832).
Your performance can also be impacted if your application isn’t sending enough I/O requests. This can
be monitored by looking at your volume’s queue length and I/O size. The queue length is the number
of pending I/O requests from your application to your volume. For maximum consistency, HDD-backed
volumes must maintain a queue length (rounded to the nearest whole number) of 4 or more when
performing 1 MiB sequential I/O. For more information about ensuring consistent performance of your
volumes, see I/O Characteristics and Monitoring (p. 929)
To examine the current value of read-ahead for your block devices, use the following command:
The device shown reports a read-ahead value of 256 (the default). Multiply this number by the sector
size (512 bytes) to obtain the size of the read-ahead buffer, which in this case is 128 KiB. To set the
buffer value to 1 MiB, use the following command:
Verify that the read-ahead setting now displays 2,048 by running the first command again.
Only use this setting when your workload consists of large, sequential I/Os. If it consists mostly of small,
random I/Os, this setting will actually degrade your performance. In general, if your workload consists
mostly of small or random I/Os, you should consider using a General Purpose SSD (gp2) volume rather
than st1 or sc1.
For example, in an Amazon Linux AMI with an earlier kernel, you can add it to the end of the kernel line
in the GRUB configuration found in /boot/grub/menu.lst:
927
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Performance
For more information, see Configuring GRUB (p. 174). Other Linux distributions, especially those that do
not use the GRUB boot loader, may require a different approach to adjusting the kernel parameters.
For more information about EBS I/O characteristics, see the Amazon EBS: Designing for Performance
re:Invent presentation on this topic.
928
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Performance
the approximate I/O bandwidth available on that connection, see Instance Types that Support EBS
Optimization (p. 915).
Be sure to choose an EBS-optimized instance that provides more dedicated EBS throughput than your
application needs; otherwise, the Amazon EBS to Amazon EC2 connection becomes a performance
bottleneck.
Note that some instances with 10-gigabit network interfaces do not offer EBS-optimization, and
therefore do not have dedicated EBS bandwidth available. However, you can use all of that bandwidth
for traffic to Amazon EBS if your application isn’t pushing other network traffic that contends with
Amazon EBS. Some 10-gigabit network instances offer dedicated Amazon EBS bandwidth in addition to
a 10-gigabit interface which is used exclusively for network traffic.
If an instance type has a maximum 16 KB IOPS value of 4,000, that value is an absolute best-case
scenario and is not guaranteed unless the instance is launched as EBS-optimized. To consistently achieve
the best performance, you must launch instances as EBS-optimized. However, if you attach a 4,000 IOPS
io1 volume to an EBS-optimized instance with a 16 KB IOPS value of 4,000, the Amazon EC2 to Amazon
EBS connection bandwidth limit prevents this volume from providing the 500 MB/s maximum aggregate
throughput available to it. In this case, we must use an EBS-optimized EC2 instance that supports at least
500 MB/s of throughput.
Volumes of type General Purpose SSD (gp2) have a throughput limit between 128 MiB/s and 250 MiB/s
per volume (depending on volume size), which pairs well with a 1,000 Mbps EBS-optimized connection.
Instance types that offer more than 1,000 Mbps of throughput to Amazon EBS can use more than one
gp2 volume to take advantage of the available throughput. Volumes of type Provisioned IOPS SSD (io1)
have a throughput limit range of 256 KiB for each IOPS provisioned, up to a maximum of 1,000 MiB/s (at
64,000 IOPS). For more information, see Amazon EBS Volume Types (p. 832).
Note
These performance values for io1 are guaranteed only for volumes attached to Nitro-based
instances. For other instances, AWS guarantees performance up to 500 MiB/s and 32,000 IOPS
per volume. For more information, see Amazon EBS Volume Types (p. 832).
Instance types with 10 Gigabit network connectivity support up to 800 MB/s of throughput and 48,000
16K IOPS for unencrypted Amazon EBS volumes and up to 25,000 16K IOPS for encrypted Amazon EBS
volumes. Because the maximum io1 value for EBS volumes is 64,000 for io1 volumes and 16,000 for
gp2 volumes, you can use several EBS volumes simultaneously to reach the level of I/O performance
available to these instance types. For more information about which instance types include 10 Gigabit
network connectivity, see Amazon EC2 Instance Types.
You should use EBS-optimized instances when available to get the full performance benefits of Amazon
EBS gp2 and io1 volumes. For more information, see Amazon EBS–Optimized Instances (p. 915).
IOPS
IOPS are a unit of measure representing input/output operations per second. The operations are
measured in KiB, and the underlying drive technology determines the maximum amount of data that a
929
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Performance
volume type counts as a single I/O. I/O size is capped at 256 KiB for SSD volumes and 1,024 KiB for HDD
volumes because SSD volumes handle small or random I/O much more efficiently than HDD volumes.
When small I/O operations (larger than or equal to 32KiB) are physically contiguous, Amazon EBS
attempts to merge them into a single I/O operation up to the maximum size. For example, for SSD
volumes, a single 1,024 KiB I/O operation counts as 4 operations (1,024÷256=4), while 8 contiguous I/O
operations at 32 KiB each count as 1 operation (8×32=256). However, 8 random I/O operations at 32 KiB
each count as 8 operations. Each I/O operation under 32 KiB counts as 1 operation.
Similarly, for HDD-backed volumes, both a single 1,024 KiB I/O operation and 8 sequential 128 KiB
operations would count as one operation. However, 8 random 128 KiB I/O operations would count as 8
operations.
Consequently, when you create an SSD-backed volume supporting 3,000 IOPS (either by provisioning an
io1 volume at 3,000 IOPS or by sizing a gp2 volume at 1000 GiB), and you attach it to an EBS-optimized
instance that can provide sufficient bandwidth, you can transfer up to 3,000 I/Os of data per second,
with throughput determined by I/O size.
The volume queue length is the number of pending I/O requests for a device. Latency is the true end-to-
end client time of an I/O operation, in other words, the time elapsed between sending an I/O to EBS and
receiving an acknowledgement from EBS that the I/O read or write is complete. Queue length must be
correctly calibrated with I/O size and latency to avoid creating bottlenecks either on the guest operating
system or on the network link to EBS.
Optimal queue length varies for each workload, depending on your particular application's sensitivity to
IOPS and latency. If your workload is not delivering enough I/O requests to fully use the performance
available to your EBS volume, then your volume might not deliver the IOPS or throughput that you have
provisioned.
Transaction-intensive applications are sensitive to increased I/O latency and are well-suited for SSD-
backed io1 and gp2 volumes. You can maintain high IOPS while keeping latency down by maintaining a
low queue length and a high number of IOPS available to the volume. Consistently driving more IOPS to
a volume than it has available can cause increased I/O latency.
Throughput-intensive applications are less sensitive to increased I/O latency, and are well-suited for
HDD-backed st1 and sc1 volumes. You can maintain high throughput to HDD-backed volumes by
maintaining a high queue length when performing large, sequential I/O.
For SSD-backed volumes, if your I/O size is very large, you may experience a smaller number of IOPS
than you provisioned because you are hitting the throughput limit of the volume. For example, a gp2
volume under 1000 GiB with burst credits available has an IOPS limit of 3,000 and a volume throughput
limit of 250 MiB/s. If you are using a 256 KiB I/O size, your volume reaches its throughput limit at 1000
IOPS (1000 x 256 KiB = 250 MiB). For smaller I/O sizes (such as 16 KiB), this same volume can sustain
3,000 IOPS because the throughput is well below 250 MiB/s. (These examples assume that your volume's
I/O is not hitting the throughput limits of the instance.) For more information about the throughput
limits for each EBS volume type, see Amazon EBS Volume Types (p. 832).
For smaller I/O operations, you may see a higher-than-provisioned IOPS value as measured from inside
your instance. This happens when the instance operating system merges small I/O operations into a
larger operation before passing them to Amazon EBS.
If your workload uses sequential I/Os on HDD-backed st1 and sc1 volumes, you may experience a
higher than expected number of IOPS as measured from inside your instance. This happens when the
instance operating system merges sequential I/Os and counts them in 1,024 KiB-sized units. If your
930
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Performance
workload uses small or random I/Os, you may experience a lower throughput than you expect. This is
because we count each random, non-sequential I/O toward the total IOPS count, which can cause you to
hit the volume's IOPS limit sooner than expected.
Whatever your EBS volume type, if you are not experiencing the IOPS or throughput you expect in your
configuration, ensure that your EC2 instance bandwidth is not the limiting factor. You should always use
a current-generation, EBS-optimized instance (or one that includes 10 Gb/s network connectivity) for
optimal performance. For more information, see Amazon EC2 Instance Configuration (p. 928). Another
possible cause for not experiencing the expected IOPS is that you are not driving enough I/O to the EBS
volumes.
You can monitor these I/O characteristics with each volume's CloudWatch metrics (p. 856). Important
metrics to consider include:
• BurstBalance
• VolumeReadBytes
• VolumeWriteBytes
• VolumeReadOps
• VolumeWriteOps
• VolumeQueueLength
BurstBalance displays the burst bucket balance for gp2, st1, and sc1 volumes as a percentage of
the remaining balance. When your burst bucket is depleted, volume I/O (for gp2 volumes) or volume
throughput (for st1 and sc1 volumes) is throttled to the baseline. Check the BurstBalance value to
determine whether your volume is being throttled for this reason.
HDD-backed st1 and sc1 volumes are designed to perform best with workloads that take
advantage of the 1,024 KiB maximum I/O size. To determine your volume's average I/O size, divide
VolumeWriteBytes by VolumeWriteOps. The same calculation applies to read operations. If average
I/O size is below 64 KiB, increasing the size of the I/O operations sent to an st1 or sc1 volume should
improve performance.
Note
If average I/O size is at or near 44 KiB, you may be using an instance or kernel without support
for indirect descriptors. Any Linux kernel 3.8 and above has this support, as well as any current-
generation instance.
If your I/O latency is higher than you require, check VolumeQueueLength to make sure your application
is not trying to drive more IOPS than you have provisioned. If your application requires a greater number
of IOPS than your volume can provide, you should consider using a larger gp2 volume with a higher base
performance level or an io1 volume with more provisioned IOPS to achieve faster latencies.
For more information about Amazon EBS I/O characteristics, see the Amazon EBS: Designing for
Performance re:Invent presentation on this topic.
However, storage blocks on volumes that were restored from snapshots must be pulled down from
Amazon S3 and written to the volume before they can be accessed. This preliminary action takes time
and can significantly increase the latency of I/O operations. For most applications, amortizing this cost
over the lifetime of the volume is acceptable. The volume's performance is restored after all of the blocks
931
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Performance
have been downloaded and written to the volume. To avoid this initial performance hit in a production
environment, you can perform an initialization to read all of the blocks on the volume before you use it.
Important
While initializing io1 volumes that were restored from snapshots, the performance of the
volume may drop below 50 percent of its expected level, which causes the volume to display a
warning state in the I/O Performance status check. This is expected, and you can ignore the
warning state on io1 volumes while you are initializing them. For more information, see EBS
Volume Status Checks (p. 856).
Here you can see that the new volume, /dev/xvdf, is attached, but not mounted (because there is
no path listed under the MOUNTPOINT column).
3. Use the dd or fio utilities to read all of the blocks on the device. The dd command is installed by
default on Linux systems, but fio is considerably faster because it allows multi-threaded reads.
Note
This step may take several minutes up to several hours, depending on your EC2 instance
bandwidth, the IOPS provisioned for the volume, and the size of the volume.
[dd] The if (input file) parameter should be set to the drive you wish to initialize. The of (output
file) parameter should be set to the Linux null virtual device, /dev/null. The bs parameter sets the
block size of the read operation; for optimal performance, this should be set to 1 MB.
Important
Incorrect use of dd can easily destroy a volume's data. Be sure to follow precisely the
example command below. Only the if=/dev/xvdf parameter will vary depending on the
name of the device you are reading.
[fio] If you have fio installed on your system, use the following command to initialize your volume.
The --filename (input file) parameter should be set to the drive you wish to initialize.
932
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Performance
When the operation is finished, you will see a report of the read operation. Your volume is now
ready for use. For more information, see Making an Amazon EBS Volume Available for Use on
Linux (p. 852).
Amazon EBS volume data is replicated across multiple servers in an Availability Zone to prevent the loss
of data from the failure of any single component. This replication makes Amazon EBS volumes ten times
more reliable than typical commodity disk drives. For more information, see Amazon EBS Availability and
Durability in the Amazon EBS product detail pages.
Note
You should avoid booting from a RAID volume. Grub is typically installed on only one device in
a RAID array, and if one of the mirrored devices fails, you may be unable to boot the operating
system.
If you need to create a RAID array on a Windows instance, see RAID Configuration on Windows in the
Amazon EC2 User Guide for Windows Instances.
Contents
• RAID Configuration Options (p. 933)
• Creating a RAID Array on Linux (p. 934)
• Creating Snapshots of Volumes in a RAID Array (p. 937)
RAID 0 When I/O performance is I/O is distributed across Performance of the stripe
more important than fault the volumes in a stripe. If is limited to the worst
tolerance; for example, as you add a volume, you get performing volume in the
in a heavily used database the straight addition of set. Loss of a single volume
(where data replication is throughput. results in a complete data
already set up separately). loss for the array.
RAID 1 When fault tolerance is Safer from the standpoint Does not provide a write
more important than I/O of data durability. performance improvement;
performance; for example, requires more Amazon
as in a critical application. EC2 to Amazon EBS
bandwidth than non-RAID
configurations because the
933
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Performance
Important
RAID 5 and RAID 6 are not recommended for Amazon EBS because the parity write operations
of these RAID modes consume some of the IOPS available to your volumes. Depending on the
configuration of your RAID array, these RAID modes provide 20-30% fewer usable IOPS than
a RAID 0 configuration. Increased cost is a factor with these RAID modes as well; when using
identical volume sizes and speeds, a 2-volume RAID 0 array can outperform a 4-volume RAID 6
array that costs twice as much.
Creating a RAID 0 array allows you to achieve a higher level of performance for a file system than you
can provision on a single Amazon EBS volume. A RAID 1 array offers a "mirror" of your data for extra
redundancy. Before you perform this procedure, you need to decide how large your RAID array should be
and how many IOPS you want to provision.
The resulting size of a RAID 0 array is the sum of the sizes of the volumes within it, and the bandwidth
is the sum of the available bandwidth of the volumes within it. The resulting size and bandwidth of a
RAID 1 array is equal to the size and bandwidth of the volumes in the array. For example, two 500 GiB
Amazon EBS io1 volumes with 4,000 provisioned IOPS each will create a 1000 GiB RAID 0 array with
an available bandwidth of 8,000 IOPS and 1,000 MB/s of throughput or a 500 GiB RAID 1 array with an
available bandwidth of 4,000 IOPS and 500 MB/s of throughput.
This documentation provides basic RAID setup examples. For more information about RAID
configuration, performance, and recovery, see the Linux RAID Wiki at https://raid.wiki.kernel.org/
index.php/Linux_Raid.
1. Create the Amazon EBS volumes for your array. For more information, see Creating an Amazon EBS
Volume (p. 847).
Important
Create volumes with identical size and IOPS performance values for your array. Make sure
you do not create an array that exceeds the available bandwidth of your EC2 instance. For
more information, see Amazon EC2 Instance Configuration (p. 928).
2. Attach the Amazon EBS volumes to the instance that you want to host the array. For more
information, see Attaching an Amazon EBS Volume to an Instance (p. 851).
3. Use the mdadm command to create a logical RAID device from the newly attached Amazon EBS
volumes. Substitute the number of volumes in your array for number_of_volumes and the device
names for each volume in the array (such as /dev/xvdf) for device_name. You can also substitute
MY_RAID with your own unique name for the array.
Note
You can list the devices on your instance with the lsblk command to find the device names.
(RAID 0 only) To create a RAID 0 array, execute the following command (note the --level=0 option
to stripe the array):
[ec2-user ~]$ sudo mdadm --create --verbose /dev/md0 --level=0 --name=MY_RAID --raid-
devices=number_of_volumes device_name1 device_name2
934
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Performance
(RAID 1 only) To create a RAID 1 array, execute the following command (note the --level=1 option
to mirror the array):
[ec2-user ~]$ sudo mdadm --create --verbose /dev/md0 --level=1 --name=MY_RAID --raid-
devices=number_of_volumes device_name1 device_name2
4. Allow time for the RAID array to initialize and synchronize. You can track the progress of these
operations with the following command:
Personalities : [raid1]
md0 : active raid1 xvdg[1] xvdf[0]
20955008 blocks super 1.2 [2/2] [UU]
[=========>...........] resync = 46.8% (9826112/20955008) finish=2.9min
speed=63016K/sec
In general, you can display detailed information about your RAID array with the following command:
/dev/md0:
Version : 1.2
Creation Time : Mon Jun 27 11:31:28 2016
Raid Level : raid1
Array Size : 20955008 (19.98 GiB 21.46 GB)
Used Dev Size : 20955008 (19.98 GiB 21.46 GB)
Raid Devices : 2
Total Devices : 2
Persistence : Superblock is persistent
5. Create a file system on your RAID array, and give that file system a label to use when you mount
it later. For example, to create an ext4 file system with the label MY_RAID, execute the following
command:
Depending on the requirements of your application or the limitations of your operating system, you
can use a different file system type, such as ext3 or XFS (consult your file system documentation for
the corresponding file system creation command).
6. To ensure that the RAID array is reassembled automatically on boot, create a configuration file to
contain the RAID information:
935
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Performance
Note
If you are using a Linux distribution other than Amazon Linux, this file may need to be
placed in different location. For more information, consult man mdadm.conf on your Linux
system..
7. Create a new ramdisk image to properly preload the block device modules for your new RAID
configuration:
9. Finally, mount the RAID device on the mount point that you created:
a. Create a backup of your /etc/fstab file that you can use if you accidentally destroy or delete
this file while you are editing it.
b. Open the /etc/fstab file using your favorite text editor, such as nano or vim.
c. Comment out any lines starting with "UUID=" and, at the end of the file, add a new line for your
RAID volume using the following format:
The last three fields on this line are the file system mount options, the dump frequency of the
file system, and the order of file system checks done at boot time. If you don't know what these
values should be, then use the values in the example below for them (defaults,nofail 0
2). For more information about /etc/fstab entries, see the fstab manual page (by entering
man fstab on the command line). For example, to mount the ext4 file system on the device with
the label MY_RAID at the mount point /mnt/raid, add the following entry to /etc/fstab.
Note
If you ever intend to boot your instance without this volume attached (for example,
so this volume could move back and forth between different instances), you should
add the nofail mount option that allows the instance to boot even if there are
errors in mounting the volume. Debian derivatives, such as Ubuntu, must also add the
nobootwait mount option.
d. After you've added the new entry to /etc/fstab, you need to check that your entry works.
Run the sudo mount -a command to mount all file systems in /etc/fstab.
936
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Performance
If the previous command does not produce an error, then your /etc/fstab file is OK and your
file system will mount automatically at the next boot. If the command does produce any errors,
examine the errors and try to correct your /etc/fstab.
Warning
Errors in the /etc/fstab file can render a system unbootable. Do not shut down a
system that has errors in the /etc/fstab file.
e. (Optional) If you are unsure how to correct /etc/fstab errors, you can always restore your
backup /etc/fstab file with the following command.
To create a consistent set of snapshots for your RAID array, stop applications from writing to the RAID
array and flush all caches to disk. To stop writes to the RAID array, you can take steps such as stopping
the applications, stopping the instance, or unmounting the RAID array. After you've stopped all I/O
activity, you can create the snapshots. When the snapshot has been initiated or the snapshot API returns
successfully, it is safe to resume all I/O activity.
When restoring the EBS volumes in a RAID array from a set of snapshots, stop all I/O activity as you did
when you created the snapshots and then restore the volumes from the snapshots.
Important
Some of the procedures result in the destruction of existing data on the EBS volumes you
benchmark. The benchmarking procedures are intended for use on volumes specially created for
testing purposes, not production volumes.
937
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Performance
with specifications depending on the instance type. For more information, see Amazon EBS–Optimized
Instances (p. 915).
To create an EBS-optimized instance, choose Launch as an EBS-Optimized instance when launching the
instance using the Amazon EC2 console, or specify --ebs-optimized when using the command line. Be
sure that you launch a current-generation instance that supports this option. For more information, see
Amazon EBS–Optimized Instances (p. 915).
For the example tests, we recommend that you create a RAID array with 6 volumes, which offers a high
level of performance. Because you are charged by gigabytes provisioned (and the number of provisioned
IOPS for io1 volumes), not the number of volumes, there is no additional cost for creating multiple,
smaller volumes and using them to create a stripe set. If you're using Oracle Orion to benchmark your
volumes, it can simulate striping the same way that Oracle ASM does, so we recommend that you let
Orion do the striping. If you are using a different benchmarking tool, you need to stripe the volumes
yourself.
To create a six-volume stripe set on Amazon Linux, use a command such as the following:
[ec2-user ~]$ sudo mdadm --create /dev/md0 --level=0 --chunk=64 --raid-devices=6 /dev/sdf /
dev/sdg /dev/sdh /dev/sdi /dev/sdj /dev/sdk
For this example, the file system is XFS. Use the file system that meets your requirements. Use the
following command to install XFS file system support:
Then, use these commands to create, mount, and assign ownership to the XFS file system:
AWS provides a JSON template for use with AWS CloudFormation that simplifies this setup procedure.
Access the template and save it as a JSON file. AWS CloudFormation allows you to configure your own
SSH keys and offers an easy way to set up a performance test environment to evaluate st1 volumes. The
template creates a current-generation instance and a 2 TiB st1 volume, and attaches the volume to the
instance at /dev/xvdf.
938
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Performance
Tool Description
Oracle Orion For calibrating the I/O performance of storage systems to be used with Oracle
Calibration Tool databases.
These benchmarking tools support a wide variety of test parameters. You should use commands that
approximate the workloads your volumes will support. These commands provided below are intended as
examples to help you get started.
To determine the optimal queue length for your workload on SSD-backed volumes, we recommend
that you target a queue length of 1 for every 1000 IOPS available (baseline for gp2 volumes and the
provisioned amount for io1 volumes). Then you can monitor your application performance and tune
that value based on your application requirements.
Increasing the queue length is beneficial until you achieve the provisioned IOPS, throughput or optimal
system queue length value, which is currently set to 32. For example, a volume with 3,000 provisioned
IOPS should target a queue length of 3. You should experiment with tuning these values up or down to
see what performs best for your application.
939
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Performance
Disable C-States
Before you run benchmarking, you should disable processor C-states. Temporarily idle cores in a
supported CPU can enter a C-state to save power. When the core is called on to resume processing, a
certain amount of time passes until the core is again fully operational. This latency can interfere with
processor benchmarking routines. For more information about C-states and which EC2 instance types
support them, see Processor State Control for Your EC2 Instance.
2. Disable the C-states from c1 to cN. Ideally, the cores should be in state c0.
Perform Benchmarking
The following procedures describe benchmarking commands for various EBS volume types.
Run the following commands on an EBS-optimized instance with attached EBS volumes. If the EBS
volumes were restored from snapshots, be sure to initialize them before benchmarking. For more
information, see Initializing Amazon EBS Volumes (p. 931).
When you are finished testing your volumes, see the following topics for help cleaning up: Deleting an
Amazon EBS Volume (p. 866) and Terminate Your Instance (p. 479).
For more information about interpreting the results, see this tutorial: Inspecting disk IO performance
with fio.
940
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS Performance
The following command performs 1 MiB sequential read operations against an attached st1 block
device (e.g., /dev/xvdf):
The following command performs 1 MiB sequential write operations against an attached st1 block
device:
Some workloads perform a mix of sequential reads and sequential writes to different parts of the block
device. To benchmark such a workload, we recommend that you use separate, simultaneous fio jobs for
reads and writes, and use the fio offset_increment option to target different block device locations
for each job.
Running this workload is a bit more complicated than a sequential-write or sequential-read workload.
Use a text editor to create a fio job file, called fio_rw_mix.cfg in this example, that contains the
following:
[global]
clocksource=clock_gettime
randrepeat=0
runtime=180
offset_increment=100g
[sequential-write]
bs=1M
ioengine=libaio
direct=1
iodepth=8
filename=/dev/<device>
do_verify=0
rw=write
rwmixread=0
rwmixwrite=100
[sequential-read]
bs=1M
ioengine=libaio
direct=1
iodepth=8
filename=/dev/<device>
do_verify=0
rw=read
rwmixread=100
rwmixwrite=0
941
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS CloudWatch Metrics
For more information about interpreting the results, see the Inspecting disk I/O performance with fio
tutorial.
Multiple fio jobs for direct I/O, even though using sequential read or write operations, can result in lower
than expected throughput for st1 and sc1 volumes. We recommend that you use one direct I/O job and
use the iodepth parameter to control the number of concurrent I/O operations.
The following table describes the types of monitoring data available for your Amazon EBS volumes.
Type Description
Detailed Provisioned IOPS SSD (io1) volumes automatically send one-minute metrics to
CloudWatch.
When you get data from CloudWatch, you can include a Period request parameter to specify the
granularity of the returned data. This is different than the period that we use when we collect the data
(5-minute periods). We recommend that you specify a period in your request that is equal to or larger
than the collection period to ensure that the returned data is valid.
You can get the data using either the CloudWatch API or the Amazon EC2 console. The console takes the
raw data from the CloudWatch API and displays a series of graphs based on the data. Depending on your
needs, you might prefer to use either the data from the API or the graphs in the console.
Some of these metrics have differences on Nitro-based instances. For a list of instance types based on
the Nitro system, see Nitro-based Instances (p. 181).
Volume Metrics
Metric Description
942
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS CloudWatch Metrics
Metric Description
The SampleCount statistic reports the total number of read
operations during the period, except on volumes attached to a
Nitro-based instance, where the sample count represents the
number of data points used in the statistical calculation. For Xen
instances, data is reported only when there is read activity on the
volume.
Units: Bytes
Units: Bytes
Units: Count
Units: Count
943
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS CloudWatch Metrics
Metric Description
VolumeTotalReadTime The total number of seconds spent by all read operations that
completed in a specified period of time. If multiple requests are
submitted at the same time, this total could be greater than the
length of the period. For example, for a period of 5 minutes (300
seconds): if 700 operations completed during that period, and
each operation took 1 second, the value would be 700 seconds.
For Xen instances, data is reported only when there is read
activity on the volume.
Units: Seconds
VolumeTotalWriteTime The total number of seconds spent by all write operations that
completed in a specified period of time. If multiple requests are
submitted at the same time, this total could be greater than the
length of the period. For example, for a period of 5 minutes (300
seconds): if 700 operations completed during that period, and
each operation took 1 second, the value would be 700 seconds.
For Xen instances, data is reported only when there is write
activity on the volume.
Units: Seconds
Units: Seconds
Units: Count
944
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS CloudWatch Metrics
Metric Description
VolumeThroughputPercentage Used with Provisioned IOPS SSD volumes only. The percentage
of I/O operations per second (IOPS) delivered of the total IOPS
provisioned for an Amazon EBS volume. Provisioned IOPS SSD
volumes deliver within 10 percent of the provisioned IOPS
performance 99.9 percent of the time over a given year.
Units: Percent
VolumeConsumedReadWriteOps Used with Provisioned IOPS SSD volumes only. The total amount
of read and write operations (normalized to 256K capacity units)
consumed in a specified period of time.
Units: Count
Units: Percent
945
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS CloudWatch Metrics
(Sum(VolumeReadBytes) / Sum(VolumeReadOps)) /
1024
(Sum(VolumeWriteBytes) / Sum(VolumeWriteOps)) /
1024
(Sum(VolumeTotalReadTime) / Sum(VolumeReadOps))
× 1000
(Sum(VolumeTotalWriteTime) /
Sum(VolumeWriteOps)) * 1000
946
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS CloudWatch Events
For the average latency graphs and average size graphs, the average is calculated over the total number
of operations (read or write, whichever is applicable to the graph) that completed during the period.
Events in CloudWatch are represented as JSON objects. The fields that are unique to the event are
contained in the "detail" section of the JSON object. The "event" field contains the event name. The
"result" field contains the completed status of the action that triggered the event. For more information,
see Event Patterns in CloudWatch Events in the Amazon CloudWatch Events User Guide.
For more information, see Using Events in the Amazon CloudWatch User Guide.
Contents
• EBS Volume Events (p. 947)
• EBS Snapshot Events (p. 950)
• EBS Volume Modification Events (p. 954)
• Using Amazon Lambda To Handle CloudWatch Events (p. 954)
Events
• Create Volume (createVolume) (p. 947)
• Delete Volume (deleteVolume) (p. 948)
• Volume Attach or Reattach (attachVolume, reattachVolume) (p. 949)
Event Data
The listing below is an example of a JSON object emitted by EBS for a successful createVolume event.
{
"version": "0",
"id": "01234567-0123-0123-0123-012345678901",
"detail-type": "EBS Volume Notification",
"source": "aws.ec2",
"account": "012345678901",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "us-east-1",
"resources": [
"arn:aws:ec2:us-east-1:012345678901:volume/vol-01234567"
],
"detail": {
"result": "available",
947
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS CloudWatch Events
"cause": "",
"event": "createVolume",
"request-id": "01234567-0123-0123-0123-0123456789ab"
}
}
The listing below is an example of a JSON object emitted by EBS after a failed createVolume event.
The cause for the failure was a disabled KMS key.
{
"version": "0",
"id": "01234567-0123-0123-0123-0123456789ab",
"detail-type": "EBS Volume Notification",
"source": "aws.ec2",
"account": "012345678901",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "sa-east-1",
"resources": [
"arn:aws:ec2:sa-east-1:0123456789ab:volume/vol-01234567",
],
"detail": {
"event": "createVolume",
"result": "failed",
"cause": "arn:aws:kms:sa-east-1:0123456789ab:key/01234567-0123-0123-0123-0123456789ab
is disabled.",
"request-id": "01234567-0123-0123-0123-0123456789ab",
}
}
The following is an example of a JSON object that is emitted by EBS after a failed createVolume event.
The cause for the failure was a KMS key pending import.
{
"version": "0",
"id": "01234567-0123-0123-0123-0123456789ab",
"detail-type": "EBS Volume Notification",
"source": "aws.ec2",
"account": "012345678901",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "sa-east-1",
"resources": [
"arn:aws:ec2:sa-east-1:0123456789ab:volume/vol-01234567",
],
"detail": {
"event": "createVolume",
"result": "failed",
"cause": "arn:aws:kms:sa-east-1:0123456789ab:key/01234567-0123-0123-0123-0123456789ab
is pending import.",
"request-id": "01234567-0123-0123-0123-0123456789ab",
}
}
Event Data
The listing below is an example of a JSON object emitted by EBS for a successful deleteVolume event.
948
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS CloudWatch Events
{
"version": "0",
"id": "01234567-0123-0123-0123-012345678901",
"detail-type": "EBS Volume Notification",
"source": "aws.ec2",
"account": "012345678901",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "us-east-1",
"resources": [
"arn:aws:ec2:us-east-1:012345678901:volume/vol-01234567"
],
"detail": {
"result": "deleted",
"cause": "",
"event": "deleteVolume",
"request-id": "01234567-0123-0123-0123-0123456789ab"
}
}
Event Data
The listing below is an example of a JSON object emitted by EBS after a failed attachVolume event.
The cause for the failure was a KMS key pending deletion.
Note
AWS may attempt to reattach to a volume following routine server maintenance.
{
"version": "0",
"id": "01234567-0123-0123-0123-0123456789ab",
"detail-type": "EBS Volume Notification",
"source": "aws.ec2",
"account": "012345678901",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "us-east-1",
"resources": [
"arn:aws:ec2:us-east-1:0123456789ab:volume/vol-01234567",
"arn:aws:kms:us-east-1:0123456789ab:key/01234567-0123-0123-0123-0123456789ab"
],
"detail": {
"event": "attachVolume",
"result": "failed",
"cause": "arn:aws:kms:us-east-1:0123456789ab:key/01234567-0123-0123-0123-0123456789ab
is pending deletion.",
"request-id": ""
}
}
The listing below is an example of a JSON object emitted by EBS after a failed reattachVolume event.
The cause for the failure was a KMS key pending deletion.
{
"version": "0",
"id": "01234567-0123-0123-0123-0123456789ab",
"detail-type": "EBS Volume Notification",
949
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS CloudWatch Events
"source": "aws.ec2",
"account": "012345678901",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "us-east-1",
"resources": [
"arn:aws:ec2:us-east-1:0123456789ab:volume/vol-01234567",
"arn:aws:kms:us-east-1:0123456789ab:key/01234567-0123-0123-0123-0123456789ab"
],
"detail": {
"event": "reattachVolume",
"result": "failed",
"cause": "arn:aws:kms:us-east-1:0123456789ab:key/01234567-0123-0123-0123-0123456789ab
is pending deletion.",
"request-id": ""
}
}
Events
• Create Snapshot (createSnapshot) (p. 950)
• Create Snapshots (createSnapshots) (p. 951)
• Copy Snapshot (copySnapshot) (p. 952)
• Share Snapshot (shareSnapshot) (p. 953)
Event Data
The listing below is an example of a JSON object emitted by EBS for a successful createSnapshot
event. In the detail section, the source field contains the ARN of the source volume. The StartTime
and EndTime fields indicate when creation of the snapshot started and completed.
{
"version": "0",
"id": "01234567-0123-0123-0123-012345678901",
"detail-type": "EBS Snapshot Notification",
"source": "aws.ec2",
"account": "012345678901",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "us-east-1",
"resources": [
"arn:aws:ec2:us-west-2::snapshot/snap-01234567"
],
"detail": {
"event": "createSnapshot",
"result": "succeeded",
"cause": "",
"request-id": "",
"snapshot_id": "arn:aws:ec2:us-west-2::snapshot/snap-01234567",
"source": "arn:aws:ec2:us-west-2::volume/vol-01234567",
"StartTime": "yyyy-mm-ddThh:mm:ssZ",
"EndTime": "yyyy-mm-ddThh:mm:ssZ" }
}
950
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS CloudWatch Events
Event Data
The listing below is an example of a JSON object emitted by EBS for a successful createSnapshots
event. In the detail section, the source field contains the ARNs of the source volumes of the multi-
volume snapshot set. The StartTime and EndTime fields indicate when creation of the snapshot
started and completed.
{
"version": "0",
"id": "01234567-0123-0123-0123-012345678901",
"detail-type": "EBS Multi-Volume Snapshots Completion Status",
"source": "aws.ec2",
"account": "012345678901",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "us-east-1",
"resources": [
"arn:aws:ec2::us-east-1:snapshot/snap-01234567",
"arn:aws:ec2::us-east-1:snapshot/snap-012345678"
],
"detail": {
"event": "createSnapshots",
"result": "succeeded",
"cause": "",
"request-id": "",
"startTime": "yyyy-mm-ddThh:mm:ssZ",
"endTime": "yyyy-mm-ddThh:mm:ssZ",
"snapshots": [
{
"snapshot_id": "arn:aws:ec2::us-east-1:snapshot/snap-01234567",
"source": "arn:aws:ec2::us-east-1:volume/vol-01234567",
"status": "completed"
},
{
"snapshot_id": "arn:aws:ec2::us-east-1:snapshot/snap-012345678",
"source": "arn:aws:ec2::us-east-1:volume/vol-012345678",
"status": "completed"
}
]
}
}
The listing below is an example of a JSON object emitted by EBS after a failed createSnapshots event.
The cause for the failure was one or more snapshots failed to complete. The values of snapshot_id are
the ARNs of the failed snapshots. StartTime and EndTime represent when the create-snapshots action
started and ended.
{
"version": "0",
"id": "01234567-0123-0123-0123-012345678901",
"detail-type": "EBS Multi-Volume Snapshots Completion Status",
"source": "aws.ec2",
"account": "012345678901",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "us-east-1",
"resources": [
"arn:aws:ec2::us-east-1:snapshot/snap-01234567",
"arn:aws:ec2::us-east-1:snapshot/snap-012345678"
951
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS CloudWatch Events
],
"detail": {
"event": "createSnapshots",
"result": "failed",
"cause": "Snapshot snap-01234567 is in status deleted",
"request-id": "",
"startTime": "yyyy-mm-ddThh:mm:ssZ",
"endTime": "yyyy-mm-ddThh:mm:ssZ",
"snapshots": [
{
"snapshot_id": "arn:aws:ec2::us-east-1:snapshot/snap-01234567",
"source": "arn:aws:ec2::us-east-1:volume/vol-01234567",
"status": "error"
},
{
"snapshot_id": "arn:aws:ec2::us-east-1:snapshot/snap-012345678",
"source": "arn:aws:ec2::us-east-1:volume/vol-012345678",
"status": "deleted"
}
]
}
}
Event Data
The listing below is an example of a JSON object emitted by EBS after a successful copySnapshot
event. The value of snapshot_id is the ARN of the newly created snapshot. In the detail section, the
value of source is the ARN of the source snapshot. StartTime and EndTime represent when the copy-
snapshot action started and ended.
{
"version": "0",
"id": "01234567-0123-0123-0123-012345678901",
"detail-type": "EBS Snapshot Notification",
"source": "aws.ec2",
"account": "123456789012",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "us-east-1",
"resources": [
"arn:aws:ec2:us-west-2::snapshot/snap-01234567"
],
"detail": {
"event": "copySnapshot",
"result": "succeeded",
"cause": "",
"request-id": "",
"snapshot_id": "arn:aws:ec2:us-west-2::snapshot/snap-01234567",
"source": "arn:aws:ec2:eu-west-1::snapshot/snap-76543210",
"StartTime": "yyyy-mm-ddThh:mm:ssZ",
"EndTime": "yyyy-mm-ddThh:mm:ssZ",
"Incremental": "True"
}
}
The listing below is an example of a JSON object emitted by EBS after a failed copySnapshot event.
The cause for the failure was an invalid source snapshot ID. The value of snapshot_id is the ARN of
952
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS CloudWatch Events
the failed snapshot. In the detail section, the value of source is the ARN of the source snapshot.
StartTime and EndTime represent when the copy-snapshot action started and ended.
{
"version": "0",
"id": "01234567-0123-0123-0123-012345678901",
"detail-type": "EBS Snapshot Notification",
"source": "aws.ec2",
"account": "123456789012",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "us-east-1",
"resources": [
"arn:aws:ec2:us-west-2::snapshot/snap-01234567"
],
"detail": {
"event": "copySnapshot",
"result": "failed",
"cause": "Source snapshot ID is not valid",
"request-id": "",
"snapshot_id": "arn:aws:ec2:us-west-2::snapshot/snap-01234567",
"source": "arn:aws:ec2:eu-west-1::snapshot/snap-76543210",
"StartTime": "yyyy-mm-ddThh:mm:ssZ",
"EndTime": "yyyy-mm-ddThh:mm:ssZ"
}
}
Event Data
The following is an example of a JSON object emitted by EBS after a completed shareSnapshot event.
In the detail section, the value of source is the AWS account number of the user that shared the
snapshot with you. StartTime and EndTime represent when the share-snapshot action started and
ended. The shareSnapshot event is emitted only when a private snapshot is shared with another user.
Sharing a public snapshot does not trigger the event.
{
"version": "0",
"id": "01234567-01234-0123-0123-012345678901",
"detail-type": "EBS Snapshot Notification",
"source": "aws.ec2",
"account": "012345678901",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "us-east-1",
"resources": [
"arn:aws:ec2:us-west-2::snapshot/snap-01234567"
],
"detail": {
"event": "shareSnapshot",
"result": "succeeded",
"cause": "",
"request-id": "",
"snapshot_id": "arn:aws:ec2:us-west-2::snapshot/snap-01234567",
"source": 012345678901,
"StartTime": "yyyy-mm-ddThh:mm:ssZ",
"EndTime": "yyyy-mm-ddThh:mm:ssZ"
}
}
953
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS CloudWatch Events
{
"version": "0",
"id": "01234567-0123-0123-0123-012345678901",
"detail-type": "EBS Volume Notification",
"source": "aws.ec2",
"account": "012345678901",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "us-east-1",
"resources": [
"arn:aws:ec2:us-east-1:012345678901:volume/vol-03a55cf56513fa1b6"
],
"detail": {
"result": "optimizing",
"cause": "",
"event": "modifyVolume",
"request-id": "01234567-0123-0123-0123-0123456789ab"
}
}
The following procedure uses the createSnapshot event to automatically copy a completed snapshot
to another region for disaster recovery.
1. Create an IAM policy, such as the one shown in the following example, to provide permissions to
execute a CopySnapshot action and write to the CloudWatch Events log. Assign the policy to the
IAM user that will handle the CloudWatch event.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents"
],
"Resource": "arn:aws:logs:*:*:*"
},
{
"Effect": "Allow",
"Action": [
"ec2:CopySnapshot"
],
"Resource": "*"
}
]
}
954
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EBS CloudWatch Events
2. Define a function in Lambda that will be available from the CloudWatch console. The sample
Lambda function below, written in Node.js, is invoked by CloudWatch when a matching
createSnapshot event is emitted by Amazon EBS (signifying that a snapshot was completed).
When invoked, the function copies the snapshot from us-east-2 to us-east-1.
// define variables
var destinationRegion = 'us-east-1';
var sourceRegion = 'us-east-2';
console.log ('Loading function');
//main function
exports.handler = (event, context, callback) => {
// Load EC2 class and update the configuration to use destination region to
initiate the snapshot.
AWS.config.update({region: destinationRegion});
var ec2 = new AWS.EC2();
To ensure that your Lambda function is available from the CloudWatch console, create it in the
region where the CloudWatch event will occur. For more information, see the AWS Lambda
Developer Guide.
3. Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.
4. Choose Events, Create rule, Select event source, and Amazon EBS Snapshots.
5. For Specific Event(s), choose createSnapshot and for Specific Result(s), choose succeeded.
6. For Rule target, find and choose the sample function that you previously created.
955
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Store
Your rule should now appear on the Rules tab. In the example shown, the event that you configured
should be emitted by EBS the next time you copy a snapshot.
An instance store consists of one or more instance store volumes exposed as block devices. The size of an
instance store as well as the number of devices available varies by instance type.
The virtual devices for instance store volumes are ephemeral[0-23]. Instance types that support one
instance store volume have ephemeral0. Instance types that support two instance store volumes have
ephemeral0 and ephemeral1, and so on.
Contents
• Instance Store Lifetime (p. 957)
• Instance Store Volumes (p. 957)
• Add Instance Store Volumes to Your EC2 Instance (p. 961)
• SSD Instance Store Volumes (p. 964)
• Instance Store Swap Volumes (p. 965)
• Optimizing Disk Performance for Instance Store Volumes (p. 968)
956
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Store Lifetime
The data in an instance store persists only during the lifetime of its associated instance. If an instance
reboots (intentionally or unintentionally), data in the instance store persists. However, data in the
instance store is lost under any of the following circumstances:
Therefore, do not rely on instance store for valuable, long-term data. Instead, use more durable data
storage, such as Amazon S3, Amazon EBS, or Amazon EFS.
When you stop or terminate an instance, every block of storage in the instance store is reset. Therefore,
your data cannot be accessed through the instance store of another instance.
If you create an AMI from an instance, the data on its instance store volumes isn't preserved and isn't
present on the instance store volumes of the instances that you launch from the AMI.
If you change the instance type, an instance store will not be attached to the new instance type. For
more information, see Changing the Instance Type (p. 250) .
Some instance types use NVMe or SATA-based solid state drives (SSD) to deliver high random I/O
performance. This is a good option when you need storage with very low latency, but you don't need the
data to persist when the instance terminates or you can take advantage of fault-tolerant architectures.
For more information, see SSD Instance Store Volumes (p. 964).
The following table provides the quantity, size, type, and performance optimizations of instance store
volumes available on each supported instance type. For a complete list of instance types, including EBS-
only types, see Amazon EC2 Instance Types.
957
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Store Volumes
g2.2xlarge 1 x 60 GB SSD ✔
958
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Store Volumes
m3.medium 1 x 4 GB SSD ✔
m3.large 1 x 32 GB SSD ✔
959
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Store Volumes
r3.large 1 x 32 GB SSD ✔
r3.xlarge 1 x 80 GB SSD ✔
960
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Add Instance Store Volumes
* Volumes attached to certain instances suffer a first-write penalty unless initialized. For more
information, see Optimizing Disk Performance for Instance Store Volumes (p. 968).
** For more information, see Instance Store Volume TRIM Support (p. 965).
† The c1.medium and m1.small instance types also include a 900 MB instance store swap volume,
which may not be automatically enabled at boot time. For more information, see Instance Store Swap
Volumes (p. 965).
A block device mapping always specifies the root volume for the instance. The root volume is either
an Amazon EBS volume or an instance store volume. For more information, see Storage for the Root
Device (p. 97). The root volume is mounted automatically. For instances with an instance store volume
for the root volume, the size of this volume varies by AMI, but the maximum size is 10 GB.
You can use a block device mapping to specify additional EBS volumes when you launch your instance, or
you can attach additional EBS volumes after your instance is running. For more information, see Amazon
EBS Volumes (p. 830).
You can specify the instance store volumes for your instance only when you launch an instance. You can't
attach instance store volumes to an instance after you've launched it.
961
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Add Instance Store Volumes
If you change the instance type, an instance store will not be attached to the new instance type. For
more information, see Changing the Instance Type (p. 250) .
The number and size of available instance store volumes for your instance varies by instance type. Some
instance types do not support instance store volumes. For more information about the instance store
volumes support by each instance type, see Instance Store Volumes (p. 957). If the instance type
you choose for your instance supports instance store volumes, you must add them to the block device
mapping for the instance when you launch it. After you launch the instance, you must ensure that the
instance store volumes for your instance are formatted and mounted before you can use them. The root
volume of an instance store-backed instance is mounted automatically.
Contents
• Adding Instance Store Volumes to an AMI (p. 962)
• Adding Instance Store Volumes to an Instance (p. 962)
• Making Instance Store Volumes Available on Your Instance (p. 963)
To add instance store volumes to an Amazon EBS-backed AMI using the console
962
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Add Instance Store Volumes
Important
For M3 instances, you might receive instance store volumes even if you do not specify them in
the block device mapping for the instance.
Important
For HS1 instances, no matter how many instance store volumes you specify in the block
device mapping of an AMI, the block device mapping for an instance launched from the AMI
automatically includes the maximum number of supported instance store volumes. You must
explicitly remove the instance store volumes that you don't want from the block device mapping
for the instance before you launch it.
To update the block device mapping for an instance using the console
To update the block device mapping for an instance using the command line
You can use one of the following options commands with the corresponding command. For more
information about these command line interfaces, see Accessing Amazon EC2 (p. 3).
Many instance store volumes are pre-formatted with the ext3 file system. SSD-based instance store
volumes that support TRIM instruction are not pre-formatted with any file system. However, you can
format volumes with the file system of your choice after you launch your instance. For more information,
see Instance Store Volume TRIM Support (p. 965). For Windows instances, the EC2Config service
reformats the instance store volumes with the NTFS file system.
You can confirm that the instance store devices are available from within the instance itself using
instance metadata. For more information, see Viewing the Instance Block Device Mapping for Instance
Store Volumes (p. 985).
For Windows instances, you can also view the instance store volumes using Windows Disk Management.
For more information, see Listing the Disks Using Windows Disk Management.
For Linux instances, you can view and mount the instance store volumes as described in the following
procedure.
963
Amazon Elastic Compute Cloud
User Guide for Linux Instances
SSD Instance Store Volumes
To ensure the best IOPS performance from your SSD instance store volumes on Linux, we recommend
that you use the most recent version of Amazon Linux, or another Linux AMI with a kernel version of 3.8
or later. If you do not use a Linux AMI with a kernel version of 3.8 or later, your instance won't achieve
the maximum IOPS performance available for these instance types.
Like other instance store volumes, you must map the SSD instance store volumes for your instance when
you launch it. The data on an SSD instance volume persists only for the life of its associated instance. For
more information, see Add Instance Store Volumes to Your EC2 Instance (p. 961).
• Amazon Linux 2
• Amazon Linux AMI 2018.03
• Ubuntu 14.04 or later
• Red Hat Enterprise Linux 7.4 or later
• SUSE Linux Enterprise Server 12 SP2 or later
• CentOS 7 or later
• FreeBSD 11.1 or later
After you connect to your instance, you can list the NVMe devices using the lspci command. The
following is example output for an i3.8xlarge instance, which supports four NVMe devices.
964
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Store Swap Volumes
If you are using a supported operating system but you do not see the NVMe devices, verify that the
NVMe module is loaded using the following command.
• Amazon Linux, Amazon Linux 2, Ubuntu 14/16, Red Hat Enterprise Linux, SUSE Linux Enterprise
Server, CentOS 7
• Ubuntu 18
The NVMe volumes are compliant with the NVMe 1.0e specification. You can use the NVMe commands
with your NVMe volumes. With Amazon Linux, you can install the nvme-cli package from the repo
using the yum install command. With other supported versions of Linux, you can download the nvme-
cli package if it's not available in the image.
The data on NVMe instance storage is encrypted using an XTS-AES-256 block cipher implemented in a
hardware module on the instance. The encryption keys are generated using the hardware module and
are unique to each NVMe instance storage device. All encryption keys are destroyed when the instance
is stopped or terminated and cannot be recovered. You cannot disable this encryption and you cannot
provide your own encryption key.
Instance store volumes that support TRIM are fully trimmed before they are allocated to your instance.
These volumes are not formatted with a file system when an instance launches, so you must format
them before they can be mounted and used. For faster access to these volumes, you should skip the
TRIM operation when you format them.
With instance store volumes that support TRIM, you can use the TRIM command to notify the SSD
controller when you no longer need data that you've written. This provides the controller with more
free space, which can reduce write amplification and increase performance. On Linux, use the fstrim
command to enable periodic TRIM.
965
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Store Swap Volumes
The c1.medium and m1.small instance types have a limited amount of physical memory to work with,
and they are given a 900 MiB swap volume at launch time to act as virtual memory for Linux AMIs.
Although the Linux kernel sees this swap space as a partition on the root device, it is actually a separate
instance store volume, regardless of your root device type.
Amazon Linux automatically enables and uses this swap space, but your AMI may require some
additional steps to recognize and use this swap space. To see if your instance is using swap space, you
can use the swapon -s command.
The above instance has a 900 MiB swap volume attached and enabled. If you don't see a swap volume
listed with this command, you may need to enable swap space for the device. Check your available disks
using the lsblk command.
Here, the swap volume xvda3 is available to the instance, but it is not enabled (notice that the
MOUNTPOINT field is empty). You can enable the swap volume with the swapon command.
Note
You must prepend /dev/ to the device name listed by lsblk. Your device may be named
differently, such as sda3, sde3, or xvde3. Use the device name for your system in the command
below.
Now the swap space should show up in lsblk and swapon -s output.
You also need to edit your /etc/fstab file so that this swap space is automatically enabled at every
system boot.
Append the following line to your /etc/fstab file (using the swap device name for your system):
Any instance store volume can be used as swap space. For example, the m3.medium instance type
includes a 4 GB SSD instance store volume that is appropriate for swap space. If your instance store
966
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Store Swap Volumes
volume is much larger (for example, 350 GB), you may consider partitioning the volume with a smaller
swap partition of 4-8 GB and the rest for a data volume.
Note
This procedure applies only to instance types that support instance storage. For a list of
supported instance types, see Instance Store Volumes (p. 957).
1. List the block devices attached to your instance to get the device name for your instance store
volume.
In this example, the instance store volume is /dev/xdvb. Because this is an Amazon Linux instance,
the instance store volume is formatted and mounted at /media/ephemeral0; not all Linux
operating systems do this automatically.
2. (Optional) If your instance store volume is mounted (it lists a MOUNTPOINT in the lsblk command
output), unmount it with the following command.
3. Set up a Linux swap area on the device with the mkswap command.
6. Edit your /etc/fstab file so that this swap space is automatically enabled at every system boot.
If your /etc/fstab file has an entry for /dev/xvdb (or /dev/sdb) change it to match the line
below; if it does not have an entry for this device, append the following line to your /etc/fstab
file (using the swap device name for your system):
Important
Instance store volume data is lost when an instance is stopped; this includes the instance
store swap space formatting created in Step 3 (p. 967). If you stop and restart an
instance that has been configured to use instance store swap space, you must repeat Step
1 (p. 967) through Step 5 (p. 967) on the new instance store volume.
967
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Optimizing Disk Performance
If you require greater flexibility in latency or throughput, we recommend using Amazon EBS.
To initialize the instance store volumes, use the following dd commands, depending on the store to
initialize (for example, /dev/sdb or /dev/nvme1n1).
Note
Make sure to unmount the drive before performing this command.
Initialization can take a long time (about 8 hours for an extra large instance).
To initialize the instance store volumes, use the following commands on the m1.large, m1.xlarge,
c1.xlarge, m2.xlarge, m2.2xlarge, and m2.4xlarge instance types:
To perform initialization on all instance store volumes at the same time, use the following command:
Configuring drives for RAID initializes them by writing to every drive location. When configuring
software-based RAID, make sure to change the minimum reconstruction speed:
File Storage
Cloud file storage is a method for storing data in the cloud that provides servers and applications access
to data through shared file systems. This compatibility makes cloud file storage ideal for workloads that
rely on shared file systems and provides simple integration without code changes.
There are many file storage solutions that exist, ranging from a single node file server on a compute
instance using block storage as the underpinnings with no scalability or few redundancies to protect
the data, to a do-it-yourself clustered solution, to a fully-managed solution, such as Amazon Elastic File
System (Amazon EFS) (p. 968) or Amazon FSx for Windows File Server (p. 972).
968
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Amazon EFS
data source for workloads and applications running on multiple instances. For more information, see the
Amazon Elastic File System product page.
In this tutorial, you create an EFS file system and two Linux instances that can share data using the file
system.
Important
Amazon EFS is not supported on Windows instances.
Tasks
• Prerequisites (p. 969)
• Step 1: Create an EFS File System (p. 969)
• Step 2: Mount the File System (p. 970)
• Step 3: Test the File System (p. 971)
• Step 4: Clean Up (p. 971)
Prerequisites
• Create a security group (for example, efs-sg) to associate with the EC2 instances and EFS mount target,
and add the following rules:
• Allow inbound SSH connections to the EC2 instances from your computer (the source is the CIDR
block for your network).
• Allow inbound NFS connections to the file system via the EFS mount target from the EC2 instances
that are associated with this security group (the source is the security group itself). For more
information, see Amazon EFS Rules (p. 620), and Security Groups for Amazon EC2 Instances and
Mount Targets in the Amazon Elastic File System User Guide.
• Create a key pair. You must specify a key pair when you configure your instances or you can't connect
to them. For more information, see Create a Key Pair (p. 21).
a. For the tag with Key=Name, type a name for the file system in Value.
b. For Choose performance mode, keep the default option, General Purpose.
c. Choose Next Step.
969
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Amazon EFS
[Nondefault VPC] Select your VPC for Network and a public subnet from Subnet.
c. [Nondefault VPC] For Auto-assign Public IP, choose Enable. Otherwise, your instances do not
get public IP addresses or public DNS names.
d. Under Advanced Details, select As text, and paste the following script into User data. Update
FILE_SYSTEM_ID with the ID of your file system. You can optionally update MOUNT_POINT
with a directory for your mounted file system.
✔!/bin/bash
yum update -y
yum install -y nfs-utils
FILE_SYSTEM_ID=fs-xxxxxxxx
AVAILABILITY_ZONE=$(curl -s http://169.254.169.254/latest/meta-data/placement/
availability-zone )
REGION=${AVAILABILITY_ZONE:0:-1}
MOUNT_POINT=/mnt/efs
mkdir -p ${MOUNT_POINT}
chown ec2-user:ec2-user ${MOUNT_POINT}
echo ${FILE_SYSTEM_ID}.efs.${REGION}.amazonaws.com:/ ${MOUNT_POINT} nfs4
nfsvers=4.1,rsize=1048576,wsize=1048576,hard,timeo=600,retrans=2,_netdev 0 0 >> /
etc/fstab
mount -a -t nfs4
970
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Amazon EFS
8. In the Select an existing key pair or create a new key pair dialog box, select Choose an existing
key pair and choose your key pair. Select the acknowledgment check box, and choose Launch
Instances.
9. In the navigation pane, choose Instances to see the status of your instances. Initially, their status is
pending. After the status changes to running, your instances are ready for use.
1. Connect to your instances. For more information, see Connect to Your Linux Instance (p. 446).
2. From the terminal window for each instance, run the df -T command to verify that the EFS file
system is mounted.
$ df -T
Filesystem Type 1K-blocks Used Available Use% Mounted on
/dev/xvda1 ext4 8123812 1949800 6073764 25% /
devtmpfs devtmpfs 4078468 56 4078412 1% /dev
tmpfs tmpfs 4089312 0 4089312 0% /dev/shm
efs-dns nfs4 9007199254740992 0 9007199254740992 0% /mnt/efs
Note that the name of the file system, shown in the example output as efs-dns, has the following
form:
file-system-id.efs.aws-region.amazonaws.com:/
3. (Optional) Create a file in the file system from one instance, and then verify that you can view the
file from the other instance.
a. From the first instance, run the following command to create the file:
b. From the second instance, run the following command to view the file:
$ ls /mnt/efs
test-file.txt
Step 4: Clean Up
When you are finished with this tutorial, you can terminate the instances and delete the file system.
971
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Amazon FSx
Amazon FSx supports a broad set of enterprise Windows workloads with fully managed file storage
built on Microsoft Windows Server. Amazon FSx has native support for Windows file system features
and for the industry-standard Server Message Block (SMB) protocol to access file storage over a
network. Amazon FSx is optimized for enterprise applications in the AWS Cloud, with native Windows
compatibility, enterprise performance and features, and consistent sub-millisecond latencies.
With file storage on Amazon FSx, the code, applications, and tools that Windows developers and
administrators use today can continue to work unchanged. The Windows applications and workloads
that are ideal for Amazon FSx include business applications, home directories, web serving, content
management, data analytics, software build setups, and media processing workloads.
As a fully managed service, Amazon FSx for Windows File Server eliminates the administrative overhead
of setting up and provisioning file servers and storage volumes. Additionally, it keeps Windows software
up to date, detects and addresses hardware failures, and performs backups. It also provides rich
integration with other AWS services, including AWS Directory Service for Microsoft Active Directory,
Amazon WorkSpaces, AWS Key Management Service, and AWS CloudTrail.
For more information, see the Amazon FSx for Windows File Server User Guide.
Important
Amazon FSx for Windows File Server is not supported on Linux instances.
Amazon EC2 uses Amazon S3 for storing Amazon Machine Images (AMIs). You use AMIs for launching
EC2 instances. In case of instance failure, you can use the stored AMI to immediately launch another
instance, thereby allowing for fast recovery and business continuity.
Amazon EC2 also uses Amazon S3 to store snapshots (backup copies) of the data volumes. You can use
snapshots for recovering data quickly and reliably in case of application or system failures. You can
also use snapshots as a baseline to create multiple new data volumes, expand the size of an existing
data volume, or move data volumes across multiple Availability Zones, thereby making your data usage
highly scalable. For more information about using data volumes and snapshots, see Amazon Elastic Block
Store (p. 828).
972
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Amazon S3 and Amazon EC2
Objects are the fundamental entities stored in Amazon S3. Every object stored in Amazon S3 is
contained in a bucket. Buckets organize the Amazon S3 namespace at the highest level and identify the
account responsible for that storage. Amazon S3 buckets are similar to Internet domain names. Objects
stored in the buckets have a unique key value and are retrieved using a HTTP URL address. For example,
if an object with a key value /photos/mygarden.jpg is stored in the myawsbucket bucket, then it is
addressable using the URL http://myawsbucket.s3.amazonaws.com/photos/mygarden.jpg.
For more information about the features of Amazon S3, see the Amazon S3 product page.
If you have permission, you can copy a file to or from Amazon S3 and your instance using one of the
following methods.
GET or wget
The wget utility is an HTTP and FTP client that allows you to download public objects from Amazon S3.
It is installed by default in Amazon Linux and most other distributions, and available for download on
Windows. To download an Amazon S3 object, use the following command, substituting the URL of the
object to download.
This method requires that the object you request is public; if the object is not public, you receive an
"ERROR 403: Forbidden" message. If you receive this error, open the Amazon S3 console and change
the permissions of the object to public. For more information, see the Amazon Simple Storage Service
Developer Guide.
The AWS Command Line Interface (AWS CLI) is a unified tool to manage your AWS services. The AWS
CLI enables users to authenticate themselves and download restricted items from Amazon S3 and also
to upload items. For more information, such as how to install and configure the tools, see the AWS
Command Line Interface detail page.
The aws s3 cp command is similar to the Unix cp command. You can copy files from Amazon S3 to your
instance, copy files from your instance to Amazon S3, and copy files from one Amazon S3 location to
another.
Use the following command to copy an object from Amazon S3 to your instance.
Use the following command to copy an object from your instance back into Amazon S3.
The aws s3 sync command can synchronize an entire Amazon S3 bucket to a local directory location. This
can be helpful for downloading a data set and keeping the local copy up-to-date with the remote set. If
you have the proper permissions on the Amazon S3 bucket, you can push your local directory back up to
the cloud when you are finished by reversing the source and destination locations in the command.
973
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Volume Limits
Use the following command to download an entire Amazon S3 bucket to a local directory on your
instance.
Amazon S3 API
If you are a developer, you can use an API to access data in Amazon S3. For more information, see the
Amazon Simple Storage Service Developer Guide. You can use this API and its examples to help develop
your application and integrate it with other APIs and SDKs, such as the boto Python interface.
Contents
• Linux-Specific Volume Limits (p. 974)
• Windows-Specific Volume Limits (p. 974)
• Instance Type Limits (p. 975)
• Bandwidth versus Capacity (p. 975)
AWS PV 26
Citrix PV 26
Red Hat PV 17
We do not recommend that you give a Windows instance more than 26 volumes with AWS PV or Citrix
PV drivers, as it is likely to cause performance issues.
974
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Type Limits
To determine which PV drivers your instance is using, or to upgrade your Windows instance from Red Hat
to Citrix PV drivers, see Upgrading PV Drivers on Your Windows Instance.
For more information about how device names related to volumes, see Mapping Disks to Volumes on
Your Windows EC2 Instance in the Amazon EC2 User Guide for Windows Instances.
The number of volumes that your instance can support is determined by the operating system. For more
information, see Instance Volume Limits (p. 974).
Contents
• Available Device Names (p. 975)
• Device Name Considerations (p. 976)
For information about device names on Windows instances, see Device Naming on Windows Instances in
the Amazon EC2 User Guide for Windows Instances.
975
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Device Name Considerations
PV only. Be sure to note the virtualization type of your AMI, because the recommended and available
device names that you can use depend on the virtualization type of your instance. For more information,
see Linux AMI Virtualization Types (p. 99).
The following table lists the available device names that you can specify in a block device mapping or
when attaching an EBS volume.
/dev/hd[a-z]
[1-15]
/dev/sd[b-y]
(d2.8xlarge)
/dev/sd[b-y]
(hs1.8xlarge)
/dev/sd[b-i]
(i2.8xlarge)
**
* The device names that you specify for NVMe EBS volumes in a block device mapping are renamed using
NVMe device names (/dev/nvme[0-26]n1). The block device driver can assign NVMe device names in a
different order than you specified for the volumes in the block device mapping.
** NVMe instance store volumes are automatically enumerated and assigned an NVMe device name.
For more information about instance store volumes, see Amazon EC2 Instance Store (p. 956). For more
information about NVMe EBS volumes, see Amazon EBS and NVMe on Linux Instances (p. 912).
• Although you can attach your EBS volumes using the device names used to attach instance store
volumes, we strongly recommend that you don't because the behavior can be unpredictable.
• The number of NVMe instance store volumes for an instance depends on the size of the instance.
NVMe instance store volumes are automatically enumerated and assigned an NVMe device name (/
dev/nvme[0-26]n1).
• Depending on the block device driver of the kernel, the device could be attached with a different
name than you specified. For example, if you specify a device name of /dev/sdh, your device could
be renamed /dev/xvdh or /dev/hdh. In most cases, the trailing letter remains the same. In some
versions of Red Hat Enterprise Linux (and its variants, such as CentOS), even the trailing letter could
976
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Block Device Mapping
change (/dev/sda could become /dev/xvde). In these cases, the trailing letter of each device name
is incremented the same number of times. For example, if /dev/sdb is renamed /dev/xvdf, then /
dev/sdc is renamed /dev/xvdg. Amazon Linux creates a symbolic link for the name you specified to
the renamed device. Other operating systems could behave differently.
• HVM AMIs do not support the use of trailing numbers on device names, except for /dev/sda1,
which is reserved for the root device, and /dev/sda2. While using /dev/sda2 is possible, we do not
recommend using this device mapping with HVM instances.
• When using PV AMIs, you cannot attach volumes that share the same device letters both with and
without trailing digits. For example, if you attach a volume as /dev/sdc and another volume as /
dev/sdc1, only /dev/sdc is visible to the instance. To use trailing digits in device names, you must
use trailing digits on all device names that share the same base letters (such as /dev/sdc1, /dev/
sdc2, /dev/sdc3).
• Some custom kernels might have restrictions that limit use to /dev/sd[f-p] or /dev/sd[f-p]
[1-6]. If you're having trouble using /dev/sd[q-z] or /dev/sd[q-z][1-6], try switching to /
dev/sd[f-p] or /dev/sd[f-p][1-6].
For more information about root device volumes, see Changing the Root Device Volume to Persist (p. 16).
Contents
• Block Device Mapping Concepts (p. 977)
• AMI Block Device Mapping (p. 980)
• Instance Block Device Mapping (p. 982)
• Instance store volumes (virtual devices whose underlying hardware is physically attached to the host
computer for the instance)
• EBS volumes (remote storage devices)
A block device mapping defines the block devices (instance store volumes and EBS volumes) to attach
to an instance. You can specify a block device mapping as part of creating an AMI so that the mapping
is used by all instances launched from the AMI. Alternatively, you can specify a block device mapping
when you launch an instance, so this mapping overrides the one specified in the AMI from which you
launched the instance. Note that all NVMe instance store volumes supported by an instance type are
automatically enumerated and assigned a device name on instance launch; including them in your block
device mapping has no effect.
Contents
977
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Block Device Mapping Concepts
• The device name used within Amazon EC2. The block device driver for the instance assigns the actual
volume name when mounting the volume. The name assigned can be different from the name that
Amazon EC2 recommends. For more information, see Device Naming on Linux Instances (p. 975).
• [Instance store volumes] The virtual device: ephemeral[0-23]. Note that the number and size of
available instance store volumes for your instance varies by instance type.
• [NVMe instance store volumes] These volumes are automatically enumerated and assigned a device
name; including them in your block device mapping has no effect.
• [EBS volumes] The ID of the snapshot to use to create the block device (snap-xxxxxxxx). This value is
optional as long as you specify a volume size.
• [EBS volumes] The size of the volume, in GiB. The specified size must be greater than or equal to the
size of the specified snapshot.
• [EBS volumes] Whether to delete the volume on instance termination (true or false). The default
value is true for the root device volume and false for attached volumes. When you create an AMI, its
block device mapping inherits this setting from the instance. When you launch an instance, it inherits
this setting from the AMI.
• [EBS volumes] The volume type, which can be gp2 for General Purpose SSD, io1 for Provisioned IOPS
SSD, st1 for Throughput Optimized HDD, sc1 for Cold HDD, or standard for Magnetic. The default
value is gp2 in the Amazon EC2 console, and standard in the AWS SDKs and the AWS CLI.
• [EBS volumes] The number of input/output operations per second (IOPS) that the volume supports.
(Not used with gp2, st1, sc1, or standard volumes.)
• Some instance types include more instance store volumes than others, and some instance types
contain no instance store volumes at all. If your instance type supports one instance store volume, and
your AMI has mappings for two instance store volumes, then the instance launches with one instance
store volume.
• Instance store volumes can only be mapped at launch time. You cannot stop an instance without
instance store volumes (such as the t2.micro), change the instance to a type that supports instance
store volumes, and then restart the instance with instance store volumes. However, you can create an
AMI from the instance and launch it on an instance type that supports instance store volumes, and
map those instance store volumes to the instance.
• If you launch an instance with instance store volumes mapped, and then stop the instance and change
it to an instance type with fewer instance store volumes and restart it, the instance store volume
mappings from the initial launch still show up in the instance metadata. However, only the maximum
number of supported instance store volumes for that instance type are available to the instance.
Note
When an instance is stopped, all data on the instance store volumes is lost.
978
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Block Device Mapping Concepts
• Depending on instance store capacity at launch time, M3 instances may ignore AMI instance store
block device mappings at launch unless they are specified at launch. You should specify instance
store block device mappings at launch time, even if the AMI you are launching has the instance store
volumes mapped in the AMI, to ensure that the instance store volumes are available when the instance
launches.
Note that this example block device mapping is used in the example commands and APIs in this topic.
You can find example commands and APIs that create block device mappings in Specifying a Block
Device Mapping for an AMI (p. 980) and Updating the Block Device Mapping when Launching an
Instance (p. 982).
With a Linux instance, the device names specified in the block device mapping are mapped to their
corresponding block devices when the instance first boots. The instance type determines which instance
store volumes are formatted and mounted by default. You can mount additional instance store volumes
at launch, as long as you don't exceed the number of instance store volumes available for your instance
type. For more information, see Amazon EC2 Instance Store (p. 956). The block device driver for the
instance determines which devices are used when the volumes are formatted and mounted. For more
information, see Attaching an Amazon EBS Volume to an Instance (p. 851).
979
Amazon Elastic Compute Cloud
User Guide for Linux Instances
AMI Block Device Mapping
Contents
• Specifying a Block Device Mapping for an AMI (p. 980)
• Viewing the EBS Volumes in an AMI Block Device Mapping (p. 981)
For an EBS-backed AMI, you can add EBS volumes and instance store volumes using a block device
mapping. For an instance store-backed AMI, you can add instance store volumes only by modifying the
block device mapping entries in the image manifest file when registering the image.
Note
For M3 instances, you must specify instance store volumes in the block device mapping for the
instance when you launch it. When you launch an M3 instance, instance store volumes specified
in the block device mapping for the AMI may be ignored if they are not specified as part of the
instance block device mapping.
Use the create-image AWS CLI command to specify a block device mapping for an EBS-backed AMI. Use
the register-image AWS CLI command to specify a block device mapping for an instance store-backed
AMI.
Specify the block device mapping using the --block-device-mappings parameter. Arguments encoded in
JSON can be supplied either directly on the command line or by reference to a file:
980
Amazon Elastic Compute Cloud
User Guide for Linux Instances
AMI Block Device Mapping
"DeviceName": "/dev/sdf",
"VirtualName": "ephemeral0"
}
To add an empty 100 GiB Magnetic volume, use the following mapping:
{
"DeviceName": "/dev/sdg",
"Ebs": {
"VolumeSize": 100
}
}
{
"DeviceName": "/dev/sdh",
"Ebs": {
"SnapshotId": "snap-xxxxxxxx"
}
}
{
"DeviceName": "/dev/sdj",
"NoDevice": ""
}
Alternatively, you can use the -BlockDeviceMapping parameter with the following commands (AWS
Tools for Windows PowerShell):
• New-EC2Image
• Register-EC2Image
If the AMI was created with additional EBS volumes using a block device mapping, the Block Devices
field displays the mapping for those additional volumes as well. (Recall that this screen doesn't
display instance store volumes.)
981
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Block Device Mapping
To view the EBS volumes for an AMI using the command line
Use the describe-images (AWS CLI) command or Get-EC2Image (AWS Tools for Windows PowerShell)
command to enumerate the EBS volumes in the block device mapping for an AMI.
Limits
• For the root volume, you can only modify the following: volume size, volume type, and the Delete on
Termination flag.
• When you modify an EBS volume, you can't decrease its size. Therefore, you must specify a snapshot
whose size is equal to or greater than the size of the snapshot specified in the block device mapping of
the AMI.
Contents
• Updating the Block Device Mapping when Launching an Instance (p. 982)
• Updating the Block Device Mapping of a Running Instance (p. 983)
• Viewing the EBS Volumes in an Instance Block Device Mapping (p. 984)
• Viewing the Instance Block Device Mapping for Instance Store Volumes (p. 985)
• To change the size of the root volume, locate the Root volume under the Type column, and
change its Size field.
• To suppress an EBS volume specified by the block device mapping of the AMI used to launch the
instance, locate the volume and click its Delete icon.
• To add an EBS volume, choose Add New Volume, choose EBS from the Type list, and fill in the
fields (Device, Snapshot, and so on).
• To suppress an instance store volume specified by the block device mapping of the AMI used to
launch the instance, locate the volume, and choose its Delete icon.
• To add an instance store volume, choose Add New Volume, select Instance Store from the Type
list, and select a device name from Device.
982
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Block Device Mapping
Use the run-instances AWS CLI command to specify a block device mapping for an instance.
For example, suppose that an EBS-backed AMI specifies the following block device mapping:
• /dev/sdb=ephemeral0
• /dev/sdh=snap-1234567890abcdef0
• /dev/sdj=:100
To prevent /dev/sdj from attaching to an instance launched from this AMI, use the following mapping:
{
"DeviceName": "/dev/sdj",
"NoDevice": ""
}
To increase the size of /dev/sdh to 300 GiB, specify the following mapping. Notice that you don't need
to specify the snapshot ID for /dev/sdh, because specifying the device name is enough to identify the
volume.
{
"DeviceName": "/dev/sdh",
"Ebs": {
"VolumeSize": 300
}
}
To attach an additional instance store volume, /dev/sdc, specify the following mapping. If the instance
type doesn't support multiple instance store volumes, this mapping has no effect.
{
"DeviceName": "/dev/sdc",
"VirtualName": "ephemeral1"
}
Alternatively, you can use the -BlockDeviceMapping parameter with the New-EC2Instance command
(AWS Tools for Windows PowerShell).
983
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Block Device Mapping
For example, to preserve the root volume at instance termination, specify the following in
mapping.json:
[
{
"DeviceName": "/dev/sda1",
"Ebs": {
"DeleteOnTermination": false
}
}
]
Alternatively, you can use the -BlockDeviceMapping parameter with the Edit-EC2InstanceAttribute
command (AWS Tools for Windows PowerShell).
If the instance was launched with additional EBS volumes using a block device mapping, the Block
devices field displays those additional volumes as well as the root device. (Recall that this dialog box
doesn't display instance store volumes.)
5. To display additional information about a block device, select its entry next to Block devices. This
displays the following information for the block device:
• EBS ID (vol-xxxxxxxx)
• Root device type (ebs)
• Attachment time (yyyy-mmThh:mm:ss.ssTZD)
• Block device status (attaching, attached, detaching, detached)
• Delete on termination (Yes, No)
984
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Block Device Mapping
To view the EBS volumes for an instance using the command line
Use the describe-instances (AWS CLI) command or Get-EC2Instance (AWS Tools for Windows PowerShell)
command to enumerate the EBS volumes in the block device mapping for an instance.
First, connect to your running instance. From the instance, use this query to get its block device mapping.
The response includes the names of the block devices for the instance. For example, the output for an
instance store–backed m1.small instance looks like this.
ami
ephemeral0
root
swap
The ami device is the root device as seen by the instance. The instance store volumes are named
ephemeral[0-23]. The swap device is for the page file. If you've also mapped EBS volumes, they
appear as ebs1, ebs2, and so on.
To get details about an individual block device in the block device mapping, append its name to the
previous query, as shown here.
For more information, see Instance Metadata and User Data (p. 526).
985
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Resource Locations
Some resources can be tagged with values that you define, to help you organize and identify them.
The following topics describe resources and tags, and how you can work with them.
Contents
• Resource Locations (p. 986)
• Resource IDs (p. 987)
• Listing and Filtering Your Resources (p. 992)
• Tagging Your Amazon EC2 Resources (p. 995)
• Amazon EC2 Service Limits (p. 1005)
• Amazon EC2 Usage Reports (p. 1007)
Resource Locations
Some resources can be used in all regions (global), and some resources are specific to the region or
Availability Zone in which they reside.
AWS account Global You can use the same AWS account in all regions.
Key pairs Global or The key pairs that you create using Amazon EC2 are
Regional tied to the region where you created them. You can
create your own RSA key pair and upload it to the
region in which you want to use it; therefore, you can
make your key pair globally available by uploading it
to each region.
Amazon EC2 resource Regional Each resource identifier, such as an AMI ID, instance ID,
identifiers EBS volume ID, or EBS snapshot ID, is tied to its region
and can be used only in the region where you created
the resource.
User-supplied resource Regional Each resource name, such as a security group name
names or key pair name, is tied to its region and can be used
only in the region where you created the resource.
Although you can create resources with the same name
in multiple regions, they aren't related to each other.
AMIs Regional An AMI is tied to the region where its files are located
within Amazon S3. You can copy an AMI from one
region to another. For more information, see Copying
an AMI (p. 154).
986
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Resource IDs
Security groups Regional A security group is tied to a region and can be assigned
only to instances in the same region. You can't enable
an instance to communicate with an instance outside
its region using security group rules. Traffic from an
instance in another region is seen as WAN bandwidth.
EBS snapshots Regional An EBS snapshot is tied to its region and can only
be used to create volumes in the same region. You
can copy a snapshot from one region to another.
For more information, see Copying an Amazon EBS
Snapshot (p. 874).
EBS volumes Availability Zone An Amazon EBS volume is tied to its Availability Zone
and can be attached only to instances in the same
Availability Zone.
Resource IDs
When resources are created, we assign each resource a unique resource ID. You can use resource IDs to
find your resources in the Amazon EC2 console. If you are using a command line tool or the Amazon EC2
API to work with Amazon EC2, resource IDs are required for certain commands. For example, if you are
using the stop-instances AWS CLI command to stop an instance, you must specify the instance ID in the
command.
Resource ID Length
A resource ID takes the form of a resource identifier (such as snap for a snapshot) followed by a hyphen
and a unique combination of letters and numbers. Starting in January 2016, we're gradually introducing
longer length IDs for Amazon EC2 and Amazon EBS resource types. The length of the alphanumeric
character combination was in an 8-character format; the new IDs are in a 17-character format, for
example, i-1234567890abcdef0 for an instance ID.
Supported resource types have an opt-in period, during which you can choose a resource ID format, and
a deadline date, after which the resource defaults to the longer ID format. After the deadline has passed
for a specific resource type, you can no longer disable the longer ID format for that resource type.
Different resource types have different opt-in periods and deadline dates. The following table lists the
supported resource types, along with their opt-in periods and deadline dates.
bundle | conversion-task | customer-gateway | dhcp- February 09, 2018 June 30, 2018
options | elastic-ip-allocation | - June 30, 2018
987
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with Longer IDs
network-interface | network-interface-
attachment | prefix-list |
You can enable or disable longer IDs for a resource at any time during the opt-in period. After you've
enabled longer IDs for a resource type, any new resources that you create are created with a longer ID.
Note
A resource ID does not change after it's created. Therefore, enabling or disabling longer IDs
during the opt-in period does not affect your existing resource IDs.
Depending on when you created your AWS account, supported resource types may default to using
longer IDs. However, you can opt out of using longer IDs until the deadline date for that resource type.
For more information, see Longer EC2 and EBS Resource IDs in the Amazon EC2 FAQs.
You can’t disable longer IDs for a resource type after its deadline date has passed. Any new resources
that you create are created with a longer ID.
Topics
• Viewing Longer ID Settings (p. 988)
• Modifying Longer ID Settings (p. 989)
988
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with Longer IDs
4. Expand Advanced Resource ID Management to view the resource types that support longer IDs and
their deadline dates.
To view longer ID settings for a specific IAM user or IAM role using the command line
Use one of the following commands and specify the ARN of an IAM user, IAM role, or root account user in
the request.
To view the aggregated longer ID settings for a specific region using the command line
Use the describe-aggregate-id-format AWS CLI command to view the aggregated longer ID setting for
the entire region, as well as the aggregated longer ID setting of all ARNs for each resource type. This
command is useful for performing a quick audit to determine whether a specific region is fully opted in
for longer IDs.
Use the describe-principal-id-format AWS CLI command to view the longer ID format settings for the
root user and all IAM roles and IAM users that have explicitly specified a longer ID preference. This
command is useful for identifying IAM users and IAM roles that have overridden the default longer ID
settings.
989
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with Longer IDs
To modify longer ID settings for your IAM user account using the command line
You can also use the command to modify the longer ID settings for all supported resource types. To do
this, replace the resource_type parameter with all-current.
Note
To disable longer IDs, replace the use-long-ids parameter with no-use-long-ids.
• Edit-EC2IdFormat (AWS Tools for Windows PowerShell)
You can also use the command to modify the longer ID settings for all supported resource types. To do
this, replace the resource_type parameter with all-current.
To modify longer ID settings for a specific IAM user or IAM role using the command line
Use one of the following commands and specify the ARN of an IAM user, IAM role, or root user in the
request.
990
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Controlling Access to Longer ID Settings
You can also use the command to modify the longer ID settings for all supported resource types. To do
this, specify all-current for the --resource parameter.
Note
To disable longer IDs, replace the use-long-ids parameter with no-use-long-ids.
• Edit-EC2IdentityIdFormat (AWS Tools for Windows PowerShell)
You can also use the command to modify the longer ID settings for all supported resource types. To do
this, specify all-current for the -Resource parameter.
• ec2:DescribeIdFormat
• ec2:DescribeIdentityIdFormat
• ec2:DescribeAggregateIdFormat
• ec2:DescribePrincipalIdFormat
• ec2:ModifyIdFormat
• ec2:ModifyIdentityIdFormat
For example, an IAM role may have permission to use all Amazon EC2 actions through an "Action":
"ec2:*" element in the policy statement.
To prevent IAM users and roles from viewing or modifying the longer resource ID settings for themselves
or other users and roles in your account, ensure that the IAM policy contains the following statement:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": [
"ec2:ModifyIdFormat",
"ec2:DescribeIdFormat",
"ec2:ModifyIdentityIdFormat",
"ec2:DescribeIdentityIdFormat",
991
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Listing and Filtering Your Resources
"ec2:DescribeAggregateIdFormat",
"ec2:DescribePrincipalIdFormat"
],
"Resource": "*"
}
]
}
• ec2:DescribeIdFormat
• ec2:DescribeIdentityIdFormat
• ec2:DescribeAggregateIdFormat
• ec2:DescribePrincipalIdFormat
• ec2:ModifyIdFormat
• ec2:ModifyIdentityIdFormat
Contents
• Advanced Search (p. 992)
• Listing Resources Using the Console (p. 993)
• Filtering Resources Using the Console (p. 994)
• Listing and Filtering Using the CLI and API (p. 995)
Advanced Search
Advanced search allows you to search using a combination of filters to achieve precise results. You can
filter by keywords, user-defined tag keys, and predefined resource attributes.
• Search by keyword
To search by keyword, type or paste what you’re looking for in the search box, and then choose Enter.
For example, to search for a specific instance, you can type the instance ID.
• Search by fields
You can also search by fields, tags, and attributes associated with a resource. For example, to find all
instances in the stopped state:
1. In the search box, start typing Instance State. As you type, you'll see a list of suggested fields.
2. Select Instance State from the list.
3. Select Stopped from the list of suggested values.
4. To further refine your list, select the search box for more search options.
• Advanced search
992
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Listing Resources Using the Console
You can create advanced queries by adding multiple filters. For example, you can search by tags and
see instances for the Flying Mountain project running in the Production stack, and then search by
attributes to see all t2.micro instances, or all instances in us-west-2a, or both.
• Inverse search
You can search for resources that do not match a specified value. For example, to list all instances
that are not terminated, search by the Instance State field, and prefix the Terminated value with an
exclamation mark (!).
• Partial search
When searching by field, you can also enter a partial string to find all resources that contain the string
in that field. For example, search by Instance Type, and then type t2 to find all t2.micro, t2.small or
t2.medium instances.
• Regular expression
Regular expressions are useful when you need to match the values in a field with a specific pattern. For
example, search by the Name tag, and then type ^s.* to see all instances with a Name tag that starts
with an 's'. Regular expression search is not case-sensitive.
After you have the precise results of your search, you can bookmark the URL for easy reference. In
situations where you have thousands of instances, filters and bookmarks can save you a great deal of
time; you don’t have to run searches repeatedly.
In general, multiple filters with the same key field (for example, tag:Name, search, Instance State)
are automatically joined with OR. This is intentional, as the vast majority of filters would not be
logical if they were joined with AND. For example, you would get zero results for a search on Instance
State=running AND Instance State=stopped. In many cases, you can granulate the results by using
complementary search terms on different key fields, where the AND rule is automatically applied instead.
If you search for tag: Name:=All values and tag:Instance State=running, you get search results that
contain both those criteria. To fine-tune your results, simply remove one filter in the string until the
results fit your requirements.
993
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Filtering Resources Using the Console
You can also use the search field on each page to find resources with specific attributes or values. You
can use regular expressions to search on partial or multiple strings. For example, to find all instances that
are using the MySG security group, enter MySG in the search field. The results will include any values that
contain MySG as a part of the string, such as MySG2 and MySG3. To limit your results to MySG only, enter
\bMySG\b in the search field. To list all the instances whose type is either m1.small or m1.large, enter
m1.small|m1.large in the search field.
994
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Listing and Filtering Using the CLI and API
The resulting lists of resources can be long, so you might want to filter the results to include only the
resources that match certain criteria. You can specify multiple filter values, and you can also specify
multiple filters. For example, you can list all the instances whose type is either m1.small or m1.large,
and that have an attached EBS volume that is set to delete when the instance terminates. The instance
must match all your filters to be included in the results.
You can also use wildcards with the filter values. An asterisk (*) matches zero or more characters, and a
question mark (?) matches zero or one character.
For example, you can use database as the filter value to get only the EBS snapshots whose description
equals database. If you specify *database*, then all snapshots whose description includes database
are returned. If you specify database?, then only the snapshots whose description matches one of the
following patterns are returned: equals database or equals database followed by one character.
The number of question marks determines the maximum number of characters to include in results. For
example, if you specify database????, then only the snapshots whose description equals database
followed by up to four characters are returned. Descriptions with five or more characters following
database are excluded from the search results.
Filter values are case sensitive. We support only exact string matching, or substring matching (with
wildcards). If a resulting list of resources is long, using an exact string filter may return the response
faster.
Your search can include the literal values of the wildcard characters; you just need to escape them with
a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string
*amazon?\.
For a list of supported filters per Amazon EC2 resource, see the relevant documentation:
• For the AWS CLI, see the relevant describe command in the AWS CLI Command Reference.
• For Windows PowerShell, see the relevant Get command in the AWS Tools for PowerShell Cmdlet
Reference.
• For the Query API, see the relevant Describe API action in the Amazon EC2 API Reference.
995
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Tag Basics
Warning
Tag keys, and their values, are returned by many different API calls. As a best practice, we
recommend that you do not include sensitive data in your tags.
Contents
• Tag Basics (p. 996)
• Tagging Your Resources (p. 997)
• Tag Restrictions (p. 999)
• Tagging Your Resources for Billing (p. 999)
• Working with Tags Using the Console (p. 1000)
• Working with Tags Using the CLI or API (p. 1003)
Tag Basics
A tag is a label that you assign to an AWS resource. Each tag consists of a key and an optional value, both
of which you define.
Tags enable you to categorize your AWS resources in different ways, for example, by purpose, owner, or
environment. This is useful when you have many resources of the same type—you can quickly identify a
specific resource based on the tags you've assigned to it. For example, you could define a set of tags for
your account's Amazon EC2 instances that helps you track each instance's owner and stack level.
The following diagram illustrates how tagging works. In this example, you've assigned two tags to each
of your instances—one tag with the key Owner and another with the key Stack. Each tag also has an
associated value.
996
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Tagging Your Resources
We recommend that you devise a set of tag keys that meets your needs for each resource type. Using a
consistent set of tag keys makes it easier for you to manage your resources. You can search and filter the
resources based on the tags you add.
Tags don't have any semantic meaning to Amazon EC2 and are interpreted strictly as a string of
characters. Also, tags are not automatically assigned to your resources. You can edit tag keys and values,
and you can remove tags from a resource at any time. You can set the value of a tag to an empty string,
but you can't set the value of a tag to null. If you add a tag that has the same key as an existing tag on
that resource, the new value overwrites the old value. If you delete a resource, any tags for the resource
are also deleted.
You can work with tags using the AWS Management Console, the AWS CLI, and the Amazon EC2 API.
If you're using AWS Identity and Access Management (IAM), you can control which users in your AWS
account have permission to create, edit, or delete tags. For more information, see Controlling Access to
Amazon EC2 Resources (p. 621).
If you're using the Amazon EC2 console, you can apply tags to resources by using the Tags tab on the
relevant resource screen, or you can use the Tags screen. Some resource screens enable you to specify
tags for a resource when you create the resource; for example, a tag with a key of Name and a value that
you specify. In most cases, the console applies the tags immediately after the resource is created (rather
than during resource creation). The console may organize resources according to the Name tag, but this
tag doesn't have any semantic meaning to the Amazon EC2 service.
If you're using the Amazon EC2 API, the AWS CLI, or an AWS SDK, you can use the CreateTags EC2
API action to apply tags to existing resources. Additionally, some resource-creating actions enable you
to specify tags for a resource when the resource is created. If tags cannot be applied during resource
creation, we roll back the resource creation process. This ensures that resources are either created with
tags or not created at all, and that no resources are left untagged at any time. By tagging resources at
the time of creation, you can eliminate the need to run custom tagging scripts after resource creation.
The following table describes the Amazon EC2 resources that can be tagged, and the resources that can
be tagged on creation using the Amazon EC2 API, the AWS CLI, or an AWS SDK.
AFI Yes No
AMI Yes No
Bundle task No No
997
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Tagging Your Resources
Key pair No No
Placement group No No
Subnet Yes No
VPC Yes No
998
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Tag Restrictions
You can tag instances and volumes on creation using the Amazon EC2 Launch Instances wizard in the
Amazon EC2 console. You can tag your EBS volumes on creation using the Volumes screen, or EBS
snapshots using the Snapshots screen. Alternatively, use the resource-creating Amazon EC2 APIs (for
example, RunInstances) to apply tags when creating your resource.
You can apply tag-based resource-level permissions in your IAM policies to the Amazon EC2 API actions
that support tagging on creation to implement granular control over the users and groups that can tag
resources on creation. Your resources are properly secured from creation—tags are applied immediately
to your resources, therefore any tag-based resource-level permissions controlling the use of resources are
immediately effective. Your resources can be tracked and reported on more accurately. You can enforce
the use of tagging on new resources, and control which tag keys and values are set on your resources.
You can also apply resource-level permissions to the CreateTags and DeleteTags Amazon EC2 API
actions in your IAM policies to control which tag keys and values are set on your existing resources. For
more information, see Supported Resource-Level Permissions for Amazon EC2 API Actions (p. 633) and
Example Policies for Working with the AWS CLI or an AWS SDK (p. 661).
For more information about tagging your resources for billing, see Using Cost Allocation Tags in the AWS
Billing and Cost Management User Guide.
Tag Restrictions
The following basic restrictions apply to tags:
You can't terminate, stop, or delete a resource based solely on its tags; you must specify the resource
identifier. For example, to delete snapshots that you tagged with a tag key called DeleteMe, you
must use the DeleteSnapshots action with the resource identifiers of the snapshots, such as
snap-1234567890abcdef0.
You can tag public or shared resources, but the tags you assign are available only to your AWS account
and not to the other accounts sharing the resource.
You can't tag all resources. For more information, see Tagging Support for Amazon EC2
Resources (p. 997).
999
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with Tags Using the Console
allocation report with tags, see The Monthly Cost Allocation Report in AWS Billing and Cost Management
User Guide. To see the cost of your combined resources, you can organize your billing information
based on resources that have the same tag key values. For example, you can tag several resources with
a specific application name, and then organize your billing information to see the total cost of that
application across several services. For more information, see Using Cost Allocation Tags in the AWS
Billing and Cost Management User Guide.
Note
If you've just enabled reporting, data for the current month is available for viewing after 24
hours.
Cost allocation tags can indicate which resources are contributing to costs, but deleting or deactivating
resources doesn't always reduce costs. For example, snapshot data that is referenced by another
snapshot is preserved, even if the snapshot that contains the original data is deleted. For more
information, see Amazon Elastic Block Store Volumes and Snapshots in the AWS Billing and Cost
Management User Guide.
Note
Elastic IP addresses that are tagged do not appear on your cost allocation report.
For more information about using filters when listing your resources, see Listing and Filtering Your
Resources (p. 992).
For ease of use and best results, use Tag Editor in the AWS Management Console, which provides a
central, unified way to create and manage your tags. For more information, see Working with Tag Editor
in Getting Started with the AWS Management Console.
Contents
• Displaying Tags (p. 1000)
• Adding and Deleting Tags on an Individual Resource (p. 1001)
• Adding and Deleting Tags to a Group of Resources (p. 1002)
• Adding a Tag When You Launch an Instance (p. 1002)
• Filtering a List of Resources by Tag (p. 1003)
Displaying Tags
You can display tags in two different ways in the Amazon EC2 console. You can display the tags for an
individual resource or for all resources.
When you select a resource-specific page in the Amazon EC2 console, it displays a list of those resources.
For example, if you select Instances from the navigation pane, the console displays a list of Amazon EC2
instances. When you select a resource from one of these lists (for example, an instance), if the resource
supports tags, you can view and manage its tags. On most resource pages, you can view the tags in the
Tags tab on the details pane.
You can add a column to the resource list that displays all values for tags with the same key. This column
enables you to sort and filter the resource list by the tag. There are two ways to add a new column to the
resource list to display your tags.
1000
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with Tags Using the Console
• On the Tags tab, select Show Column. A new column is added to the console.
• Choose the Show/Hide Columns gear-shaped icon, and in the Show/Hide Columns dialog box, select
the tag key under Your Tag Keys.
You can display tags across all resources by selecting Tags from the navigation pane in the Amazon EC2
console. The following image shows the Tags pane, which lists all tags in use by resource type.
1001
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with Tags Using the Console
1. From the navigation bar, select the Region for the instance. This choice is important because some
Amazon EC2 resources can be shared between Regions, while others can't. Select the Region that
meets your needs. For more information, see Resource Locations (p. 986).
2. Choose Launch Instance.
3. The Choose an Amazon Machine Image (AMI) page displays a list of basic configurations called
Amazon Machine Images (AMIs). Select the AMI to use and choose Select. For more information
about selecting an AMI, see Finding a Linux AMI (p. 100).
4. On the Configure Instance Details page, configure the instance settings as necessary, and then
choose Next: Add Storage.
5. On the Add Storage page, you can specify additional storage volumes for your instance. Choose
Next: Add Tags when done.
6. On the Add Tags page, specify tags for the instance, the volumes, or both. Choose Add another tag
to add more than one tag to your instance. Choose Next: Configure Security Group when you are
done.
1002
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with Tags Using the CLI or API
7. On the Configure Security Group page, you can choose from an existing security group that you
own, or let the wizard create a new security group for you. Choose Review and Launch when you are
done.
8. Review your settings. When you're satisfied with your selections, choose Launch. Select an existing
key pair or create a new one, select the acknowledgment check box, and then choose Launch
Instances.
a. Select a resource.
b. In the details pane, choose Tags.
c. Locate the tag in the list and choose Show Column.
2. Choose the filter icon in the top right corner of the column for the tag to display the filter list.
3. Select the tag values, and then choose Apply Filter to filter the results list.
Note
For more information about filters, see Listing and Filtering Your Resources (p. 992).
You can also filter a list of resources according to their tags. The following examples demonstrate how to
filter your instances using tags with the describe-instances command.
Note
The way you enter JSON-formatted parameters on the command line differs depending on your
operating system. Linux, macOS, or Unix and Windows PowerShell use the single quote (') to
enclose the JSON data structure. Omit the single quotes when using the commands with the
Windows command line. For more information, see Specifying Parameter Values for the AWS
Command Line Interface.
The following command describes the instances with a Stack tag, regardless of the value of the tag.
1003
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with Tags Using the CLI or API
The following command describes the instances with the tag Stack=production.
The following command describes the instances with a tag with the value production, regardless of the
tag key.
Some resource-creating actions enable you to specify tags when you create the resource. The following
actions support tagging on creation.
The following examples demonstrate how to apply tags when you create resources.
Example 4: Launch an instance and apply tags to the instance and volume
The following command launches an instance and applies a tag with a key of webserver and value of
production to the instance. The command also applies a tag with a key of cost-center and a value
of cc123 to any EBS volume that's created (in this case, the root volume).
You can apply the same tag keys and values to both instances and volumes during launch. The following
command launches an instance and applies a tag with a key of cost-center and a value of cc123 to
both the instance and any EBS volume that's created.
The following command creates a volume and applies two tags: purpose = production, and cost-
center = cc123.
1004
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Service Limits
This example adds the tag Stack=production to the specified image, or overwrites an existing tag for
the AMI where the tag key is Stack. If the command succeeds, no output is returned.
This example adds (or overwrites) two tags for an AMI and an instance. One of the tags contains just a
key (webserver), with no value (we set the value to an empty string). The other tag consists of a key
(stack) and value (Production). If the command succeeds, no output is returned.
This example adds the tag [Group]=test to an instance. The square brackets ([ and ]) are special
characters, and must be escaped with a backslash (\).
If you are using Windows PowerShell, break out the characters with a backslash (\), surround them with
double quotes ("), and then surround the entire key and value structure with single quotes (').
If you are using Linux or OS X, enclose the entire key and value structure with single quotes ('), and then
enclose the element with the special character with double quotes (").
The Amazon EC2 console provides limit information for the resources managed by the Amazon EC2 and
Amazon VPC consoles. You can request an increase for many of these limits. Use the limit information
that we provide to manage your AWS infrastructure. Plan to request any limit increases in advance of the
time that you'll need them.
For more information about the limits for other services, see AWS Service Limits in the Amazon Web
Services General Reference.
1005
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Requesting a Limit Increase
1006
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Limits on Email Sent Using Port 25
Cost Explorer is a free tool that you can use to view charts of your usage and costs. You can view data up
to the last 13 months, and forecast how much you are likely to spend for the next three months. You can
use Cost Explorer to see patterns in how much you spend on AWS resources over time, identify areas that
need further inquiry, and see trends that you can use to understand your costs. You also can specify time
ranges for the data, and view time data by day or by month.
Here's an example of some of the questions that you can answer when using Cost Explorer:
The report opens in Cost Explorer. It provides a preconfigured view, based on fixed filter settings,
that displays information about your usage and cost trends.
For more information about working with reports in Cost Explorer, including saving reports, see
Analyzing Your Costs with Cost Explorer.
1007
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Installing EC2Rescue for Linux
Contents
Prerequisites
If your system has the required Python version, you can install the standard build. Otherwise, you can
install the bundled build, which includes a minimal copy of Python.
1. From a working Linux instance, download the EC2Rescue for Linux tool:
curl -O https://s3.amazonaws.com/ec2rescuelinux/ec2rl.tgz
2. (Optional) Before proceeding, you can optionally verify the signature of the EC2Rescue for Linux
installation file. For more information, see (Optional) Verify the Signature of EC2Rescue for
Linux (p. 1009).
3. Download the sha256 hash file:
curl -O https://s3.amazonaws.com/ec2rescuelinux/ec2rl.tgz.sha256
1008
Amazon Elastic Compute Cloud
User Guide for Linux Instances
(Optional) Verify the Signature of EC2Rescue for Linux
sha256sum -c ec2rl.tgz.sha256
cd ec2rl-<version_number>
./ec2rl help
For a link to the download and a list of limitations, see EC2Rescue for Linux on github.
When you download an application from the internet, we recommend that you authenticate the identity
of the software publisher and check that the application has not been altered or corrupted after it was
published. This protects you from installing a version of the application that contains a virus or other
malicious code.
If, after running the steps in this topic, you determine that the software for EC2Rescue for Linux is
altered or corrupted, do not run the installation file. Instead, contact Amazon Web Services.
EC2Rescue for Linux files for Linux-based operating systems are signed using GnuPG, an open-source
implementation of the Pretty Good Privacy (OpenPGP) standard for secure digital signatures. GnuPG
(also known as GPG) provides authentication and integrity checking through a digital signature. AWS
publishes a public key and signatures that you can use to verify the downloaded EC2Rescue for Linux
package. For more information about PGP and GnuPG (GPG), see http://www.gnupg.org.
The first step is to establish trust with the software publisher. Download the public key of the software
publisher, check that the owner of the public key is who they claim to be, and then add the public key to
your keyring. Your keyring is a collection of known public keys. After you establish the authenticity of the
public key, you can use it to verify the signature of the application.
Tasks
• Install the GPG Tools (p. 1009)
• Authenticate and Import the Public Key (p. 1010)
• Verify the Signature of the Package (p. 1010)
1009
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Authenticate and Import the Public Key
1. At a command prompt, use the following command to obtain a copy of our public GPG build key:
curl -O https://s3.amazonaws.com/ec2rescuelinux/ec2rl.key
2. At a command prompt in the directory where you saved ec2rl.key, use the following command to
import the EC2Rescue for Linux public key into your keyring:
1. At a command prompt, run the following command to download the signature file for the
installation script:
curl -O https://s3.amazonaws.com/ec2rescuelinux/ec2rl.tgz.sig
2. Verify the signature by running the following command at a command prompt in the directory
where you saved ec2rl.tgz.sig and the EC2Rescue for Linux installation file. Both files must be
present.
1010
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Working with EC2Rescue for Linux
gpg: Signature made Thu 12 Jul 2018 01:57:51 AM UTC using RSA key ID 6991ED45
gpg: Good signature from "[email protected] <EC2 Rescue for Linux>"
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: E528 BCC9 0DBF 5AFA 0F6C C36A F780 4843 2FAE 2A1C
Subkey fingerprint: 966B 0D27 85E9 AEEC 1146 7A9D 8851 1153 6991 ED45
If the output contains the phrase Good signature from "[email protected] <EC2
Rescue for Linux>", it means that the signature has successfully been verified, and you can
proceed to run the EC2Rescue for Linux installation script.
If the output includes the phrase BAD signature, check whether you performed the procedure
correctly. If you continue to get this response, contact Amazon Web Services and do not run the
installation file that you downloaded previously.
The following are details about the warnings that you might see:
• WARNING: This key is not certified with a trusted signature! There is no indication that the
signature belongs to the owner. This refers to your personal level of trust in your belief that you
possess an authentic public key for EC2Rescue for Linux. In an ideal world, you would visit an Amazon
Web Services office and receive the key in person. However, more often you download it from a
website. In this case, the website is an Amazon Web Services website.
• gpg2: no ultimately trusted keys found. This means that the specific key is not "ultimately trusted" by
you (or by other people whom you trust).
Tasks
• Running EC2Rescue for Linux (p. 1011)
• Uploading the Results (p. 1012)
• Creating Backups (p. 1012)
• Getting Help (p. 1013)
./ec2rl run
1011
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Uploading the Results
Some modules require root access. If you are not a root user, use sudo to run these modules as follows:
For example, this command runs the dig module to query the amazon.com domain:
cat /var/tmp/ec2rl/logfile_location
For example, view the log file for the dig module:
cat /var/tmp/ec2rl/2017-05-11T15_39_21.893145/mod_out/run/dig.log
For more information about generating pre-signed URLs for Amazon S3, see Uploading Objects Using
Pre-Signed URLs.
Creating Backups
Create a backup for your instance, one or more volumes, or a specific device ID using the following
commands.
1012
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Getting Help
Getting Help
EC2Rescue for Linux includes a help file that gives you information and syntax for each available
command.
./ec2rl help
./ec2rl list
For example, use the following command to show the help file for the dig module:
Attribute Description
1013
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Adding Module Attributes
Attribute Description
in length. If the module consumes arguments,
required or optional, include them in the helptext
value.
For example:
helptext: !!str |
Collect output from ps for system
analysis
Consumes --times= for number of times to
repeat
Consumes --period= for time period
between repetition
• prediagnostic
• run
• postdiagnostic
• bash
• python
Note
Python code must be compatible with
both Python 2.7.9+ and Python 3.2+.
• application
• net
• os
• performance
1014
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Adding Module Attributes
Attribute Description
1015
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Adding Environment Variables
Default value:/var/tmp/ec2rl/
<date×tamp>/mod_out/gathered/.
Examples:
• xen_netfront
• ixgbevf
• ena
Examples:
• default-hvm
• default-paravirtual
1016
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Example Modules
• The !ec2rlcore.module.Module tag tells the YAML parser which constructor to call when creating
the object from the data stream. You can find the constructor inside the module.py file.
• The !!str tag tells the YAML parser to not attempt to determine the type of data, and instead
interpret the content as a string literal.
• The pipe character (|) tells the YAML parser that the value is a literal-style scalar. In this case, the
parser includes all whitespace. This is important for modules because indentation and newline
characters are kept.
• The YAML standard indent is two spaces, which can be seen in the following examples. Ensure that you
maintain standard indentation (for example, four spaces for Python) for your script and then indent
the entire content two spaces inside the module file.
Example Modules
Example one (mod.d/ps.yaml):
--- !ec2rlcore.module.Module
✔ Module document. Translates directly into an almost-complete Module object
name: !!str ps
path: !!str
version: !!str 1.0
title: !!str Collect output from ps for system analysis
helptext: !!str |
Collect output from ps for system analysis
Requires --times= for number of times to repeat
Requires --period= for time period between repetition
placement: !!str run
package:
- !!str
language: !!str bash
content: !!str |
✔!/bin/bash
error_trap()
{
printf "%0.s=" {1..80}
echo -e "\nERROR: "$BASH_COMMAND" exited with an error on line ${BASH_LINENO[0]}"
exit 0
}
trap error_trap ERR
1017
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Troubleshooting Launch Issues
Troubleshooting Instances
The following documentation can help you troubleshoot problems that you might have with your
instance.
Contents
• Troubleshooting Instance Launch Issues (p. 1018)
• Troubleshooting Connecting to Your Instance (p. 1020)
• Troubleshooting Stopping Your Instance (p. 1027)
• Troubleshooting Terminating (Shutting Down) Your Instance (p. 1029)
• Troubleshooting Instances with Failed Status Checks (p. 1029)
• Getting Console Output (p. 1051)
• Booting from the Wrong Volume (p. 1054)
For additional help with Windows instances, see Troubleshooting Windows Instances in the Amazon EC2
User Guide for Windows Instances.
Launch Issues
• Instance Limit Exceeded (p. 1018)
• Insufficient Instance Capacity (p. 1019)
• Instance Terminates Immediately (p. 1019)
Cause
If you get an InstanceLimitExceeded error when you try to launch a new instance or restart a
stopped instance, you have reached the limit on the number of instances that you can launch in a region.
When you create your AWS account, we set default limits on the number of instances you can run on a
per-region basis.
Solution
You can request an instance limit increase on a per-region basis. For more information, see Amazon EC2
Service Limits (p. 1005).
1018
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Insufficient Instance Capacity
Cause
If you get an InsufficientInstanceCapacity error when you try to launch an instance or restart a
stopped instance, AWS does not currently have enough available On-Demand capacity to service your
request.
Solution
To resolve the issue, try the following:
• Wait a few minutes and then submit your request again; capacity can shift frequently.
• Submit a new request with a reduced number of instances. For example, if you're making a single
request to launch 15 instances, try making 3 requests for 5 instances, or 15 requests for 1 instance
instead.
• If you're launching an instance, submit a new request without specifying an Availability Zone.
• If you're launching an instance, submit a new request using a different instance type (which you can
resize at a later stage). For more information, see Changing the Instance Type (p. 250).
• If you are launching instances into a cluster placement group, you can get an insufficient capacity
error. For more information, see Placement Group Rules and Limitations (p. 787).
• Try creating an On-Demand Capacity Reservation, which enables you to reserve Amazon EC2 capacity
for any duration. For more information, see On-Demand Capacity Reservations (p. 382).
• Try purchasing Reserved Instances, which are a long-term capacity reservation. For more information,
see Amazon EC2 Reserved Instances.
Cause
The following are a few reasons why an instance might immediately terminate:
Solution
You can use the Amazon EC2 console or AWS Command Line Interface to get the termination reason.
1019
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Connecting to Your Instance
To get the termination reason using the AWS Command Line Interface
2. Review the JSON response returned by the command and note the values in the StateReason
response element.
"StateReason": {
"Message": "Client.VolumeLimitExceeded: Volume limit exceeded",
"Code": "Server.InternalError"
},
Take one of the following actions depending on the termination reason you noted:
Contents
• Error connecting to your instance: Connection timed out (p. 1021)
• Error: User key not recognized by server (p. 1023)
• Error: Host key not found, Permission denied (publickey), or Authentication failed, permission
denied (p. 1024)
• Error: Unprotected Private Key File (p. 1025)
• Error: Private key must begin with "-----BEGIN RSA PRIVATE KEY-----" and end with "-----END RSA
PRIVATE KEY-----" (p. 1026)
• Error: Server refused our key or No supported authentication methods available (p. 1026)
1020
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Error connecting to your instance: Connection timed out
For additional help with Windows instances, see Troubleshooting Windows Instances in the Amazon EC2
User Guide for Windows Instances.
• Check your security group rules. You need a security group rule that allows inbound traffic from your
public IPv4 address on the proper port.
For Windows instances: When you select view inbound rules, a window will appear that displays
the port(s) to which traffic is allowed. Verify that there is a rule that allows traffic from your
computer to port 3389 (RDP).
Each time you restart your instance, a new IP address (and host name) will be assigned. If your
security group has a rule that allows inbound traffic from a single IP address, this address may not
be static if your computer is on a corporate network or if you are connecting through an internet
service provider (ISP). Instead, specify the range of IP addresses used by client computers. If your
security group does not have a rule that allows inbound traffic as described in the previous step,
add a rule to your security group. For more information, see Authorizing Network Access to Your
Instances (p. 704).
For more information about Security Group rules, see Security Group Rules in the Amazon VPC
User Guide.
• Check the route table for the subnet. You need a route that sends all traffic destined outside the VPC
to the internet gateway for the VPC.
1021
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Error connecting to your instance: Connection timed out
address, verify that there is a route for all IPv6 traffic (::/0) that points to the internet gateway.
Otherwise, do the following:
a. Choose the ID of the route table (rtb-xxxxxxxx) to navigate to the route table.
b. On the Routes tab, choose Edit routes. Choose Add route, use 0.0.0.0/0 as the destination
and the internet gateway as the target. For IPv6, choose Add route, use ::/0 as the
destination and the internet gateway as the target.
c. Choose Save routes.
• Check the network access control list (ACL) for the subnet. The network ACLs must allow inbound and
outbound traffic from your local IP address on the proper port. The default network ACL allows all
inbound and outbound traffic.
If you have a firewall on your computer, verify that it allows inbound and outbound traffic from your
computer on port 22 (for Linux instances) or port 3389 (for Windows instances).
• Check that your instance has a public IPv4 address. If not, you can associate an Elastic IP address with
your instance. For more information, see Elastic IP Addresses (p. 724).
• Check the CPU load on your instance; the server may be overloaded. AWS automatically provides data
such as Amazon CloudWatch metrics and instance status, which you can use to see how much CPU
load is on your instance and, if necessary, adjust how your loads are handled. For more information,
see Monitoring Your Instances Using CloudWatch (p. 558).
• If your load is variable, you can automatically scale your instances up or down using Auto Scaling
and Elastic Load Balancing.
• If your load is steadily growing, you can move to a larger instance type. For more information, see
Changing the Instance Type (p. 250).
• Your subnet must be associated with a route table that has a route for IPv6 traffic (::/0) to an
internet gateway.
• Your security group rules must allow inbound traffic from your local IPv6 address on the proper port
(22 for Linux and 3389 for Windows).
• Your network ACL rules must allow inbound and outbound IPv6 traffic.
• If you launched your instance from an older AMI, it may not be configured for DHCPv6 (IPv6 addresses
are not automatically recognized on the network interface). For more information, see Configure IPv6
on Your Instances in the Amazon VPC User Guide.
• Your local computer must have an IPv6 address, and must be configured to use IPv6.
1022
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Error: User key not recognized by server
• Use ssh -vvv to get triple verbose debugging information while connecting:
The following sample output demonstrates what you might see if you were trying to connect to your
instance with a key that was not recognized by the server:
open/ANT/myusername/.ssh/known_hosts).
debug2: bits set: 504/1024
debug1: ssh_rsa_verify: signature correct
debug2: kex_derive_keys
debug2: set_newkeys: mode 1
debug1: SSH2_MSG_NEWKEYS sent
debug1: expecting SSH2_MSG_NEWKEYS
debug2: set_newkeys: mode 0
debug1: SSH2_MSG_NEWKEYS received
debug1: Roaming not allowed by server
debug1: SSH2_MSG_SERVICE_REQUEST sent
debug2: service_accept: ssh-userauth
debug1: SSH2_MSG_SERVICE_ACCEPT received
debug2: key: boguspem.pem ((nil))
debug1: Authentications that can continue: publickey
debug3: start over, passed a different list publickey
debug3: preferred gssapi-keyex,gssapi-with-mic,publickey,keyboard-interactive,password
debug3: authmethod_lookup publickey
debug3: remaining preferred: keyboard-interactive,password
debug3: authmethod_is_enabled publickey
debug1: Next authentication method: publickey
debug1: Trying private key: boguspem.pem
debug1: read PEM private key done: type RSA
debug3: sign_and_send_pubkey: RSA 9c:4c:bc:0c:d0:5c:c7:92:6c:8e:9b:16:e4:43:d8:b2
debug2: we sent a publickey packet, wait for reply
debug1: Authentications that can continue: publickey
debug2: we did not send a packet, disable method
debug1: No more authentication methods to try.
Permission denied (publickey).
• If Java is not enabled, the server does not recognize the user key. To enable Java, go to How do I
enable Java in my web browser? in the Java documentation.
• Verify that your private key (.pem) file has been converted to the format recognized by PuTTY (.ppk).
For more information about converting your private key, see Connecting to Your Linux Instance from
Windows Using PuTTY (p. 459).
Note
In PuTTYgen, load your private key file and select Save Private Key rather than Generate.
• Verify that you are connecting with the appropriate user name for your AMI. Enter the user name in
the Host name box in the PuTTY Configuration window.
• For Amazon Linux 2 or the Amazon Linux AMI, the user name is ec2-user.
1023
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Error: Host key not found, Permission denied
(publickey), or Authentication failed, permission denied
• For a CentOS AMI, the user name is centos.
• For a Debian AMI, the user name is admin or root.
• For a Fedora AMI, the user name is ec2-user or fedora.
• For a RHEL AMI, the user name is ec2-user or root.
• For a SUSE AMI, the user name is ec2-user or root.
• For an Ubuntu AMI, the user name is ubuntu.
• Otherwise, if ec2-user and root don't work, check with the AMI provider.
• Verify that you have an inbound security group rule to allow inbound traffic to the appropriate port.
For more information, see Authorizing Network Access to Your Instances (p. 704).
• For Amazon Linux 2 or the Amazon Linux AMI, the user name is ec2-user.
• For a CentOS AMI, the user name is centos.
• For a Debian AMI, the user name is admin or root.
• For a Fedora AMI, the user name is ec2-user or fedora.
• For a RHEL AMI, the user name is ec2-user or root.
• For a SUSE AMI, the user name is ec2-user or root.
• For an Ubuntu AMI, the user name is ubuntu.
• Otherwise, if ec2-user and root don't work, check with the AMI provider.
For example, to use an SSH client to connect to an Amazon Linux instance, use the following command:
Confirm that you are using the private key file that corresponds to the key pair that you selected when
you launched the instance.
If you generated your own key pair, ensure that your key generator is set up to create RSA keys. DSA keys
are not accepted.
1024
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Error: Unprotected Private Key File
If you get a Permission denied (publickey) error and none of the above applies (for example, you
were able to connect previously), the permissions on the home directory of your instance may have been
changed. Permissions for /home/ec2-user/.ssh/authorized_keys must be limited to the owner
only.
1. Stop your instance and detach the root volume. For more information, see Stop and Start Your
Instance (p. 468) and Detaching an Amazon EBS Volume from an Instance (p. 864).
2. Launch a temporary instance in the same Availability Zone as your current instance (use a similar or
the same AMI as you used for your current instance), and attach the root volume to the temporary
instance. For more information, see Attaching an Amazon EBS Volume to an Instance (p. 851).
3. Connect to the temporary instance, create a mount point, and mount the volume that you attached.
For more information, see Making an Amazon EBS Volume Available for Use on Linux (p. 852).
4. From the temporary instance, check the permissions of the /home/ec2-user/ directory of the
attached volume. If necessary, adjust the permissions as follows:
5. Unmount the volume, detach it from the temporary instance, and re-attach it to the original
instance. Ensure that you specify the correct device name for the root volume; for example, /dev/
xvda.
6. Start your instance. If you no longer require the temporary instance, you can terminate it.
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ WARNING: UNPROTECTED PRIVATE KEY FILE! @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
Permissions 0777 for '.ssh/my_private_key.pem' are too open.
It is required that your private key files are NOT accessible by others.
This private key will be ignored.
bad permissions: ignore key: .ssh/my_private_key.pem
Permission denied (publickey).
If you see a similar message when you try to log in to your instance, examine the first line of the error
message to verify that you are using the correct public key for your instance. The above example uses
the private key .ssh/my_private_key.pem with file permissions of 0777, which allow anyone to read
or write to this file. This permission level is very insecure, and so SSH ignores this key. To fix the error,
execute the following command, substituting the path for your private key file.
1025
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Error: Private key must begin with "-----BEGIN RSA PRIVATE
KEY-----" and end with "-----END RSA PRIVATE KEY-----"
To resolve the error, the private key must be in the PEM format. Use the following command to create
the private key in the PEM format:
ssh-keygen -m PEM
• For Amazon Linux 2 or the Amazon Linux AMI, the user name is ec2-user.
• For a CentOS AMI, the user name is centos.
• For a Debian AMI, the user name is admin or root.
• For a Fedora AMI, the user name is ec2-user or fedora.
• For a RHEL AMI, the user name is ec2-user or root.
• For a SUSE AMI, the user name is ec2-user or root.
• For an Ubuntu AMI, the user name is ubuntu.
• Otherwise, if ec2-user and root don't work, check with the AMI provider.
You should also verify that your private key (.pem) file has been correctly converted to the format
recognized by PuTTY (.ppk). For more information about converting your private key, see Connecting to
Your Linux Instance from Windows Using PuTTY (p. 459).
You must update the browser's security settings to allow the AWS Management Console to run the Java
plugin in unsafe mode.
1. In Safari, keep the Amazon EC2 console open, and choose Safari, Preferences, Security.
1026
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Cannot Ping Instance
2. Choose Plug-in Settings (or Manage Website Settings on older versions of Safari).
3. Choose the Java plugin on the left.
4. For Currently Open Websites, select the AWS Management Console URL and choose Run in Unsafe
Mode.
5. When prompted, choose Trust in the warning dialog box and choose Done.
If you still experience issues after enabling keepalives, try to disable Nagle's algorithm on the Connection
page of the Putty Configuration.
There is no cost for any instance usage while an instance is not in the running state.
Force the instance to stop using either the console or the AWS CLI.
• To force the instance to stop using the console, select the stuck instance, and choose Actions, Instance
State, Stop, and Yes, Forcefully Stop.
• To force the instance to stop using the AWS CLI, use the stop-instances command and the --force
option as follows:
If, after 10 minutes, the instance has not stopped, post a request for help in the Amazon EC2 forum.
To help expedite a resolution, include the instance ID, and describe the steps that you've already taken.
Alternatively, if you have a support plan, create a technical support case in the Support Center.
1027
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Creating a Replacement Instance
For more information, see Creating a Linux AMI from an Instance (p. 117).
5. Launch a new instance from the AMI and verify that the new instance is working.
6. Select the stuck instance, and choose Actions, Instance State, Terminate. If the instance also gets
stuck terminating, Amazon EC2 automatically forces it to terminate within a few hours.
1. Create an AMI from the stuck instance using the create-image (AWS CLI) command and the --no-
reboot option as follows:.
2. Launch a new instance from the AMI using the run-instances (AWS CLI) command as follows:
If you are unable to create an AMI from the instance as described in the previous procedures, you can set
up a replacement instance as follows:
1. Select the instance and choose Description, Block devices. Select each volume and write down its
volume ID. Be sure to note which volume is the root volume.
2. In the navigation pane, choose Volumes. Select each volume for the instance, and choose Actions,
Create Snapshot.
3. In the navigation pane, choose Snapshots. Select the snapshot that you just created, and choose
Actions, Create Volume.
4. Launch an instance with the same operating system as the stuck instance. Note the volume ID and
device name of its root volume.
5. In the navigation pane, choose Instances, select the instance that you just launched, choose Actions,
Instance State, and then choose Stop.
6. In the navigation pane, choose Volumes, select the root volume of the stopped instance, and choose
Actions, Detach Volume.
1028
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Terminating Your Instance
7. Select the root volume that you created from the stuck instance, choose Actions, Attach Volume,
and attach it to the new instance as its root volume (using the device name that you wrote down).
Attach any additional non-root volumes to the instance.
8. In the navigation pane, choose Instances and select the replacement instance. Choose Actions,
Instance State, Start. Verify that the instance is working.
9. Select the stuck instance, choose Actions, Instance State, Terminate. If the instance also gets stuck
terminating, Amazon EC2 automatically forces it to terminate within a few hours.
Another possible cause is a problem with the underlying host computer. If your instance remains in the
shutting-down state for several hours, Amazon EC2 treats it as a stuck instance and forcibly terminates
it.
If it appears that your instance is stuck terminating and it has been longer than several hours, post a
request for help to the Amazon EC2 forum. To help expedite a resolution, include the instance ID and
describe the steps that you've already taken. Alternatively, if you have a support plan, create a technical
support case in the Support Center.
For more information, see the Amazon EC2 Auto Scaling User Guide or the AWS Elastic Beanstalk
Developer Guide.
1029
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Review Status Check Information
Topics
• Review Status Check Information (p. 1030)
• Retrieve the System Logs (p. 1031)
• Troubleshooting System Log Errors for Linux-Based Instances (p. 1031)
• Out of memory: kill process (p. 1032)
• ERROR: mmu_update failed (Memory management update failed) (p. 1033)
• I/O Error (Block Device Failure) (p. 1033)
• I/O ERROR: neither local nor remote disk (Broken distributed block device) (p. 1035)
• request_module: runaway loop modprobe (Looping legacy kernel modprobe on older Linux
versions) (p. 1035)
• "FATAL: kernel too old" and "fsck: No such file or directory while trying to open /dev" (Kernel and AMI
mismatch) (p. 1036)
• "FATAL: Could not load /lib/modules" or "BusyBox" (Missing kernel modules) (p. 1037)
• ERROR Invalid kernel (EC2 incompatible kernel) (p. 1038)
• request_module: runaway loop modprobe (Looping legacy kernel modprobe on older Linux
versions) (p. 1039)
• fsck: No such file or directory while trying to open... (File system not found) (p. 1040)
• General error mounting filesystems (Failed mount) (p. 1041)
• VFS: Unable to mount root fs on unknown-block (Root filesystem mismatch) (p. 1043)
• Error: Unable to determine major/minor number of root device... (Root file system/device
mismatch) (p. 1044)
• XENBUS: Device with no driver... (p. 1045)
• ... days without being checked, check forced (File system check required) (p. 1046)
• fsck died with exit status... (Missing device) (p. 1046)
• GRUB prompt (grubdom>) (p. 1047)
• Bringing up interface eth0: Device eth0 has different MAC address than expected, ignoring. (Hard-
coded MAC address) (p. 1049)
• Unable to load SELinux Policy. Machine is in enforcing mode. Halting now. (SELinux
misconfiguration) (p. 1050)
• XENBUS: Timeout connecting to devices (Xenbus timeout) (p. 1051)
If a system status check has failed, you can try one of the following options:
• Create an instance recovery alarm. For more information, see Create Alarms That Stop, Terminate,
Reboot, or Recover an Instance (p. 577).
• If you changed the instance type to a Nitro-based instance (p. 181), status checks fail if you migrated
from an instance that does not have the required ENA and NVMe drivers. For more information, see
Compatibility for Resizing Instances (p. 251).
1030
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Retrieve the System Logs
• For an instance using an Amazon EBS-backed AMI, stop and restart the instance.
• For an instance using an instance-store backed AMI, terminate the instance and launch a replacement.
• Wait for Amazon EC2 to resolve the issue.
• Post your issue to the Amazon EC2 forum.
• If your instance is in an Auto Scaling group, the Amazon EC2 Auto Scaling service automatically
launches a replacement instance. For more information, see Health Checks for Auto Scaling Instances
in the Amazon EC2 Auto Scaling User Guide.
• Retrieve the system log and look for errors.
Memory Errors
Device Errors
Kernel Errors
1031
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Out of memory: kill process
• request_module: runaway loop modprobe (Looping legacy kernel modprobe on older Linux
versions) (p. 1035)
• "FATAL: kernel too old" and "fsck: No such file or directory while trying to open /dev" (Kernel and AMI
mismatch) (p. 1036)
• "FATAL: Could not load /lib/modules" or "BusyBox" (Missing kernel modules) (p. 1037)
• ERROR Invalid kernel (EC2 incompatible kernel) (p. 1038)
• request_module: runaway loop modprobe (Looping legacy kernel modprobe on older Linux
versions) (p. 1039)
• fsck: No such file or directory while trying to open... (File system not found) (p. 1040)
• General error mounting filesystems (Failed mount) (p. 1041)
• VFS: Unable to mount root fs on unknown-block (Root filesystem mismatch) (p. 1043)
• Error: Unable to determine major/minor number of root device... (Root file system/device
mismatch) (p. 1044)
• XENBUS: Device with no driver... (p. 1045)
• ... days without being checked, check forced (File system check required) (p. 1046)
• fsck died with exit status... (Missing device) (p. 1046)
Potential Cause
Exhausted memory
Suggested Actions
1032
Amazon Elastic Compute Cloud
User Guide for Linux Instances
ERROR: mmu_update failed (Memory
management update failed)
For this instance type Do this
• Stop the instance, and modify the instance
to use a different instance type, and start
the instance again. For example, a larger or a
memory-optimized instance type.
• Reboot the instance to return it to a non-
impaired status. The problem will probably
occur again unless you change the instance
type.
...
Press `ESC' to enter the menu... 0 [H[J Booting 'Amazon Linux 2011.09
(2.6.35.14-95.38.amzn1.i686)'
root (hd0)
en_US.UTF-8 KEYTABLE=us
initrd /boot/initramfs-2.6.35.14-95.38.amzn1.i686.img
Potential Cause
Issue with Amazon Linux
Suggested Action
Post your issue to the Developer Forums or contact AWS Support.
1033
Amazon Elastic Compute Cloud
User Guide for Linux Instances
I/O Error (Block Device Failure)
Potential Causes
Suggested Actions
1034
Amazon Elastic Compute Cloud
User Guide for Linux Instances
I/O ERROR: neither local nor remote
disk (Broken distributed block device)
For this instance type Do this
store volumes are directly tied to single
host and single disk failures.
...
block drbd1: Local IO failed in request_timer_fn. Detaching...
JBD2: I/O error detected when updating journal superblock for drbd1-8.
Potential Causes
Suggested Action
Terminate the instance and launch a new instance.
For an Amazon EBS-backed instance you can recover data from a recent snapshot by creating an image
from it. Any data added after the snapshot cannot be recovered.
1035
Amazon Elastic Compute Cloud
User Guide for Linux Instances
"FATAL: kernel too old" and "fsck: No such file or directory
while trying to open /dev" (Kernel and AMI mismatch)
request_module: runaway loop modprobe binfmt-464c
Suggested Actions
Option 2:
Potential Causes
Incompatible kernel and userland
Suggested Actions
1036
Amazon Elastic Compute Cloud
User Guide for Linux Instances
"FATAL: Could not load /lib/modules"
or "BusyBox" (Missing kernel modules)
For this instance type Do this
1. Stop the instance.
2. Modify the configuration to use a newer kernel.
3. Start the instance.
(initramfs)
Potential Causes
One or more of the following conditions can cause this problem:
• Missing ramdisk
• Missing correct modules from ramdisk
• Amazon EBS root volume not correctly attached as /dev/sda1
1037
Amazon Elastic Compute Cloud
User Guide for Linux Instances
ERROR Invalid kernel (EC2 incompatible kernel)
Suggested Actions
...
root (hd0)
initrd /initrd.img
Booting 'Fallback'
root (hd0)
Potential Causes
One or both of the following conditions can cause this problem:
1038
Amazon Elastic Compute Cloud
User Guide for Linux Instances
request_module: runaway loop modprobe (Looping
legacy kernel modprobe on older Linux versions)
Suggested Actions
Suggested Actions
1039
Amazon Elastic Compute Cloud
User Guide for Linux Instances
fsck: No such file or directory while
trying to open... (File system not found)
For this instance type Do this
Option 1: Terminate the instance and launch
a new instance, specifying the –kernel and –
ramdisk parameters.
Option 2:
Welcome to Fedora
Press 'I' to enter interactive startup.
Setting clock : Wed Oct 26 05:52:05 EDT 2011 [ OK ]
Starting udev: [ OK ]
No devices found
Setting up Logical Volume Management: File descriptor 7 left open
No volume groups found
[ OK ]
Checking filesystems
Checking all file systems.
[/sbin/fsck.ext3 (1) -- /] fsck.ext3 -a /dev/sda1
/dev/sda1: clean, 82081/1310720 files, 2141116/2621440 blocks
[/sbin/fsck.ext3 (1) -- /mnt/dbbackups] fsck.ext3 -a /dev/sdh
fsck.ext3: No such file or directory while trying to open /dev/sdh
/dev/sdh:
The superblock could not be read or does not describe a correct ext2
filesystem. If the device is valid and it really contains an ext2
filesystem (and not swap or ufs or something else), then the superblock
is corrupt, and you might try running e2fsck with an alternate superblock:
e2fsck -b 8193 <device>
[FAILED]
1040
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General error mounting filesystems (Failed mount)
Potential Causes
• A bug exists in ramdisk filesystem definitions /etc/fstab
• Misconfigured filesystem definitions in /etc/fstab
• Missing/failed drive
Suggested Actions
1041
Amazon Elastic Compute Cloud
User Guide for Linux Instances
General error mounting filesystems (Failed mount)
Potential Causes
Suggested Actions
1042
Amazon Elastic Compute Cloud
User Guide for Linux Instances
VFS: Unable to mount root fs on unknown-
block (Root filesystem mismatch)
For this instance type Do this
8. Start the instance.
9. Recheck the instance status.
Potential Causes
Suggested Actions
1043
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Error: Unable to determine major/minor number
of root device... (Root file system/device mismatch)
For this instance type Do this
• Refer to the documentation for your Linux
distribution to check for known update bugs.
Change or reinstall the kernel.
...
XENBUS: Device with no driver: device/vif/0
XENBUS: Device with no driver: device/vbd/2048
drivers/rtc/hctosys.c: unable to open rtc device (rtc0)
Initializing network drop monitor service
Freeing unused kernel memory: 508k freed
:: Starting udevd...
done.
:: Running Hook [udev]
:: Triggering uevents...<30>udevd[65]: starting version 173
done.
Waiting 10 seconds for device /dev/xvda1 ...
Root device '/dev/xvda1' doesn't exist. Attempting to create it.
ERROR: Unable to determine major/minor number of root device '/dev/xvda1'.
You are being dropped to a recovery shell
Type 'exit' to try and continue booting
sh: can't access tty; job control turned off
[ramfs /]#
Potential Causes
• Missing or incorrectly configured virtual block device driver
• Device enumeration clash (sda versus xvda or sda instead of sda1)
• Incorrect choice of instance kernel
Suggested Actions
1044
Amazon Elastic Compute Cloud
User Guide for Linux Instances
XENBUS: Device with no driver...
Potential Causes
• Missing or incorrectly configured virtual block device driver
• Device enumeration clash (sda versus xvda)
• Incorrect choice of instance kernel
Suggested Actions
1045
Amazon Elastic Compute Cloud
User Guide for Linux Instances
... days without being checked, check
forced (File system check required)
...
Checking filesystems
Checking all file systems.
[/sbin/fsck.ext3 (1) -- /] fsck.ext3 -a /dev/sda1
/dev/sda1 has gone 361 days without being checked, check forced
Potential Causes
Filesystem check time passed; a filesystem check is being forced.
Suggested Actions
• Wait until the filesystem check completes. A filesystem check can take a long time depending on the
size of the root filesystem.
• Modify your filesystems to remove the filesystem check (fsck) enforcement using tune2fs or tools
appropriate for your filesystem.
Cleaning up ifupdown....
Loading kernel modules...done.
...
Activating lvm and md swap...done.
Checking file systems...fsck from util-linux-ng 2.16.2
/sbin/fsck.xfs: /dev/sdh does not exist
fsck died with exit status 8
[31mfailed (code 8).[39;49m
Potential Causes
• Ramdisk looking for missing drive
• Filesystem consistency check forced
• Drive failed or detached
Suggested Actions
1046
Amazon Elastic Compute Cloud
User Guide for Linux Instances
GRUB prompt (grubdom>)
completions of a device/filename. ]
grubdom>
Potential Causes
1047
Amazon Elastic Compute Cloud
User Guide for Linux Instances
GRUB prompt (grubdom>)
Suggested Actions
1048
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Bringing up interface eth0: Device eth0
has different MAC address than expected,
For this instance type ignoring. (Hard-coded MAC Doaddress)
this
Note
To recover data from the existing
instance, contact AWS Support.
...
Bringing up loopback interface: [ OK ]
Bringing up interface eth0: Device eth0 has different MAC address than expected, ignoring.
[FAILED]
Starting auditd: [ OK ]
Potential Causes
There is a hardcoded interface MAC in the AMI configuration
Suggested Actions
OR
1049
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Unable to load SELinux Policy. Machine is in enforcing
mode. Halting now. (SELinux misconfiguration)
For this instance type Do this
• Terminate the instance and launch a new
instance.
Potential Causes
SELinux has been enabled in error:
Suggested Actions
1050
Amazon Elastic Compute Cloud
User Guide for Linux Instances
XENBUS: Timeout connecting to devices (Xenbus timeout)
Potential Causes
• The block device not is connected to the instance
• This instance is using an old instance kernel
Suggested Actions
1051
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Instance Reboot
Similarly, the ability to reboot instances that are otherwise unreachable is valuable for both
troubleshooting and general instance management.
EC2 instances do not have a physical monitor through which you can view their console output. They also
lack physical controls that allow you to power up, reboot, or shut them down. Instead, you perform these
tasks through the Amazon EC2 API and the command line interface (CLI).
Instance Reboot
Just as you can reset a computer by pressing the reset button, you can reset EC2 instances using the
Amazon EC2 console, CLI, or API. For more information, see Reboot Your Instance (p. 476).
Warning
For Windows instances, this operation performs a hard reboot that might result in data
corruption.
For Windows instances, the instance console output includes the last three system event log errors.
You can optionally retrieve the latest serial console output at any time during the instance lifecycle. This
option is only supported on Nitro-based Instances (p. 181). It is not supported through the Amazon EC2
console.
Note
Only the most recent 64 KB of posted output is stored, which is available for at least 1 hour
after the last posting.
Only the instance owner can access the console output. You can retrieve the console output for your
instances using the console or the command line.
You can use one of the following commands. For more information about these command line interfaces,
see Accessing Amazon EC2 (p. 3).
For more information about common system log errors, see Troubleshooting System Log Errors for
Linux-Based Instances (p. 1031).
1052
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Capture a Screenshot of an Unreachable Instance
There is no data transfer cost for this screenshot. The image is generated in JPG format, no larger than
100 KB.
You can use one of the following commands. The returned content is base64-encoded. For more
information about these command line interfaces, see Accessing Amazon EC2 (p. 3).
1. Back up any important data on your instance store volumes to Amazon EBS or Amazon S3.
2. Stop the instance.
3. Start the instance.
4. Restore any important data.
For more information, see Stop and Start Your Instance (p. 468).
For more information, see Creating an Instance Store-Backed Linux AMI (p. 119).
1053
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Booting from the Wrong Volume
This is due to how the initial ramdisk in Linux works. It chooses the volume defined as / in the /etc/
fstab, and in some distributions, this is determined by the label attached to the volume partition.
Specifically, you find that your /etc/fstab looks something like the following:
If you check the label of both volumes, you see that they both contain the / label:
In this example, you could end up having /dev/xvdf1 become the root device that your instance boots
to after the initial ramdisk runs, instead of the /dev/xvda1 volume from which you had intended to
boot. To solve this, use the same e2label command to change the label of the attached volume that you
do not want to boot from.
In some cases, specifying a UUID in /etc/fstab can resolve this. However, if both volumes come from
the same snapshot, or the secondary is created from a snapshot of the primary volume, they share a
UUID.
1. Use the e2label command to change the label of the volume to something other than /.
• Use the xfs_admin command to change the label of the volume to something other than /.
1054
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Booting from the Wrong Volume
After changing the volume label as shown, you should be able to reboot the instance and have the
proper volume selected by the initial ramdisk when the instance boots.
Important
If you intend to detach the volume with the new label and return it to another instance to use
as the root volume, you must perform the above procedure again and change the volume label
back to its original value. Otherwise, the other instance does not boot because the ramdisk is
unable to find the volume with the label /.
1055
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Document History
The following table describes important additions to the Amazon EC2 documentation. We also update
the documentation frequently to address the feedback that you send us.
Maximum total price 2016-11-15 You can specify a maximum hourly price for all 1 July
On-Demand Instances and Spot Instances in both 2019
EC2 Fleet and Spot Fleet. For more information,
see Control Spending (p. 424) in EC2 Fleet and
1056
Amazon Elastic Compute Cloud
User Guide for Linux Instances
• OnDemandTargetCapacity: 10
• OnDemandMaxTotalPrice: $1.50
Spot Fleet launches 10 On-Demand Instances
because the total of $1.00 (10 instances x $0.10)
does not exceed the OnDemandMaxTotalPrice
of $1.50.
• OnDemandTargetCapacity: 10
• OnDemandMaxTotalPrice: $0.80
If Spot Fleet launches the On-Demand target
capacity (10 On-Demand Instances), the
total cost per hour would be $1.00. This
is more than the amount ($0.80) specified
for OnDemandMaxTotalPrice. To prevent
spending more than you're willing to pay, Spot
Fleet launches only 8 On-Demand Instances
(below the On-Demand target capacity)
because launching more would exceed the
OnDemandMaxTotalPrice.
(p. 304) in Spot Fleet.
1057
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EC2 Instance Connect 2016-11-15 EC2 Instance Connect is a simple and secure way 27 June
to connect to your instances using Secure Shell 2019
(SSH). For more information, see Connecting
to Your Linux Instance Using EC2 Instance
Connect (p. 451).
Amazon EBS multi- 2016-11-15 Take exact point-in-time, data coordinated, and 29 May
volume snapshots crash-consistent snapshots across multiple EBS 2019
volumes attached to an EC2 instance.
Amazon EBS encryption 2016-11-15 After you enable encryption by default in a 23 May
by default Region, all new EBS volumes you create in the 2019
Region are encrypted using the default CMK
for EBS encryption. For more information, see
Encryption by Default (p. 904).
Tag VPC endpoints, 2016-11-15 You can tag VPC endpoints, endpoint services, 13 May
endpoint services, and endpoint service configurations. For more 2019
and endpoint service information, see Tagging Your Resources (p. 997).
configurations
Elastic Fabric Adapter 2016-11-15 You can attach an Elastic Fabric Adapter to 29 April
your instances to accelerate High Performance 2019
Computing (HPC) applications. For more
information, see Elastic Fabric Adapter (p. 775).
T3a instances 2016-11-15 New instances featuring AMD EYPC processors. 24 April
2019
M5ad and R5ad 2016-11-15 New instances featuring AMD EYPC processors. 27 March
instances 2019
Tag Dedicated Host 2016-11-15 You can tag your Dedicated Host Reservations. For 14 March
Reservations more information, see Tagging Dedicated Host 2019
Reservations (p. 372).
Bare metal instances for 2016-11-15 New instances that provide your applications with 13
M5, M5d, R5, R5d, and direct access to the physical resources of the host February
z1d server. 2019
1058
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Hibernate EC2 Linux 2016-11-15 You can hibernate a Linux instance if it's enabled 28
instances for hibernation and it meets the hibernation November
prerequisites. For more information, see Hibernate 2018
Your Instance (p. 470).
Instances featuring 2016-11-15 New C5n instances can utilize up to 100 Gbps of 26
100 Gbps of network network bandwidth. November
bandwidth 2018
New EC2 Fleet request 2016-11-15 EC2 Fleet now supports a new request type, 14
type: instant instant, that you can use to synchronously November
provision capacity across instance types and 2018
purchase models. The instant request returns
the launched instances in the API response, and
takes no further action, enabling you to control
if and when instances are launched. For more
information, see EC2 Fleet Request Types (p. 421).
Spot savings 2016-11-15 You can view the savings made from using Spot 5
information Instances for a single Spot Fleet or for all Spot November
Instances. For more information, see Savings From 2018
Purchasing Spot Instances (p. 309).
Console support for 2016-11-15 When you launch an instance, you can optimize 31
optimizing CPU options the CPU options to suit specific workloads or October
business needs using the Amazon EC2 console. 2018
For more information, see Optimizing CPU
Options (p. 504).
1059
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Console support for 2016-11-15 You can create a launch template using 30
creating a launch an instance as the basis for a new launch October
template from an template using the Amazon EC2 console. 2018
instance For more information, see Creating a Launch
Template (p. 405).
On-Demand Capacity 2016-11-15 You can reserve capacity for your Amazon EC2 25
Reservations instances in a specific Availability Zone for any October
duration. This allows you to create and manage 2018
capacity reservations independently from the
billing discounts offered by Reserved Instances
(RI). For more information, see On-Demand
Capacity Reservations (p. 382).
Bring Your Own IP 2016-11-15 You can bring part or all of your public IPv4 23
Addresses (BYOIP) address range from your on-premises network to October
your AWS account. After you bring the address 2018
range to AWS, it appears in your account as an
address pool. You can create an Elastic IP address
from your address pool and use it with your AWS
resources. For more information, see Bring Your
Own IP Addresses (BYOIP) (p. 721).
Dedicated Host tag 2016-11-15 You can tag your Dedicated Hosts on creation, and 08
on create and console you can manage your Dedicated Host tags using October
support the Amazon EC2 console. For more information, 2018
see Allocating Dedicated Hosts (p. 363).
High memory instances 2016-11-15 These instances are purpose-built to run large 27
in-memory databases. They offer bare metal September
performance with direct access to host hardware. 2018
For more information, see Memory Optimized
Instances (p. 226).
1060
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Allocation strategies for 2016-11-15 You can specify whether On-Demand capacity 26 July
EC2 Fleets is fulfilled by price (lowest price first) or priority 2018
(highest priority first). You can specify the number
of Spot pools across which to allocate your
target Spot capacity. For more information, see
Allocation Strategies for Spot Instances (p. 422).
Allocation strategies for 2016-11-15 You can specify whether On-Demand capacity 26 July
Spot Fleets is fulfilled by price (lowest price first) or priority 2018
(highest priority first). You can specify the number
of Spot pools across which to allocate your
target Spot capacity. For more information, see
Allocation Strategy for Spot Instances (p. 302).
R5 and R5d instances 2016-11-15 R5 and R5d instances are ideally suited for high- 25 July
performance databases, distributed in-memory 2018
caches, and in-memory analytics. R5d instances
come with NVMe instance store volumes. For
more information, see Memory Optimized
Instances (p. 226).
z1d instances 2016-11-15 These instances are designed for applications 25 July
that require high per-core performance with 2018
a large amount of memory, such as electronic
design automation (EDA) and relational databases.
These instances come with NVME instance store
volumes. For more information, see Memory
Optimized Instances (p. 226).
Automate snapshot 2016-11-15 You can use Amazon Data Lifecycle Manager to 12 July
lifecycle automate creation and deletion of snapshots 2018
for your EBS volumes. For more information,
see Automating the Amazon EBS Snapshot
Lifecycle (p. 881).
Launch template CPU 2016-11-15 When you create a launch template using the 11 July
options command line tools, you can optimize the CPU 2018
options to suit specific workloads or business
needs. For more information, see Creating a
Launch Template (p. 405).
Tag Dedicated Hosts 2016-11-15 You can tag your Dedicated Hosts. For 3 July
more information, see Tagging Dedicated 2018
Hosts (p. 367).
Get latest console 2016-11-15 You can retrieve the latest console output for 9 May
output some instance types when you use the get- 2018
console-output AWS CLI command.
1061
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Optimize CPU options 2016-11-15 When you launch an instance, you can optimize 8 May
the CPU options to suit specific workloads or 2018
business needs. For more information, see
Optimizing CPU Options (p. 504).
EC2 Fleet 2016-11-15 You can use EC2 Fleet to launch a group of 2 May
instances across different EC2 instance types 2018
and Availability Zones, and across On-Demand
Instance, Reserved Instance, and Spot Instance
purchasing models. For more information, see
Launching an EC2 Fleet (p. 418).
On-Demand Instances 2016-11-15 You can include a request for On-Demand 2 May
in Spot Fleets capacity in your Spot Fleet request to ensure 2018
that you always have instance capacity. For more
information, see How Spot Fleet Works (p. 301).
Tag EBS snapshots on 2016-11-15 You can apply tags to snapshots during creation. 2 April
creation For more information, see Creating Amazon EBS 2018
Snapshots (p. 869).
Change placement 2016-11-15 You can move an instance in or out of a placement 1 March
groups group, or change its placement group. For more 2018
information, see Changing the Placement Group
for an Instance (p. 791).
Longer resource IDs 2016-11-15 You can enable the longer ID format for more 9 February
resource types. For more information, see 2018
Resource IDs (p. 987).
Tag Elastic IP addresses 2016-11-15 You can tag your Elastic IP addresses. For 21
more information, see Tagging an Elastic IP December
Address (p. 726). 2017
Amazon Time Sync 2016-11-15 You can use the Amazon Time Sync Service to 29
Service keep accurate time on your instance. For more November
information, see Setting the Time for Your Linux 2017
Instance (p. 499).
1062
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Launch templates 2016-11-15 A launch template can contain all or some of the 29
parameters to launch an instance, so that you November
don't have to specify them every time you launch 2017
an instance. For more information, see Launching
an Instance from a Launch Template (p. 403).
Spot Instance 2016-11-15 The Spot service can hibernate Spot Instances 28
hibernation in the event of an interruption. For more November
information, see Hibernating Interrupted Spot 2017
Instances (p. 353).
Spot Fleet target 2016-11-15 You can set up target tracking scaling policies for 17
tracking your Spot Fleet. For more information, see Scale November
Spot Fleet Using a Target Tracking Policy (p. 341). 2017
Spot Fleet integrates 2016-11-15 You can attach one or more load balancers to a 10
with Elastic Load Spot Fleet. November
Balancing 2017
X1e instances 2016-11-15 X1e instances are ideally suited for high- 28
performance databases, in-memory databases, November
and other memory-intensive enterprise 2017
applications. For more information, see Memory
Optimized Instances (p. 226).
Merge and split 2016-11-15 You can exchange (merge) two or more 6
Convertible Reserved Convertible Reserved Instances for a new November
Instances Convertible Reserved Instance. You can also use 2017
the modification process to split a Convertible
Reserved Instance into smaller reservations. For
more information, see Exchanging Convertible
Reserved Instances (p. 289).
1063
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Modify VPC tenancy 2016-11-15 You can change the instance tenancy attribute of 16
a VPC from dedicated to default. For more October
information, see Changing the Tenancy of a 2017
VPC (p. 382).
Per second billing 2016-11-15 Amazon EC2 charges for Linux-based usage by the 2 October
second, with a one-minute minimum charge. 2017
Stop on interruption 2016-11-15 You can specify whether Amazon EC2 should 18
stop or terminate Spot instances when they September
are interrupted. For more information, see 2017
Interruption Behavior (p. 352).
Tag NAT gateways 2016-11-15 You can tag your NAT gateway. For more 7
information, see Tagging Your Resources (p. 997). September
2017
Security group rule 2016-11-15 You can add descriptions to your security group 31 August
descriptions rules. For more information, see Security Group 2017
Rules (p. 608).
Recover Elastic IP 2016-11-15 If you release an Elastic IP address for use in 11 August
addresses a VPC, you might be able to recover it. For 2017
more information, see Recovering an Elastic IP
Address (p. 728).
Tag Spot fleet instances 2016-11-15 You can configure your Spot fleet to automatically 24 July
tag the instances that it launches. 2017
Tag resources during 2016-11-15 You can apply tags to instances and volumes 28 March
creation during creation. For more information, see 2017
Tagging Your Resources (p. 997). In addition, you
can use tag-based resource-level permissions
to control the tags that are applied. For more
information see, Resource-Level Permissions for
Tagging (p. 659).
1064
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Perform modifications 2016-11-15 With most EBS volumes attached to most EC2 13
on attached EBS instances, you can modify volume size, type, and February
volumes IOPS without detaching the volume or stopping 2017
the instance. For more information, see Amazon
EBS Elastic Volumes (p. 892).
Attach an IAM role 2016-11-15 You can attach, detach, or replace an IAM role for 9 February
an existing instance. For more information, see 2017
IAM Roles for Amazon EC2 (p. 696).
Dedicated Spot 2016-11-15 You can run Spot instances on single-tenant 19 January
instances hardware in a virtual private cloud (VPC). For 2017
more information, see Specifying a Tenancy for
Your Spot Instances (p. 312).
IPv6 support 2016-11-15 You can associate an IPv6 CIDR with your VPC and 1
subnets, and assign IPv6 addresses to instances in December
your VPC. For more information, see Amazon EC2 2016
Instance IP Addressing (p. 706).
P2 instances 2016-09-15 P2 instances use NVIDIA Tesla K80 GPUs and are 29
designed for general purpose GPU computing September
using the CUDA or OpenCL programming models. 2016
For more information, see Linux Accelerated
Computing Instances (p. 241).
Automatic scaling for You can now set up scaling policies for your Spot 1
Spot fleet fleet. For more information, see Automatic Scaling September
for Spot Fleet (p. 340). 2016
1065
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Elastic Network Adapter 2016-04-01 You can now use ENA for enhanced networking. 28 June
(ENA) For more information, see Enhanced Networking 2016
Types (p. 751).
Enhanced support for 2016-04-01 You can now view and modify longer ID settings 23 June
viewing and modifying for other IAM users, IAM roles, or the root user. For 2016
longer IDs more information, see Resource IDs (p. 987).
Copy encrypted 2016-04-01 You can now copy encrypted EBS snapshots 21 June
Amazon EBS snapshots between AWS accounts. For more information, see 2016
between AWS accounts Copying an Amazon EBS Snapshot (p. 874).
Capture a screenshot of 2015-10-01 You can now obtain additional information when 24 May
an instance console debugging instances that are unreachable. For 2016
more information, see Capture a Screenshot of an
Unreachable Instance (p. 1053).
Two new EBS volume 2015-10-01 You can now create Throughput Optimized 19 April
types HDD (st1) and Cold HDD (sc1) volumes. For 2016
more information, see Amazon EBS Volume
Types (p. 832).
CloudWatch metrics for You can now get CloudWatch metrics for your 21 March
Spot fleet Spot fleet. For more information, see CloudWatch 2016
Metrics for Spot Fleet (p. 338).
Longer resource IDs 2015-10-01 We're gradually introducing longer length IDs 13 January
for some Amazon EC2 and Amazon EBS resource 2016
types. During the opt-in period, you can enable
the longer ID format for supported resource
types. For more information, see Resource
IDs (p. 987).
1066
Amazon Elastic Compute Cloud
User Guide for Linux Instances
ClassicLink DNS support 2015-10-01 You can enable ClassicLink DNS support for 11 January
your VPC so that DNS hostnames that are 2016
addressed between linked EC2-Classic instances
and instances in the VPC resolve to private
IP addresses and not public IP addresses. For
more information, see Enabling ClassicLink DNS
Support (p. 809).
Spot instance duration 2015-10-01 You can now specify a duration for your Spot 6 October
instances. For more information, see Specifying a 2015
Duration for Your Spot Instances (p. 311).
Spot fleet modify 2015-10-01 You can now modify the target capacity of your 29
request Spot fleet request. For more information, see September
Modifying a Spot Fleet Request (p. 328). 2015
Spot fleet diversified 2015-04-15 You can now allocate Spot instances in multiple 15
allocation strategy Spot pools using a single Spot fleet request. For September
more information, see Allocation Strategy for 2015
Spot Instances (p. 302).
Spot fleet instance 2015-04-15 You can now define the capacity units that each 31 August
weighting instance type contributes to your application's 2015
performance, and adjust your bid price for each
Spot pool accordingly. For more information, see
Spot Fleet Instance Weighting (p. 304).
New reboot alarm Added the reboot alarm action and new IAM role 23 July
action and new IAM for use with alarm actions. For more information, 2015
role for use with alarm see Create Alarms That Stop, Terminate, Reboot,
actions or Recover an Instance (p. 577).
1067
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot fleets 2015-04-15 You can manage a collection, or fleet, of Spot 18 May
instances instead of managing separate Spot 2015
instance requests. For more information, see How
Spot Fleet Works (p. 301).
Migrate Elastic IP 2015-04-15 You can migrate an Elastic IP address that you've 15 May
addresses to EC2- allocated for use in EC2-Classic to be used in 2015
Classic a VPC. For more information, see Migrating an
Elastic IP Address from EC2-Classic (p. 801).
Importing VMs with 2015-03-01 The VM Import process now supports importing 23 April
multiple disks as AMIs VMs with multiple disks as AMIs. For more 2015
information, see Importing a VM as an Image
Using VM Import/Export in the VM Import/Export
User Guide .
1068
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Automatic recovery for You can create an Amazon CloudWatch alarm 12 January
EC2 instances that monitors an Amazon EC2 instance and 2015
automatically recovers the instance if it becomes
impaired due to an underlying hardware failure
or a problem that requires AWS involvement to
repair. A recovered instance is identical to the
original instance, including the instance ID, IP
addresses, and all instance metadata.
Spot instance The best way to protect against Spot instance 5 January
termination notices interruption is to architect your application to be 2015
fault tolerant. In addition, you can take advantage
of Spot instance termination notices, which
provide a two-minute warning before Amazon
EC2 must terminate your Spot instance.
1069
Amazon Elastic Compute Cloud
User Guide for Linux Instances
New EC2 Service Limits Use the EC2 Service Limits page in the Amazon 19 June
page EC2 console to view the current limits for 2014
resources provided by Amazon EC2 and Amazon
VPC, on a per-region basis.
Amazon EBS General 2014-05-01 General Purpose SSD volumes offer cost- 16 June
Purpose SSD Volumes effective storage that is ideal for a broad range 2014
of workloads. These volumes deliver single-digit
millisecond latencies, the ability to burst to 3,000
IOPS for extended periods of time, and a base
performance of 3 IOPS/GiB. General Purpose SSD
volumes can range in size from 1 GiB to 1 TiB. For
more information, see General Purpose SSD (gp2)
Volumes (p. 835).
Amazon EBS encryption 2014-05-01 Amazon EBS encryption offers seamless 21 May
encryption of EBS data volumes and snapshots, 2014
eliminating the need to build and maintain a
secure key management infrastructure. EBS
encryption enables data at rest security by
encrypting your data using Amazon-managed
keys. The encryption occurs on the servers that
host EC2 instances, providing encryption of data
as it moves between EC2 instances and EBS
storage. For more information, see Amazon EBS
Encryption (p. 903).
New Amazon Linux AMI Amazon Linux AMI 2014.03 is released. 27 March
release 2014
1070
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Amazon EC2 Usage Amazon EC2 Usage Reports is a set of reports that 28 January
Reports shows cost and usage data of your usage of EC2. 2014
For more information, see Amazon EC2 Usage
Reports (p. 1007).
Additional M3 instances 2013-10-15 The M3 instance sizes m3.medium and m3.large 20 January
are now supported. For more information about 2014
the hardware specifications for each Amazon EC2
instance type, see Amazon EC2 Instance Types.
Importing Linux virtual 2013-10-15 The VM Import process now supports the 16
machines importation of Linux instances. For more December
information, see the VM Import/Export User 2013
Guide.
Resource-level 2013-10-15 You can now create policies in AWS Identity and 20
permissions for Access Management to control resource-level November
RunInstances permissions for the Amazon EC2 RunInstances 2013
API action. For more information and example
policies, see Controlling Access to Amazon EC2
Resources (p. 621).
Launching an instance You can now launch an instance from the AWS 11
from the AWS Marketplace using the Amazon EC2 launch wizard. November
Marketplace For more information, see Launching an AWS 2013
Marketplace Instance (p. 417).
1071
Amazon Elastic Compute Cloud
User Guide for Linux Instances
New launch wizard There is a new and redesigned EC2 launch wizard. 10
For more information, see Launching an Instance October
Using the Launch Instance Wizard (p. 395). 2013
Modifying Instance 2013-10-01 You can now modify the instance type of Linux 09
Types of Amazon EC2 Reserved Instances within the same family (for October
Reserved Instances example, M1, M2, M3, C1). For more information, 2013
see Modifying Reserved Instances (p. 281).
Modifying Amazon EC2 2013-08-15 You can now modify Reserved Instances in a 11
Reserved Instances region. For more information, see Modifying September
Reserved Instances (p. 281). 2013
Assigning a public IP 2013-07-15 You can now assign a public IP address when 20 August
address you launch an instance in a VPC. For more 2013
information, see Assigning a Public IPv4 Address
During Instance Launch (p. 711).
Granting resource-level 2013-06-15 Amazon EC2 supports new Amazon Resource 8 July
permissions Names (ARNs) and condition keys. For more 2013
information, see IAM Policies for Amazon
EC2 (p. 624).
Incremental Snapshot 2013-02-01 You can now perform incremental snapshot 11 June
Copies copies. For more information, see Copying an 2013
Amazon EBS Snapshot (p. 874).
New Tags page There is a new Tags page in the Amazon EC2 04 April
console. For more information, see Tagging Your 2013
Amazon EC2 Resources (p. 995).
New Amazon Linux AMI Amazon Linux AMI 2013.03 is released. 27 March
release 2013
Additional EBS- 2013-02-01 The following instance types can now be launched 19 March
optimized instance as EBS-optimized instances: c1.xlarge, 2013
types m2.2xlarge, m3.xlarge, and m3.2xlarge.
1072
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Copy an AMI from one 2013-02-01 You can copy an AMI from one region to another, 11 March
region to another enabling you to launch consistent instances in 2013
more than one AWS region quickly and easily.
Launch instances into a 2013-02-01 Your AWS account is capable of launching 11 March
default VPC instances into either EC2-Classic or a VPC, or only 2013
into a VPC, on a region-by-region basis. If you
can launch instances only into a VPC, we create a
default VPC for you. When you launch an instance,
we launch it into your default VPC, unless you
create a nondefault VPC and specify it when you
launch the instance.
High-memory cluster 2012-12-01 Have large amounts of memory coupled with high 21 January
(cr1.8xlarge) instance CPU and network performance. These instances 2013
type are well suited for in-memory analytics, graph
analysis, and scientific computing applications.
High storage 2012-12-01 High storage instances provide very high storage 20
(hs1.8xlarge) density and high sequential read and write December
instance type performance per instance. They are well-suited 2012
for data warehousing, Hadoop/MapReduce, and
parallel file systems.
EBS snapshot copy 2012-12-01 You can use snapshot copies to create backups 17
of data, to create new Amazon EBS volumes, or December
to create Amazon Machine Images (AMIs). For 2012
more information, see Copying an Amazon EBS
Snapshot (p. 874).
Updated EBS metrics 2012-10-01 Updated the EBS metrics to include two new 20
and status checks for metrics for Provisioned IOPS SSD volumes. For November
Provisioned IOPS SSD more information, see Amazon CloudWatch 2012
volumes Metrics for Amazon EBS (p. 942). Also added new
status checks for Provisioned IOPS SSD volumes.
For more information, see EBS Volume Status
Checks (p. 856).
Spot instance request 2012-10-01 Spot instance request status makes it easy to 14
status determine the state of your Spot requests. October
2012
1073
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Provisioned IOPS SSD 2012-07-20 Provisioned IOPS SSD volumes deliver predictable, 31 July
for Amazon EBS high performance for I/O intensive workloads, 2012
such as database applications, that rely
on consistent and fast response times. For
more information, see Amazon EBS Volume
Types (p. 832).
High I/O instances for 2012-06-15 High I/O instances provides very high, low latency, 18 July
Amazon EC2 disk I/O performance using SSD-based local 2012
instance storage.
IAM roles on Amazon 2012-06-01 IAM roles for Amazon EC2 provide: 11 June
EC2 instances 2012
• AWS access keys for applications running on
Amazon EC2 instances.
• Automatic rotation of the AWS access keys on
the Amazon EC2 instance.
• Granular permissions for applications running
on Amazon EC2 instances that make requests to
your AWS services.
Spot instance features You can now manage your Spot instances as 7 June
that make it easier follows: 2012
to get started and
handle the potential of • Place bids for Spot instances using Auto Scaling
interruption. launch configurations, and set up a schedule
for placing bids for Spot instances. For more
information, see Launching Spot Instances in
Your Auto Scaling Group in the Amazon EC2
Auto Scaling User Guide.
• Get notifications when instances are launched
or terminated.
• Use AWS CloudFormation templates to launch
Spot instances in a stack with AWS resources.
EC2 instance export and 2012-05-01 Added support for timestamps on instance status 25 May
timestamps for status and system status to indicate the date and time 2012
checks for Amazon EC2 that a status check failed.
1074
Amazon Elastic Compute Cloud
User Guide for Linux Instances
EC2 instance export, 2012-05-01 Added support for EC2 instance export to Citrix 25 May
and timestamps in Xen, Microsoft Hyper-V, and VMware vSphere. 2012
instance and system
status checks for Added support for timestamps in instance and
Amazon VPC system status checks.
Cluster Compute Eight 2012-04-01 Added support for cc2.8xlarge instances in a 26 April
Extra Large instances VPC. 2012
AWS Marketplace AMIs 2012-04-01 Added support for AWS Marketplace AMIs. 19 April
2012
New Linux AMI release Amazon Linux AMI 2012.03 is released. 28 March
2012
New AKI version We've released AKI version 1.03 and AKIs for the 28 March
AWS GovCloud (US) region. 2012
Medium instances, 2011-12-15 Added support for a new instance type and 64-bit 7 March
support for 64-bit on information. Added procedures for using the Java- 2012
all AMIs, and a Java- based SSH client to connect to Linux instances.
based SSH Client
Reserved Instance 2011-12-15 Added a new section discussing how to take 5 March
pricing tiers advantage of the discount pricing that is built into 2012
the Reserved Instance pricing tiers.
New GRU Region and Added information about the release of new 14
AKIs AKIs for the SA-East-1 Region. This release December
deprecates the AKI version 1.01. AKI version 1.02 2011
will continue to be backward compatible.
New offering types for 2011-11-01 You can choose from a variety of Reserved 01
Amazon EC2 Reserved Instance offerings that address your projected use December
Instances of the instance. 2011
Amazon EC2 instance 2011-11-01 You can view additional details about the status 16
status of your instances, including scheduled events November
planned by AWS that might have an impact 2011
on your instances. These operational activities
include instance reboots required to apply
software updates or security patches, or instance
retirements required where there are hardware
issues. For more information, see Monitoring the
Status of Your Instances (p. 547).
Amazon EC2 Cluster Added support for Cluster Compute Eight Extra 14
Compute Instance Type Large (cc2.8xlarge) to Amazon EC2. November
2011
1075
Amazon Elastic Compute Cloud
User Guide for Linux Instances
New PDX Region and Added information about the release of new AKIs 8
AKIs for the new US-West 2 Region. November
2011
Spot instances in 2011-07-15 Added information about the support for Spot 11
Amazon VPC instances in Amazon VPC. With this update, users October
can launch Spot instances a virtual private cloud 2011
(VPC). By launching Spot instances in a VPC,
users of Spot instances can enjoy the benefits of
Amazon VPC.
New Linux AMI release Added information about the release of Amazon 26
Linux AMI 2011.09. This update removes the beta September
tag from the Amazon Linux AMI, supports the 2011
ability to lock the repositories to a specific version,
and provides for notification when updates are
available to installed packages including security
updates.
Support for importing VM Import can now import virtual machine 24 August
in VHD file format image files in VHD format. The VHD file format 2011
is compatible with the Citrix Xen and Microsoft
Hyper-V virtualization platforms. With this
release, VM Import now supports RAW, VHD and
VMDK (VMware ESX-compatible) image formats.
For more information, see the VM Import/Export
User Guide.
Update to the Amazon Added information about the 1.1 version of the 27 June
EC2 VM Import Amazon EC2 VM Import Connector for VMware 2011
Connector for VMware vCenter virtual appliance (Connector). This update
vCenter includes proxy support for Internet access, better
error handling, improved task progress bar
accuracy, and several bug fixes.
Enabling Linux AMI Added information about the AKI version change 20 June
to run user-provided from 1.01 to 1.02. This version updates the 2011
kernels PVGRUB to address launch failures associated
with t1.micro Linux instances. For more
information, see Enabling Your Own Linux
Kernels (p. 172).
1076
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Spot instances 2011-05-15 Added information about the Spot instances 26 May
Availability Zone pricing Availability Zone pricing feature. In this release, 2011
changes we've added new Availability Zone pricing options
as part of the information returned when you
query for Spot instance requests and Spot
price history. These additions make it easier to
determine the price required to launch a Spot
instance into a particular Availability Zone.
AWS Identity and Added information about AWS Identity and 26 April
Access Management Access Management (IAM), which enables users to 2011
specify which Amazon EC2 actions a user can use
with Amazon EC2 resources in general. For more
information, see Controlling Access to Amazon
EC2 Resources (p. 621).
Enabling Linux AMI Added information about enabling a Linux AMI to 26 April
to run user-provided use PVGRUB Amazon Kernel Image (AKI) to run a 2011
kernels user-provided kernel. For more information, see
Enabling Your Own Linux Kernels (p. 172).
New Amazon Linux The new Amazon Linux reference AMI replaces 15 March
reference AMI the CentOS reference AMI. Removed information 2011
about the CentOS reference AMI, including
the section named Correcting Clock Drift for
Cluster Instances on CentOS 5.4 AMI. For more
information, see AMIs for GPU-Based Accelerated
Computing Instances (p. 245).
1077
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Amazon EC2 VM Import Added information about the Amazon EC2 VM 3 March
Connector for VMware Import Connector for VMware vCenter virtual 2011
vCenter appliance (Connector). The Connector is a plug-in
for VMware vCenter that integrates with VMware
vSphere Client and provides a graphical user
interface that you can use to import your VMware
virtual machines to Amazon EC2.
Force volume You can now use the AWS Management Console 23
detachment to force the detachment of an Amazon EBS February
volume from an instance. For more information, 2011
see Detaching an Amazon EBS Volume from an
Instance (p. 864).
Instance termination You can now use the AWS Management Console 23
protection to prevent an instance from being terminated. February
For more information, see Enabling Termination 2011
Protection for an Instance (p. 481).
Correcting Clock Drift Added information about how to correct clock 25 January
for Cluster Instances on drift for cluster instances running on Amazon's 2011
CentOS 5.4 AMI CentOS 5.4 AMI.
Basic monitoring for 2010-08-31 Added information about basic monitoring for 12
instances EC2 instances. December
2010
Filters and Tags 2010-08-31 Added information about listing, filtering, and 19
tagging resources. For more information, see September
Listing and Filtering Your Resources (p. 992) and 2010
Tagging Your Amazon EC2 Resources (p. 995).
AWS Identity and Amazon EC2 now integrates with AWS Identity 2
Access Management for and Access Management (IAM). For more September
Amazon EC2 information, see Controlling Access to Amazon 2010
EC2 Resources (p. 621).
1078
Amazon Elastic Compute Cloud
User Guide for Linux Instances
Cluster instances 2010-06-15 Amazon EC2 offers cluster compute instances for 12 July
high-performance computing (HPC) applications. 2010
For more information about the hardware
specifications for each Amazon EC2 instance type,
see Amazon EC2 Instance Types.
Amazon VPC IP Address 2010-06-15 Amazon VPC users can now specify the IP address 12 July
Designation to assign an instance launched in a VPC. 2010
1079
Amazon Elastic Compute Cloud
User Guide for Linux Instances
AWS Glossary
For the latest AWS terminology, see the AWS Glossary in the AWS General Reference.
1080