Amazon Elastic Compute Cloud
User Guide (API Version 2013-02-01)
AWS Documentation » Amazon EC2 » User Guide » Storage » Block Device Mapping
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.Did this page help you?  Yes | No |  Tell us about it...
Filter View:

Block Device Mapping

Each Amazon EC2 instance that you launch has an associated root device volume, either an Amazon Elastic Block Store (EBS) volume or an instance store volume. You can use block device mapping 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; see Attaching a Volume to an Instance. However, the only way to attach instance store volumes to an instance is to use block device mapping to attach them as the instance is launched.

For more information about root device volumes, see Changing the Root Device Volume to Persist.

Topics

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)

  • Amazon EBS volumes (remote storage devices)

A block device mapping defines the block devices to be attached to an Amazon EC2 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.

Specifying a Block Device Mapping

Use a block device mapping to attach instance store volumes and EBS volumes to an Amazon EC2 instance.

When you create a block device mapping, you specify this information for each block device that you need to attach to the instance:

  • [Linux/UNIX] The device name within Amazon EC2, as shown in this table. The block device driver for the instance assigns the actual volume name when mounting the volume, and the name assigned can be different than the name that Amazon EC2 recommends.

    Reserved for the root device

    /dev/sda1

    Recommended for instance store volumes

    /dev/sd[b-e]

    Recommended for EBS volumes

    /dev/sd[f-p]

    /dev/sd[f-p][1-6]

    Possible for EBS volumes

    /dev/sd[a-z]

    /dev/sd[a-z][1-15] (see Tip)

    /dev/hd[a-z]

    /dev/hd[a-z][1-15]

    Tip

    On some devices, the names that you specify in your block device mapping can conflict with the default block device names. To avoid this issue, do not use names of the form /dev/sda[2-15].

  • [Windows] The device name within Amazon EC2, as shown in this table. The block device driver for the instance assigns the actual volume name when mounting the volume, and the name assigned can be different than the name that Amazon EC2 recommends.

    Reserved for the root device

    /dev/sda1

    Recommended for instance store volumes

    xvd[a-e]

    Recommended for EBS volumes

    xvd[f-p]

    Possible for EBS volumes

    xvd[a-p]

    /dev/sda[1-2]

    /dev/sd[b-e]

  • [Instance store volumes only] The virtual device: ephemeral[0-3].

  • [EBS volumes only] The ID of the snapshot to use to create the block device (snap-xxxxxxxx). This value is optional as long as you specify a volume size.

  • [EBS volumes only] The size of the volume, in GiB. The specified size must be greater than or equal to the size of the specified snapshot.

  • [EBS volumes only] Whether to delete the volume on instance termination (true or false). The default value is true.

  • [EBS volumes only] The volume type (standard or io1). The default value is standard.

  • [EBS volumes only] The number of input/output operations per second (IOPS) that the volume supports. (Not used with standard volumes.)

Example Block Device Mapping

This figure shows an example block device mapping for an Amazon 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 device volume, /dev/sda1.

Relationship between instance, instance store volumes, and EBS volumes.

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

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

With a Linux instance, the device names specified in the block device mapping are mapped to their corresponding block devices when the instance first boots. The instance type determines which instance store volumes are formatted and mounted by default. You can mount additional instance store volumes at launch, as long as you don't exceed the number of instance store volumes available for your instance type. For more information, see Amazon EC2 Instance Store. The block device driver for the instance determines which devices are used when the volumes are formatted and mounted. For more information, see Attaching a Volume to an Instance.

With a Windows instance, 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 device volume is mounted as C:\. The instance store volumes are mounted as D:\, E:\, and so on. When an EBS volume is mounted, it can be mounted using any available drive letter. However, you can configure how the Ec2Config Service assigns drive letters to EBS volumes; for more information, see Using EC2Config.

Viewing Block Device Mappings

You can view information about each block device in a block device mapping. For details, see:

AMI Block Device Mapping

Each AMI has a block device mapping that specifies the block devices to attach to an instance when it is launched from the AMI. An AMI that Amazon provides includes a root device only. To add additional block devices to an AMI, you must create your own AMI.

Specifying 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 instance store-backed AMI, you can add only instance store volumes using a block device mapping.

AWS Management Console

To add volumes to an AMI

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. In the navigation pane, click Instances.

  3. Select an instance and select Create Image (EBS AMI) from the Actions list.

  4. In the Create Image dialog box, click Instance Store Volumes.

  5. [Optional] For each instance store volume, select a volume from the Instance Store list and a device name from Device, and then click Add.

    Instance Store Volumes tab in the Create Image dialog box

  6. Click Yes, Create.

Command Line Interface

Use ec2-register -b "devicename=blockdevice" to create an AMI with a block device mapping.

devicename

The device name within Amazon EC2

blockdevice

To omit a mapping for the device from the AMI, specify none.

To add an instance store device, specify ephemeral[0-3].

[EBS-backed instance only] To add an EBS volume, specify snapshot-id:size:[true|false]. To add an empty EBS volume, omit the snapshot ID. To indicate whether the EBS volume should be deleted on termination, specify true or false; the default value is true.

For example, run this command at a command prompt to register an Amazon EBS-backed Linux AMI with a EBS root volume, an instance store volume, an EBS volume based on a snapshot, and an empty 100 GiB EBS volume. (Be sure to set the EC2_PRIVATE_KEY and EC2_CERT environment variables first.)

ec2-register -n ImageName --root-device-name /dev/sda1 -s snap-e1eb279f
-b "/dev/sdb=ephemeral0" -b "/dev/sdh=snap-d5eb27ab" -b "/dev/sdj=:100"

This command maps /dev/sda to a EBS root volume based on a snapshot, /dev/sdb to ephemeral0, /dev/sdh to an EBS volume based on a snapshot, and /dev/sdj to an empty EBS volume that is 100 GiB in size. The output is the ID for your new AMI.

IMAGE ami-72aa081b

For more information, see ec2-register.

To verify that the AMI was created successfully, look for it in the Amazon EC2 Console (click AMIs in the navigation pane, then select Owned By Me from the Filter drop-down list) or the output of the following command:

ec2-describe-images -o self

Alternatively, if you've already attached volumes to an instance, you can use one of these methods as appropriate.

Viewing the EBS Volumes in an AMI Block Device Mapping

You can easily enumerate the EBS volumes in the block device mapping for an AMI.

AWS Management Console

Use the AWS Management Console as follows to enumerate the EBS volumes in the block device mapping for an AMI:

To view the EBS volumes for an AMI

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/

  2. In the navigation pane, click AMIs.

  3. Select EBS Images from the Filter drop-down list to get a list of EBS-backed AMIs.

  4. Locate and the desired AMI and click the Go to Details Page button (the magnifying glass). At a minimum, the following information is available for the root device:

    • Root Device Type (ebs)

    • Root Device Name (for example, /dev/sda1)

    • Block Devices (for example, /dev/sda1=snap-e1eb279f: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 EBS volumes as well. (Recall that this screen doesn’t display instance store volumes.)

Command Line Interface

Use ec2-describe-images ami_id to enumerate the EBS volumes in the block device mapping for an AMI.

For example, run this command at a command prompt to get information about an AMI, including its block device mapping. (Be sure to set the EC2_PRIVATE_KEY and EC2_CERT environment variables first.)

ec2-describe-images ami-72aa081b

The output includes the block device mapping for your AMI. The following information is available for EBS volumes:

  • The device name within Amazon EC2

  • The ID of the snapshot used when creating the block device (optional)

  • The size of the volume, in GiB

  • The volume type.

Here's example output for a Linux AMI.

BLOCKDEVICEMAPPING    /dev/sda1    snap-e1eb279f    8      standard
BLOCKDEVICEMAPPING    /dev/sdh     snap-d5eb27ab    200    standard
BLOCKDEVICEMAPPING    /dev/sdj                      100    standard

For more information, see ec2-describe-images.

Instance Block Device Mapping

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. However, you can't modify the block device mapping entry for the root device volume.

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

AWS Management Console

To add volumes to an instance

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. From the Amazon EC2 console dashboard, click Launch Instance.

  3. On the Create a New Instance page, click Classic Wizard.

  4. On the CHOOSE AN AMI page, choose the AMI to use and click Select.

  5. Follow the wizard to complete the first and second INSTANCE DETAIL pages.

  6. On the third INSTANCE DETAIL page, click Edit under Storage Device Configuration. You can modify the root volume, EBS volumes, and instance store volumes as follows:

    • To change the size of the root volume, click Root Volume, fill in the Volume Size field, and click Save.

    • To suppress an EBS volume specified by the block device mapping of the AMI used to launch the instance, click EBS Volumes, go to the volume, and click Delete.

    • To add an EBS volume, click EBS Volumes, fill in the fields (Device, Snapshot, and so on), and click Add.

    • To suppress an instance store volume specified by the block device mapping of the AMI used to launch the instance, click Instance Store Volumes, go to the volume, and click Delete.

    • To add an instance store volume, click Instance Store Volumes, select the Instance Store and Device, and click Add.

    Instance Store Volumes tab in Storage Device Configuration

  7. Complete the remaining wizard pages, and then click Launch Instance.

Command Line Interface

Use ec2-run-instances -b "devicename=blockdevice" to define an entry for the block device mapping for an instance.

devicename

The device name within Amazon EC2

blockdevice

To omit a mapping for the device from the AMI, specify none.

To add an instance store device, specify ephemeral[0-3].

[EBS-backed instance only] To add an EBS volume, specify snapshot-id:size:[true|false]. To add an empty EBS volume, omit the snapshot ID. To indicate whether the EBS volume should be deleted on termination, specify true or false; the default value is true.

For example, suppose that an EBS-backed Linux AMI specifies the following block device mapping:

  • /dev/sdb=ephemeral0

  • /dev/sdh=snap-92d333fb

  • /dev/sdj=:100

To prevent /dev/sdj from attaching to an instance launched from this AMI, use this option.

–b "/dev/sdj=none"

To increase the size of /dev/sdh to 300 GiB, use this option.

–b "/dev/sdh=:300"

Notice that we didn't need to specify the snapshot ID for /dev/sdh, because specifying the device name is enough to identify the volume.

To attach an additional instance store volume, /dev/sdc, use this option. If the instance type doesn't support more than one instance store volume, this option has no effect.

–b "/dev/sdc=ephemeral1"

For more information, see ec2-run-instances.

Viewing the EBS Volumes in an Instance Block Device Mapping

You can easily enumerate the EBS volumes mapped to an instance.

Note

For instances launched before the release of the 2009-10-31 API, AWS can't display the block device mapping. You must detach and reattach the volumes so that AWS can display the block device mapping.

AWS Management Console

Use the AWS Management Console to enumerate the EBS volumes in the block device mapping for an instance.

To view the EBS volumes for an instance

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/

  2. In the navigation pane, click Instances.

  3. In the Viewing menu, click EBS Root Device to filter the list. This displays a list of Amazon EBS-backed instances.

  4. Locate and click the desired instance and look at the details displayed in the EC2 Instances pane. At a minimum, the following information is available for the root device:

    • Root Device Type (ebs)

    • Root Device (for example, sda1)

    • Block Devices (for example, sda1, sdh, and sdj)

    If the instance was launched with additional EBS volumes using a block device mapping, the Block Devices box displays those additional EBS volumes as well as the root device. (Recall that this dialog box doesn't display instance store volumes.)

    Block devices for an instance.

  5. To display additional information about a block device, click its entry under Block Devices. This displays the following information for the block device:

    • EBS ID (vol-xxxxxxxx)

    • Root Device Type (ebs)

    • Attachment time (yyyy-mmThh:mm:ss.ssTZD)

    • Block device status (attaching, attached, detaching, detached)

    • Delete on termination (Yes, No)

    • Snapshot ID (snap-xxxxxxxx)

    Details for a block device.

Command Line Interface

Use ec2-describe-instances instance_id to enumerate the EBS volumes in the block device mapping for an instance.

For example, run this command at a command prompt to get information about an instance, including its block devices. (Be sure to set the EC2_PRIVATE_KEY and EC2_CERT environment variables first.)

ec2-describe-instances i-xxxxxxxx

The output includes the block devices for your instance. The following information is available for EBS volumes:

  • The device name within Amazon EC2

  • The volume ID

  • The time when the attachment was initiated

  • Whether to delete the volume on instance termination

  • The volume type (standard or io1)

  • The number of input/output operations per second (IOPS) that the volume supports. (Not used with standard volumes.)

The output for a Linux instance looks something like this.

BLOCKDEVICE    /dev/sda1    vol-xxxxxxxx    yyyy-mmThh:mm:ss.sTZD    true
BLOCKDEVICE    /dev/sdh     vol-xxxxxxxx    yyyy-mmThh:mm:ss.sTZD    true
BLOCKDEVICE    /dev/sdj     vol-xxxxxxxx    yyyy-mmThh:mm:ss.sTZD    true

To view this information plus the status (attaching, attached, detaching, detached), run the ec2-describe-instances command with the –v option to see the full SOAP response.

For more info, see ec2-describe-instances.

Viewing the Instance Block Device Mapping for Instance Store Volumes

When you view the block device mapping for your instance, you can see only the EBS volumes, not the instance store volumes. You can use instance metadata to query the complete block device mapping. The base URI for all requests for instance metadata is http://169.254.169.254/latest/.

First, connect to your running instance. If the instance is running Linux, the GET command is already available. If the instance is running Windows, install wget on the instance, and replace GET with wget in the examples below.

Use this query on a running instance to get its block device mapping. 

GET 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 device as seen by the instance. The instance store volumes are named ephemeral[0-3]. 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.

GET http://169.254.169.254/latest/meta-data/block-device-mapping/ephemeral0

For more info, see Instance Metadata.

Document Conventions« PreviousNext »
Terms of UseDid this page help you?  Yes | No |  Tell us about it...