# Storage options for your Amazon EC2 instances 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. **Block storage** + [Amazon EBS](https://docs.aws.amazon.com/ebs/latest/userguide/) — Amazon EBS provides durable, block-level storage volumes that you can attach and detach from your instances. You can attach multiple EBS volumes to an instance. An EBS volume persists independently from the life of its associated instance. You can encrypt your EBS volumes. To keep a backup copy of your data, you can create snapshots from your EBS volumes. Snapshots are stored in Amazon S3. You can create an EBS volume from a snapshot. + [Instance store temporary block storage for EC2 instances](InstanceStorage.md) — Instance store provides temporary block-level storage for instances. The number, size, and type of instance store volumes are determined by the instance type and instance size. The data on an instance store volume persists only during the life of the associated instance; if you stop, hibernate, or terminate an instance, any data on instance store volumes is lost. **Object storage** + [Amazon S3](AmazonS3.md) — 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 Amazon S3-backed AMIs. **File storage** + [Amazon EFS](AmazonEFS.md) (Linux instances only) — 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. + [Amazon FSx](storage_fsx.md) — With Amazon FSx, you can launch, run, and scale feature-rich, high-performance file systems in the cloud. Amazon FSx is a fully-managed service that supports a wide range of workloads. You can choose between these widely-used file systems: Lustre, NetApp ONTAP, OpenZFS, and Windows File Server. **File caching** + [Use Amazon File Cache with Amazon EC2 instances](AmazonEFC.md) — Amazon File Cache provides temporary, high-performance cache on AWS for processing file data. The cache provides read and write data access to compute workloads on Amazon EC2 with sub-millisecond latencies, up to hundreds of GB/s of throughput, and up to millions of IOPS. The following figure shows the relationship between these storage options and your instance. ![\[Storage options for Amazon EC2\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/architecture_storage.png) ## AWS Storage pricing Open [AWS Pricing](https://aws.amazon.com/pricing/), scroll to **Pricing for AWS products** and select **Storage**. Choose the storage product to open its pricing page. # Amazon EBS persistent block storage for Amazon EC2 instances Amazon Elastic Block Store (Amazon EBS) provides scalable, high-performance block storage resources that can be used with Amazon EC2 instances. With Amazon EBS, you can create and manage the following block storage resources: + **Amazon EBS volumes** — These are storage volumes that you attach to Amazon EC2 instances. After you attach a volume to an instance, you can use it in the same way you would use block storage. The instance can interact with the volume just as it would with a local drive. + **Amazon EBS snapshots** — These are point-in-time backups of Amazon EBS volumes that persist independently from the volume itself. You can create snapshots to back up the data on your Amazon EBS volumes. You can then restore new volumes from those snapshots at any time. You can create and attach EBS volumes to an instance during launch, and you can create and attach EBS volumes to an instance at any time after launch. You can also increase the size or performance of your EBS volumes without detaching the volume or restarting your instance. You can create EBS snapshots from an EBS volume at any time after creation. You can use EBS snapshots to back up the data stored on your volumes. You can then use those snapshots to instantly restore volumes, or to migrate data across AWS accounts, AWS Regions, or Availability Zones. You can use Amazon Data Lifecycle Manager or AWS Backup to automate the creation, retention, and deletion of your EBS snapshots. A *managed EBS volume* is managed by a service provider, such as Amazon EKS Auto Mode. You can’t directly modify the settings of a managed EBS volume. Managed EBS volumes are identified by a **true** value in the **Managed** field. For more information, see [Amazon EC2 managed instances](amazon-ec2-managed-instances.md). For more information about working with volumes and snapshots, see the [Amazon EBS User Guide](https://docs.aws.amazon.com/ebs/latest/userguide/what-is-ebs.html). # Amazon EBS volume limits for Amazon EC2 instances The maximum number of Amazon EBS volumes that you can attach to an instance depends on the instance type and instance size. If you exceed the volume attachment limit for an instance, the attachment request fails with the `AttachmentLimitExceeded` error. When considering how many volumes to attach to your instance, you should consider whether you need increased I/O bandwidth or increased storage capacity. **Bandwidth versus capacity** For consistent and predictable bandwidth use cases, use Amazon EBS-optimized instances with General Purpose SSD volumes or Provisioned IOPS SSD volumes. For maximum performance, match the IOPS you have provisioned for your volumes with the bandwidth available for your instance type. For RAID configurations, you might find that arrays larger than 8 volumes have diminished performance returns due to increased I/O overhead. Test your individual application performance and tune it as required. **Contents** + [Volume limits for instances built on the Nitro System](#nitro-system-limits) + [Dedicated EBS volume limit](#dedicated-limit) + [Shared EBS volume limit](#shared-limit) + [Volume limits for Xen-based instances](#xen-limits) + [Linux instances](#linux-specific-volume-limits) + [Windows instances](#windows-specific-volume-limits) ## Volume limits for instances built on the Nitro System The volume limits for instances built on the Nitro System depend on the instance type. Some Nitro instance types have a **dedicated EBS volume limit**, while most have a **shared volume limit**. To view the volume attachment limits for each instance type, see the following: + [Amazon EBS specifications – General purpose](https://docs.aws.amazon.com/ec2/latest/instancetypes/gp.html#gp_storage-ebs) + [Amazon EBS specifications – Compute optimized](https://docs.aws.amazon.com/ec2/latest/instancetypes/co.html#co_storage-ebs) + [Amazon EBS specifications – Memory optimized](https://docs.aws.amazon.com/ec2/latest/instancetypes/mo.html#mo_storage-ebs) + [Amazon EBS specifications – Storage optimized](https://docs.aws.amazon.com/ec2/latest/instancetypes/so.html#so_storage-ebs) + [Amazon EBS specifications – Accelerated computing](https://docs.aws.amazon.com/ec2/latest/instancetypes/ac.html#ac_storage-ebs) + [Amazon EBS specifications – High-performance computing](https://docs.aws.amazon.com/ec2/latest/instancetypes/hpc.html#hpc_storage-ebs) + [Amazon EBS specifications – Previous generation](https://docs.aws.amazon.com/ec2/latest/instancetypes/pg.html#pg_storage-ebs) ### Dedicated EBS volume limit The following Nitro instance types have a dedicated EBS volume limit that varies depending on instance size. The limit is not shared with other device attachments. In other words, you can attach any number of EBS volumes up to the volume attachment limit, regardless of the number of attached devices, such as NVMe instance store volumes and network interfaces. + **General purpose:** M7a \$1 M7i \$1 M7i-flex \$1 M8a \$1 M8azn \$1 M8g \$1 M8gb \$1 M8gd \$1 M8gn \$1 M8i \$1 M8id \$1 M8i-flex + **Compute optimized:** C7a \$1 C7i \$1 C7i-flex \$1 C8a \$1 C8g \$1 C8gb \$1 C8gd \$1 C8gn \$1 C8i \$1 C8ib \$1 C8id \$1 C8in \$1 C8i-flex + **Memory optimized:** R7a \$1 R7i \$1 R7iz \$1 R8a \$1 R8g \$1 R8gb \$1 R8gd \$1 R8gn \$1 R8i \$1 R8id \$1 R8i-flex \$1 U7i-6tb \$1 U7i-8tb \$1 U7i-12tb \$1 U7in-16tb \$1 U7in-24tb \$1 U7in-32tb \$1 U7inh-32tb \$1 X8g \$1 X8aedz \$1 X8i + **Storage optimized:** I7i \$1 I7ie \$1 I8g \$1 I8ge + **Accelerated computing:** F2 \$1 G6 \$1 G6e \$1 G6f \$1 Gr6 \$1 Gr6f \$1 G7e \$1 P4d \$1 P4de \$1 P5 \$1 P5e \$1 P5en \$1 P6-B200 \$1 P6-B300 \$1 P6e-GB200 \$1 Trn2 \$1 Trn2u + **High performance computing:** Hpc7a \$1 Hpc8a ### Shared EBS volume limit All other Nitro instance types (not listed in [Dedicated EBS volume limit](#dedicated-limit)) have a volume attachment limit that is shared between Amazon EBS volumes, network interfaces, and NVMe instance store volumes. You can attach any number of Amazon EBS volumes up to that limit, less the number of attached network interfaces and NVMe instance store volumes. Keep in mind that every instance must have at least one network interface, and that NVMe instance store volumes are automatically attached at launch. Most Nitro instances support a maximum of 28 attachments. The following examples demonstrate how to calculate how many EBS volumes you can attach. **Examples** + With an `m5.xlarge` instance with only the primary network interface, you can attach 27 EBS volumes. 28 volumes - 1 network interface = 27 + With an `m5.xlarge` instance with two additional network interfaces, you can attach 25 EBS volumes. 28 volumes - 3 network interfaces = 25 + With an `m5d.xlarge` instance with two additional network interfaces, you can attach 24 EBS volumes. 28 volumes - 3 network interfaces - 1 NVMe instance store volume = 24 ## Volume limits for Xen-based instances The volume limits for Xen-based instances, such as T2, depend on the operating system. For more information, see [Xen-based instances](instance-types.md#instance-hypervisor-type). ### Linux instances Attaching more than 40 volumes to a Xen-based Linux instance can cause boot failures. This number includes the root volume, plus any attached instance store volumes and Amazon EBS volumes. If you experience boot problems on an instance with a large number of volumes, stop the instance, detach any volumes that are not essential to the boot process, start the instance, and then reattach the volumes after the instance is running. **Important** Attaching more than 40 volumes to a Xen-based Linux instance is supported on a best effort basis only and is not guaranteed. ### Windows instances The following table shows the volume limits for Xen-based Windows instances based on the driver used. That these numbers include the root volume, plus any attached instance store volumes and Amazon EBS volumes. | Driver | Volume Limit | | --- | --- | | AWS PV | 26 | | Citrix PV | 26 | | Red Hat PV | 17 | We recommend that you do not that attach more than 26 volumes to a Xen-based Windows instance with AWS PV or Citrix PV drivers, as it is likely to cause performance issues. To determine which PV drivers your instance is using, or to upgrade your Windows instance from Red Hat to Citrix PV drivers, see [Upgrade PV drivers on EC2 Windows instances](Upgrading_PV_drivers.md). **Important** Attaching more than the following number of volumes to a Xen-based Windows instance is supported on a best effort basis only and is not guaranteed. For more information about how device names are related to volumes, see [How volumes are attached and mapped for Amazon EC2 Windows instances](ec2-windows-volumes.md). # EBS cards Most instance types support one EBS card. Instance types that support multiple EBS cards provide higher EBS-optimized performance, both in EBS throughput and IOPS. Your Amazon EC2 instance maximum performance is spread equally across each EBS card. For example, on an EC2 instance that supports `1,000,000` total IOPS with 2 EBS cards, each EBS card can support up to `500,000` IOPS. For information about the supported Amazon EBS performance of your Amazon EC2 instance, see [Amazon EBS-optimized instance types](ebs-optimized.md). When you attach an Amazon EBS volume to an instance that supports multiple EBS cards, you can select the EBS card for the volume by specifying the EBS card index. The root volume must be attached to EBS card index 0. ## Instance types with multiple EBS cards The following instance types support multiple EBS cards. For information about the number of Amazon EBS volumes that an instance type supports, see [Amazon EBS volume limits for Amazon EC2 instances](volume_limits.md). | Instance Type | Number of EBS cards | | --- | --- | | General Purpose | | m8gb.48xlarge | 2 | | m8gb.metal-48xl | 2 | | m8gn.48xlarge | 2 | | m8gn.metal-48xl | 2 | | Compute Optimized | | c8gb.48xlarge | 2 | | c8gb.metal-48xl | 2 | | c8gn.48xlarge | 2 | | c8gn.metal-48xl | 2 | | c8ib.96xlarge | 2 | | c8ib.metal-96xl | 2 | | c8in.96xlarge | 2 | | c8in.metal-96xl | 2 | | Memory Optimized | | r8gb.48xlarge | 2 | | r8gb.metal-48xl | 2 | | r8gn.48xlarge | 2 | | r8gn.metal-48xl | 2 | # Instance store temporary block storage for EC2 instances An *instance store* provides temporary block-level storage for your EC2 instance. This storage is provided by disks that are physically attached to the host computer. Instance store is ideal for temporary storage of information that changes frequently, such as buffers, caches, scratch data, and other temporary content. It can also be used to store temporary data that you replicate across a fleet of instances, such as a load-balanced pool of web servers. 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 and instance size. For example, not every instance type provides instance store volumes. For more information, see [Instance store volume limits for EC2 instances](instance-store-volumes.md). The virtual devices for instance store volumes are given virtual device names in order from `ephemeral0` to `ephemeral23`. For example, with an instance type that supports one instance store volume, the virtual device name of the one volume is `ephemeral0`. With an instance type that supports four instance store volumes, the virtual device names of the four volumes are as follows: `ephemeral0`, `ephemeral1`, `ephemeral2` and `ephemeral3`. ![\[Amazon EC2 instance storage\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/instance_storage.png) **Instance store pricing** There is no additional charge to use the instance store volumes provided for your instance. Instance store volumes are included as part of the usage cost of the instance. **Topics** + [Data persistence for Amazon EC2 instance store volumes](instance-store-lifetime.md) + [Instance store volume limits for EC2 instances](instance-store-volumes.md) + [SSD instance store volumes for EC2 instances](ssd-instance-store.md) + [Add instance store volumes to an EC2 instance](add-instance-store-volumes.md) + [Enable instance store swap volume for M1 and C1 EC2 instances](instance-store-swap-volumes.md) + [Initialize instance store volumes on EC2 instances](disk-performance.md) + [Detailed performance statistics for Amazon EC2 instance store volumes](nvme-detailed-performance-stats.md) # Data persistence for Amazon EC2 instance store volumes Instance store volumes are attached only at instance launch. You can't attach instance store volumes after launch. You can’t detach an instance store volume from one instance and attach it to a different instance. An instance store volume exists only during the lifetime of the instance to which it is attached. You can’t configure an instance store volume to persist beyond the lifetime of its associated instance. The data on an instance store volume persists even if the instance is rebooted. However, the data does not persist if the instance is stopped, hibernated, or terminated. When the instance is stopped, hibernated, or terminated, every block of the instance store volume is cryptographically erased. Therefore, do not rely on instance store volumes for valuable, long-term data. If you need to retain the data stored on an instance store volume beyond the lifetime of the instance, you need to manually copy that data to more persistent storage, such as an Amazon EBS volume, an Amazon S3 bucket, or an Amazon EFS file system. There are some events that can result in your data not persisting throughout the lifetime of the instance. The following table indicates whether data on instance store volumes is persisted during specific events, for both virtualized and bare metal instances. | Event | What happens to your data? | | --- |--- | | **User-initiated instance lifecycle events** | | --- | | [The instance is rebooted](ec2-instance-reboot.md) | The data persists | | [The instance is stopped](Stop_Start.md) | The data does not persist | | [The instance is hibernated](Hibernate.md) | The data does not persist | | [The instance is terminated](terminating-instances.md) | The data does not persist | | [The instance type is changed](ec2-instance-resize.md) | The data does not persist \$1 | | [An EBS-backed AMI is created from the instance](creating-an-ami-ebs.md) | The data does not persist in the created AMI \$1\$1 | | [An Amazon S3-backed AMI is created from the instance](creating-an-ami-instance-store.md) (Linux instances) | The data persists in the AMI bundle uploaded to Amazon S3 \$1\$1\$1 | | **User-initiated OS events** | | --- | | A shutdown is initiated | The data does not persist † | | A restart is initiated | The data persists | | **AWS scheduled events** | | --- | | [Instance stop](schedevents_actions_retire.md) | The data does not persist | | [Instance reboot](schedevents_actions_reboot.md) | The data persists | | [System reboot](schedevents_actions_reboot.md) | The data persists | | [Instance retirement](schedevents_actions_retire.md) | The data does not persist | | **Unplanned events** | | --- | | [Simplified automatic recovery](instance-configuration-recovery.md) | The data does not persist | | [CloudWatch action based recovery](cloudwatch-recovery.md) | The data does not persist | | The underlying disk fails | The data on the failed disk does not persist | | Power failure | The data persists upon reboot | \$1 If the new instance type supports instance store, the instance gets the number of instance store volumes supported by the new instance type, but the data does not transfer to the new instance. If the new instance type does not support instance store, the instance does not get the instance store volumes. \$1\$1 The data is not included in the EBS-backed AMI, and it is not included on instance store volumes attached to instances launched from that AMI. \$1\$1\$1 The data is included in the AMI bundle that is uploaded to Amazon S3. When you launch an instance from that AMI, the instance gets the instance store volumes bundled in the AMI with the data they contained at the time the AMI was created. † Termination protection and stop protection do not protect instances against instance stops or terminations as a result of shutdowns initiated through the operating system on the instance. Data stored on instance store volumes does not persist in both instance stop and termination events. # Instance store volume limits for EC2 instances The number, size, and type of instance store volumes are determined by the instance type. Some instance types, such as C8i, M8i, and R8i, do not support instance store volumes, while other instance types, such as C8id, M8id, and R8id, do support instance store volumes. You can’t attach more instance store volumes to an instance than is supported by its instance type. For the instance types that do support instance store volumes, the number and size of the instance store volumes vary by instance size. For example, `r8id.large` supports 1 x 118 GB instance store volume, while `r8id.32xlarge` supports 2 x 3800 GB instance store volumes. For instance types with **NVMe instance store volumes**, all of the supported instance store volumes are automatically attached to the instance at launch. For instance types with **non-NVMe instance store volumes**, such as C1, C3, M1, M2, M3, R3, D2, H1, I2, X1, and X1e, you must manually specify the block device mappings for the instance store volumes that you want to attach at launch. Then, after the instance has launched, you must [ format and mount the attached instance store volumes](making-instance-stores-available-on-your-instances.md) before you can use them. You can't attach an instance store volume after you launch the instance. Some instance types use NVMe or SATA-based solid state drives (SSD), while others use SATA-based hard disk drives (HDD). SSDs deliver high random I/O performance 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 for EC2 instances](ssd-instance-store.md). The data on NVMe instance store volumes and some HDD instance store volumes is encrypted at rest. For more information, see [Data protection in Amazon EC2](data-protection.md). ## Available instance store volumes The *Amazon EC2 Instance Types Guide* provides the quantity, size, type, and performance optimizations of instance store volumes available on each supported instance type. For more information, see the following: + [Instance store specifications – General purpose](https://docs.aws.amazon.com/ec2/latest/instancetypes/gp.html#gp_instance-store) + [Instance store specifications – Compute optimized](https://docs.aws.amazon.com/ec2/latest/instancetypes/co.html#co_instance-store) + [Instance store specifications – Memory optimized](https://docs.aws.amazon.com/ec2/latest/instancetypes/mo.html#mo_instance-store) + [Instance store specifications – Storage optimized](https://docs.aws.amazon.com/ec2/latest/instancetypes/so.html#so_instance-store) + [Instance store specifications – Accelerated computing](https://docs.aws.amazon.com/ec2/latest/instancetypes/ac.html#ac_instance-store) + [Instance store specifications – High-performance computing](https://docs.aws.amazon.com/ec2/latest/instancetypes/hpc.html#hpc_instance-store) + [Instance store specifications – Previous generation](https://docs.aws.amazon.com/ec2/latest/instancetypes/pg.html#pg_instance-store) ------ #### [ Console ] **To retrieve instance store volume information** 1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. In the navigation pane, choose **Instance Types**. 1. Add the filter **Local instance storage = true**. The **Storage** column indicates the total size of the instance storage for the instance type. 1. (Optional) Click the **Preferences** icon and then turn on **Storage disk count**. This column indicates the number of instance store volumes. 1. (Optional) Add filters to further scope to specific instance types of interest. ------ #### [ AWS CLI ] **To retrieve instance store volume information** Use the [describe-instance-types](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instance-types.html) command. The following example displays the total size of the instance storage for each instance type in the R8i instance families with instance store volumes. ``` aws ec2 describe-instance-types \ --filters "Name=instance-type,Values=r8i*" "Name=instance-storage-supported,Values=true" \ --query 'sort_by(InstanceTypes, &InstanceStorageInfo.TotalSizeInGB)[].{InstanceType:InstanceType,TotalSizeInGB:InstanceStorageInfo.TotalSizeInGB}' \ --output table ``` The following is example output. ``` -------------------------------------- | DescribeInstanceTypes | +------------------+-----------------+ | InstanceType | TotalSizeInGB | +------------------+-----------------+ | r8id.large | 118 | | r8id.xlarge | 237 | | r8id.2xlarge | 474 | | r8id.4xlarge | 950 | | r8id.8xlarge | 1900 | | r8id.12xlarge | 2850 | | r8id.16xlarge | 3800 | | r8id.24xlarge | 5700 | | r8id.32xlarge | 7600 | | r8id.48xlarge | 11400 | | r8id.metal-48xl | 11400 | | r8id.96xlarge | 22800 | | r8id.metal-96xl | 22800 | +------------------+-----------------+ ``` **To get complete instance storage details for an instance type** Use the [describe-instance-types](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instance-types.html) command. ``` aws ec2 describe-instance-types \ --filters "Name=instance-type,Values=r8id.32xlarge" \ --query 'InstanceTypes[0].InstanceStorageInfo' \ --output json ``` The example output shows that this instance type has two 3800 GB NVMe SSD volumes, for a total of 7600 GB of instance storage. ``` { "TotalSizeInGB": 7600, "Disks": [ { "SizeInGB": 3800, "Count": 2, "Type": "ssd" } ], "NvmeSupport": "required", "EncryptionSupport": "required" } ``` ------ #### [ PowerShell ] **To retrieve instance store volume information** Use the [Get-EC2InstanceType](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2InstanceType.html) cmdlet. The following example displays the total size of the instance storage for each instance type in the R8i instance families with instance store volumes. ``` (Get-EC2InstanceType -Filter ` @{Name="instance-type"; Values="r8i*"}, @{Name="instance-storage-supported"; Values="true"}) | Sort-Object {$_.InstanceStorageInfo.TotalSizeInGB} | Format-Table InstanceType, @{Name="Disks.SizeInGB";Expression={$_.InstanceStorageInfo.Disks[0].SizeInGB}}, @{Name="Disks.Count";Expression={$_.InstanceStorageInfo.Disks[0].Count}}, @{Name="TotalSizeInGB";Expression={$_.InstanceStorageInfo.TotalSizeInGB}} ``` The following is example output. ``` InstanceType Disks.SizeInGB Disks.Count TotalSizeInGB ------------ -------------- ----------- ------------- r8id.large 118 1 118 r8id.xlarge 237 1 237 r8id.2xlarge 474 1 474 r8id.4xlarge 950 1 950 r8id.8xlarge 1900 1 1900 r8id.12xlarge 2850 1 2850 r8id.16xlarge 3800 1 3800 r8id.24xlarge 2850 2 5700 r8id.32xlarge 3800 2 7600 r8id.48xlarge 3800 3 11400 r8id.metal-48xl 3800 3 11400 r8id.96xlarge 3800 6 22800 r8id.metal-96xl 3800 6 22800 ``` **To get complete instance storage details for an instance type** Use the [Get-EC2InstanceType](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2InstanceType.html) cmdlet. ``` (Get-EC2InstanceType ` -Filter @{Name="instance-type"; Values="r8id.32xlarge"}).InstanceStorageInfo | Format-List *, @{Name="Disks.Count";Expression={$_.Disks[0].Count}}, @{Name="Disks.SizeInGB";Expression={$_.Disks[0].SizeInGB}}, @{Name="Disks.Type";Expression={$_.Disks[0].Type.Value}} ``` The example output shows that this instance type has two 3800 GB NVMe SSD volumes, for a total of 7600 GB of instance storage. ``` Disks : {Amazon.EC2.Model.DiskInfo} EncryptionSupport : required NvmeSupport : required TotalSizeInGB : 7600 Disks.Count : 2 Disks.SizeInGB : 3800 Disks.Type : ssd ``` ------ # SSD instance store volumes for EC2 instances 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 an EC2 instance](add-instance-store-volumes.md). ## NVMe SSD volumes Some instances offer non-volatile memory express (NVMe) solid state drives (SSD) instance store volumes. For more information about the type of instance store volume supported by each instance type, see [Instance store volume limits for EC2 instances](instance-store-volumes.md). 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. ### Linux instances To access NVMe volumes, the NVMe drivers must be installed. The following AMIs meet this requirement: + AL2023 + Amazon Linux 2 + Amazon Linux AMI 2018.03 and later + Ubuntu 14.04 or later with `linux-aws` kernel **Note** AWS Graviton-based instance types require Ubuntu 18.04 or later with `linux-aws` kernel + Red Hat Enterprise Linux 7.4 or later + SUSE Linux Enterprise Server 12 SP2 or later + CentOS 7.4.1708 or later + FreeBSD 11.1 or later + Debian GNU/Linux 9 or later + Bottlerocket 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. ``` [ec2-user ~]$ lspci 00:00.0 Host bridge: Intel Corporation 440FX - 82441FX PMC [Natoma] (rev 02) 00:01.0 ISA bridge: Intel Corporation 82371SB PIIX3 ISA [Natoma/Triton II] 00:01.1 IDE interface: Intel Corporation 82371SB PIIX3 IDE [Natoma/Triton II] 00:01.3 Bridge: Intel Corporation 82371AB/EB/MB PIIX4 ACPI (rev 01) 00:02.0 VGA compatible controller: Cirrus Logic GD 5446 00:03.0 Ethernet controller: Device 1d0f:ec20 00:17.0 Non-Volatile memory controller: Device 1d0f:cd01 00:18.0 Non-Volatile memory controller: Device 1d0f:cd01 00:19.0 Non-Volatile memory controller: Device 1d0f:cd01 00:1a.0 Non-Volatile memory controller: Device 1d0f:cd01 00:1f.0 Unassigned class [ff80]: XenSource, Inc. Xen Platform Device (rev 01) ``` 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 ``` $ lsmod | grep nvme nvme 48813 0 ``` + Ubuntu 18 ``` $ cat /lib/modules/$(uname -r)/modules.builtin | grep nvme s/nvme/host/nvme-core.ko kernel/drivers/nvme/host/nvme.ko kernel/drivers/nvmem/nvmem_core.ko ``` 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. ### Windows instances The latest AWS Windows AMIs for the following operating systems contain the AWS NVMe drivers used to interact with SSD instance store volumes that are exposed as NVMe block devices for better performance: + Windows Server 2025 + Windows Server 2022 + Windows Server 2019 + Windows Server 2016 + Windows Server 2012 R2 After you connect to your instance, you can verify that you see the NVMe volumes in Disk Manager. On the taskbar, open the context (right-click) menu for the Windows logo and choose **Disk Management**. The AWS Windows AMIs provided by Amazon include the AWS NVMe driver. If you are not using the latest AWS Windows AMIs, you can [install the current AWS NVMe driver](aws-nvme-drivers.md). ## Non-NVMe SSD volumes The following instances support instance store volumes that use non-NVMe SSDs to deliver high random I/O performance: C3, I2, M3, R3, and X1. For more information about the instance store volumes supported by each instance type, see [Instance store volume limits for EC2 instances](instance-store-volumes.md). ## SSD-based instance store volume I/O performance 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 do not have any space reserved for over-provisioning. To reduce write amplification, we recommend that you leave 10 percent 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 have 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](#InstanceStoreTrimSupport). ## Instance store volume TRIM support Some instance types support SSD volumes with TRIM. For more information, see [Instance store volume limits for EC2 instances](instance-store-volumes.md). **Note** (Windows instances only) Instances running Windows Server 2012 R2 support TRIM as of AWS PV Driver version 7.3.0. Instances running earlier versions of Windows Server do not support TRIM. 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. (Windows instances) To temporarily disable TRIM support during initial formatting, use the `fsutil behavior set DisableDeleteNotify 1` command. After formatting is complete, re-enable TRIM support by using `fsutil behavior set DisableDeleteNotify 0`. 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 instances**, use the `fstrim` command to enable periodic TRIM. On **Windows instances**, use the `fsutil behavior set DisableDeleteNotify 0` command to ensure TRIM support is enabled during normal operation. # Add instance store volumes to an EC2 instance For instance types with **NVMe instance store volumes**, all of the supported instance store volumes are automatically attached to the instance at launch. They are automatically enumerated and assigned a device name on instance launch. For instance types with **non-NVMe instance store volumes**, such as C1, C3, M1, M2, M3, R3, D2, H1, I2, X1, and X1e, you must manually specify the block device mappings for the instance store volumes that you want to attach at launch. Block device mappings can be specified in the instance launch request or in the AMI used to launch the instance. The block device mapping includes a device name and the volume that it maps to. For more information, see [Block device mappings for volumes on Amazon EC2 instances](block-device-mapping-concepts.md) **Important** Instance store volumes can be attached to an instance only when you launch it. You can't attach instance store volumes to an instance after you've launched it. After you launch an instance, you must ensure that the instance store volumes for your instance are formatted and mounted before you can use them. The instance store root volume is mounted automatically. **Consideration for root volumes** A block device mapping always specifies the root volume for the instance. The root volume is always mounted automatically. **Linux instances** – The root volume is either an Amazon EBS volume or an instance store volume. 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. For more information, see [Root volume type](ComponentsAMIs.md#storage-for-the-root-device). **Windows instances** – The root volume must be an Amazon EBS volume. Instance store is not supported for the root volume. **Topics** + [Add instance store volumes to an Amazon EC2 AMI](adding-instance-storage-ami.md) + [Add instance store volumes to an EC2 instance during launch](adding-instance-storage-instance.md) + [Make instance store volume available for use on an EC2 instance](making-instance-stores-available-on-your-instances.md) # Add instance store volumes to an Amazon EC2 AMI You can create an AMI with a block device mapping that includes instance store volumes. If you launch an instance that supports **non-NVMe instance store volumes** using an AMI that specifies instance store volume block device mappings, the instance includes the instance store volumes. If the number of instance store volume block device mappings in the AMI exceeds the number of instance store volumes available to the instance, the additional instance store volume block device mappings are ignored. If you launch an instance that supports **NVMe instance store volumes** using an AMI that specifies instance store volume block device mappings, the instance store volume block device mappings are ignored. Instances that support NVMe instance store volumes get all of their supported instance store volumes, regardless of the block device mappings specified in the instance launch request and the AMI. The device mapping of these volumes depends on the order in which the operating system enumerates the volumes. **Considerations** + The number of available instance store volumes depends on the instance type. For more information, see [Available instance store volumes](instance-store-volumes.md#available-instance-store-volumes). + You must specify a device name for each block device. For more information, see [Device names for volumes on Amazon EC2 instances](device_naming.md). + When you launch an instance, you can omit non-NVMe instance store volumes specified in the AMI block device mapping or add instance store volumes. + For M3 instances, specify instance store volumes in the block device mapping of the instance, not the AMI. Amazon EC2 might ignore instance store volume block device mappings in the AMI. ------ #### [ Console ] **To add instance store volumes to an Amazon EBS-backed AMI** 1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. In the navigation pane, choose **Instances** and select the instance. 1. Choose **Actions**, **Image and templates**, **Create image**. 1. On the **Create image** page, enter a meaningful name and description for your image. 1. For each instance store volume to add, choose **Add volume**, from **Volume type** select an instance store volume, and from **Device** select a device name. 1. Choose **Create image**. ------ #### [ AWS CLI ] **To add instance store volumes to an AMI** Use the [create-image](https://docs.aws.amazon.com/cli/latest/reference/ec2/create-image.html) command with the `--block-device-mappings` option to specify a block device mapping for an EBS-backed AMI. Use the [register-image](https://docs.aws.amazon.com/cli/latest/reference/ec2/register-image.html) command with the `--block-device-mappings` option to specify a block device mapping for an iAmazon S3-backed AMI. ``` --block-device-mappings file://mapping.json ``` The following block device mapping adds two instance store volumes. ``` [ { "DeviceName": "/dev/sdc", "VirtualName": "ephemeral0" }, { "DeviceName": "/dev/sdd", "VirtualName": "ephemeral1" } ] ``` ------ #### [ PowerShell ] **To add instance store volumes to an AMI** Use the [New-EC2Image](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2Image.html) cmdlet with the `-BlockDeviceMapping` parameter to specify a block device mapping for an EBS-backed AMI. Use the [Register-EC2Image](https://docs.aws.amazon.com/powershell/latest/reference/items/Register-EC2Image.html) cmdlet with the `-BlockDeviceMapping` parameter to specify a block device mapping for an Amazon S3-backed AMI. ``` -BlockDeviceMapping $bdm ``` The following block device mapping adds two instance store volumes. ``` $bdm = @() $sdc = New-Object -TypeName Amazon.EC2.Model.BlockDeviceMapping $sdc.DeviceName = "/dev/sdc" $sdc.VirtualName = "ephemeral0" $bdm += $sdc $sdd = New-Object -TypeName Amazon.EC2.Model.BlockDeviceMapping $sdd.DeviceName = "/dev/sdd" $sdd.VirtualName = "ephemeral1" $bdm += $sdd ``` ------ # Add instance store volumes to an EC2 instance during launch When you launch an instance type with **non-NVMe instance store volumes**, such as C1, C3, M1, M2, M3, R3, D2, H1, I2, X1, and X1e, you must specify the block device mappings for the instance store volumes that you want to attach at launch. The block device mappings must be specified in the instance launch request or in the AMI used to launch the instance. If the AMI includes block device mappings for the instance store volumes, you do not need to specify block device mappings in the instance launch request, unless you need more instance store volumes than is included in the AMI. If the AMI does not include block device mappings for instance store volumes, then you must specify the block device mappings in the instance launch request. For instance types with NVMe instance store volumes, all of the supported instance store volumes are automatically attached to the instance at launch. **Considerations** + The number of available instance store volumes depends on the instance type. For more information, see [Available instance store volumes](instance-store-volumes.md#available-instance-store-volumes). + You must specify a device name for each block device. For more information, see [Device names for volumes on Amazon EC2 instances](device_naming.md). + For M3 instances, you might receive instance store volumes even if you do not specify them in the block device mapping for the instance. ------ #### [ Console ] **To specify a block device mapping in an instance launch request** 1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. From the dashboard, choose **Launch instance**. 1. In the **Application and OS Images** section, select the AMI to use. 1. In the **Configure storage** section, the **Instance store volumes** section lists the instance store volumes that can be attached to the instance. 1. For each instance store volume to attach, for **Device name**, select the device name to use. 1. Configure the remaining instance settings as needed, and then choose **Launch instance**. ------ #### [ AWS CLI ] **To specify a block device mapping in an instance launch request** Use the [run-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html) command with the `--block-device-mappings` option. ``` --block-device-mappings file://mapping.json ``` The following block device mapping adds two instance store volumes. ``` [ { "DeviceName": "/dev/sdc", "VirtualName": "ephemeral0" }, { "DeviceName": "/dev/sdd", "VirtualName": "ephemeral1" } ] ``` ------ #### [ PowerShell ] **To specify a block device mapping in an instance launch request** Use the [New-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2Instance.html) cmdlet with the `-BlockDeviceMapping` option. ``` -BlockDeviceMapping $bdm ``` The following block device mapping adds two instance store volumes. ``` $bdm = @() $sdc = New-Object -TypeName Amazon.EC2.Model.BlockDeviceMapping $sdc.DeviceName = "/dev/sdc" $sdc.VirtualName = "ephemeral0" $bdm += $sdc $sdd = New-Object -TypeName Amazon.EC2.Model.BlockDeviceMapping $sdd.DeviceName = "/dev/sdd" $sdd.VirtualName = "ephemeral1" $bdm += $sdd ``` ------ # Make instance store volume available for use on an EC2 instance After you launch an instance with attached instance store volumes, you must mount the volumes before you can access them. ## Linux instances You can format volumes with the file system of your choice after you launch your instance. **To make an instance store volume available on Linux** 1. Connect to the instance using an SSH client. For more information, see [Connect to your Linux instance using SSH](connect-to-linux-instance.md). 1. Use the `df -h` command to view the volumes that are formatted and mounted. ``` $ df -h Filesystem Size Used Avail Use% Mounted on devtmpfs 3.8G 72K 3.8G 1% /dev tmpfs 3.8G 0 3.8G 0% /dev/shm /dev/nvme0n1p1 7.9G 1.2G 6.6G 15% / ``` 1. Use the `lsblk` to view any volumes that were mapped at launch but not formatted and mounted. ``` $ lsblk NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT nvme0n1 259:1 0 8G 0 disk ├─nvme0n1p1 259:2 0 8G 0 part / └─nvme0n1p128 259:3 0 1M 0 part nvme1n1 259:0 0 69.9G 0 disk ``` 1. To format and mount an instance store volume that was mapped only, do the following: 1. Create a file system on the device using the `mkfs` command. ``` $ sudo mkfs -t xfs /dev/nvme1n1 ``` 1. Create a directory on which to mount the device using the `mkdir` command. ``` $ sudo mkdir /data ``` 1. Mount the device on the newly created directory using the `mount` command. ``` $ sudo mount /dev/nvme1n1 /data ``` ## Windows instances For Windows instances, we reformat the instance store volumes with the NTFS file system. You can view the instance store volumes using Windows Disk Management. For more information, see [List non-NVMe disks](windows-list-disks.md#windows-disks). **To manually mount an instance store volume** 1. Choose **Start**, enter **Computer Management**, and then press **Enter**. 1. In left-hand panel, choose **Disk Management**. 1. If you are prompted to initialize the volume, choose the volume to initialize, select the required partition type depending on your use case, and then choose **OK**. 1. In the list of volumes, right-click the volume to mount, and then choose **New Simple Volume**. 1. On the wizard, choose **Next**. 1. On the Specify Volume Size screen, choose **Next** to use the maximum volume size. Alternatively, choose a volume size that is between the minimum and maximum disk space. 1. On the Assign a Drive Letter or Path screen, do one of the following, and choose **Next**. + To mount the volume with a drive letter, choose **Assign the following drive letter** and then choose the drive letter to use. + To mount the volume as a folder, choose **Mount in the following empty NTFS folder** and then choose **Browse** to create or select the folder to use. + To mount the volume without a drive letter or path, choose **Do not assign a drive letter or drive path**. 1. On the Format Partition screen, specify whether or not to format the volume. If you choose to format the volume, choose the required file system and unit size, and specify a volume label. 1. Choose **Next**, **Finish**. # Enable instance store swap volume for M1 and C1 EC2 instances **Note** This topic applies to `c1.medium` and `m1.small` Linux instances only. The `c1.medium` and `m1.small` instance types have a limited amount of physical memory. Therefore, they are given a 900 MiB swap volume at launch time to act as virtual memory, or *swap space*, for the Linux system. Swap space in Linux can be used when a system requires more memory than it has been physically allocated. When swap space is enabled, Linux systems can swap infrequently used memory pages from physical memory to swap space (either a dedicated partition or a swap file in an existing file system) and free up that space for memory pages that require high-speed access. **Note** Using swap space for memory paging is not as fast or efficient as using RAM. If your workload is regularly paging memory into swap space, you should consider migrating to a larger instance type with more RAM. For more information, see [Amazon EC2 instance type changes](ec2-instance-resize.md). Although the Linux kernel sees this swap space as a partition on the root volume, it is actually a separate instance store volume, regardless of your root volume 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. ``` [ec2-user ~]$ swapon -s Filename Type Size Used Priority /dev/xvda3 partition 917500 0 -1 ``` 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. ``` [ec2-user ~]$ lsblk NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT xvda1 202:1 0 8G 0 disk / xvda3 202:3 0 896M 0 disk ``` 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. ``` [ec2-user ~]$ sudo swapon /dev/xvda3 ``` Now the swap space should show up in **lsblk** and **swapon -s** output. ``` [ec2-user ~]$ lsblk NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT xvda1 202:1 0 8G 0 disk / xvda3 202:3 0 896M 0 disk [SWAP] [ec2-user ~]$ swapon -s Filename Type Size Used Priority /dev/xvda3 partition 917500 0 -1 ``` You also need to edit your `/etc/fstab` file so that this swap space is automatically enabled at every system boot. ``` [ec2-user ~]$ sudo vim /etc/fstab ``` Append the following line to your `/etc/fstab` file (using the swap device name for your system): ``` /dev/xvda3 none swap sw 0 0 ``` **To use an instance store volume as swap space** 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 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 volume limits for EC2 instances](instance-store-volumes.md). 1. List the block devices attached to your instance to get the device name for your instance store volume. ``` [ec2-user ~]$ lsblk -p NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT /dev/xvdb 202:16 0 4G 0 disk /media/ephemeral0 /dev/xvda1 202:1 0 8G 0 disk / ``` In this example, the instance store volume is `/dev/xvdb`. 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. 1. (Optional) If your instance store volume is mounted (it lists a `MOUNTPOINT` in the **lsblk** command output), unmount it with the following command. ``` [ec2-user ~]$ sudo umount /dev/xvdb ``` 1. Set up a Linux swap area on the device with the **mkswap** command. ``` [ec2-user ~]$ sudo mkswap /dev/xvdb mkswap: /dev/xvdb: warning: wiping old ext3 signature. Setting up swapspace version 1, size = 4188668 KiB no label, UUID=b4f63d28-67ed-46f0-b5e5-6928319e620b ``` 1. Enable the new swap space. ``` [ec2-user ~]$ sudo swapon /dev/xvdb ``` 1. Verify that the new swap space is being used. ``` [ec2-user ~]$ swapon -s Filename Type Size Used Priority /dev/xvdb partition 4188668 0 -1 ``` 1. Edit your `/etc/fstab` file so that this swap space is automatically enabled at every system boot. ``` [ec2-user ~]$ sudo vim /etc/fstab ``` 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): ``` /dev/xvdb none swap sw 0 0 ``` **Important** Instance store volume data is lost when an instance is stopped or hibernated; this includes the instance store swap space formatting created in [Step 3](#step_mkswap). If you stop and restart an instance that has been configured to use instance store swap space, you must repeat [Step 1](#step_swap_start) through [Step 5](#step_swap_enable) on the new instance store volume. # Initialize instance store volumes on EC2 instances Because of the way that Amazon EC2 virtualizes disks, the first write to any location on some instance store volumes performs more slowly than subsequent writes. For most applications, amortizing this cost over the lifetime of the instance is acceptable. However, if you require high disk performance, we recommend that you initialize your drives by writing once to every drive location before production use. **Note** Instance types with direct-attached solid state drives (SSD) and TRIM support provide maximum performance at launch time, without initialization. For information about the instance store for each instance type, see [Instance store volume limits for EC2 instances](instance-store-volumes.md). 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: ``` dd if=/dev/zero of=/dev/sdb bs=1M dd if=/dev/zero of=/dev/sdc bs=1M dd if=/dev/zero of=/dev/sdd bs=1M dd if=/dev/zero of=/dev/sde bs=1M ``` To perform initialization on all instance store volumes at the same time, use the following command: ``` dd if=/dev/zero bs=1M|tee /dev/sdb|tee /dev/sdc|tee /dev/sde > /dev/sdd ``` 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: ``` echo $((30*1024)) > /proc/sys/dev/raid/speed_limit_min ``` # Detailed performance statistics for Amazon EC2 instance store volumes Amazon EC2 provides real-time, high-resolution performance statistics for NVMe instance store volumes attached to Nitro-based Amazon EC2 instances. These statistics are presented as aggregated counters that are retained for the duration of the instance's lifetime. The statistics provide details about the cumulative number of operations, bytes sent and received, time spent on read and write I/O operations, and histograms for read and write I/O operations. While these statistics maintain consistency with [Amazon EBS detailed performance statistics](https://docs.aws.amazon.com/ebs/latest/userguide/nvme-detailed-performance-stats.html), they also include detailed latency histograms broken down by I/O size, which can provide more granular insights into your storage performance patterns. This enhanced visibility enables you to precisely identify which specific I/O sizes are experiencing latency issues, allowing you to optimize application performance and troubleshoot issues more effectively. You can collect these statistics at a granularity of up to 1 second intervals. If requests are made more frequently than 1 second intervals, the NVMe driver might queue the requests, along with other admin commands, to be processed at a later time. **Considerations** + The statistics are supported only for NVMe instance store volumes attached to Nitro-based instances. + The counters are not persistent across instance stops and restarts. + The statistics are available at no additional cost. ## Statistics The NVMe block device vends the following statistics: | Statistic name | Full name | Type | Description | | --- | --- | --- | --- | | total\$1read\$1ops | Total read operations | Counter | The total number of completed read operations. | | total\$1write\$1ops | Total write operations | Counter | The total number of completed write operations. | | total\$1read\$1bytes | Total read bytes | Counter | The total number of read bytes transferred. | | total\$1write\$1bytes | Total write bytes | Counter | The total number of write bytes transferred. | | total\$1read\$1time | Total read time | Counter | The total time spent, in microseconds, by all completed read operations. | | total\$1write\$1time | Total write time | Counter | The total time spent, in microseconds, by all completed write operations. | | instance\$1store\$1volume\$1performance\$1exceeded\$1iops | Total time demand exceeded volume's maximum IOPS | Counter | The total time, in microseconds, that IOPS requests exceeded the volume's maximum IOPS. Any value above 0 indicates that your workload demanded more IOPS than the volume could deliver. Ideally, the incremental count of this metric, between two snapshot times, should be minimal. | | instance\$1store\$1volume\$1performance\$1exceeded\$1tp | Total time demand exceeded volume's maximum throughput | Counter | The total time, in microseconds, that throughput requests exceeded the volume's maximum throughput. Any value above 0 indicates that your workload demanded more throughput than the volume could deliver. Ideally, the incremental count of this metric, between two snapshot times, should be minimal. | | volume\$1queue\$1length | Volume queue length | Point in time | The number of read and write operations waiting to be completed. | | read\$1io\$1latency\$1histogram | Read I/O histogram | Histogram \$1 | The number of read operations completed within each latency bin, in microseconds. | | write\$1io\$1latency\$1histogram | Write I/O histogram | Histogram \$1 | The number of write operations completed within each latency bin, in microseconds. | **Note** \$1 Histogram statistics represent only I/O operations that have completed successfully. Stalled or impaired I/O operations are not included, but will be evident in the `volume_queue_length` statistics, which is presented as a point-in-time statistic. ## Accessing the statistics The statistics must be accessed directly from the instance to which the instance store volumes is attached. You can access the statistics using one of the following methods. ### Linux instances ------ #### [ Amazon CloudWatch ] You can configure the Amazon CloudWatch agent to collect the statistics from your instance and make them available as custom metrics in CloudWatch. You can then use the metrics in CloudWatch to analyze I/O patterns, track performance trends, create custom dashboards, and set up automated alarms based on performance thresholds. For more information about configuring the CloudWatch agent, see [ Collect Amazon EC2 instance store volume metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Container-Insights-metrics-instance-store-Collect.html). ------ #### [ nvme-cli tool ] **To access the statistics** 1. Connect to the instance to which the volume is attached. 1. Amazon Linux 2023 AMIs released after September 15, 2025 include the latest version of the `nvme-cli` tool. If you are using an older Amazon Linux AMI, update the `nvme-cli` tool. ``` sudo yum install nvme-cli ``` 1. Run the following command and specify the device name for the volume. ``` sudo nvme amzn stats /dev/nvme0n1 ``` The statistics also provide detailed latency histograms broken down by I/O size. To view statistics broken down by I/O size, include the `--details` option. For example: ``` sudo nvme amzn stats --details /dev/nvme0n1 ``` You can get more information about how to use the tool by specifying the `--help` option. For example: ``` sudo nvme amzn stats --help ``` ------ ### Windows instances ------ #### [ nvme\$1amzn.exe tool ] **To access the statistics** 1. Connect to the instance to which the volume is attached. 1. Make sure that you're using AWSNVMe driver version `1.7.0` or later. For more information about updating the AWSNVMe driver, see [AWS NVMe drivers](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/aws-nvme-drivers.html). 1. Get the disk number for the volume. For more information, see [Map NVMe disks on Amazon EC2 Windows instance to volumes](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/windows-list-disks-nvme.html). 1. Run the following command as Administrator and specify the disk number for the volume. ``` .\nvme_amzn.exe stats disk_number ``` The statistics also provide detailed latency histograms broken down by I/O size. To view statistics broken down by I/O size, include the `--details` option. For example: ``` .\nvme_amzn.exe stats --details disk_number ``` ------ # Root volumes for your Amazon EC2 instances When you launch an instance, we create a *root volume* for the instance. The root volume contains the image used to boot the instance. Each instance has a single root volume. You can add storage volumes to your instances during or after launch. The AMI that you use to launch an instance determines the type of root volume. You can launch an instance from either an *Amazon EBS-backed AMI* (Linux and Windows instances) or an *Amazon S3-backed AMI* (Linux instances only). There are significant differences between what you can do with each type of AMI. For more information about these differences, see [Root volume type](ComponentsAMIs.md#storage-for-the-root-device). We recommend that you use AMIs backed by Amazon EBS, because these instances launch faster and use persistent storage. We reserve specific device names for root volumes. For more information, see [Device names for volumes on Amazon EC2 instances](device_naming.md). **Topics** + [Instances with an Amazon EBS root volume](#root-volume-ebs-backed) + [Instances with an instance store root volume (Linux instances only)](#root-volume-instance-store-backed) + [Keep an Amazon EBS root volume after an Amazon EC2 instance terminates](configure-root-volume-delete-on-termination.md) + [Replace the root volume for an Amazon EC2 instance without stopping it](replace-root.md) ## Instances with an Amazon EBS root volume Instances that use Amazon EBS for the root volume automatically have an Amazon EBS volume attached. When you launch an instance with an Amazon EBS-AMI, we create an Amazon EBS volume for each Amazon EBS snapshot referenced by the AMI. You can optionally use other Amazon EBS volumes or instance store volumes, depending on the instance type. An instance with an EBS root volume 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 instance with an EBS root volume 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 its root volume to a different running instance for debugging or any other purpose. For more information, see [Amazon EBS volumes](https://docs.aws.amazon.com/ebs/latest/userguide/ebs-volumes.html). ![\[Root volume and other Amazon EBS volumes of an instance launched from an Amazon EBS-backed AMI\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/ebs_backed_instance.png) **Limitation** You can't use `st1` or `sc1` EBS volumes as root volumes. **Instance failure** If an instance with an EBS root volume fails, you can restore your session by following one of these methods: + Stop and then start again (try this method first). + Automatically snapshot all relevant volumes and create a new AMI. For more information, see [Create an Amazon EBS-backed AMI](creating-an-ami-ebs.md). + Attach the volume to the new instance by following these steps: 1. Create a snapshot of the root volume. 1. Register a new AMI using the snapshot. 1. Launch a new instance from the new AMI. 1. Detach the remaining Amazon EBS volumes from the old instance. 1. Reattach the Amazon EBS volumes to the new instance. ## Instances with an instance store root volume (Linux instances only) **Note** Windows instances do not support instance store root volumes. Instances that use instance store for the root volume automatically have one or more instance store volumes available, with one volume serving as the root volume. When an instance is launched from an Amazon S3-backed AMI, the AMI 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 (instances with an instance store root volume do not support the **Stop** action) or if it fails (such as if an underlying drive has issues). For more information, see [Instance store temporary block storage for EC2 instances](InstanceStorage.md). ![\[Root volume on an Amazon EC2 instance launched from an Amazon S3-backed AMI\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/instance_store_backed_instance.png) **Supported instance types** Only the following instance types support an instance store volume as the root volume: C1, C3, D2, I2, M1, M2, M3, R3, and X1. **Instance failure** After an instance with an instance store root volume fails or terminates, it can't be restored. If you plan to use an instances with an instance store root volume, we highly recommend that you distribute the data on your instance store volumes across multiple Availability Zones. You should also back up critical data from your instance store volumes to persistent storage on a regular basis. # Keep an Amazon EBS root volume after an Amazon EC2 instance terminates By default, the Amazon EBS root volume for an instance is deleted when the instance terminates. You can change the default behavior to ensure that an Amazon EBS root volume persists after the instance terminates. To change the default behavior, set the `DeleteOnTermination` attribute to `false`. You can do so either at instance launch or later on. **Topics** + [Configure the root volume to persist during instance launch](#Using_ChangeRootDeviceVolumeToPersist) + [Configure the root volume to persist for an existing instance](#set-deleteOnTermination-aws-cli) + [Confirm that a root volume is configured to persist](#Using_ConfirmRootDeviceVolumeToPersist) ## Configure the root volume to persist during instance launch You can configure the root volume to persist when you launch an instance. ------ #### [ Console ] **To configure the root volume to persist when you launch an instance** 1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. In the navigation pane, choose **Instances** and then choose **Launch instances**. 1. Choose an Amazon Machine Image (AMI), choose and instance type, choose a key pair, and configure your network settings. 1. For **Configure storage**, choose **Advanced**. 1. Expand the root volume. 1. For **Delete on termination**, choose **No**. 1. When you are finished configuring your instance, choose **Launch instance**. ------ #### [ AWS CLI ] **To configure the root volume to persist when you launch an instance** Use the [run-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html) command and include the following option. ``` --block-device-mappings file://mapping.json ``` In `mapping.json`, specify a block device mapping that sets the `DeleteOnTermination` attribute to `false`. ``` [ { "DeviceName": "/dev/sda1", "Ebs": { "DeleteOnTermination": false } } ] ``` ------ #### [ PowerShell ] **To configure the root volume to persist when you launch an instance** Use the [New-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2Instance.html) cmdlet and include the following parameter. ``` -BlockDeviceMapping $bdm ``` Create a block device mapping that sets the `DeleteOnTermination` attribute to `$false`. ``` $ebs = New-Object Amazon.EC2.Model.EbsBlockDevice $ebs.DeleteOnTermination = $false $bdm = New-Object Amazon.EC2.Model.BlockDeviceMapping $bdm.DeviceName = "dev/xvda" $bdm.Ebs = $ebs ``` ------ ## Configure the root volume to persist for an existing instance You can configure the root volume to persist for a running instance. Note that you can't complete this task using the Amazon EC2 console. ------ #### [ AWS CLI ] **To configure the root volume to persist for an existing instance** Use the [modify-instance-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-attribute.html) command with a block device mapping that sets the `DeleteOnTermination` attribute to `false`. ``` aws ec2 modify-instance-attribute \ --instance-id i-1234567890abcdef0 \ --block-device-mappings file://mapping.json ``` Specify the following in `mapping.json`. ``` [ { "DeviceName": "/dev/xvda", "Ebs": { "DeleteOnTermination": false } } ] ``` ------ #### [ PowerShell ] **To configure the root volume to persist for an existing instance** Use the [Edit-EC2InstanceAttribute](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceAttribute.html) cmdlet with a block device mapping that sets the `DeleteOnTermination` attribute to `$false`. ``` $ebs = New-Object Amazon.EC2.Model.EbsInstanceBlockDeviceSpecification $ebs.DeleteOnTermination = $false $bdm = New-Object Amazon.EC2.Model.InstanceBlockDeviceMappingSpecification $bdm.DeviceName = "/dev/xvda" $bdm.Ebs = $ebs Edit-EC2InstanceAttribute ` -InstanceId i-1234567890abcdef0 ` -BlockDeviceMapping $bdm ``` ------ ## Confirm that a root volume is configured to persist You can confirm that a root volume is configured to persist. ------ #### [ Console ] **To confirm that a root volume is configured to persist** 1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. In the navigation pane, choose **Instances** and then select the instance. 1. In the **Storage** tab, under **Block devices**, locate the entry for the root volume. If **Delete on termination** is `No`, the volume is configured to persist. ------ #### [ AWS CLI ] **To confirm that a root volume is configured to persist** Use the [describe-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html) command and verify that the `DeleteOnTermination` attribute is set to `false`. ``` aws ec2 describe-instances \ --instance-id i-1234567890abcdef0 \ --query "Reservations[].Instances[].BlockDeviceMappings" ``` The following is example output. ``` [ [ { "DeviceName": "/dev/xvda", "Ebs": { "AttachTime": "2024-07-12T04:05:33.000Z", "DeleteOnTermination": false, "Status": "attached", "VolumeId": "vol-1234567890abcdef0" } ] ] ``` ------ #### [ PowerShell ] **To confirm that a root volume is configured to persist** Use the [ Get-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2Instance.html) cmdlet and verify that the `DeleteOnTermination` attribute is set to `False`. ``` (Get-EC2Instance -InstanceId i-i-1234567890abcdef0).Instances.BlockDeviceMappings.Ebs ``` The following is example output. ``` AssociatedResource : AttachTime : 7/12/2024 4:05:33 AM DeleteOnTermination : False Operator : Status : attached VolumeId : vol-1234567890abcdef0 ``` ------ # Replace the root volume for an Amazon EC2 instance without stopping it Amazon EC2 enables you to replace the root Amazon EBS volume for a running instance while retaining the following: + Data stored on instance store volumes — Instance store volumes remain attached to the instance after the root volume has been restored. + Data stored on data (non-root) Amazon EBS volumes — Non-root Amazon EBS volumes remain attached to the instance after the root volume has been restored. + Network configuration — All network interfaces remain attached to the instance and they retain their IP addresses, identifiers, and attachment IDs. When the instance becomes available, all pending network traffic is flushed. Additionally, the instance remains on the same physical host, so it retains its public and private IP addresses and DNS name. + IAM policies — IAM profiles and policies (such as tag-based policies) that are associated with the instance are retained and enforced. **Topics** + [How root volume replacement works](#replace-root-how) + [Considerations](#replace-root-considerations) + [Replace a root volume](#replace) ## How root volume replacement works When you replace the root volume for an instance, we create *root volume replacement task*. The original root volume is detached from the instance, and the new root volume is attached to the instance in its place. The instance's block device mapping is updated to reflect the ID of the replacement root volume. When you replace the root volume for an instance, you must specify the source of the snapshot for the new volume. The following are the possible options. ### Restore a root volume to its original state This option replaces the current root volume with a volume that is based on the snapshot that was used to create it. **Considerations for using the launch state** The replacement root volume gets the same type, size, and delete on termination attributes as the original root volume. ### Replace the root volume using a snapshot This option replaces the current root volume with a replacement volume that is based on the snapshot that you specify. For example, a specific snapshot that you previously created from this root volume. This is useful if you need to recover from issues caused by corruption of the root volume or network configuration errors in the guest operating system. The replacement root volume gets the same type, size, and delete on termination attributes as the original root volume. **Considerations for using a snapshot** + You can only use snapshots that were created directly from the instance's current or previous root volumes. + You can't use snapshot copies created from snapshots that were taken from the root volume. + After successfully replacing the root volume, you can still use snapshots taken from the original root volume to replace the new (replacement) root volume. ### Replace the root volume using an AMI This option replaces the current root volume using an AMI that you specify. This is useful if you need to perform operating system and application patching or upgrades. The AMI must have the same product code, billing information, architecture type, and virtualization type as the instance. If the instance is enabled for ENA or sriov-net, then you must use an AMI that supports those features. If the instance is not enabled for ENA or sriov-net, then you can either select an AMI that doesn't include support for those features, or you can automatically add support if you select an AMI that supports ENA or sriov-net. If the instance is enabled for NitroTPM, then you must use an AMI that has NitroTPM enabled. NitroTPM support is not enabled if the instance was not configured for it, regardless of the AMI that you select. You can select an AMI with a different boot mode than that of the instance, as long as the instance supports the boot mode of the AMI. If the instance does not support the boot mode, the request fails. If the instance supports the boot mode, the new boot mode is propagated to the instance and its UEFI data is updated accordingly. If you manually modified the boot order or added a private UEFI Secure Boot key to load private kernel modules, the changes are lost during root volume replacement. The replacement root volume gets the same volume type and delete on termination attribute as the original root volume, and it gets the size of the AMI root volume block device mapping. **Note** The size of the AMI root volume block device mapping must be equal to or greater than the size of the original root volume. If the size of the AMI root volume block device mapping is smaller than the size of the original root volume, the request fails. After the root volume replacement task completes, the following new and updated information is reflected when you describe the instance using the console, AWS CLI or AWS SDKs: + New AMI ID + New volume ID for the root volume + Updated boot mode configuration (if changed by the AMI) + Updated NitroTPM configuration (if enabled by the AMI) + Updated ENA configuration (if enabled by the AMI) + Updated sriov-net configuration (if enabled by the AMI) The new AMI ID is also reflected in the instance metadata. **Considerations for using an AMI:** + If you use an AMI that has multiple block device mappings, only the root volume of the AMI is used. The other (non-root) volumes are ignored. + You can only use this feature if you have permissions to the AMI and its associated root volume snapshot. You cannot use this feature with AWS Marketplace AMIs. + You can only use an AMI without a product code only if the instance does not have a product code. + The size of the AMI root volume block device mapping must be equal to or greater than the size of the original root volume. If the size of the AMI root volume block device mapping is smaller than the size of the original root volume, the request fails. + The instance identity documents for the instance are automatically updated. + If the instance supports NitroTPM, the NitroTPM data for the instance is reset and new keys are generated. You can choose whether to keep the original root volume after the root volume replacement process has completed. If you choose delete the original root volume after the replacement process completes, the original root volume is automatically deleted and becomes unrecoverable. If you choose to keep the original root volume after the process completes, the volume remains provisioned in your account; you must manually delete the volume when you no longer need it. The root volume replacement task transitions through the following states: + `pending` — The replacement volume is being created. + `in-progress` — The original volume is being detached and the replacement volume is being attached. + `succeeded` — The replacement volume has been successfully attached to the instance and the instance is available. + `failing` — The replacement task is in the process of failing. + `failed` — The replacement task has failed, but the root volume is still attached. + `failing-detached` — The replacement task is in the process of failing and the instance might not have a root volume attached. + `failed-detached` — The replacement task has failed and the instance doesn't have a root volume attached. If the root volume replacement task fails, the instance is rebooted and the original root volume remains attached to the instance. ## Considerations Before you begin, consider the following. **Requirements** + The instance must be in the `running` state. + The instance is automatically rebooted during the process. The contents of the memory (RAM) is erased during the reboot. No manual reboots are required. + You can't replace the root volume if it is an instance store volume. Only instances with Amazon EBS root volumes are supported. + You can replace the root volume for all virtualized instance types and EC2 Mac bare metal instances. No other bare metal instance types are supported. + You can only use snapshots that were created directly from the instance's current or previous root volumes. + If your account is enabled for Amazon EBS encryption by default in the current Region, the replacement root volume created by the root volume replacement task is always encrypted, regardless of the encryption status of the specified snapshot or the root volume of the specified AMI. **Encryption outcomes** The following table summarizes the possible encryption outcomes. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/replace-root.html) ## Replace a root volume When you replace the root volume for an instance, a *root volume replacement task* is created. You can use the root volume replacement task to monitor the progress and outcome of the replacement process. ------ #### [ Console ] **To replace the root volume** 1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. In the navigation pane, choose **Instances**. 1. Select the instance for which to replace the root volume and choose **Actions**, **Monitor and troubleshoot**, **Replace root volume**. **Note** The **Replace root volume** action is disabled if the selected instance is not in the `running` state. 1. For **Restore**, choose one of the following options: + **Launch state** – Restore the replacement root volume from the snapshot that was used to create the current root volume. + **Snapshot** – Restore the replacement root volume to the snapshot that you specify. For **Snapshot**, select the snapshot to use. + **Image** – Restore the replacement root volume using the AMI that you specify. For **Image**, select the AMI to use. 1. (Optional) For **Volume initialization rate**, you can specify the Amazon EBS Provisioned Rate for Volume Initialization (volume initialization rate), in MiB/s, at which the snapshot blocks are to be downloaded from Amazon S3 to the volume. For more information, see [ Use an Amazon EBS Provisioned Rate for Volume Initialization](https://docs.aws.amazon.com/ebs/latest/userguide/initalize-volume.html#volume-initialization-rate). To use the default initialization rate or fast snapshot restore (if it is enabled for the selected snapshot), don't specify a rate. 1. (Optional) To delete the root volume that you are replacing, select **Delete replaced root volume**. 1. Choose **Create replacement task**. 1. To monitor the replacement task, choose the **Storage** tab for the instance and expand **Recent root volume replacement tasks**. ------ #### [ AWS CLI ] **To restore the replacement root volume to the launch state** Use the [ create-replace-root-volume-task](https://docs.aws.amazon.com/cli/latest/reference/ec2/create-replace-root-volume-task.html) command. For `--instance-id`, specify the ID of the instance for which to replace the root volume. Omit the `--snapshot-id` and `--image-id` parameters. To delete the original root volume after it has been replaced, include `--delete-replaced-root-volume` and specify `true`. To specify the volume initialization rate at which the snapshot blocks are downloaded from Amazon S3 to the volume, for `--volume-initialization-rate`, specify a value between `100` and `300` MiB/s. ``` aws ec2 create-replace-root-volume-task \ --instance-id i-1234567890abcdef0 \ --delete-replaced-root-volume \ --volume-initialization-rate 150 ``` **To restore the replacement root volume to a specific snapshot** Use the [create-replace-root-volume-task](https://docs.aws.amazon.com/cli/latest/reference/ec2/create-replace-root-volume-task.html) command. For `--instance-id`, specify the ID of the instance for which to replace the root volume. For `--snapshot-id`, specify the ID of the snapshot to use. To delete the original root volume after it has been replaced, include `--delete-replaced-root-volume` and specify `true`. To specify the volume initialization rate at which the snapshot blocks are downloaded from Amazon S3 to the volume, for `--volume-initialization-rate`, specify a value between `100` and `300` MiB/s. ``` aws ec2 create-replace-root-volume-task \ --instance-id i-1234567890abcdef0 \ --snapshot-id snap-9876543210abcdef0 \ --delete-replaced-root-volume \ --volume-initialization-rate 150 ``` **To restore the replacement root volume using an AMI** Use the [ create-replace-root-volume-task](https://docs.aws.amazon.com/cli/latest/reference/ec2/create-replace-root-volume-task.html) command. For `--instance-id`, specify the ID of the instance for which to replace the root volume. For `--image-id`, specify the ID of the AMI to use. To delete the original root volume after it has been replaced, include `--delete-replaced-root-volume` and specify `true`. To specify the volume initialization rate at which the snapshot blocks are downloaded from Amazon S3 to the volume, for `--volume-initialization-rate`, specify a value between `100` and `300` MiB/s. ``` aws ec2 create-replace-root-volume-task \ --instance-id i-1234567890abcdef0 \ --image-id ami-09876543210abcdef \ --delete-replaced-root-volume \ --volume-initialization-rate 150 ``` **To view the status of a root volume replacement task** Use the [describe-replace-root-volume-tasks](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-replace-root-volume-tasks.html) command and specify the IDs of the root volume replacement tasks to view. ``` aws ec2 describe-replace-root-volume-tasks \ --replace-root-volume-task-ids replacevol-1234567890abcdef0 \ --query ReplaceRootVolumeTasks[].TaskState ``` The following is example output. ``` [ "succeeded" ] ``` Alternatively, specify the `instance-id` filter to filter the results by instance. ``` $ aws ec2 describe-replace-root-volume-tasks \ --filters Name=instance-id,Values=i-1234567890abcdef0 ``` ------ #### [ PowerShell ] **To restore the replacement root volume to the launch state** Use the [New-EC2ReplaceRootVolumeTask](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2ReplaceRootVolumeTask.html) command. For `-InstanceId`, specify the ID of the instance for which to replace the root volume. Omit the `-SnapshotId` and `-ImageId` parameters. To delete the original root volume after it has been replaced, include `-DeleteReplacedRootVolume` and specify `$true`. To specify the volume initialization rate at which the snapshot blocks are downloaded from Amazon S3 to the volume, for `-VolumeInitializationRate`, specify a value between `100` and `300` MiB/s. ``` New-EC2ReplaceRootVolumeTask ` -InstanceId i-1234567890abcdef0 ` -VolumeInitializationRate 150 ` -DeleteReplacedRootVolume $true ``` **To restore the replacement root volume to a specific snapshot** Use the [New-EC2ReplaceRootVolumeTask](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2ReplaceRootVolumeTask.html) command. For `--InstanceId`, specify the ID of the instance for which to replace the root volume. For `-SnapshotId`, specify the ID of the snapshot to use. To delete the original root volume after it has been replaced, include `-DeleteReplacedRootVolume` and specify `$true`. To specify the volume initialization rate at which the snapshot blocks are downloaded from Amazon S3 to the volume, for `-VolumeInitializationRate`, specify a value between `100` and `300` MiB/s. ``` New-EC2ReplaceRootVolumeTask ` -InstanceId i-1234567890abcdef0 ` -SnapshotId snap-9876543210abcdef0 ` -VolumeInitializationRate 150 ` -DeleteReplacedRootVolume $true ``` **To restore the replacement root volume using an AMI** Use the [New-EC2ReplaceRootVolumeTask](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2ReplaceRootVolumeTask.html) command. For `-InstanceId`, specify the ID of the instance for which to replace the root volume. For `-ImageId`, specify the ID of the AMI to use. To delete the original root volume after it has been replaced, include `-DeleteReplacedRootVolume` and specify `$true`. To specify the volume initialization rate at which the snapshot blocks are downloaded from Amazon S3 to the volume, for `-VolumeInitializationRate`, specify a value between `100` and `300` MiB/s. ``` New-EC2ReplaceRootVolumeTask ` -InstanceId i-1234567890abcdef0 ` -ImageId ami-0abcdef1234567890 ` -VolumeInitializationRate 150 ` -DeleteReplacedRootVolume $true ``` **To view the status of a root volume replacement task** Use the [Get-EC2ReplaceRootVolumeTask](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2ReplaceRootVolumeTask.html) command and specify the IDs of the root volume replacement tasks to view. ``` (Get-EC2ReplaceRootVolumeTask ` -ReplaceRootVolumeTaskIds replacevol-1234567890abcdef0).TaskState.Value ``` The following is example output. ``` Succeeded ``` Alternatively, specify the `instance-id` filter to filter the results by instance. ``` PS C:\> Get-EC2ReplaceRootVolumeTask -Filters @{Name = 'instance-id'; Values = 'i-1234567890abcdef0'} | Format-Table ``` ------ # Device names for volumes on Amazon EC2 instances When you attach a volume to your instance, you include a device name for the volume. This device name is used by Amazon EC2. The block device driver for the instance assigns the actual volume name when mounting the volume, and the name assigned can be different from the name that Amazon EC2 uses. The number of volumes that your instance can support is determined by the operating system. For more information, see [Amazon EBS volume limits for Amazon EC2 instances](volume_limits.md). **Topics** + [Available device names](#available-ec2-device-names) + [Device name considerations](#device-name-limits) ## Available device names ### Linux instances There are two types of virtualization available for Linux instances: paravirtual (PV) and hardware virtual machine (HVM). The virtualization type of an instance is determined by the AMI used to launch the instance. All instance types support HVM AMIs. Some previous generation instance types support PV AMIs. 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 [Virtualization types](ComponentsAMIs.md#virtualization_types). The following table lists the available device names that you can specify in a block device mapping or when attaching an EBS volume. | Virtualization type | Available | Reserved for root volume | Recommended for EBS data volumes | Instance store volumes | | --- | --- | --- | --- | --- | | Paravirtual | /dev/sd[a-z] /dev/sd[a-z][1-15] /dev/hd[a-z] /dev/hd[a-z][1-15] | /dev/sda1 | /dev/sd[f-p] /dev/sd[f-p][1-6] | /dev/sd[b-e] | | HVM | /dev/sd[a-z] /dev/xvd[a-c][a-z] /dev/xvdd[a-x] | Differs by AMI /dev/sda1 or /dev/xvda | /dev/sd[b-z] /dev/xvdb[b-z] \$1 | /dev/sd[b-e] /dev/sd[b-h] (h1.16xlarge) /dev/sd[b-y] (d2.8xlarge) /dev/sd[b-i] (i2.8xlarge) \$1\$1 | \$1 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. \$1\$1 NVMe instance store volumes are automatically enumerated and assigned an NVMe device name. ### Windows instances AWS Windows AMIs use one of the following sets of drivers to permit access to virtualized hardware: + AWS PV: [Paravirtual drivers for Windows instances](xen-drivers-overview.md) + AWS NVMe: [AWS NVMe drivers](aws-nvme-drivers.md) **Device names for Nitro based instances** The following table lists the available device names that you can specify in a block device mapping or when attaching an EBS volume to a Nitro based instance. | Driver type | Available | Reserved for root volume | Recommended for EBS volumes | Instance store volumes | | --- | --- | --- | --- | --- | | AWS NVMe | xvd[a-z] xvd[a-c][a-z] xvdd[a-x] /dev/sda1 | /dev/sda1 | xvd[b-z] xvdb[b-z] | \$1 | \$1 NVMe instance store volumes are automatically enumerated and are assigned a Windows drive letter. **Device names for Xen based instances** The following table lists the available device names that you can specify in a block device mapping or when attaching an EBS volume to a Xen based instance. | Driver type | Available | Reserved for root volume | Recommended for EBS volumes | Instance store volumes | | --- | --- | --- | --- | --- | | AWS PV | xvd[b-z] xvd[b-c][a-z] /dev/sda1 /dev/sd[b-e] | /dev/sda1 | xvd[f-z] | xvdc[a-x] xvd[a-e] | | Citrix PV (no longer supported) | xvd[b-z] xvd[b-c][a-z] /dev/sda1 /dev/sd[b-e] | /dev/sda1 | xvd[f-z] | xvdc[a-x] xvd[a-e] | | Red Hat PV (no longer supported) | xvd[a-z] xvd[b-c][a-z] /dev/sda1 /dev/sd[b-e] | /dev/sda1 | xvd[f-p] | xvdc[a-x] xvd[a-e] | For more information about instance store volumes, see [Instance store temporary block storage for EC2 instances](InstanceStorage.md). For more information about NVMe EBS volumes (Nitro-based instances), including how to identify the EBS device, see [Amazon EBS and NVMe](https://docs.aws.amazon.com/ebs/latest/userguide/nvme-ebs-volumes.html) in the *Amazon EBS User Guide*. ## Device name considerations Keep the following in mind when selecting a device name: + The ending portion of device names that you use shouldn't overlap as it can cause issues when you start your instance. For example, avoid using combinations such as `/dev/xvdf` and `xvdf` for volumes attached to the same instance. + 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 (Linux instances) or a Windows drive letter (Windows instances). + (Windows instances) AWS Windows AMIs come with additional software that prepares an instance when it first boots up. This is either the EC2Config service (Windows AMIs prior to Windows Server 2016) or EC2Launch (Windows Server 2016 and later). After the devices have been mapped to drives, they are initialized and mounted. The root drive is initialized and mounted as `C:\`. By default, when an EBS volume is attached to a Windows instance, it can show up as any drive letter on the instance. You can change the settings to set the drive letters of the volumes per your specifications. For instance store volumes, the default depends on the driver. AWS PV drivers and Citrix PV drivers assign instance store volumes drive letters going from Z: to A:. Red Hat drivers assign instance store volumes drive letters going from D: to Z:. For more information, see [Windows launch agents on Amazon EC2 Windows instances](configure-launch-agents.md), and [How volumes are attached and mapped for Amazon EC2 Windows instances](ec2-windows-volumes.md). + (Linux instances) 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), the trailing letter could 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. + (Linux instances) HVM AMIs do not support the use of trailing numbers on device names, except for `/dev/sda1`, which is reserved for the root volume, and `/dev/sda2`. While using `/dev/sda2` is possible, we do not recommend using this device mapping with HVM instances. + (Linux 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`). + (Linux instances) 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]`. Before you specify the device name that you've selected, verify that it is available. Otherwise, you'll get an error that the device name is already in use. To view the disk devices and their mount points, use the **lsblk** command (Linux instances), or the Disk Management utility or the **diskpart** command (Windows instances). # Block device mappings for volumes on Amazon EC2 instances Each instance that you launch has an associated root volume, which is either an Amazon EBS volume or an instance store volume. You can use block device mappings to specify additional EBS volumes or instance store volumes to attach to an instance when it's launched. You can also attach additional EBS volumes to a running instance. However, the only way to attach instance store volumes to an instance is to use block device mappings to attach the volumes as the instance is launched. **Topics** + [Block device mapping concepts](#block-device-mapping-def) + [Add block device mappings to an AMI](ami-block-device-mapping.md) + [Add block device mappings to Amazon EC2 instance](instance-block-device-mapping.md) ## Block device mapping concepts A *block device* is a storage device that moves data in sequences of bytes or bits (blocks). These devices support random access and generally use buffered I/O. Examples include hard disks, CD-ROM drives, and flash drives. A block device can be physically attached to a computer or accessed remotely as if it were physically attached to the computer. Amazon EC2 supports two types of block devices: + 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. **Topics** + [Block device mapping entries](#parts-of-a-block-device-mapping) + [Block device mapping instance store caveats](#instance_store_caveats) + [Example block device mapping](#block-device-mapping-ex) + [How devices are made available in the operating system](#bdm-to-os) ### Block device mapping entries When you create a block device mapping, you specify the following information for each block device that you need to attach to the instance: + 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 names for volumes on Amazon EC2 instances](device_naming.md). For Instance store volumes, you also specify the following information: + The virtual device: `ephemeral[0-23]`. Note that the number and size of available instance store volumes for your instance varies by instance type. For NVMe instance store volumes, the following information also applies: + These volumes are automatically enumerated and assigned a device name; including them in your block device mapping has no effect. For EBS volumes, you also specify the following information: + 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. You can't specify the ID of an archived snapshot. + The size of the volume, in GiB. The specified size must be greater than or equal to the size of the specified snapshot. + Whether to delete the volume on instance termination (`true` or `false`). The default value is `true` for the root 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. + The volume type, which can be `gp2` and `gp3` for General Purpose SSD, `io1` and `io2` for Provisioned IOPS SSD, `st1` for Throughput Optimized HDD, `sc1` for Cold HDD, or `standard` for Magnetic. + The number of input/output operations per second (IOPS) that the volume supports. (Used only with `io1` and `io2` volumes.) + Some instance types support more than one EBS card. You can select the EBS card for the volume to be attached to by specifying the EBS card index. For more information, see [EBS cards](ebs_cards.md). ### Block device mapping instance store caveats There are several caveats to consider when launching instances with AMIs that have instance store volumes in their block device mappings. + 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. + 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. ### Example block device mapping This figure shows an example block device mapping for an EBS-backed instance. It maps `/dev/sdb` to `ephemeral0` and maps two EBS volumes, one to `/dev/sdh` and the other to `/dev/sdj`. It also shows the EBS volume that is the root volume, `/dev/sda1`. ![\[Relationship between instance, instance store volumes, and EBS volumes.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/block_device_mapping_figure.png) 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 [Specify a block device mapping for an AMI](ami-block-device-mapping.md#create-ami-bdm) and [Update the block device mapping when launching an instance](instance-block-device-mapping.md#Using_OverridingAMIBDM). ### How devices are made available in the operating system Device names like `/dev/sdh` and `xvdh` are used by Amazon EC2 to describe block devices. The block device mapping is used by Amazon EC2 to specify the block devices to attach to an EC2 instance. After a block device is attached to an instance, it must be mounted by the operating system before you can access the storage device. When a block device is detached from an instance, it is unmounted by the operating system and you can no longer access the storage device. **Linux instances** – 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 [Instance store temporary block storage for EC2 instances](InstanceStorage.md). The block device driver for the instance determines which devices are used when the volumes are formatted and mounted. **Windows instances** – The device names specified in the block device mapping are mapped to their corresponding block devices when the instance first boots, and then the Ec2Config service initializes and mounts the drives. The root volume is mounted as `C:\`. The instance store volumes are mounted as `Z:\`, `Y:\`, and so on. When an EBS volume is mounted, it can be mounted using any available drive letter. However, you can configure how drive letters are assigned to EBS volumes; for more information, see [Windows launch agents on Amazon EC2 Windows instances](configure-launch-agents.md). # Add block device mappings to an AMI Each AMI has a block device mapping that specifies the block devices to attach to an instance when it is launched from the AMI. To add more block devices to an AMI, you must create your own AMI. **Topics** + [Specify a block device mapping for an AMI](#create-ami-bdm) + [View the EBS volumes in an AMI block device mapping](#view-ami-bdm) ## Specify a block device mapping for an AMI There are two ways to specify volumes in addition to the root volume when you create an AMI. If you've already attached volumes to a running instance before you create an AMI from the instance, the block device mapping for the AMI includes those same volumes. For EBS volumes, the existing data is saved to a new snapshot, and it's this new snapshot that's specified in the block device mapping. For instance store volumes, the data is not preserved. For an EBS-backed AMI, you can add EBS volumes and instance store volumes using a block device mapping. For an Amazon S3-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. ------ #### [ Console ] **To add volumes to an AMI** 1. Open the Amazon EC2 console. 1. In the navigation pane, choose **Instances**. 1. Select an instance and choose **Actions**, **Image and templates**, **Create image**. 1. Enter a name and a description for the image. 1. The instance volumes appear under **Instance volumes**. To add another volume, choose **Add volume**. 1. For **Volume type**, choose the volume type. For **Device** choose the device name. For an EBS volume, you can specify additional details, such as a snapshot, volume size, volume type, IOPS, and encryption state. 1. Choose **Create image**. ------ #### [ AWS CLI ] **To add volumes to an AMI** Use the [create-image](https://docs.aws.amazon.com/cli/latest/reference/ec2/create-image.html) command to specify a block device mapping for an EBS-backed AMI. Use the [register-image](https://docs.aws.amazon.com/cli/latest/reference/ec2/register-image.html) command to specify a block device mapping for an Amazon S3-backed AMI. Specify the block device mapping using the `--block-device-mappings` parameter. You can specified arguments encoded in JSON directly on the command line or by referencing a JSON file, as shown here. ``` --block-device-mappings file://mapping.json ``` To add an instance store volume, use the following mapping. Note that NVMe instance store volumes are added automatically. ``` { "DeviceName": "device_name", "VirtualName": "ephemeral0" } ``` To add an empty 100 GiB volume, use the following mapping. ``` { "DeviceName": "device_name", "Ebs": { "VolumeSize": 100 } } ``` To add an EBS volume based on a snapshot, use the following mapping. ``` { "DeviceName": "device_name", "Ebs": { "SnapshotId": "snap-1234567890abcdef0" } } ``` To omit a mapping for a device, use the following mapping. ``` { "DeviceName": "device_name", "NoDevice": "" } ``` ------ #### [ PowerShell ] Use the [New-EC2Image](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2Image.html) cmdlet to specify a block device mapping for an EBS-backed AMI. Use the [Register-EC2Image](https://docs.aws.amazon.com/powershell/latest/reference/items/Register-EC2Image.html) cmdlet to specify a block device mapping for an Amazon S3-backed AMI. Add the `-BlockDeviceMapping` option, specifying the updates in `bdm`: ``` -BlockDeviceMapping $bdm ``` The following mapping adds a volume based on a snapshot. ``` $ebd = New-Object -TypeName Amazon.EC2.Model.EbsBlockDevice $ebd.SnapshotId = "snap-1234567890abcdef0" $bdm = New-Object -TypeName Amazon.EC2.Model.BlockDeviceMapping $bdm.DeviceName = "device_name" $bdm.Ebs = $ebd ``` The following mapping adds an empty 100 GB volume. ``` $ebd = New-Object -TypeName Amazon.EC2.Model.EbsBlockDevice $ebd.VolumeSize = 100 $bdm = New-Object -TypeName Amazon.EC2.Model.BlockDeviceMapping $bdm.DeviceName = "device_name" $bdm.Ebs = $ebd ``` ------ ## View the EBS volumes in an AMI block device mapping You can easily enumerate the EBS volumes in the block device mapping for an AMI. ------ #### [ Console ] **To view the EBS volumes for an AMI** 1. Open the Amazon EC2 console. 1. In the navigation pane, choose **AMIs**. 1. Choose **EBS images** from the **Filter** list to get a list of EBS-backed AMIs. 1. Select the desired AMI, and look at the **Details** tab. At a minimum, the following information is available for the root volume (where the term **root device** is equivalent to **root volume**): + **Root Device Type** (`ebs`) + **Root Device Name** (for example, `/dev/sda1`) + **Block Devices** (for example, `/dev/sda1=snap-1234567890abcdef0:8:true`) 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. (This screen doesn't display instance store volumes.) ------ #### [ AWS CLI ] **To view the EBS volumes for an AMI** Use the [describe-images](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-images.html) command. ``` aws ec2 describe-images \ --image-ids ami-0abcdef1234567890 \ --query Image[0].BlockDeviceMappings ``` ------ #### [ PowerShell ] **To view the EBS volumes for an AMI** Use the [Get-EC2Image](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2Image.html) cmdlet. ``` (Get-EC2Image -ImageId ami-0abcdef1234567890).BlockDeviceMappings ``` ------ # Add block device mappings to Amazon EC2 instance By default, an instance that you launch includes any storage devices specified in the block device mapping of the AMI from which you launched the instance. You can specify changes to the block device mapping for an instance when you launch it, and these updates overwrite or merge with the block device mapping of the AMI. **Limitations** + 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. **Topics** + [Update the block device mapping when launching an instance](#Using_OverridingAMIBDM) + [Update the block device mapping of a running instance](#update-instance-bdm) + [View the EBS volumes in an instance block device mapping](#view-instance-bdm) + [View the instance block device mapping for instance store volumes](#bdm-instance-metadata) ## Update the block device mapping when launching an instance You can add EBS volumes and instance store volumes to an instance when you launch it. Note that updating the block device mapping for an instance doesn't make a permanent change to the block device mapping of the AMI from which it was launched. ------ #### [ Console ] **To update the volumes for an instance at launch** 1. Follow the procedure to [launch an instance](ec2-launch-instance-wizard.md), but don't launch the instance until you've completed the following steps to update the volumes. 1. (Optional) To add a volume, choose **Configure storage**, **Add new volume**. Select the volume size and volume type. 1. (Optional) To suppress a volume that was specified by the block device mapping of the AMI, choose **Configure storage**, **Remove**. 1. (Optional) To modify the configuration of an EBS volume, on the **Configure storage** pane, choose **Advanced**. Expand the information for the volume, and make whatever changes you need. 1. In the **Summary** panel, review your instance configuration, and then choose **Launch instance**. For more information, see [Launch an EC2 instance using the launch instance wizard in the console](ec2-launch-instance-wizard.md). ------ #### [ AWS CLI ] **To update the volumes for an instance at launch** Use the [run-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html) command with the `--block-device-mappings` option. ``` --block-device-mappings file://mapping.json ``` For example, suppose that an AMI block device mapping specifies the following: + `/dev/xvda` - EBS root volume + `/dev/sdh` - EBS volume created from `snap-1234567890abcdef0` + `/dev/sdj` - Empty EBS volume with a size of `100` + `/dev/sdb` - Instance store volume `ephemeral0` Suppose that the following is the instance block device mapping in `mapping.json`. ``` [ { "DeviceName": "/dev/xvda", "Ebs": { "VolumeSize": 100 } }, { "DeviceName": "/dev/sdj", "NoDevice": "" }, { "DeviceName": "/dev/sdh", "Ebs": { "VolumeSize": 300 } }, { "DeviceName": "/dev/sdc", "VirtualName": "ephemeral1" } ] ``` The instance block device mapping does the following: + Overrides the size of the root volume, `/dev/xvda`, increasing it to 100 GiB. + Prevents `/dev/sdj` from attaching to the instance. + Overrides the size of `/dev/sdh`, increasing it to 300 GiB. Notice that you don't need to specify the snapshot ID again. + Adds an ephemeral volume, `/dev/sdc`. If the instance type doesn't support multiple instance store volumes, this has no effect. If the instance type supports NVMe instance store volumes, they are automatically enumerated and included in the instance block device mapping and can't be overridden. ------ #### [ PowerShell ] **To update the volumes for an instance at launch** Use the `-BlockDeviceMapping` parameter with the [New-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2Instance.html) cmdlet with the `-BlockDeviceMapping` parameter. ``` -BlockDeviceMapping $bdm ``` Suppose that the following is the instance block device mapping in `$bdm`. ``` $bdm = @() $root = New-Object -TypeName Amazon.EC2.Model.BlockDeviceMapping $root.DeviceName = "/dev/xvda" $ebs1 = New-Object -TypeName Amazon.EC2.Model.EbsBlockDevice $ebs1.VolumeSize = 100 $root.Ebs = $ebs1 $bdm += $root $sdj = New-Object -TypeName Amazon.EC2.Model.BlockDeviceMapping $sdj.DeviceName = "/dev/sdj" $sdj.NoDevice = "" $bdm += $sdj $sdh = New-Object -TypeName Amazon.EC2.Model.BlockDeviceMapping $sdh.DeviceName = "/dev/sdh" $ebs2 = New-Object -TypeName Amazon.EC2.Model.EbsBlockDevice $ebs2.VolumeSize = 300 $sdh.Ebs = $ebs2 $bdm += $sdh $sdc = New-Object -TypeName Amazon.EC2.Model.BlockDeviceMapping $sdc.DeviceName = "/dev/sdc" $sdc.VirtualName = "ephemeral1" $bdm += $sdc ``` The instance block device mapping does the following: + Overrides the size of the root volume, `/dev/xvda`, increasing it to 100 GiB. + Prevents `/dev/sdj` from attaching to the instance. + Overrides the size of `/dev/sdh`, increasing it to 300 GiB. Notice that you don't need to specify the snapshot ID again. + Adds an ephemeral volume, `/dev/sdc`. If the instance type doesn't support multiple instance store volumes, this has no effect. If the instance type supports NVMe instance store volumes, they are automatically enumerated and included in the instance block device mapping and can't be overridden. ------ ## Update the block device mapping of a running instance You do not need to stop the instance before changing this attribute. ------ #### [ AWS CLI ] **To update the block device mapping of a running instance** Use the [modify-instance-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-attribute.html) command. Add the `--block-device-mappings` option: ``` --block-device-mappings file://mapping.json ``` In `mapping.json`, specify the updates. For example, the following update changes the root volume to persist. ``` [ { "DeviceName": "/dev/sda1", "Ebs": { "DeleteOnTermination": false } } ] ``` ------ #### [ PowerShell ] **To update the block device mapping of a running instance** Use the [Edit-EC2InstanceAttribute](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceAttribute.html) cmdlet. Add the `-BlockDeviceMapping` option: ``` -BlockDeviceMapping $bdm ``` In `bdm`, specify the updates. For example, the following update changes the root volume to persist. ``` $ebd = New-Object -TypeName Amazon.EC2.Model.EbsBlockDevice $ebd.DeleteOnTermination = false $bdm = New-Object -TypeName Amazon.EC2.Model.BlockDeviceMapping $bdm.DeviceName = "/dev/sda1" $bdm.Ebs = $ebd ``` ------ ## View the EBS volumes in an instance block device mapping You can easily enumerate the EBS volumes mapped to an instance. ------ #### [ Console ] **To view the EBS volumes for an instance** 1. Open the Amazon EC2 console. 1. In the navigation pane, choose **Instances**. 1. Select the instance and look at the details displayed in the **Storage** tab. At a minimum, the following information is available for the root volume (where the term **root device** is equivalent to **root volume**): + **Root device type** (for example, **EBS**) + **Root device name** (for example, `/dev/xvda`) + **Block devices** (for example, `/dev/xvda`, `/dev/sdf`, and `/dev/sdj`) If the instance was launched with additional EBS volumes using a block device mapping, they appear under **Block devices**. Any instance store volumes do not appear on this tab. 1. To display additional information about an EBS volume, choose its volume ID to go to the volume page. ------ #### [ AWS CLI ] **To view the EBS volumes for an instance** Use the [describe-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html) command. ``` aws ec2 describe-instances \ --instance-ids i-1234567890abcdef0 \ --query Reservations[*].Instances[0].BlockDeviceMappings ``` ------ #### [ PowerShell ] **To view the EBS volumes for an instance** Use the [Get-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2Instance.html) cmdlet. ``` (Get-EC2Instance -InstanceId i-0bac57d7472c89bac).Instances.BlockDeviceMappings ``` ------ ## View the instance block device mapping for instance store volumes The instance type determines the number and type of instance store volumes that are available to the instance. If the number of instance store volumes in a block device mapping exceeds the number of instance store volumes available to an instance, the additional volumes are ignored. To view the instance store volumes for your instance, run the **lsblk** command (Linux instances) or open **Windows Disk Management** (Windows instances). To learn how many instance store volumes are supported by each instance type, see [ Amazon EC2 instance type specifications](https://docs.aws.amazon.com/ec2/latest/instancetypes/ec2-instance-type-specifications.html). When you view the block device mapping for your instance, you can see only the EBS volumes, not the instance store volumes. The method you use to view the instance store volumes for your instance depends on the volume type. ### NVMe instance store volumes #### Linux instances You can use the NVMe command line package, [nvme-cli](https://github.com/linux-nvme/nvme-cli), to query the NVMe instance store volumes in the block device mapping. Download and install the package on your instance, and then run the following command. ``` [ec2-user ~]$ sudo nvme list ``` The following is example output for an instance. The text in the Model column indicates whether the volume is an EBS volume or an instance store volume. In this example, both `/dev/nvme1n1` and `/dev/nvme2n1` are instance store volumes. ``` Node SN Model Namespace ---------------- -------------------- ---------------------------------------- --------- /dev/nvme0n1 vol06afc3f8715b7a597 Amazon Elastic Block Store 1 /dev/nvme1n1 AWS2C1436F5159EB6614 Amazon EC2 NVMe Instance Storage 1 /dev/nvme2n1 AWSB1F4FF0C0A6C281EA Amazon EC2 NVMe Instance Storage 1 ... ``` #### Windows instances You can use Disk Management or PowerShell to list both EBS and instance store NVMe volumes. For more information, see [Map NVMe disks on Amazon EC2 Windows instance to volumes](windows-list-disks-nvme.md). ### HDD or SSD instance store volumes You can use instance metadata to query the HDD or SSD instance store volumes in the block device mapping. NVMe instance store volumes are not included. The base URI for all requests for instance metadata is `http://169.254.169.254/latest/`. For more information, see [Use instance metadata to manage your EC2 instance](ec2-instance-metadata.md). #### Linux instances First, connect to your running instance. From the instance, use this query to get its block device mapping. ------ #### [ IMDSv2 ] ``` [ec2-user ~]$ TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \ && curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/block-device-mapping/ ``` ------ #### [ IMDSv1 ] ``` [ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/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 volume 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. ------ #### [ IMDSv2 ] ``` [ec2-user ~]$ TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \ && curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/block-device-mapping/ephemeral0 ``` ------ #### [ IMDSv1 ] ``` [ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/block-device-mapping/ephemeral0 ``` ------ #### Windows instances First, connect to your running instance. From the instance, use this query to get its block device mapping. ``` PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/meta-data/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 volume 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. ``` PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/meta-data/block-device-mapping/ephemeral0 ``` # How volumes are attached and mapped for Amazon EC2 Windows instances **Note** This topic applies to Windows instances only. Your Windows instance comes with an EBS volume that serves as the root volume. If your Windows instance uses AWS PV or Citrix PV drivers, you can optionally add up to 25 volumes, making a total of 26 volumes. For more information, see [Amazon EBS volume limits for Amazon EC2 instances](volume_limits.md). Depending on the instance type of your instance, you'll have from 0 to 24 possible instance store volumes available to the instance. To use any of the instance store volumes that are available to your instance, you must specify them when you create your AMI or launch your instance. You can also add EBS volumes when you create your AMI or launch your instance, or attach them while your instance is running. When you add a volume to your instance, you specify the device name that Amazon EC2 uses. For more information, see [Device names for volumes on Amazon EC2 instances](device_naming.md). AWS Windows Amazon Machine Images (AMIs) contain a set of drivers that are used by Amazon EC2 to map instance store and EBS volumes to Windows disks and drive letters. **Topics** + [Map NVME disks to volumes](windows-list-disks-nvme.md) + [Map non-NVME disks to volumes](windows-list-disks.md) # Map NVMe disks on Amazon EC2 Windows instance to volumes With [Nitro-based instances](instance-types.md#instance-hypervisor-type), EBS volumes are exposed as NVMe devices. This topic explains how to view the **NVMe disks** that are available to the Windows operating system on your instance. It also shows how to map those NVMe disks to the underlying Amazon EBS volumes and the device names specified for the block device mappings used by Amazon EC2. **Topics** + [List NVMe disks](#windows-disks-nvme) + [Map NVMe disks to volumes](#ebs-nvme-volume-map) ## List NVMe disks You can find the disks on your Windows instance using Disk Management or Powershell. ------ #### [ Disk Management ] **To find the disks on your Windows instance** 1. Log in to your Windows instance using Remote Desktop. For more information, see [Connect to your Windows instance using RDP](connecting_to_windows_instance.md). 1. Start the Disk Management utility. 1. Review the disks. The root volume is an EBS volume mounted as `C:\`. If there are no other disks shown, then you didn't specify additional volumes when you created the AMI or launched the instance. The following is an example that shows the disks that are available if you launch an `r5d.4xlarge` instance with two additional EBS volumes. ![\[Disk Management with a root volume, two instance store volumes, and two EBS volumes.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/disk_management_nvme.png) ------ #### [ PowerShell ] The following PowerShell script lists each disk and its corresponding device name and volume. It is intended for use with [Nitro-based instances](instance-types.md#instance-hypervisor-type), which use NVMe EBS and instance store volumes. Connect to your Windows instance and run the following command to enable PowerShell script execution. ``` Set-ExecutionPolicy RemoteSigned ``` Copy the following script and save it as `mapping.ps1` on your Windows instance. ``` # List the disks for NVMe volumes function Get-EC2InstanceMetadata { param([string]$Path) (Invoke-WebRequest -Uri "http://169.254.169.254/latest/$Path").Content } function GetEBSVolumeId { param($Path) $SerialNumber = (Get-Disk -Path $Path).SerialNumber if($SerialNumber -clike 'vol*'){ $EbsVolumeId = $SerialNumber.Substring(0,20).Replace("vol","vol-") } else { $EbsVolumeId = $SerialNumber.Substring(0,20).Replace("AWS","AWS-") } return $EbsVolumeId } function GetDeviceName{ param($EbsVolumeId) if($EbsVolumeId -clike 'vol*'){ $Device = ((Get-EC2Volume -VolumeId $EbsVolumeId ).Attachment).Device $VolumeName = "" } else { $Device = "Ephemeral" $VolumeName = "Temporary Storage" } Return $Device,$VolumeName } function GetDriveLetter{ param($Path) $DiskNumber = (Get-Disk -Path $Path).Number if($DiskNumber -eq 0){ $VirtualDevice = "root" $DriveLetter = "C" $PartitionNumber = (Get-Partition -DriveLetter C).PartitionNumber } else { $VirtualDevice = "N/A" $DriveLetter = (Get-Partition -DiskNumber $DiskNumber).DriveLetter if(!$DriveLetter) { $DriveLetter = ((Get-Partition -DiskId $Path).AccessPaths).Split(",")[0] } $PartitionNumber = (Get-Partition -DiskId $Path).PartitionNumber } return $DriveLetter,$VirtualDevice,$PartitionNumber } $Report = @() foreach($Path in (Get-Disk).Path) { $Disk_ID = ( Get-Partition -DiskId $Path).DiskId $Disk = ( Get-Disk -Path $Path).Number $EbsVolumeId = GetEBSVolumeId($Path) $Size =(Get-Disk -Path $Path).Size $DriveLetter,$VirtualDevice, $Partition = (GetDriveLetter($Path)) $Device,$VolumeName = GetDeviceName($EbsVolumeId) $Disk = New-Object PSObject -Property @{ Disk = $Disk Partitions = $Partition DriveLetter = $DriveLetter EbsVolumeId = $EbsVolumeId Device = $Device VirtualDevice = $VirtualDevice VolumeName= $VolumeName } $Report += $Disk } $Report | Sort-Object Disk | Format-Table -AutoSize -Property Disk, Partitions, DriveLetter, EbsVolumeId, Device, VirtualDevice, VolumeName ``` Run the script as follows: ``` PS C:\> .\mapping.ps1 ``` The following is example output for an instance with a root volume, two EBS volumes, and two instance store volumes. ``` Disk Partitions DriveLetter EbsVolumeId Device VirtualDevice VolumeName ---- ---------- ----------- ----------- ------ ------------- ---------- 0 1 C vol-03683f1d861744bc7 /dev/sda1 root 1 1 D vol-082b07051043174b9 xvdb N/A 2 1 E vol-0a4064b39e5f534a2 xvdc N/A 3 1 F AWS-6AAD8C2AEEE1193F0 Ephemeral N/A Temporary Storage 4 1 G AWS-13E7299C2BD031A28 Ephemeral N/A Temporary Storage ``` If you did not configure your credentials for Tools for Windows PowerShell on the Windows instance, the script cannot get the EBS volume ID and uses N/A in the `EbsVolumeId` column. ------ ## Map NVMe disks to volumes You can use the [ Get-Disk](https://learn.microsoft.com/en-us/powershell/module/storage/get-disk) command to map Windows disk numbers to Amazon EBS volumes and Amazon EC2 instance store volumes. ``` PS C:\> Get-Disk Number Friendly Name Serial Number HealthStatus OperationalStatus Total Size Partition Style ------ ------------- ------------- ------------ ----------------- ---------- ---------- 3 NVMe Amazo... AWS6AAD8C2AEEE1193F0_00000001. Healthy Online 279.4 GB MBR 4 NVMe Amazo... AWS13E7299C2BD031A28_00000001. Healthy Online 279.4 GB MBR 2 NVMe Amazo... vol0a4064b39e5f534a2_00000001. Healthy Online 8 GB MBR 0 NVMe Amazo... vol03683f1d861744bc7_00000001. Healthy Online 30 GB MBR 1 NVMe Amazo... vol082b07051043174b9_00000001. Healthy Online 8 GB MBR ``` You can also run the **ebsnvme-id** command to map NVMe disk numbers to EBS volume IDs and device names. ``` PS C:\> C:\PROGRAMDATA\Amazon\Tools\ebsnvme-id.exe Disk Number: 0 Volume ID: vol-03683f1d861744bc7 Device Name: sda1 Disk Number: 1 Volume ID: vol-082b07051043174b9 Device Name: xvdb Disk Number: 2 Volume ID: vol-0a4064b39e5f534a2 Device Name: xvdc ``` # Map non-NVMe disks on Amazon EC2 Windows instance to volumes For instances launched from a Windows AMI that uses AWS PV or Citrix PV drivers, you can use the relationships described on this page to map your Windows disks to your instance store and EBS volumes. This topic explains how to view the **non-NVMe disks** that are available to the Windows operating system on your instance. It also shows how to map those non-NVMe disks to the underlying Amazon EBS volumes and the device names specified for the block device mappings used by Amazon EC2. **Note** If you launch an instance If your Windows AMI uses Red Hat PV drivers, you can update your instance to use the Citrix drivers. For more information, see [Upgrade PV drivers on EC2 Windows instances](Upgrading_PV_drivers.md). **Topics** + [List non-NVMe disks](#windows-disks) + [Map non-NVMe disks to volumes](#windows-volume-mapping) ## List non-NVMe disks You can find the disks on your Windows instance using Disk Management or PowerShell. ------ #### [ Disk Management ] **To find the disks on your Windows instance** 1. Log in to your Windows instance using Remote Desktop. For more information, see [Connect to your Windows instance using RDP](connecting_to_windows_instance.md). 1. Start the Disk Management utility. On the taskbar, right-click the Windows logo, and then choose **Disk Management**. 1. Review the disks. The root volume is an EBS volume mounted as `C:\`. If there are no other disks shown, then you didn't specify additional volumes when you created the AMI or launched the instance. The following is an example that shows the disks that are available if you launch an `m3.medium` instance with an instance store volume (Disk 2) and an additional EBS volume (Disk 1). ![\[Disk Management with a root volume, one instance store volume, and one EBS volume.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/disk_management.png) 1. Right-click the gray pane labeled Disk 1, and then select **Properties**. Note the value of **Location** and look it up in the tables in [Map non-NVMe disks to volumes](#windows-volume-mapping). For example, the following disk has the location Bus Number 0, Target Id 9, LUN 0. According to the table for EBS volumes, the device name for this location is `xvdj`. ![\[The location of an EBS volume.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/disk_1_location.png) ------ #### [ PowerShell ] The following PowerShell script lists each disk and its corresponding device name and volume. **Requirements and limitations** + Requires Windows Server 2012 or later. + Requires credentials to get the EBS volume ID. You can configure a profile using the Tools for PowerShell, or attach an IAM role to the instance. + Does not support NVMe volumes. + Does not support dynamic disks. Connect to your Windows instance and run the following command to enable PowerShell script execution. ``` Set-ExecutionPolicy RemoteSigned ``` Copy the following script and save it as `mapping.ps1` on your Windows instance. ``` # List the disks function Convert-SCSITargetIdToDeviceName { param([int]$SCSITargetId) If ($SCSITargetId -eq 0) { return "sda1" } $deviceName = "xvd" If ($SCSITargetId -gt 25) { $deviceName += [char](0x60 + [int]($SCSITargetId / 26)) } $deviceName += [char](0x61 + $SCSITargetId % 26) return $deviceName } [string[]]$array1 = @() [string[]]$array2 = @() [string[]]$array3 = @() [string[]]$array4 = @() Get-WmiObject Win32_Volume | Select-Object Name, DeviceID | ForEach-Object { $array1 += $_.Name $array2 += $_.DeviceID } $i = 0 While ($i -ne ($array2.Count)) { $array3 += ((Get-Volume -Path $array2[$i] | Get-Partition | Get-Disk).SerialNumber) -replace "_[^ ]*$" -replace "vol", "vol-" $array4 += ((Get-Volume -Path $array2[$i] | Get-Partition | Get-Disk).FriendlyName) $i ++ } [array[]]$array = $array1, $array2, $array3, $array4 Try { $InstanceId = Get-EC2InstanceMetadata -Category "InstanceId" $Region = Get-EC2InstanceMetadata -Category "Region" | Select-Object -ExpandProperty SystemName } Catch { Write-Host "Could not access the instance Metadata using AWS Get-EC2InstanceMetadata CMDLet. Verify you have AWSPowershell SDK version '3.1.73.0' or greater installed and Metadata is enabled for this instance." -ForegroundColor Yellow } Try { $BlockDeviceMappings = (Get-EC2Instance -Region $Region -Instance $InstanceId).Instances.BlockDeviceMappings $VirtualDeviceMap = (Get-EC2InstanceMetadata -Category "BlockDeviceMapping").GetEnumerator() | Where-Object { $_.Key -ne "ami" } } Catch { Write-Host "Could not access the AWS API, therefore, VolumeId is not available. Verify that you provided your access keys or assigned an IAM role with adequate permissions." -ForegroundColor Yellow } Get-disk | ForEach-Object { $DriveLetter = $null $VolumeName = $null $VirtualDevice = $null $DeviceName = $_.FriendlyName $DiskDrive = $_ $Disk = $_.Number $Partitions = $_.NumberOfPartitions $EbsVolumeID = $_.SerialNumber -replace "_[^ ]*$" -replace "vol", "vol-" if ($Partitions -ge 1) { $PartitionsData = Get-Partition -DiskId $_.Path $DriveLetter = $PartitionsData.DriveLetter | Where-object { $_ -notin @("", $null) } $VolumeName = (Get-PSDrive | Where-Object { $_.Name -in @($DriveLetter) }).Description | Where-object { $_ -notin @("", $null) } } If ($DiskDrive.path -like "*PROD_PVDISK*") { $BlockDeviceName = Convert-SCSITargetIdToDeviceName((Get-WmiObject -Class Win32_Diskdrive | Where-Object { $_.DeviceID -eq ("\\.\PHYSICALDRIVE" + $DiskDrive.Number) }).SCSITargetId) $BlockDeviceName = "/dev/" + $BlockDeviceName $BlockDevice = $BlockDeviceMappings | Where-Object { $BlockDeviceName -like "*" + $_.DeviceName + "*" } $EbsVolumeID = $BlockDevice.Ebs.VolumeId $VirtualDevice = ($VirtualDeviceMap.GetEnumerator() | Where-Object { $_.Value -eq $BlockDeviceName }).Key | Select-Object -First 1 } ElseIf ($DiskDrive.path -like "*PROD_AMAZON_EC2_NVME*") { $BlockDeviceName = (Get-EC2InstanceMetadata -Category "BlockDeviceMapping")."ephemeral$((Get-WmiObject -Class Win32_Diskdrive | Where-Object { $_.DeviceID -eq ("\\.\PHYSICALDRIVE" + $DiskDrive.Number) }).SCSIPort - 2)" $BlockDevice = $null $VirtualDevice = ($VirtualDeviceMap.GetEnumerator() | Where-Object { $_.Value -eq $BlockDeviceName }).Key | Select-Object -First 1 } ElseIf ($DiskDrive.path -like "*PROD_AMAZON*") { if ($DriveLetter -match '[^a-zA-Z0-9]') { $i = 0 While ($i -ne ($array3.Count)) { if ($array[2][$i] -eq $EbsVolumeID) { $DriveLetter = $array[0][$i] $DeviceName = $array[3][$i] } $i ++ } } $BlockDevice = "" $BlockDeviceName = ($BlockDeviceMappings | Where-Object { $_.ebs.VolumeId -eq $EbsVolumeID }).DeviceName } ElseIf ($DiskDrive.path -like "*NETAPP*") { if ($DriveLetter -match '[^a-zA-Z0-9]') { $i = 0 While ($i -ne ($array3.Count)) { if ($array[2][$i] -eq $EbsVolumeID) { $DriveLetter = $array[0][$i] $DeviceName = $array[3][$i] } $i ++ } } $EbsVolumeID = "FSxN Volume" $BlockDevice = "" $BlockDeviceName = ($BlockDeviceMappings | Where-Object { $_.ebs.VolumeId -eq $EbsVolumeID }).DeviceName } Else { $BlockDeviceName = $null $BlockDevice = $null } New-Object PSObject -Property @{ Disk = $Disk; Partitions = $Partitions; DriveLetter = If ($DriveLetter -eq $null) { "N/A" } Else { $DriveLetter }; EbsVolumeId = If ($EbsVolumeID -eq $null) { "N/A" } Else { $EbsVolumeID }; Device = If ($BlockDeviceName -eq $null) { "N/A" } Else { $BlockDeviceName }; VirtualDevice = If ($VirtualDevice -eq $null) { "N/A" } Else { $VirtualDevice }; VolumeName = If ($VolumeName -eq $null) { "N/A" } Else { $VolumeName }; DeviceName = If ($DeviceName -eq $null) { "N/A" } Else { $DeviceName }; } } | Sort-Object Disk | Format-Table -AutoSize -Property Disk, Partitions, DriveLetter, EbsVolumeId, Device, VirtualDevice, DeviceName, VolumeName ``` Run the script as follows: ``` PS C:\> .\mapping.ps1 ``` The following is example output. ``` Disk Partitions DriveLetter EbsVolumeId Device VirtualDevice DeviceName VolumeName ---- ---------- ----------- ----------- ------ ------------- ---------- ---------- 0 1 C vol-0561f1783298efedd /dev/sda1 N/A NVMe Amazon Elastic B N/A 1 1 D vol-002a9488504c5e35a xvdb N/A NVMe Amazon Elastic B N/A 2 1 E vol-0de9d46fcc907925d xvdc N/A NVMe Amazon Elastic B N/A ``` If you did not provide your credentials on the Windows instance, the script cannot get the EBS volume ID and uses N/A in the `EbsVolumeId` column. ------ ## Map non-NVMe disks to volumes The block device driver for the instance assigns the actual volume names when mounting volumes. **Topics** + [Instance store volumes](#instance-store-volume-map) + [EBS volumes](#ebs-volume-map) ### Instance store volumes The following table describes how the Citrix PV and AWS PV drivers map non-NVMe instance store volumes to Windows volumes. The number of available instance store volumes is determined by the instance type. For more information, see [Instance store volume limits for EC2 instances](instance-store-volumes.md). | Location | Device name | | --- | --- | | Bus Number 0, Target ID 78, LUN 0 | xvdca | | Bus Number 0, Target ID 79, LUN 0 | xvdcb | | Bus Number 0, Target ID 80, LUN 0 | xvdcc | | Bus Number 0, Target ID 81, LUN 0 | xvdcd | | Bus Number 0, Target ID 82, LUN 0 | xvdce | | Bus Number 0, Target ID 83, LUN 0 | xvdcf | | Bus Number 0, Target ID 84, LUN 0 | xvdcg | | Bus Number 0, Target ID 85, LUN 0 | xvdch | | Bus Number 0, Target ID 86, LUN 0 | xvdci | | Bus Number 0, Target ID 87, LUN 0 | xvdcj | | Bus Number 0, Target ID 88, LUN 0 | xvdck | | Bus Number 0, Target ID 89, LUN 0 | xvdcl | ### EBS volumes The following table describes how the Citrix PV and AWS PV drivers map non-NVME EBS volumes to Windows volumes. | Location | Device name | | --- | --- | | Bus Number 0, Target ID 0, LUN 0 | /dev/sda1 | | Bus Number 0, Target ID 1, LUN 0 | xvdb | | Bus Number 0, Target ID 2, LUN 0 | xvdc | | Bus Number 0, Target ID 3, LUN 0 | xvdd | | Bus Number 0, Target ID 4, LUN 0 | xvde | | Bus Number 0, Target ID 5, LUN 0 | xvdf | | Bus Number 0, Target ID 6, LUN 0 | xvdg | | Bus Number 0, Target ID 7, LUN 0 | xvdh | | Bus Number 0, Target ID 8, LUN 0 | xvdi | | Bus Number 0, Target ID 9, LUN 0 | xvdj | | Bus Number 0, Target ID 10, LUN 0 | xvdk | | Bus Number 0, Target ID 11, LUN 0 | xvdl | | Bus Number 0, Target ID 12, LUN 0 | xvdm | | Bus Number 0, Target ID 13, LUN 0 | xvdn | | Bus Number 0, Target ID 14, LUN 0 | xvdo | | Bus Number 0, Target ID 15, LUN 0 | xvdp | | Bus Number 0, Target ID 16, LUN 0 | xvdq | | Bus Number 0, Target ID 17, LUN 0 | xvdr | | Bus Number 0, Target ID 18, LUN 0 | xvds | | Bus Number 0, Target ID 19, LUN 0 | xvdt | | Bus Number 0, Target ID 20, LUN 0 | xvdu | | Bus Number 0, Target ID 21, LUN 0 | xvdv | | Bus Number 0, Target ID 22, LUN 0 | xvdw | | Bus Number 0, Target ID 23, LUN 0 | xvdx | | Bus Number 0, Target ID 24, LUN 0 | xvdy | | Bus Number 0, Target ID 25, LUN 0 | xvdz | # Torn write prevention on Amazon EC2 Linux instances **Note** Torn write prevention is supported with Linux instances only. Torn write prevention is a block storage feature designed by AWS to improve the performance of your I/O-intensive relational database workloads and reduce latency without negatively impacting data resiliency. Relational databases that use InnoDB or XtraDB as the database engine, such as MySQL and MariaDB, will benefit from torn write prevention. Typically, relational databases that use pages larger than the *power fail atomicity* of the storage device use *data logging* mechanisms to protect against torn writes. MariaDB and MySQL use a *doublewrite buffer* file to log data before writing it to data tables. In the event of incomplete or torn writes, as a result of operating system crashes or power loss during write transactions, the database can recover the data from the doublewrite buffer. The additional I/O overhead associated with writing to the doublewrite buffer impacts database performance and application latency, and it reduces the number transactions that can be processed per second. For more information about doublewrite buffer, see the [ MariaDB](https://mariadb.com/kb/en/innodb-doublewrite-buffer/) and [ MySQL](https://dev.mysql.com/doc/refman/5.7/en/innodb-doublewrite-buffer.html) documentation. With *torn write prevention*, data is written to storage in *all-or-nothing* write transactions, which eliminates the need for using the doublewrite buffer. This prevents partial, or torn, data from being written to storage in the event of operating system crashes or power loss during write transactions. The number of transactions processed per second can be increased by up to 30 percent, and write latency can be decreased by up to 50 percent, without compromising the resiliency of your workloads. **Pricing** There are no additional costs for using torn write prevention. **Topics** + [Supported block sizes](supported-block-sizes.md) + [Requirements](twp-reqs.md) + [Check instance support](twp-namespace.md) + [Configure workload](configure-twp.md) # Block sizes for torn write prevention on Amazon EC2 Torn write prevention supports write operations for 4 KiB, 8 KiB, and 16 KiB blocks of data. The data block start logical block address (LBA) must be aligned to the respective block boundary size of 4 KiB, 8 KiB, or 16 KiB. For example, for 16 KiB write operations, the data block start LBA must be aligned to a block boundary size of 16 KiB. The following table shows support across storage and instance types. |   | 4 KiB blocks | 8 KiB blocks | 16 KiB blocks | | --- | --- | --- | --- | | Instance store volumes | All NVMe instance store volumes attached to current generation I-family instances. | I4i, Im4gn, Is4gen, I7i, I7ie, I8g, and I8ge instances supported by AWS Nitro SSD. | | Amazon EBS volumes | All Amazon EBS volumes attached to [Nitro-based instances](instance-types.md#instance-hypervisor-type). | To confirm whether your instance and volume support torn write prevention, query to check if the instance supports torn write prevention and other details, like supported block and boundary sizes. For more information, see [Check Amazon EC2 instance support for torn write prevention](twp-namespace.md). # Requirements for using torn write prevention on Amazon EC2 For torn write prevention to work properly, an I/O operation must meet size, alignment, and boundary requirements, as specified in the `NTWPU`, `NTWGU`, `NTWBU` fields. You must configure your operating system to ensure that the specific storage subsystem (file system, LVM, RAID, etc) does not modify I/O properties down the storage stack, including block merges, splits, or block address relocation, before being submitted to the device. Torn write prevent has been tested with the following configuration: + An instance type and storage type that supports the required block size. + Amazon Linux 2 with kernel version 5.10 or later. + ext4 with `bigalloc` enabled and a cluster size of 16 KiB, and the most recent ext4 utilities (e2fsprogs 1.46.5 or later). + `O_DIRECT` file access mode to bypass Linux kernel buffer cache. **Note** You do not need to disable I/O merging for MySQL and MariaDB workloads. # Check Amazon EC2 instance support for torn write prevention To confirm whether your instance and volume supports torn write prevention, and to view the NVMe namespace vendor specific data that contains torn write prevention information, use the following command. ``` $ sudo nvme id-ns -v device_name ``` **Note** The command returns the vendor-specific information in hex with ASCII interpretation. You might need to build a tool, similar to `ebsnvme-id`, into your applications that can read and parse the output. For example, the following command returns the NVMe namespace vendor specific data that contains torn write prevention information for `/dev/nvme1n1`. ``` $ sudo nvme id-ns -v /dev/nvme1n1 ``` If your instance and volume support torn write prevention, it returns the following AWS torn write prevention information in the NVMe namespace vendor specific data. **Note** The bytes in the following table represent the offset in bytes from the beginning of the NVMe namespace vendor specific data. | Bytes | Description | | --- | --- | | 0:31 | The name of the device attachment mount point, for example /dev/xvda. You provide this during volume attachment request and it can be used by the Amazon EC2 instance to create a symlink to the NVMe block device(nvmeXn1). | | 32:63 | The volume ID. For example, vol01234567890abcdef. This field can be used to map the NVMe device to the attached volume. | | 64:255 | Reserved for future use. | | 256:257 | Namespace Torn Write Prevention Unit size (NTWPU). This field indicates the namespace specific size of the write operation guaranteed to be written atomically to the NVM during a power failure or error condition. This field is specified in logical blocks represented in zero based values. | | 258:259 | Namespace Torn Write Prevention Granularity size (NTWPG). This field indicates the namespace specific size increments below NTWPU of the write operation guaranteed to be written atomically to the NVM during a power failure or error condition. That is, size should be NTWPG \$1 n <= NTWPU where n is positive integer. The write operation LBA offset also must be aligned to this field. This field is specified in logical blocks represented in zero based values. | | 260:263 | Namespace Torn Write Prevention Boundary size (NTWPB). This field indicates the atomic boundary size for this namespace for the NTWPU value. Writes to this namespace that cross atomic boundaries are not guaranteed to be written atomically to the NVM during a power failure or error condition. A value of 0h indicates that there are no atomic boundaries for power fail or error conditions. All other values specify a size in terms of logical blocks using the same encoding as the NTWPU field. | # Configure your workload on Amazon EC2 for torn write prevention Torn write prevention is enabled by default on [supported instance types with supported volumes](supported-block-sizes.md). You do not need to enabled any additional settings to enable your volume or instance for torn write prevention. **Note** There is no performance impact on workloads that do not support torn write prevention. You do not need to make any changes for these workloads. Workloads that do support torn write prevention, but are not configured to use it, continue to use the doublewrite buffer and do not receive any performance benefits. To configure your MySQL or MariaDB software stack to disable the doublewrite buffer and use torn write prevention, complete the following steps: 1. Configure your volume to use ext4 file system with the BigAlloc option and set the cluster size to 4 KiB, 8 KiB, or 16 KiB. Using BigAlloc with a cluster size of 4 KiB, 8 KiB, or 16 KiB ensures that the file system allocates files that align with the respective boundary. ``` $ mkfs.ext4 -O bigalloc -C 4096|8192|16384 device_name ``` **Note** For MySQL and MariaDB, you must use `-C 16384` to match the database page size. Setting allocation granularity to a value other than a multiple of the page size can result in allocations that might be mismatched with torn write prevention boundaries of the storage device. For example: ``` $ mkfs.ext4 -O bigalloc -C 16384 /dev/nvme1n1 ``` 1. Configure InnoDB to use the `0_DIRECT` flushing method and turn off InnoDB doublewrite. Use your preferred text editor to open `/etc/my.cnf`, and update the `innodb_flush_method` and `innodb_doublewrite` parameters as follows: ``` innodb_flush_method=O_DIRECT innodb_doublewrite=0 ``` **Important** If you are using Logical Volume Manager (LVM) or other storage virtualization layer, make sure that the starting offsets of the volumes are aligned on 16 KiB multiples. This is relative to the underlying NVMe storage to account for the metadata headers and superblocks used by the storage virtualization layer. If you add an offset to the LVM physical volume, it can cause misalignment between the file system allocations and the NVMe device's offsets, which would invalidate torn write prevention. For more information, see `--dataalignmentoffset` in the [Linux manual page](https://man7.org/linux/man-pages/man8/pvcreate.8.html). # Application consistent Windows VSS based Amazon EBS snapshots You can take application-consistent snapshots of all Amazon EBS volumes attached to your Amazon EC2 Windows instances using [AWS Systems Manager Run Command](https://docs.aws.amazon.com/systems-manager/latest/userguide/run-command.html). The snapshot process uses the Windows [Volume Shadow Copy Service (VSS)](https://learn.microsoft.com/en-us/windows-server/storage/file-server/volume-shadow-copy-service) to take EBS volume level backups of VSS-aware applications. The snapshots include data from pending transactions between these applications and the disk. You don't have to shut down your instances or disconnect them when you need to back up all attached volumes. There is no additional cost to use VSS based EBS snapshots. You only pay for EBS snapshots created by the backup process. For more information, see [How am I billed for my Amazon EBS snapshots?](https://repost.aws/knowledge-center/ebs-snapshot-billing) **Note** Application consistent Windows VSS based snapshots are supported with Windows instances only. **Topics** + [What is VSS?](#application-consistent-snapshots-how) + [How the VSS based Amazon EBS snapshot solution works](#how-vss-works) + [VSS prerequisites](application-consistent-snapshots-prereqs.md) + [Create VSS snapshots](create-vss-snaps.md) + [Troubleshoot VSS snapshots](application-consistent-snapshots-troubleshooting.md) + [Restore options for the AWS VSS solution](application-consistent-snapshots-restore.md) + [Version history](vss-comps-history.md) ## What is VSS? Volume Shadow Copy Service (VSS) is a backup and recovery technology included in Microsoft Windows. It can create backup copies, or snapshots, of computer files or volumes while they are in use. For more information, see [ Volume Shadow Copy Service](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/ee923636(v=ws.10)?redirectedfrom=MSDN). To create an application-consistent snapshot, the following software components are involved. + *VSS service* — Part of the Windows operating system + *VSS requester* — The software that requests the creation of shadow copies + *VSS writer* — Typically provided as part of an application, such as SQL Server, to ensure a consistent data set to back up + *VSS provider* — The component that creates the shadow copies of the underlying volumes The Windows VSS based Amazon EBS snapshot solution consists of multiple Systems Manager (SSM) Run Command documents that facilitate backup creation, and a [ Systems Manager Distributor package](https://docs.aws.amazon.com/systems-manager/latest/userguide/distributor.html), called `AwsVssComponents`, that includes an *EC2 VSS requester* and an *EC2 VSS provider*. The `AwsVssComponents` package must be installed on EC2 Windows instances to take application-consistent snapshots of EBS volumes. The following diagram illustrates the relationship between these software components. ![\[VSS software components\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/vss_components.png) ## How the VSS based Amazon EBS snapshot solution works The process for taking application-consistent, VSS based EBS snapshot scripts consists of the following steps. 1. Complete the [Prerequisites to create Windows VSS based EBS snapshots](application-consistent-snapshots-prereqs.md). 1. Enter parameters for the `AWSEC2-VssInstallAndSnapshot` SSM document and run this document by using Run Command. For more information, see [Run the AWSEC2-VssInstallAndSnapshot command document (recommended)](create-vss-snapshots-ssm.md#create-with-AWSEC2-VssInstallAndSnapshot). 1. The Windows VSS service on your instance coordinates all ongoing I/O operations for running applications. 1. The system flushes all I/O buffers and temporarily pauses all I/O operations. The pause lasts, at most, ten seconds. 1. During the pause, the system creates snapshots of all volumes attached to the instance. 1. The pause is lifted and I/O resumes operation. 1. The system adds all newly-created snapshots to the list of EBS snapshots. The system tags all VSS based EBS snapshots successfully created by this process with **AppConsistent:true**. 1. If you need to restore from a snapshot, you can use the standard EBS process of creating a volume from a snapshot, or you can restore all volumes to an instance by using a sample script, as described in [Use the AWS VSS solution to restore data for your instance](application-consistent-snapshots-restore.md). # Prerequisites to create Windows VSS based EBS snapshots You can create VSS based EBS snapshots with Systems Manager Run Command, AWS Backup, or Amazon Data Lifecycle Manager. The following prerequisites apply for all solutions. **[System requirements](#vss-sys-reqs)** Ensure that your EC2 Windows instance meets all of the system requirements to create VSS based snapshots, including supported versions of the Windows operating system, .NET framework, PowerShell, AWS Tools for Windows PowerShell, and the AWS Systems Manager Agent. **[IAM permissions](vss-iam-reqs.md)** The IAM role that's attached to your Amazon EC2 Windows instance must have permission to create application-consistent snapshots with VSS. To grant the necessary permissions, you can attach the `AWSEC2VssSnapshotPolicy` managed policy to your instance profile. **[VSS components](application-consistent-snapshots-getting-started.md)** To create application-consistent snapshots on Windows operating systems, the `AwsVssComponents` package must be installed on the instance. The package contains an on-instance EC2 VSS Agent that functions as the VSS requester, and an EC2 VSS provider for EBS volumes. ## System requirements **Install the Systems Manager Agent** VSS is orchestrated by the Systems Manager Agent using PowerShell. Ensure that you have installed SSM Agent version `3.0.502.0` or later on your EC2 instance. If you are already using an older version of the SSM Agent, update it using Run Command. For more information, see [ Setting up Systems Manager for Amazon EC2 instances](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-setting-up-ec2.html) and [Working with SSM Agent on Amazon EC2 instances for Windows Server](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent-windows.html) in the *AWS Systems Manager User Guide*. **Amazon EC2 Windows instance requirements** VSS based EBS snapshots are supported for instances running Windows Server 2016 and later. **.NET Framework version** The `AwsVssComponents` package requires .NET Framework version `4.6` or later. Windows operating system versions prior to Windows Server 2016 default to an earlier version of the .NET Framework. If your instance uses an earlier version of the .NET Framework, you must install version `4.6` or later using Windows Update. **AWS Tools for Windows PowerShell version** Ensure that your instance is running AWS Tools for Windows PowerShell version `3.3.48.0` or later. To check your version, run the following command in the PowerShell terminal on the instance. ``` C:\> Get-AWSPowerShellVersion ``` If you need to update AWS Tools for Windows PowerShell on your instance, see [ Installing the AWS Tools for Windows PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up-windows.html) in the *AWS Tools for PowerShell User Guide*. **Windows PowerShell version** Ensure that your instance is running Windows PowerShell major version `3`, `4`, or `5`. To check your version, run the following command in a PowerShell terminal on the instance. ``` C:\> $PSVersionTable.PSVersion ``` **PowerShell language mode** Ensure that your instance has the PowerShell language mode set to `FullLanguage`. For more information, see [ about\$1Language\$1Modes](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_language_modes?view=powershell-7.3) in the Microsoft documentation. # Use an IAM managed policy to grant permissions for VSS based snapshots The AWSEC2VssSnapshotPolicy managed policy enables Systems Manager to perform the following actions on your Windows instance: + Create and tag EBS snapshots + Create and tag Amazon Machine Images (AMIs) + Attach metadata, such as the device ID, to the default snapshot tags that VSS creates. This topic covers permission details for the VSS managed policy, and how to attach it to your EC2 instance profile IAM role. **Topics** + [AWSEC2VssSnapshotPolicy managed policy details](#vss-iam-manpol-AWSEC2VssSnapshotPolicy) + [Attach the VSS snapshot managed policy to your instance profile role](#vss-snapshots-attach-policy) ## AWSEC2VssSnapshotPolicy managed policy details An AWS managed policy is a standalone policy that Amazon provides for AWS customers. AWS managed policies are designed to grant permissions for common use cases. You can't change the permissions that are defined in AWS managed policies. However, you can copy the policy and use it as a baseline for a [customer managed policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#customer-managed-policies) that is specific to your use case. For more information about AWS managed policies, see [AWS managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies) in the *IAM User Guide*. To use the **AWSEC2VssSnapshotPolicy** managed policy, you can attach it to the IAM role that's attached to your EC2 Windows Instances. This policy enables the EC2 VSS solution to create and add tags to Amazon Machine Images (AMIs) and EBS Snapshots. To attach the policy, see [Attach the VSS snapshot managed policy to your instance profile role](#vss-snapshots-attach-policy). ### Permissions granted by AWSEC2VssSnapshotPolicy The **AWSEC2VssSnapshotPolicy** policy includes the following Amazon EC2 permissions to allow Amazon EC2 to create and manage VSS snapshots on your behalf. You can attach this managed policy to the IAM instance profile role that you use for your EC2 Windows instances. + **ec2:CreateTags** – Add tags to EBS snapshots and AMIs to help identify and categorize the resources. + **ec2:DescribeInstanceAttribute** – Retrieve the EBS volumes and corresponding block device mappings that are attached to the target instance. + **ec2:CreateSnapshots** – Create snapshots of EBS volumes. + **ec2:CreateImage** – Create an AMI from a running EC2 instance. + **ec2:DescribeImages** – Retrieve the information for EC2 AMIs and snapshots. + **ec2:DescribeSnapshots** – Determine the create time and status of snapshots to verify application consistency. **Note** To view permission details for this policy, see [https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSEC2VssSnapshotPolicy.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSEC2VssSnapshotPolicy.html) in the *AWS Managed Policy Reference*. ### Streamline permissions for specific use cases - advanced The `AWSEC2VssSnapshotPolicy` managed policy includes permissions for all of the ways that you can create VSS based snapshots. You can create a custom policy that includes only the permissions that you need. **Use case: Create AMI, Use case: Use AWS Backup service** If you exclusively use the `CreateAmi` option, or if you create VSS based snapshots only through the AWS Backup service, then you can streamline the policy statements as follows. + Omit policy statements identified by the following statement IDs (SIDs): + `CreateSnapshotsWithTag` + `CreateSnapshotsAccessInstance` + `CreateSnapshotsAccessVolume` + Adjust the `CreateTagsOnResourceCreation` statement as follows: + Remove `arn:aws:ec2:*:*:snapshot/*` from the resources. + Remove `CreateSnapshots` from the `ec2:CreateAction` condition. + Adjust the `CreateTagsAfterResourceCreation` statement to remove `arn:aws:ec2:*:*:snapshot/*` from the resources. + Adjust the `DescribeImagesAndSnapshots` statement to remove `ec2:DescribeSnapshots` from the statement action. **Use case: Snapshot only** If you don't use the `CreateAmi` option, then you can streamline the policy statements as follows. + Omit policy statements identified by the following statement IDs (SIDs): + `CreateImageAccessInstance` + `CreateImageWithTag` + Adjust the `CreateTagsOnResourceCreation` statement as follows: + Remove `arn:aws:ec2:*:*:image/*` from the resources. + Remove `CreateImage` from the `ec2:CreateAction` condition. + Adjust the `CreateTagsAfterResourceCreation` statement to remove `arn:aws:ec2:*:*:image/*` from the resources. + Adjust the `DescribeImagesAndSnapshots` statement to remove `ec2:DescribeImages` from the statement action. **Note** To ensure that your customized policy performs as expected, we recommend that you regularly review and incorporate updates to the managed policy. ## Attach the VSS snapshot managed policy to your instance profile role To grant permissions for VSS based snapshots for your EC2 Windows instance, you can attach the **AWSEC2VssSnapshotPolicy** managed policy to your instance profile role as follows. It's important to ensure that your instance meets all [System requirements](application-consistent-snapshots-prereqs.md#vss-sys-reqs). **Note** To use the managed policy, your instance must have the `AwsVssComponents` package version `2.3.1` or later installed. For version history, see [AwsVssComponents package versions](vss-comps-history.md#AwsVssComponents-history). 1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Roles** to see a list of IAM roles that you have access to. 1. Select the **Role name** link for the role that's attached to your instance. This opens the role detail page. 1. To attach the managed policy, choose **Add permissions**, located in the upper right corner of the list panel. Then select **Attach policies** from the dropdown list. 1. To streamline results, enter the policy name in the search bar (`AWSEC2VssSnapshotPolicy`). 1. Select the checkbox next to the name of the policy to attach, and choose **Add permissions**. # Manage VSS components package for Windows VSS based EBS snapshots Before you create VSS based EBS snapshots, ensure that you have the latest version of the VSS components package installed on your Windows instance. There are several ways that you can install the `AwsVssComponents` package onto an existing instance, as follows: + (Recommended) [Run the AWSEC2-VssInstallAndSnapshot command document (recommended)](create-vss-snapshots-ssm.md#create-with-AWSEC2-VssInstallAndSnapshot). This automatically installs or updates if needed every time it runs. + [Manually install the VSS components on an EC2 Windows instance](#install-vss-comps). + [Update the VSS components package on your EC2 Windows instance](#update-vss-comps). You can also create an AMI with EC2 Image Builder that uses the `aws-vss-components-windows` managed component to install the `AwsVssComponents` package for the image. The managed component uses AWS Systems Manager Distributor to install the package. After Image Builder creates the image, every instance that you launch from the associated AMI will have the VSS package installed on it. For more information about how you can create an AMI with the VSS package installed, see [Distributor package managed components for Windows](https://docs.aws.amazon.com/imagebuilder/latest/userguide/mgdcomponent-distributor-win.html) in the *EC2 Image Builder User Guide*. **Topics** + [Manual install](#install-vss-comps) + [Update components](#update-vss-comps) ## Manually install the VSS components on an EC2 Windows instance Your EC2 Windows instance must have VSS components installed before you can create application-consistent snapshots with Systems Manager. If you don't run the `AWSEC2-VssInstallAndSnapshot` command document to automatically install or update the package every time you create application-consistent snapshots, you must manually install the package. You must also install manually if you plan to use one of the following methods to create application-consistent snapshots from your EC2 instance. + Create VSS snapshots using AWS Backup + Create VSS snapshots using Amazon Data Lifecycle Manager If you need to perform a manual install, we recommend that you use the latest AWS VSS component package to improve the reliability and performance of application-consistent snapshots on your EC2 Windows instances. **Note** To automatically install or update the `AwsVssComponents` package whenever you create application-consistent snapshots, we recommend that you use Systems Manager to run the `AWSEC2-VssInstallAndSnapshot` document. For more information, see [Run the AWSEC2-VssInstallAndSnapshot command document (recommended)](create-vss-snapshots-ssm.md#create-with-AWSEC2-VssInstallAndSnapshot). To install the VSS components on an Amazon EC2 Windows instance, follow the steps for your preferred environment. ------ #### [ Console ] **To install the VSS components using SSM Distributor** 1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/). 1. In the navigation pane, choose **Run Command**. 1. Choose **Run command**. 1. For **Command document**, choose the button next to **AWS-ConfigureAWSPackage**. 1. For **Command parameters**, do the following: 1. Verify that **Action** is set to **Install**. 1. For **Name**, enter `AwsVssComponents`. 1. For **Version**, enter a version or leave the field empty so that Systems Manager installs the latest version. 1. For **Targets**, identify the instances on which you want to run this operation by specifying tags or selecting instances manually. **Note** If you choose to select instances manually, and an instance you expect to see is not included in the list, see [Where Are My Instances?](https://docs.aws.amazon.com/systems-manager/latest/userguide/troubleshooting-remote-commands.html#where-are-instances) in the *AWS Systems Manager User Guide* for troubleshooting tips. 1. For **Other parameters**: + (Optional) For **Comment**, type information about this command. + For **Timeout (seconds)**, specify the number of seconds for the system to wait before failing the overall command execution. 1. (Optional) For **Rate control**: + For **Concurrency**, specify either a number or a percentage of instances on which to run the command at the same time. **Note** If you selected targets by choosing Amazon EC2 tags, and you are not certain how many instances use the selected tags, then limit the number of instances that can run the document at the same time by specifying a percentage. + For **Error threshold**, specify when to stop running the command on other instances after it fails on either a number or a percentage of instances. For example, if you specify three errors, then Systems Manager stops sending the command when the fourth error is received. Instances still processing the command might also send errors. 1. (Optional) For **Output options** section, if you want to save the command output to a file, select the box next to **Enable writing to an S3 bucket**. Specify the bucket and (optional) prefix (folder) names. **Note** The S3 permissions that grant the ability to write the data to an S3 bucket are those of the instance profile assigned to the instance, not those of the user performing this task. For more information, see [Configure EC2 instance permissions](https://docs.aws.amazon.com/systems-manager/latest/userguide/setup-instance-permissions.html#instance-profile-add-permissions) in the *AWS Systems Manager User Guide*. 1. (Optional) Specify options for **SNS notifications**. For information about configuring Amazon SNS notifications for Run Command, see [Configuring Amazon SNS Notifications for AWS Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/monitoring-sns-notifications.html). 1. Choose **Run**. ------ #### [ AWS CLI ] Use the following procedure to download and install the `AwsVssComponents` package on your instances by using Run Command from the AWS CLI. The package installs two components: a VSS requester and a VSS provider. The system copies these components to a directory on the instance, and then registers the provider DLL as a VSS provider. **To install the VSS package** Run the following command to download and install the required VSS components for Systems Manager. ``` aws ssm send-command \ --document-name "AWS-ConfigureAWSPackage" \ --instance-ids "i-1234567890abcdef0" \ --parameters '{"action":["Install"],"name":["AwsVssComponents"]}' ``` ------ #### [ PowerShell ] Use the following procedure to download and install the `AwsVssComponents` package on your instances by using Run Command from the Tools for Windows PowerShell. The package installs two components: a VSS requester and a VSS provider. The system copies these components to a directory on the instance, and then registers the provider DLL as a VSS provider. **To install the VSS package** Run the following command to download and install the required VSS components for Systems Manager. ``` Send-SSMCommand ` -DocumentName "AWS-ConfigureAWSPackage" ` -InstanceId "i-1234567890abcdef0" ` -Parameter @{'action'='Install';'name'='AwsVssComponents'} ``` ------ ### Verify the signature on AWS VSS components Use the following procedure to verify the signature on the `AwsVssComponents` package. 1. Connect to your Windows instance. For more information, see [Connect to your Windows instance using RDP](connecting_to_windows_instance.md). 1. Navigate to C:\$1Program Files\$1Amazon\$1AwsVssComponents. 1. Open the context (right-click) menu for `ec2-vss-agent.exe`, and then choose **Properties**. 1. Navigate to the **Digital Signatures** tab and verify that the name of the signer is Amazon Web Services Inc. 1. Use the preceding steps to verify the signature on `Ec2VssInstaller` and `Ec2VssProvider.dll`. ## Update the VSS components package on your EC2 Windows instance We recommend that you keep the VSS components updated with the latest recommended version. There are several different ways that you can update components when a new version of the `AwsVssComponents` package is released. **Update methods** + You can repeat the steps described in [Manually install the VSS components on an EC2 Windows instance](#install-vss-comps) when a new version of the AWS VSS components is released. + You can configure a Systems Manager State Manager association to automatically download and install new or updated VSS components when the `AwsVssComponents` package becomes available. + You can automatically install or update the `AwsVssComponents` package whenever you create application-consistent snapshots, when you use Systems Manager to run the `AWSEC2-VssInstallAndSnapshot` document. **Note** We recommend that you use Systems Manager to run the `AWSEC2-VssInstallAndSnapshot` command document, which automatically installs or updates the `AwsVssComponents` package before it creates the application-consistent snapshots. For more information, see [Run the AWSEC2-VssInstallAndSnapshot command document (recommended)](create-vss-snapshots-ssm.md#create-with-AWSEC2-VssInstallAndSnapshot). To create a Systems Manager State Manager association, follow the steps for your preferred environment. ------ #### [ Console ] When you create a Systems Manager State Manager association, there are two options for updating the `AwsVssComponents` package, as follows: **Uninstall and reinstall** This method downloads and installs the package with no additional prerequisites. **In-place update** This performs an in-place update for the package, and has the following prerequisites: + The SSM Agent version that's installed on the instance must be version `3.3.808.0` or later. For more information, see [Working with SSM Agent on EC2 instances for Windows Server](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent-windows.html) in the *AWS Systems Manager User Guide*. + If specified, the `AwsVssComponents` package version must be version `2.5.0` or later. Earlier versions don't support in-place update. if your instance doesn't meet these prerequisites, in-place update will fail. Use the **Uninstall and reinstall** option instead. **To create a State Manager association** 1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/). 1. In the navigation pane, choose **State Manager**. Or, if the Systems Manager homepage opens first, open the navigation pane and then choose **State Manager**. 1. Choose **Create association**. 1. In the **Name** field, enter a descriptive name. 1. In the **Document** list, choose **AWS-ConfigureAWSPackage**. 1. In the **Parameters** section, choose **Install** from the **Action** list. 1. For **Installation type**, choose either **Uninstall and reinstall** or **In-place update**. 1. In the **Name** field, enter `AwsVssComponents`. You can keep the **Version** and **Additional Arguments** fields empty. 1. In the **Targets** section, choose an option. **Note** If you choose to target instances by using tags, and you specify tags that map to Linux instances, the association succeeds on the Windows instance but fails on the Linux instances. The overall status of the association shows **Failed**. 1. In the **Specify schedule** section, choose an option. 1. In the **Advanced options** section, for **Compliance severity**, choose a severity level for the association. For more information, see [Learn about association compliance](https://docs.aws.amazon.com/systems-manager/latest/userguide/compliance-about.html). For **Change Calendars**, select a preconfigured change calendar. For more information, see about [AWS Systems Manager Change Calendar](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-change-calendar.html). 1. For **Rate control**, do the following: + For **Concurrency**, specify either a number or a percentage of managed nodes on which to run the command at the same time. + For **Error threshold**, specify when to stop running the command on other managed nodes after it fails on either a number or a percentage of nodes. 1. (Optional) For **Output options**, to save the command output to a file, select **Enable writing output to S3**. Enter the bucket and prefix (folder) names in the boxes. 1. Choose **Create association**, and then choose **Close**. The system attempts to create the association on the instances and immediately apply the state. **Note** If EC2 instances for Windows Server show a status of **Failed**, verify that the SSM Agent is running on the instance, and verify that the instance is configured with an AWS Identity and Access Management (IAM) role for Systems Manager. For more information, see [ Setting up AWS Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-setting-up-ec2.html). ------ #### [ AWS CLI ] Use the [create-association](https://docs.aws.amazon.com/cli/latest/reference/ssm/create-association.html) command to update a Distributor package on a schedule without taking the associated application offline. Only new or updated files in the package are replaced. **To create a State Manager association** Run the following command to create an association. The value of `--name`, the document name, is always `AWS-ConfigureAWSPackage`. The following command uses the key `InstanceIds` to specify target instances. ``` aws ssm create-association \ --name "AWS-ConfigureAWSPackage" \ --parameters action=Install,installationType="Uninstall and reinstall",name=AwsVssComponents \ --targets Key=InstanceIds,Values=i-1234567890abcdef0,i-000011112222abcde ``` ------ #### [ PowerShell ] **To create a State Manager association** Use the [New-SSMAssociation](https://docs.aws.amazon.com/powershell/latest/reference/items/New-SSMAssociation.html) cmdlet. ``` New-SSMAssociation ` -Name "AWS-ConfigureAWSPackage" ` -Parameter @{ "action" = "Install" "installationType" = "Uninstall and reinstall" "name" = "AwsVssComponents" } ` -Target @{ "Key" = "InstanceIds" "Values" = @("i-1234567890abcdef0", "i-000011112222abcde") } ``` ------ # Create VSS based EBS snapshots for your EC2 Windows instance After you've met all of the [Prerequisites to create Windows VSS based EBS snapshots](application-consistent-snapshots-prereqs.md), you can use any of the following methods to create VSS based snapshots from your EC2 instance. **AWS Systems Manager command documents** [Use Systems Manager command documents](create-vss-snapshots-ssm.md) to create VSS based snapshots. To automate backups, you can create an AWS Systems Manager maintenance window task that uses the `AWSEC2-VssInstallAndSnapshot` command document. For more information, see [Working with Maintenance Windows (Console)](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-maintenance-working.html) in the *AWS Systems Manager User Guide*. **AWS Backup** You can create a VSS backup when using AWS Backup by enabling VSS in the console or CLI. For more information, see [Creating Windows VSS backups](https://docs.aws.amazon.com/aws-backup/latest/devguide/windows-backups.html) in the *AWS Backup Developer Guide*. AWS Backup doesn’t automatically install the `AwsVssComponents` package on your instance. You must perform a manual install on your instance. For more information, see [Manually install the VSS components on an EC2 Windows instance](application-consistent-snapshots-getting-started.md#install-vss-comps). **Amazon Data Lifecycle Manager** You can create VSS snapshots using Amazon Data Lifecycle Manager by enabling pre and post scripts in your snapshot lifecycle policies. For more information, see [Automating application-consistent snapshots](https://docs.aws.amazon.com/ebs/latest/userguide/automate-app-consistent-backups.html) in the *Amazon EBS User Guide*. Amazon Data Lifecycle Manager doesn’t automatically install the `AwsVssComponents` package on your instance. You must perform a manual install on your instance. For more information, see [Manually install the VSS components on an EC2 Windows instance](application-consistent-snapshots-getting-started.md#install-vss-comps). # Use Systems Manager command documents to create VSS based snapshots You can use AWS Systems Manager command documents to create VSS based snapshots. The following content introduces the command documents that are available, and the runtime parameters that the documents use to create your snapshots. Before you use any of the Systems Manager command documents, ensure that you've met all [Prerequisites to create Windows VSS based EBS snapshots](application-consistent-snapshots-prereqs.md). **Topics** + [Parameters for Systems Manager VSS snapshot documents](#create-vss-snapshots-ssm-params) + [Run Systems Manager VSS snapshot command documents](#create-vss-snapshots-ssm-methods) ## Parameters for Systems Manager VSS snapshot documents The Systems Manager documents that create VSS snapshots all use the following parameters, except where noted: **AmiName** (string, optional) If the **CreateAmi** option is set to `True`, specify the name of the AMI that the backup creates. **description** (string, optional) Specify a description for the snapshots or image that this process creates. **CollectDiagnosticLogs** (string, optional) To collect more information during snapshot and AMI creation steps, set this parameter to "`True`". The default value for this parameter is "`False`". Consolidated diagnostic logs are saved as a `.zip` format archive at the following location on your instance: `C:\ProgramData\Amazon\AwsVss\Logs\timestamp.zip` **CopyOnly** (string, optional) If you use the native SQL Server backup in addition to AWS VSS, performing a Copy-only backup prevents AWS VSS from breaking the native differential backup chain. To perform a Copy-only backup operation, set this parameter to `True`. The default value for this parameter is `False`, which causes AWS VSS to perform a full backup operation. **CreateAmi** (string, optional) To create a VSS based Amazon Machine Image (AMI) to back up your instance, set this parameter to `True`. The default value for this parameter is `False`, which backs up your instance with an EBS snapshot instead. For more information about creating an AMI from an instance, see [Create an Amazon EBS-backed AMI](creating-an-ami-ebs.md). **executionTimeout** (string, optional) Specify the maximum time in seconds to run the snapshot creation process on the instance, or to create an AMI from the instance. Increasing this timeout allows the command to wait longer for VSS to start its freeze and complete tagging of the resources it creates. This timeout only applies to the snapshot or AMI creation steps. The initial step to install or update the `AwsVssComponents` package is not included in the timeout. **ExcludeBootVolume** (string, optional) This setting excludes boot volumes from the backup process if you create snapshots. To exclude boot volumes from your snapshots, set **ExcludeBootVolume** to `True`, and **CreateAmi** to `False`. If you create an AMI for your backup, this parameter should be set to `False`. The default value for this parameter is `False`. **NoWriters** (string, optional) To exclude application VSS writers from the snapshot process, set this parameter to `True`. Excluding application VSS writers can help you resolve conflicts with third-party VSS backup components. The default value for this parameter is `False`. If `SaveVssMetadata` is `True`, this parameter must be set to `False`. **SaveVssMetadata** (string, optional) To save VSS metadata files during every snapshot, set this parameter to `True`. The default value is `False`. These files help provide insights into which components or writers were included in a backup operation, and the associated files and volumes for each snapshot. The metadata files are used when restoring a SQL database using VSS restore solution. For more information on how to restore a SQL database from VSS snapshots, see [Use an automation runbook to restore your database from AWS VSS solution snapshots](https://docs.aws.amazon.com/sql-server-ec2/latest/userguide/ms-ssdb-ec2-restore-vss.html). Metadata files have the associated snapshot set id in their names. You can find them at the following location on your instance: ``` C:\ProgramData\Amazon\AwsVss\VssMetadata\ ``` + Saving VSS metadata files requires `AwsVssComponents` package version 2.4.0 or later. If your instance has an earlier version installed, setting `SaveVssMetadata` to `True` causes the snapshot creation to fail. + The `NoWriters` and `SaveVssMetadata` parameters are mutually exclusive. If both are set to `True` then snapshot creation fails. **tags** (string, optional) We recommend that you tag your snapshots and images to help you locate and manage your resources, for example, to restore volumes from a list of snapshots. The system adds the `Name` key, with a blank value where you can specify the name that you want to apply to your output snapshots or images. If you want to specify additional tags, separate tags with a semicolon in between. For example, `Key=Environment,Value=Test;Key=User,Value=TestUser1`. Tag keys and values must only contain alphanumeric characters and the following special characters: `() ./\-"'@_+:={}`. By default, the system adds the following reserved tags for VSS based snapshots and images. + **Device** – For VSS based snapshots, this is the device name of the EBS volume that the snapshot captures. + **AppConsistent** – This tag indicates the successful creation of a VSS based snapshot or AMI. + **AwsVssConfig** – This identifies snapshots and AMIs that are created with VSS enabled. The tag includes meta information such as the `AwsVssComponents` version, and the Snapshot Set ID. Specifying any of these reserved tags in your parameter list will cause an error. **VssVersion** (string, optional) For the `AWSEC2-VssInstallAndSnapshot` document only, you can specify the `VssVersion` parameter to install a specific version of `AwsVssComponents` package on your instance. Leave this parameter blank to install the recommended default version. If the specified version of the `AwsVssComponents` package is already installed, the script skips the install step and moves on to the backup step. For a list of `AwsVssComponents` package versions and operating support, see [AWS VSS solution version history](vss-comps-history.md). ## Run Systems Manager VSS snapshot command documents You can create VSS based EBS snapshots with AWS Systems Manager command documents as follows. ### Run the AWSEC2-VssInstallAndSnapshot command document (recommended) When you use AWS Systems Manager to run the `AWSEC2-VssInstallAndSnapshot` document, the script runs the following steps. 1. The script first installs or updates the `AwsVssComponents` package on your instance, depending on whether it's already installed. 1. The script creates the application-consistent snapshots after the first step completes. To run the `AWSEC2-VssInstallAndSnapshot` document, follow the steps for your preferred environment. ------ #### [ Console ] **Create VSS based EBS snapshots from the console** 1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/). 1. Select **Run Command** from the navigation pane. This shows a list of commands that are currently running in your account, if applicable. 1. Choose **Run command**. This opens a list of command documents that you have access to. 1. Select `AWSEC2-VssInstallAndSnapshot` from the list of command documents. To streamline results, you can enter all or part of the document name. You can also filter by the owner, by platform types, or by tags. When you select a command document, details populate below the list. 1. Select `Default version at runtime` from the **Document version** list. 1. Configure the **Command parameters** to define how `AWSEC2-VssInstallAndSnapshot` will install the `AwsVssComponents` package and back up with VSS snapshots or an AMI. For parameter details, see [Parameters for Systems Manager VSS snapshot documents](#create-vss-snapshots-ssm-params). 1. For **Target selection**, specify tags or select instances manually to identify the instances on which to run this operation. **Note** If you select instances manually, and an instance you expect to see is not included in the list, see [Where Are My Instances?](https://docs.aws.amazon.com/systems-manager/latest/userguide/troubleshooting-remote-commands.html#where-are-instances) for troubleshooting tips. 1. For additional parameters to define Systems Manager Run Command behavior such as **Rate control**, enter values as described in [Running commands from the console](https://docs.aws.amazon.com/systems-manager/latest/userguide/running-commands-console.html). 1. Choose **Run**. If successful, the command populates the list of EBS snapshots with the new snapshots. You can locate these snapshots in the list of EBS snapshots by searching for the tags you specified, or by searching for `AppConsistent`. If the command execution failed, view the Systems Manager command output for details about why the execution failed. If the command successfully completed, but a specific volume backup failed, you can troubleshoot the failure in the list of EBS volumes. ------ #### [ AWS CLI ] You can run the following commands in the AWS CLI to create VSS based EBS snapshots and get the status of your snapshot creation. **Create VSS based EBS snapshots** Run the following command to create VSS based EBS snapshots. To create the snapshots, you must identify the instances with the `--instance-ids` parameter. For more information about other parameters that you can use, see [Parameters for Systems Manager VSS snapshot documents](#create-vss-snapshots-ssm-params). ``` aws ssm send-command \ --document-name "AWSEC2-VssInstallAndSnapshot" \ --instance-ids "i-01234567890abcdef" \ --parameters '{"ExcludeBootVolume":["False"],"description":["Description"],"tags":["Key=key_name,Value=tag_value"],"VssVersion":[""]}' ``` If successful, the command document populates the list of EBS snapshots with the new snapshots. You can locate these snapshots in the list of EBS snapshots by searching for the tags you specified, or by searching for `AppConsistent`. If the command execution failed, view the command output for details about why the execution failed. **Get command status** To get the current status of the snapshots, run the following command using the command ID returned from **send-command**. ``` aws ssm get-command-invocation --instance-ids "i-01234567890abcdef" \ --command-id "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111" \ --plugin-name "CreateVssSnapshot" ``` ------ #### [ PowerShell ] Run the following commands with AWS Tools for Windows PowerShell to create VSS based EBS snapshots and get the current runtime status for the creation of your output. Specify parameters described in the prior list to modify the behavior of the snapshot process. **Create VSS based EBS snapshots with Tools for Windows PowerShell** Run the following command to create VSS based EBS snapshots or AMIs. ``` Send-SSMCommand -DocumentName "AWSEC2-VssInstallAndSnapshot" -InstanceId "i-01234567890abcdef" -Parameter @{'ExcludeBootVolume'='False';'description'='a_description' ;'tags'='Key=key_name,Value=tag_value';'VssVersion'=''} ``` **Get command status** To get the current status of the snapshots, run the following command using the command ID returned from **Send-SSMCommand**. ``` Get-SSMCommandInvocationDetail -InstanceId "i-01234567890abcdef" -CommandId "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111" -PluginName "CreateVssSnapshot" ``` If successful, the command populates the list of EBS snapshots with the new snapshots. You can locate these snapshots in the list of EBS snapshots by searching for the tags you specified, or by searching for `AppConsistent`. If the command execution failed, view the command output for details about why the execution failed. ------ ### Run the AWSEC2-CreateVssSnapshot command document To run the `AWSEC2-CreateVssSnapshot` document, follow the steps for your preferred environment. ------ #### [ Console ] **Create VSS based EBS snapshots from the console** 1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/). 1. Select **Run Command** from the navigation pane. This shows a list of commands that are currently running in your account, if applicable. 1. Choose **Run command**. This opens a list of command documents that you have access to. 1. Select `AWSEC2-CreateVssSnapshot` from the list of command documents. To streamline results, you can enter all or part of the document name. You can also filter by the owner, by platform types, or by tags. When you select a command document, details populate below the list. 1. Select `Default version at runtime` from the **Document version** list. 1. Configure the **Command parameters** to define how `AWSEC2-CreateVssSnapshot` will back up with VSS snapshots or an AMI. For parameter details, see [Parameters for Systems Manager VSS snapshot documents](#create-vss-snapshots-ssm-params). 1. For **Target selection**, specify tags or select instances manually to identify the instances on which to run this operation. **Note** If you select instances manually, and an instance you expect to see is not included in the list, see [Where Are My Instances?](https://docs.aws.amazon.com/systems-manager/latest/userguide/troubleshooting-remote-commands.html#where-are-instances) for troubleshooting tips. 1. For additional parameters to define Systems Manager Run Command behavior such as **Rate control**, enter values as described in [Running commands from the console](https://docs.aws.amazon.com/systems-manager/latest/userguide/running-commands-console.html). 1. Choose **Run**. If successful, the command populates the list of EBS snapshots with the new snapshots. You can locate these snapshots in the list of EBS snapshots by searching for the tags you specified, or by searching for `AppConsistent`. If the command execution failed, view the Systems Manager command output for details about why the execution failed. If the command successfully completed, but a specific volume backup failed, you can troubleshoot the failure in the list of EBS volumes. ------ #### [ AWS CLI ] You can run the following command in the AWS CLI to create VSS based EBS snapshots. **Create VSS based EBS snapshots** Run the following command to create VSS based EBS snapshots. To create the snapshots, you must identify the instances with the `--instance-ids` parameter. For more information about other parameters that you can use, see [Parameters for Systems Manager VSS snapshot documents](#create-vss-snapshots-ssm-params). ``` aws ssm send-command \ --document-name "AWSEC2-CreateVssSnapshot" \ --instance-ids "i-01234567890abcdef" \ --parameters '{"ExcludeBootVolume":["False"],"description":["Description"],"tags":["Key=key_name,Value=tag_value"]}' ``` If successful, the command document populates the list of EBS snapshots with the new snapshots. You can locate these snapshots in the list of EBS snapshots by searching for the tags you specified, or by searching for `AppConsistent`. If the command execution failed, view the command output for details about why the execution failed. ------ #### [ PowerShell ] Run the following command with AWS Tools for Windows PowerShell to create VSS based EBS snapshots. **Create VSS based EBS snapshots with Tools for Windows PowerShell** Run the following command to create VSS based EBS snapshots. To create the snapshots, you must identify the instances with the `InstanceId` parameter. You can specify more than one instance to create snapshots for. For more information about other parameters that you can use, see [Parameters for Systems Manager VSS snapshot documents](#create-vss-snapshots-ssm-params). ``` Send-SSMCommand -DocumentName AWSEC2-CreateVssSnapshot -InstanceId "i-01234567890abcdef" -Parameter @{'ExcludeBootVolume'='False';'description'='a_description' ;'tags'='Key=key_name,Value=tag_value'} ``` If successful, the command populates the list of EBS snapshots with the new snapshots. You can locate these snapshots in the list of EBS snapshots by searching for the tags you specified, or by searching for `AppConsistent`. If the command execution failed, view the command output for details about why the execution failed. If the command successfully completed, but a specific volume backup failed, you can troubleshoot the failure in the list of EBS snapshots. ------ ### Run command documents for a Windows Failover Cluster with shared EBS storage You can use any of the command line procedures described in the previous section to create a VSS based snapshot. The command document (`AWSEC2-VssInstallAndSnapshot` or `AWSEC2-CreateVssSnapshot`) must run on the primary node in your cluster. The document will fail on the secondary nodes as they don't have access to the shared disks. If your primary and secondary change dynamically, you can run the AWS Systems Manager Run Command document on multiple nodes with the expectation that the command will succeed on the primary node and fail on secondary nodes. **Note** To automate backups, you can create an AWS Systems Manager maintenance window task that uses the `AWSEC2-VssInstallAndSnapshot` document. For more information, see [Working with Maintenance Windows (Console)](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-maintenance-working.html) in the *AWS Systems Manager User Guide*. # Troubleshoot Windows VSS based EBS snapshots Before you try any other troubleshooting steps, we recommend that you verify the following details. + Ensure that you've met all [Prerequisites to create Windows VSS based EBS snapshots](application-consistent-snapshots-prereqs.md). + Verify that you're using the latest [Windows OS version support](vss-comps-history.md#windows-version-support) of the `AwsVssComponents` package for your operating system. The issue that you've observed might have been addressed in newer versions. **Topics** + [Check log files](#general-log-files) + [Collect additional diagnostic logs](#vss-ts-collect-diagnostic-logs) + [Use VSS on instances with proxy configured](#general-using-vss-with-proxy) + [Error: Thaw pipe connection timed out, error on thaw, timeout waiting for VSS Freeze, or other timeout errors](#error-thaw) + [Error: Cannot invoke method. Method invocation is supported only on core types in this language mode](#error-invoke) ## Check log files If you experience problems or receive error messages when you create VSS based EBS snapshots, you can view the command output in the Systems Manager console. For Systems Manager documents that create VSS snapshots, you can set the `CollectDiagnosticLogs` parameter to "`True`" at runtime. When the `CollectDiagnosticLogs` parameter is set to "`True`", VSS collects additional logs to aid in debugging. For more information, see [Collect additional diagnostic logs](#vss-ts-collect-diagnostic-logs). If you collect diagnostic logs, the Systems Manager document stores them on your instance at the following location: `C:\ProgramData\Amazon\AwsVss\Logs\timestamp.zip`. The default for the `CollectDiagnosticLogs` parameter is "`False`". **Note** For additional debugging help, you can send the `.zip` file to Support. The following additional logs are available, whether you collect diagnostic logs or not: + `%ProgramData%\Amazon\SSM\InstanceData\InstanceID\document\orchestration\SSMCommandID\awsrunPowerShellScript\runPowerShellScript\stdout` + `%ProgramData%\Amazon\SSM\InstanceData\InstanceID\document\orchestration\SSMCommandID\awsrunPowerShellScript\runPowerShellScript\stderr` You can also open the Event Viewer Windows application and choose **Windows Logs**, **Application** to view additional logs. To see events specifically from the EC2 Windows VSS Provider and the Volume Shadow Copy Service, filter by **Source** on the terms **Ec2VssSoftwareProvider** and **VSS**. If you're using Systems Manager with VPC endpoints, and the Systems Manager [send-command](https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html) API action (**Run Command** in the console) failed, verify that you configured the following endpoint correctly: **com.amazonaws.*region*.ec2**. Without the Amazon EC2 endpoint defined, the call to enumerate attached EBS volumes fails, which causes the Systems Manager command to fail. For more information about setting up VPC endpoints with Systems Manager, see [Create a Virtual Private Cloud Endpoint](https://docs.aws.amazon.com/systems-manager/latest/userguide/setup-create-vpc.html) in the *AWS Systems Manager User Guide*. ## Collect additional diagnostic logs To collect additional diagnostic logs when you use the Systems Manager send command to run the VSS snapshot document, set the `CollectDiagnosticLogs` input parameter to "`True`" at runtime. We recommend that you set this parameter to "`True`" when you troubleshoot. To see a command line example, select one of the following tabs. ------ #### [ AWS CLI ] The following example runs the `AWSEC2-CreateVssSnapshot` Systems Manager document in the AWS CLI: ``` aws ssm send-command \ --document-name "AWSEC2-CreateVssSnapshot" \ --instance-ids "i-1234567890abcdef0" \ --parameters '{"description":["Example - create diagnostic logs at runtime."],"tags":["Key=tag_name,Value=tag_value"],"CollectDiagnosticLogs":["True"]}' ``` ------ #### [ PowerShell ] The following example runs the `AWSEC2-CreateVssSnapshot` Systems Manager document in PowerShell: ``` Send-SSMCommand ` -DocumentName "AWSEC2-CreateVssSnapshot" ` -InstanceId "i-1234567890abcdef0" ` -Parameter @{'description'='Example - create diagnostic logs at runtime.';'tags'='Key=tag_name,Value=tag_value';'CollectDiagnosticLogs'='True'} ``` ------ ## Use VSS on instances with proxy configured If you experience problems when creating VSS based EBS snapshots on instances that use a proxy to reach EC2 endpoints, verify the following settings on your instance: + Verify that the proxy is configured so that the EC2 service endpoints in the instance’s Region and IMDS are reachable by AWS Tools for Windows PowerShell running as SYSTEM. + To support using the system configured WinHTTP proxy, make sure that you've installed the latest `AwsVssComponents` version on your instance. For more information about configuring WinHTTP proxy, see [Netsh Commands for Windows Hypertext Transfer Protocol (WINHTTP)](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-r2-and-2008/cc731131(v=ws.10)) on the Microsoft website. ## Error: Thaw pipe connection timed out, error on thaw, timeout waiting for VSS Freeze, or other timeout errors The EC2 Windows VSS Provider might time out due to activity or services on the instance preventing VSS based snapshots from proceeding in a timely manner. The Windows VSS Framework provides a non-configurable 10-second window during which communication to the file system is paused. During this time, `AWSEC2-CreateVssSnapshot` snapshots your volumes. The following issues can cause the EC2 Windows VSS Provider to run into time limits during a snapshot: + Excessive I/O to a volume + Slow responsiveness of the EC2 API on the instance + Fragmented volumes + Incompatibility with some antivirus software + Issues with a VSS Application writer + When Module Logging is enabled for a large number of PowerShell modules, that can cause PowerShell scripts to run slowly Most timeout issues that occur when you run the `AWSEC2-CreateVssSnapshot` command document are related to the workload on the instance being too high at the time of the backup. The following actions can help you take a successful snapshot: + Retry the `AWSEC2-CreateVssSnapshot` command to see if the snapshot attempt is successful. If retrying succeeds in some cases, reducing the instance load might make snapshots more successful. + Wait a while for the workload on the instance to decrease, and retry the `AWSEC2-CreateVssSnapshot` command. Alternatively, you can attempt snapshots when the instance is known to be under low stress. + Attempt VSS snapshots when the antivirus software on the system is turned off. If this resolves the issue, refer to the antivirus software instructions and configure it to allow VSS snapshots. + If there is a high volume of Amazon EC2 API calls in your account within the same Region where you're running a snapshot, API throttling might delay snapshot operations. To reduce throttling impact, use the latest `AwsVssComponents` package. This package utilizes the EC2 `CreateSnapshots` API action to reduce the number of mutating actions like per-volume snapshot creation and tagging. + If you have multiple `AWSEC2-CreateVssSnapshot` command scripts running at the same time, you can take the following steps to reduce concurrency issues. + Consider scheduling snapshots during periods of lower API activity. + If you use **Run Command** in the Systems Manager console (or **SendCommand** in the API) to run the command script, you can use Systems Manager rate controls to reduce concurrency. You can also use Systems Manager rate controls to reduce concurrency for services like AWS Backup that use Systems Manager to run the command script. + Run the command `vssadmin list writers` in a shell and see if it reports any errors in the **Last error** field for any writers on the system. If any writers report a **time out** error, consider retrying snapshots when the instance is under less load. + When you use smaller instance types like *t2 \$1 t3 \$1 t3a*.nano or *t2 \$1 t3 \$1 t3a*.micro, timeouts due to memory and CPU constraints can occur. The following actions might help reduce timeout issues. + Try closing memory or CPU intensive applications before taking snapshots. + Try taking snapshots during periods of lower instance activity. ## Error: Cannot invoke method. Method invocation is supported only on core types in this language mode You will encounter this error when the PowerShell language mode is not set to `FullLanguage`. The `AWSEC2-CreateVssSnapshot` SSM document requires PowerShell to be configured to `FullLanguage` mode. To verify the language mode, run the following command on the instance in a PowerShell console: ``` $ExecutionContext.SessionState.LanguageMode ``` For more information about language modes, see [about\$1Language\$1Modes](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_language_modes) in the Microsoft documentation. # Use the AWS VSS solution to restore data for your instance You can restore EBS volumes for a Windows instance from VSS based snapshots created by the AWS VSS solution. If your AWS VSS solution snapshots contain backups of a Microsoft SQL Server database, you can restore the database using the `AWSEC2-RestoreSqlServerDatabaseWithVss` AWS Systems Manager Automation runbook. The database restore runbook automates the entire restore process, including creating volumes from the snapshots and attaching them to the instance. The automation leverages VSS technology to restore the database, allowing you to restore without stopping your SQL Server application or disconnecting any active connections. For detailed instructions on how to use the Microsoft SQL Server database runbook, see [Restore from VSS based snapshots](https://docs.aws.amazon.com/sql-server-ec2/latest/userguide/ms-ssdb-ec2-restore-vss.html) in the *Microsoft SQL Server on Amazon EC2 User Guide*. ## Customize a script to restore EBS volumes from AWS VSS solution snapshots You can use the `RestoreVssSnapshotSampleScript.ps1` script as a model to create your own custom script that restores EBS volumes from AWS VSS solution snapshots. The sample script performs the following tasks: + Stops an instance + Removes all existing drives from the instance (except the boot volume, if it was excluded) + Creates new volumes from the snapshots + Attaches the volumes to the instance by using the device ID tag on the snapshot + Restarts the instance **Important** The following script detaches all volumes attached to an instance, and then creates new volumes from a snapshot. Make sure that you have properly backed-up the instance. The old volumes are not deleted. If you want, you can edit the script to delete the old volumes. **To restore volumes from VSS based EBS snapshots** 1. Download the [RestoreVssSnapshotSampleScript.zip](https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/RestoreVssSnapshotSampleScript.zip) file and extract the file contents. 1. Open `RestoreVssSnapshotSampleScript.ps1` in a text editor and edit the sample call at the bottom of the script with a valid EC2 instance ID and EBS snapshot ID, and then run the script from PowerShell. # AWS VSS solution version history This page includes release notes by version for the AWS VSS component package, as well as component and script version requirements for each supported version of Windows Server. **Topics** + [AwsVssComponents package versions](#AwsVssComponents-history) + [Windows OS version support](#windows-version-support) ## AwsVssComponents package versions The following table describes the released versions of the AWS VSS component package. | Version | Details | Release date | Downloadable | | --- | --- | --- | --- | | 2.5.1 | Fixed a case where SQL database restoration could fail when the target database parameter is specified. | March 13, 2025 | Yes | | 2.5.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/vss-comps-history.html) | January 17, 2025 | Yes | | 2.4.0 | Added the capability to save VSS metadata files on snapshot creation. To enable this feature, see SaveVssMetadata in [Parameters for Systems Manager VSS snapshot documents](create-vss-snapshots-ssm.md#create-vss-snapshots-ssm-params). | October 7, 2024 | Yes | | 2.3.3 | Updated the VSS agent to ensure that the `Ec2VssProvider` is used during snapshot creation. | June 25, 2024 | Yes | | 2.3.2 | Fixed a case where VSS provider registration is not removed on uninstallation. | May 9, 2024 | Yes | | 2.3.1 | Added new default tag `AwsVssConfig` to identify snapshots and AMIs created by AWS VSS. | March 7, 2024 | Yes | | 2.2.1 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/vss-comps-history.html) | January 18, 2024 | Yes | | 2.1.0 | Added support for using the `CreateSnapshots` API. | November 6, 2023 | Yes | | 2.0.1 | Added support for using the WinHTTP proxy settings. | October 26, 2023 | No | | 2.0.0 | Added capability to the AWS VSS component to create snapshots and AMIs, which enables compatibility with PowerShell module logging, script block logging, and transcription features. | April 28, 2023 | No | | 1.3.2.0 | Fixed a case where installation failure is not reported correctly. | May 10, 2022 | No | | 1.3.1.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/vss-comps-history.html) | February 6, 2020 | Yes | | 1.3.00 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/vss-comps-history.html) | March 19, 2019 | No | | 1.2.00 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/vss-comps-history.html) | November 15, 2018 | No | | 1.1 | Fixed AWS VSS components that were being used incorrectly as the default Windows Backup and Restore provider. | December 12, 2017 | No | | 1.0 | Initial release. | November 20, 2017 | No | ## Windows OS version support The following table shows which AWS VSS solution versions you should run on each version of Windows Server on Amazon EC2. | Windows Server version | AwsVssComponents version | AWSEC2-VssInstallAndSnapshot version name | AWSEC2-CreateVssSnapshot version name | | --- | --- | --- | --- | | Windows Server 2025 | default | default | default | | Windows Server 2022 | default | default | default | | Windows Server 2019 | default | default | default | | Windows Server 2016 | default | default | default | | Windows Server 2012 R2 | 2.1.0 | not supported | 2012R2 | | Windows Server 2012 | 2.1.0 | not supported | 2012R2 | | Windows Server 2008 R2 | 1.3.1.0 | not supported | 2008R2 | # Object storage, file storage, and file caching on Amazon EC2 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. The following content introduces some of the storage services provided by AWS for use with Amazon EC2 instances. **Topics** + [Use Amazon S3 with Amazon EC2 instances](AmazonS3.md) + [Use Amazon EFS with Amazon EC2 Linux instances](AmazonEFS.md) + [Use Amazon FSx with Amazon EC2 instances](storage_fsx.md) + [Use Amazon File Cache with Amazon EC2 instances](AmazonEFC.md) # Use Amazon S3 with Amazon EC2 instances Amazon Simple Storage Service (Amazon S3) is an object storage service that offers industry-leading scalability, data availability, security, and performance. You can use Amazon S3 to store and retrieve any amount of data for a range of use cases, such as data lakes, websites, backups, and big data analytics, from an Amazon EC2 instance or from anywhere over the internet. For more information, see [What is Amazon S3?](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html) There are two ways to access Amazon S3 data from your Amazon EC2 instances: + **File access** – Use [Amazon S3 Files](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-files.html) to mount an S3 bucket as a high performance file system on your instance. + **Object access** – Use the [Amazon S3 API](https://docs.aws.amazon.com/AmazonS3/latest/API/), AWS CLI, AWS SDKs, or tools like wget to copy objects to and from S3. ## File access with Amazon S3 Files Amazon S3 Files is a serverless file system that lets you mount your S3 general purpose bucket as a high performance file system on your compute instance. With S3 Files, you can access your S3 objects as files by using standard file system operations such as read and write on the local mount path. You can mount an S3 file system to an EC2 instance either at launch, or after launch on a running instance. **Prerequisites** Before you set up S3 Files with your EC2 instance, make sure you have the following: + An S3 file system and at least one mount target in the available state. For information about creating an S3 file system, see [Working with Amazon S3 Files](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-files.html) in the *Amazon S3 User Guide*. + An EC2 Linux instance with an instance profile attached to it. For information about the required permissions to mount the file system, see [IAM roles and policies ](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-files-prereq-policies.html#s3-files-prereq-iam) in the *Amazon S3 User Guide*. + Security groups that allow NFS traffic (port 2049) between your instance and the file system’s mount targets. For information about the required security group settings, see [Security groups](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-files-prereq-policies.html#s3-files-prereq-security-groups) in the *Amazon S3 User Guide*. **To mount a file system to an EC2 instance at launch using the EC2 console** 1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. Choose **Launch instance**. 1. Under **Network settings**, do the following: 1. Choose **Edit**. 1. For **Subnet**, select a subnet. 1. Select the default security group to make sure that your EC2 instance can access your S3 file system. You can't access your EC2 instance by Secure Shell (SSH) using this security group. For access by SSH, you can later edit the default security group and add a rule to allow SSH, or add a new security group that allows SSH. You can use the following settings: 1. **Type:** SSH 1. **Protocol:** TCP 1. **Port Range:** 22 1. **Source:** Anywhere 0.0.0.0/0 1. Under **Configure storage**, do the following: 1. Under **File systems**, choose **S3 Files**. 1. Choose **Add shared file system**. 1. For **S3 file system**, your file systems appear in the Availability Zone based on the subnet that you selected in your Network settings. Choose the S3 file system that you want to mount. If you don’t have any file systems, choose **Create a new file system** to create a new one. 1. Enter a local mount path on your EC2 instance where you want to mount the file system (for example, `/mnt/s3files`). 1. A command will be generated to mount the file system and add it to fstab. You can add this command to the **User data** field under **Advanced details**. Your EC2 instance will then be configured to mount the S3 file system at launch and whenever it's rebooted. You can also run these commands in your EC2 instance after it is launched. 1. Under **Advanced details**, attach an instance profile to your instance. Your IAM role must have permissions to mount the file system and access the S3 bucket. For more information about the required permissions, see [IAM roles and policies](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-files-prereq-policies.html#s3-files-prereq-iam) in the *Amazon S3 User Guide*. 1. Choose **Launch instance**. After the instance launches, the required software utilities are installed and the file system is mounted. You can view the file system by navigating to your local mount path. **To mount a file system to an EC2 instance after launch** 1. [Connect to your EC2 instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connect.html) through Secure Shell (SSH) or by using EC2 Instance Connect in the EC2 console. 1. To mount your S3 file system, use the mount helper utility `amazon-efs-utils`. Depending on your Linux distribution, use one of the following commands to install the `amazon-efs-utils` package: 1. If you’re using Amazon Linux, run the following command to install efs-utils from Amazon's repositories: ``` sudo yum -y install amazon-efs-utils ``` 1. If you are using other [supported Linux distributions](https://github.com/aws/efs-utils/?tab=readme-ov-file#efs-utils), run the following command: ``` curl https://amazon-efs-utils.aws.com/efs-utils-installer.sh | sudo sh -s -- --install ``` 1. For other Linux distributions, see the [efs-utils](https://github.com/aws/efs-utils/?tab=readme-ov-file#on-other-linux-distributions) repository on *GitHub*. 1. Create a directory for the file system mount point using the following command: ``` sudo mkdir {path/to/mount} ``` 1. Mount the S3 file system: ``` FS="{YOUR_FILE_SYSTEM_ID}" sudo mount -t s3files $FS:/ {path/to/mount} ``` 1. Confirm the file system is mounted: ``` df -h {path/to/mount} ``` **To view objects in your S3 bucket as files** Having completed the preceding procedures, you can now read and write S3 objects as files on your local mount path using standard file system operations. If you have objects in your S3 bucket, you can view them as files by using the following command: ``` ls {path/to/mount} ``` ## Object-based access You can copy files to and from Amazon S3 using the S3 API, AWS CLI, AWS SDKs, or standard HTTP tools. If you have the required permissions, you can copy a file to or from Amazon S3 and your instance using one of the following methods. ------ #### [ wget ] **Note** This method works for public objects only. If the object is not public, you receive an `ERROR 403: Forbidden` message. If you receive this error, you must use either the Amazon S3 console, AWS CLI, AWS API, AWS SDK, or AWS Tools for Windows PowerShell, and you must have the required permissions. For more information, see [Identity and access management for Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/security-iam.html) and [ Downloading an object](https://docs.aws.amazon.com/AmazonS3/latest/userguide/download-objects.html) in the *Amazon S3 User Guide*. The **wget** utility is an HTTP and FTP client that you can use 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. ``` [ec2-user ~]$ wget https://amzn-s3-demo-bucket.s3.amazonaws.com/path-to-file ``` ------ #### [ PowerShell ] You can use the [AWS Tools for Windows PowerShell](https://aws.amazon.com/powershell/) to move objects to and from Amazon S3. Use the [Copy-S3Object](https://docs.aws.amazon.com/powershell/latest/reference/items/Copy-S3Object.html) cmdlet to copy an Amazon S3 object to your Windows instance as follows. ``` Copy-S3Object ` -BucketName amzn-s3-demo-bucket ` -Key path-to-file ` -LocalFile my_copied_file.ext ``` Alternatively, you can open the Amazon S3 console by using a web browser on the Windows instance. ------ #### [ AWS CLI ] You can use the AWS Command Line Interface (AWS CLI) to download restricted items from Amazon S3 and to upload items. For more information, such as how to install and configure the tools, see the [AWS Command Line Interface detail page](https://aws.amazon.com/cli/). The [aws s3 cp](https://docs.aws.amazon.com/cli/latest/reference/s3/cp.html) 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: ``` aws s3 cp s3://amzn-s3-demo-bucket/my_folder/my_file.ext my_copied_file.ext ``` Use the following command to copy an object from your instance back into Amazon S3: ``` aws s3 cp my_copied_file.ext s3://amzn-s3-demo-bucket/my_folder/my_file.ext ``` The [aws s3 sync](https://docs.aws.amazon.com/cli/latest/reference/s3/sync.html) 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. Use the following command to download an entire Amazon S3 bucket to a local directory on your instance: ``` aws s3 sync s3://amzn-s3-demo-source-bucket local_directory ``` ------ #### [ Amazon S3 API ] You can use an API to access data in Amazon S3. You can use this API to help develop your application and integrate it with other APIs and SDKs. For more information, see [Code examples for Amazon S3 using AWS SDKs](https://docs.aws.amazon.com/AmazonS3/latest/API/service_code_examples.html) in the *Amazon Simple Storage Service API Reference*. ------ # Use Amazon EFS with Amazon EC2 Linux instances **Note** Amazon EFS is not supported on Windows instances. Amazon EFS provides scalable file storage for use with Amazon EC2. You can use an EFS file system as a common data source for workloads and applications running on multiple instances. For more information, see the [Amazon Elastic File System product page](https://aws.amazon.com/efs/). This tutorial shows you how to create and attach an Amazon EFS file system using the Amazon EFS Quick Create wizard during instance launch. For a tutorial on how to create a file system using the Amazon EFS console, see [Getting started with Amazon Elastic File System](https://docs.aws.amazon.com/efs/latest/ug/getting-started.html) in the *Amazon Elastic File System User Guide*. **Note** When you create an EFS file system using EFS Quick Create, the file system is created with the following service recommended settings: [Automatic backups enabled](https://docs.aws.amazon.com/efs/latest/ug/awsbackup.html). [Manage mount targets](https://docs.aws.amazon.com/efs/latest/ug/accessing-fs.html) in the selected VPC. [ General Purpose performance mode](https://docs.aws.amazon.com/efs/latest/ug/performance.html#performancemodes). [Bursting throughput mode](https://docs.aws.amazon.com/efs/latest/ug/performance.html#throughput-modes). [Encryption of data at rest enabled](https://docs.aws.amazon.com/efs/latest/ug/encryption-at-rest.html) using your default key for Amazon EFS (`aws/elasticfilesystem`). [Amazon EFS lifecycle management enabled](https://docs.aws.amazon.com/efs/latest/ug/lifecycle-management-efs.html) with a 30-day policy. **Topics** + [Create an EFS file system using Amazon EFS Quick Create](#quick-create) + [Test the EFS file system](#efs-test-file-system) + [Delete the EFS file system](#efs-clean-up) ## Create an EFS file system using Amazon EFS Quick Create You can create an EFS file system and mount it to your instance when you launch your instance using the Amazon EFS Quick Create feature of the Amazon EC2 [launch instance wizard](ec2-launch-instance-wizard.md). **To create an EFS file system using Amazon EFS Quick Create** 1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. Choose **Launch instance**. 1. (Optional) Under **Name and tags**, for **Name**, enter a name to identify your instance. 1. Under **Application and OS Images (Amazon Machine Image)**, choose a Linux operating system, and then for **Amazon Machine Image (AMI)**, select a Linux AMI. 1. Under **Instance type**, for **Instance type**, select an instance type or keep the default. 1. Under **Key pair (login)**, for **Key pair name**, choose an existing key pair or create a new one. 1. Under **Network settings**, choose **Edit** (at right), and then for **Subnet**, select a subnet. **Note** You must select a subnet before you can add an EFS file system. 1. Under **Configure storage**, choose **Edit** (at bottom right), and then do the following: 1. For **File systems**, ensure that **EFS** is selected, and then choose **Create new shared file system**. 1. For **File system name** enter a name for the Amazon EFS file system, and then choose **Create file system**. 1. For **Mount point**, specify a custom mount point or keep the default. 1. To enable access to the file system, select **Automatically create and attach security groups**. By selecting this checkbox, the following security groups will be automatically created and attached to the instance and the mount targets of the file system: + Instance security group – Includes an outbound rule that allows traffic over the NFS 2049port, but includes no inbound rules. + File system mount targets security group – Includes an inbound rule that allows traffic over the NFS 2049 port from the instance security group (described above), and an outbound rule that allows traffic over the NFS 2049 port. **Note** Alternatively, you can manually create and attach the security groups. If you want to manually create and attach the security groups, clear **Automatically create and attach the required security groups**. 1. To automatically mount the shared file system when the instance launches, select **Automatically mount shared file system by attaching required user data script**. To view the user data that is automatically generated, expand **Advanced details**, and scroll down to **User data**. **Note** If you added user data before selecting this checkbox, the original user data is overwritten by the automatically generated user data. 1. Configure any other instance configuration settings as needed. 1. In the **Summary** panel, review your instance configuration, and then choose **Launch instance**. For more information, see [Launch an EC2 instance using the launch instance wizard in the console](ec2-launch-instance-wizard.md). ## Test the EFS file system You can connect to your instance and verify that the file system is mounted to the directory that you specified (for example, /mnt/efs). **To verify that the file system is mounted** 1. Connect to your instance. For more information, see [Connect to your Linux instance using SSH](connect-to-linux-instance.md). 1. From the terminal window for the 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:/ ``` 1. (Optional) Create a file in the file system from the instance, and then verify that you can view the file from another instance. 1. From the instance, run the following command to create the file. ``` $ sudo touch /mnt/efs/test-file.txt ``` 1. From the other instance, run the following command to view the file. ``` $ ls /mnt/efs test-file.txt ``` ## Delete the EFS file system If you no longer need your file system, you can delete it. **To delete the file system** 1. Open the Amazon Elastic File System console at [https://console.aws.amazon.com/efs/](https://console.aws.amazon.com/efs/). 1. Select the file system to delete. 1. Choose **Actions**, **Delete file system**. 1. When prompted for confirmation, enter the file system ID and choose **Delete file system**. # Use Amazon FSx with Amazon EC2 instances The Amazon FSx family of services makes it easy to launch, run, and scale shared storage powered by popular commercial and open-source file systems. You can use the *new launch instance wizard* to automatically attach the following types of Amazon FSx file systems to your Amazon EC2 instances at launch: + Amazon FSx for NetApp ONTAP provides fully managed shared storage in the AWS Cloud with the popular data access and management capabilities of NetApp ONTAP. + Amazon FSx for OpenZFS provides fully managed cost-effective shared storage powered by the popular OpenZFS file system. **Note** This functionality is available in the new launch instance wizard only. For more information, see [Launch an EC2 instance using the launch instance wizard in the console](ec2-launch-instance-wizard.md) Amazon FSx for Windows File Server and Amazon FSx for Lustre file systems can't be mounted at launch. You must mount these file systems manually after launch. You can choose to mount an existing file system that you created previously, or you can create a new file system to mount to an instance at launch. **Topics** + [Security groups and user data script](#sg-user-data) + [Mount an Amazon FSx file system at launch](#mount-fsx) ## Security groups and user data script When you mount an Amazon FSx file system to an instance using the launch instance wizard, you can choose whether to automatically create and attach the security groups needed to enable access to the file system, and whether to automatically include the user data scripts needed to mount the file system and make it available for use. **Topics** + [Security groups](#fsx-sg) + [User data script](#fsx-user-data) ### Security groups If you choose to automatically create the security groups that are needed to enable access to the file system, the launch instance wizard creates and attaches two security groups - one security group is attached to the instance, and the other is attached to the file system. For more information about the security group requirements, see [FSx for ONTAP file system access control with Amazon VPC](https://docs.aws.amazon.com/fsx/latest/ONTAPGuide/limit-access-security-groups.html) and [FSx for OpenZFS file system access control with Amazon VPC](https://docs.aws.amazon.com/fsx/latest/OpenZFSGuide/limit-access-security-groups.html). We add the tag `Name=instance-sg-1` to the security group that is created and attached to the instance. The value in the tag is automatically incremented each time the launch instance wizard creates a security group for Amazon FSx file systems. The security group includes the following output rules, but no inbound rules. **Outbound rules** | Protocol type | Port number | Destination | | --- | --- | --- | | UDP | 111 | file system security group | | UDP | 20001 - 20003 | file system security group | | UDP | 4049 | file system security group | | UDP | 2049 | file system security group | | UDP | 635 | file system security group | | UDP | 4045 - 4046 | file system security group | | TCP | 4049 | file system security group | | TCP | 635 | file system security group | | TCP | 2049 | file system security group | | TCP | 111 | file system security group | | TCP | 4045 - 4046 | file system security group | | TCP | 20001 - 20003 | file system security group | | All | All | file system security group | The security group that is created and attached to the file system is tagged with `Name=fsx-sg-1`. The value in the tag is automatically incremented each time the launch instance wizard creates a security group for Amazon FSx file systems. The security group includes the following rules. **Inbound rules** | Protocol type | Port number | Source | | --- | --- | --- | | UDP | 2049 | instance security group | | UDP | 20001 - 20003 | instance security group | | UDP | 4049 | instance security group | | UDP | 111 | instance security group | | UDP | 635 | instance security group | | UDP | 4045 - 4046 | instance security group | | TCP | 4045 - 4046 | instance security group | | TCP | 635 | instance security group | | TCP | 2049 | instance security group | | TCP | 4049 | instance security group | | TCP | 20001 - 20003 | instance security group | | TCP | 111 | instance security group | **Outbound rules** | Protocol type | Port number | Destination | | --- | --- | --- | | All | All | 0.0.0.0/0 | ### User data script If you choose to automatically attach user data scripts, the launch instance wizard adds the following user data to the instance. This script installs the necessary packages, mounts the file system, and updates your instance settings so that the file system will automatically re-mount whenever the instance restarts. ``` #cloud-config package_update: true package_upgrade: true runcmd: - yum install -y nfs-utils - apt-get -y install nfs-common - svm_id_1=svm_id - file_system_id_1=file_system_id - vol_path_1=/vol1 - fsx_mount_point_1=/mnt/fsx/fs1 - mkdir -p "${fsx_mount_point_1}" - if [ -z "$svm_id_1" ]; then printf "\n${file_system_id_1}.fsx.eu-north-1.amazonaws.com:/${vol_path_1} ${fsx_mount_point_1} nfs4 nfsvers=4.1,rsize=1048576,wsize=1048576,hard,timeo=600,retrans=2,noresvport,_netdev 0 0\n" >> /etc/fstab; else printf "\n${svm_id_1}.${file_system_id_1}.fsx.eu-north-1.amazonaws.com:/${vol_path_1} ${fsx_mount_point_1} nfs4 nfsvers=4.1,rsize=1048576,wsize=1048576,hard,timeo=600,retrans=2,noresvport,_netdev 0 0\n" >> /etc/fstab; fi - retryCnt=15; waitTime=30; while true; do mount -a -t nfs4 defaults; if [ $? = 0 ] || [ $retryCnt -lt 1 ]; then echo File system mounted successfully; break; fi; echo File system not available, retrying to mount.; ((retryCnt--)); sleep $waitTime; done; ``` ## Mount an Amazon FSx file system at launch **To mount a new or existing Amazon FSx file system at launch** 1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. In the navigation pane, choose **Instances** and then choose **Launch instance** to open the launch instance wizard. 1. In the **Application and OS Images** section, select the AMI to use. 1. In the **Instance type** section, select the instance type. 1. In the **Key pair** section, select an existing key pair or create a new one. 1. In the **Network settings** section, do the following: 1. Choose **Edit**. 1. If you want to **mount an existing file system**, for **Subnet**, choose the file system's preferred subnet. We recommend that you launch the instance into the same Availability Zone as the file system's preferred subnet to optimize performance. If you want to **create a new file system** to mount to an instance, for **Subnet**, choose the subnet into which to launch the instance. **Important** You must select a subnet to enable the Amazon FSx functionality in the new launch instance wizard. If you do not select a subnet, you will not be able to mount an existing file system or create a new one. 1. In the **Storage** section, do the following: 1. Configure the volumes as needed. 1. Expand the **File systems** section and select **FSx**. 1. Choose **Add shared file system**. 1. For **File system**, select the file system to mount. **Note** The list displays all Amazon FSx for NetApp ONTAP and Amazon FSx for OpenZFS file systems in your account in the selected Region. 1. To automatically create and attach the security groups needed to enable access to the file system, select **Automatically create and attach security groups**. If you prefer to create the security groups manually, clear the checkbox. For more information, see [Security groups](#fsx-sg). 1. To automatically attach the user data scripts needed to mount the file system, select **Automatically mount shared file system by attaching required user data script**. If you prefer to provide the user data scripts manually, clear the checkbox. For more information, see [User data script](#fsx-user-data). 1. In the **Advanced** section, configure the additional instance settings as needed. 1. Choose **Launch**. # Use Amazon File Cache with Amazon EC2 instances Amazon File Cache provides a fully managed, high-speed cache on AWS that makes it easier to process file data, regardless of where the data is stored. Amazon File Cache serves as a temporary, high-performance storage location for data that's stored in on-premises file systems, AWS file systems, and Amazon Simple Storage Service (Amazon S3) buckets. You can use this capability to make dispersed datasets available to file-based applications on AWS with a unified view, and at high speeds—sub-millisecond latencies and high throughput. For more information, see the [Amazon File Cache User Guide](https://docs.aws.amazon.com/fsx/latest/FileCacheGuide/what-is.html). Amazon File Cache works with the most popular Linux AMIs, and is compatible with x86-based instance types and Graviton instance types. You can access your cache from your Amazon EC2 instances using the open-source Lustre client. You can mount your cache and then work with the files and directories in your cache using standard Linux commands. Amazon EC2 instances can access your cache from other Availability Zones within the same virtual private cloud (VPC), provided that your network configuration allows access across subnets within the VPC. You can also create a cache in a shared VPC. To get started, see [ Getting started with Amazon File Cache](https://docs.aws.amazon.com/fsx/latest/FileCacheGuide/getting-started.html) in the *Amazon File Cache User Guide*.