Did this page help you? Yes No Tell us about it...

Block Device Mapping

Topics

Every AMI and instance has a block device mapping structure that specifies the block devices to be attached to the instance. For example, AWS provides some simple Amazon EBS-backed AMIs that you can use to get started with Amazon EC2. By default, when you launch an instance of one of these AMIs, there's a volume attached for the root device, and that's all. There's no instance store attached by default, and no additional Amazon EBS volumes. The block device mapping for that AMI or instance contains information about the one block device that's mapped: the root device volume. That information is included as part of the AMI details displayed in the AWS Management Console. You can also get the information by describing the AMI with the command line tools or API.

Amazon EC2 instance store-backed AMIs also have a block device mapping structure. These AMIs have instance storage available by default; however, there's no information about this storage included in the AMI's block device mapping. Also, you can't set up an Amazon EC2 instance store-backed AMI to automatically attach a volume at launch time (something you can do with Amazon EBS-backed AMIs). Therefore, the block device mapping structure for Amazon EC2 instance store-backed AMIs is effectively empty.

This section describes the parts of a block device mapping and what you can do with an AMI's or instance's block device mapping.

Parts of a Block Device Mapping

A block device mapping structure contains one or more items, and each item describes the mapping for a single block device. As shown in the following figure, each item specifies the device name, and whether the device is mapped to a virtual device (i.e., an instance store), an Amazon EBS volume, or to nothing. You need to use the last option only when you want to suppress a block device from attaching at launch time (for an example, see AMI Mapping Override).

Parts of a device's block device mapping info

For a device mapped to a virtual device, the block device mapping specifies the name of the store (e.g., ephemeral0).

	Note
	Even though the virtual device part of the block device mapping exists in the Amazon EC2 system, it isn't included in the block device mapping information that is visible to you in the AWS Management Console or when you describe the AMI. However, you can determine which instance storage devices are mapped from within the running instance itself.

For a device mapped to an Amazon EBS volume (which is available only for Amazon EBS-backed AMIs), the block device mapping specifies the following items:

Snapshot ID to use for the volume
Volume size (in GiB)
DeleteOnTermination flag (whether to delete the volume on instance termination)

At a minimum, either a snapshot ID or a volume size is required. If there's no snapshot ID, then an empty volume is created in the size specified. If both a snapshot ID and a size are specified, then a volume of the specified snapshot is created in the specified size. The specified size must be equal to or larger than the size of the snapshot.

The default value for the DeleteOnTermination flag is true for any volumes that are created when the instance is launched. If you attach any volumes to a running instance, new items are added to the block device mapping for those volumes. The DeleteOnTermination flag is false by default for any volumes you attach after the instance is running. You can change the DeleteOnTermination value for any of the volumes in the block device mapping. For an example of how to do this with the root device, see Using Amazon EC2 Root Device Storage.

You can view an AMI's block device mapping information in the AWS Management Console or by describing the AMI with the command line tools or API. The available information includes mappings only for volumes; no information about instance store devices is included. For more information, see Viewing Block Device Mappings.

Let's say you want to take one of the Amazon EBS-backed AMIs that AWS provides to help you get started with Amazon EC2 and create your own AMI from it with instance storage devices or additional Amazon EBS volumes that automatically attach at launch time. You can do that by specifying a block device mapping with your additions when you register the AMI. For more information, see Adding A Default Instance Store and Automatically Attaching Volumes.

	Note
	When you launch an instance of a particular AMI and then terminate the instance, any remaining volumes are not automatically related to any future instances of that AMI. In other words, a new instance that you launch of that same AMI doesn't attempt to attach to the remaining volume. However, you can manually attach the remaining volume to the new instance if you want.

Instance Block Device Mapping

Just as every AMI has a block device mapping structure that specifies the block devices that are attached to it, so does every instance. You can view the block device mapping for an instance in the AWS Management Console or by describing the instance with the command line tools or API. The available information includes information only for volumes; no information about instance store devices is currently available.

	Note
	For instances launched before the release of the 2009-10-31 API version, no block device mapping information for any attached volumes is available when you describe the instance. You must detach and reattach the volumes for the information to be available when you describe the instance.

The following information is included for each Amazon EBS volume attached to the instance:

The device name (e.g., /dev/sda1 or xvda)
The volume ID (e.g., vol-12345678)
The status of the attachment (e.g., attached)
The time when the attachment was initiated
The DeleteOnTermination value (true or false)

For more information about viewing this information, see Viewing Block Device Mappings.

AMI Mapping Override

You can override the block device mapping for an instance that you plan to launch. This will not make a permanent change to the mapping of the AMI by specifying a block device mapping structure when you run the instance. Any differences between the AMI's block device mapping and the one you specify for the instance overwrite or merge with the AMI's original mapping. You can use the override capability with any storage attachment the AMI has, including the root device volume. Exception: You can't change the size of the root device volume with a block device mapping override.

	Note
	For Amazon EC2 instance store-backed AMIs, you can't specify a block device mapping that includes Amazon EBS volumes to attach at launch time. You can only modify the instance storage (e.g., add or remove an instance storage device).

For example, let's say you have an Amazon EBS-backed AMI that has a block device mapping that includes two additional volumes (beyond the root device volume) called ExtraSnapshot1 and ExtraSnapshot2. You set both of these volumes to and you've set both of persist when the instance terminates. You want to launch a single instance that:

Includes a larger version of ExtraSnapshot1 that is set to delete on instance termination
Doesn't include ExtraSnapshot2
Includes instance storage device

At launch time, you specify a block device mapping that includesthe changes that you want. When the instance launches, its block device mapping includes the original AMI settings that were unaffected by your overrides, plus the new overrides you specified.

For an example of how to override the AMI's block device mapping at launch time, see Overriding the AMI's Block Device Mapping.

Viewing Block Device Mappings

You can get a list of the block devices mapped to an AMI or an instance. The list includes only the Amazon EBS volumes that are mapped to the AMI or instance; no information about instance storage is provided. For general information about block device mapping, see Block Device Mapping.

AWS Management Console

The devices mapped to an AMI are listed as part of the AMI details displayed in the console. Only the Amazon EBS snapshots mapped to the AMI are listed; no information is displayed for instance storage devices that are mapped. The following screenshot shows the details of a sample AMI.

The Block Devices field shows information about the root device's mapping: /dev/sda1=snap-ae624ccd:8:true. This means the root device /dev/sda1 is mapped to a 8 GiB volume created from the snap-ae624ccd snapshot, and the volume's DeleteOnTermination flag is true.

The devices mapped to an instance are listed as part of the instance details displayed in the console. Only the Amazon EBS volumes mapped to the instance are listed; no information is displayed for instance store devices that are mapped. The following screenshot shows the details of a sample instance.

When you click a link in the Block Devices field, it displays information about that device. For each device, the following items are displayed:

The device name (e.g., sda1)
The EBS or volume ID (e.g., vol-da6cd4b5)
The root device type (e.g., ebs)
The time when the attachment was initiated (e.g., April 20, 2012 at 16:45 UTC)
The status of the attachment (e.g., attached)
Whether to delete the device when the instance terminates (e.g., Yes)
The ID of the snapshot it was created from (e.g., snap-ae624ccd)

For the example shown in the preceding screenshot, the root device is sda1 and it's mapped to vol-da6cd4b5. The volume was attached on April 20, 2012 at 16:45 UTC and is currently attached. It was created from snap-ae624ccd. The device is set to be deleted when the instance terminates.

Command Line Tools

You can get information about an AMI's or instance's block device mapping through the command line tools.

To view the block device mapping for an AMI

Use the ec2-describe-images command.
```
PROMPT>  ec2-describe-images ami_id
```
Following is an example of the part of the response that includes the block device mapping.
```
BLOCKDEVICEMAPPING      /dev/sda1               snap-a08912c9   15
```

This response shows device /dev/sda1 is mapped to a 15GiB volume created from the snap-a08912c9 snapshot. The response doesn't include the value of the DeleteOnTermination flag. However, if you run the command in verbose mode (i.e., with the -v switch), you can view the underlying XML response, which includes the flag's value.

To view the block device mapping for an instance

Use the ec2-describe-instances command.

PROMPT>  ec2-describe-instances instance_id

Following is an example of the part of the response that includes the block device mapping.

BLOCKDEVICE     /dev/sda1       vol-818843e8    2010-02-22T20:36:18.000Z
BLOCKDEVICE     /dev/sdk        vol-b7ae65de    2010-02-23T22:58:31.000Z

The response shows the ID of the volume mapped to the root device /dev/sda1. The response currently doesn't include the status of the volume's attachment or the value of the DeleteOnTermination flag. However, if you run the command in verbose mode (i.e., with the -v switch), you can view the underlying XML response, which includes that information.

The second mapped device is /dev/sdk, and it's mapped to vol-b7ae65de. The volume was attached on February 23 at 22:58 UTC.

API

You can get information about an AMI's or instance's block device mapping through the API.

To view the block device mapping for an AMI

Issue the following Query request to get a description of the AMI's block device mapping.
```
https://ec2.amazonaws.com/
?Action=DescribeImages
&...auth parameters...
```
For information about the auth parameters, go to Common Query Parameters in the Amazon Elastic Compute Cloud API Reference.
In the output XML, locate the rootDeviceName and blockDeviceMapping elements for the instance (they're right next to each other in the response). Following is an example of that part of the response.
```
...
<rootDeviceName>/dev/sda1</rootDeviceName>
<blockDeviceMapping>
   <item>
     <deviceName>/dev/sda1</deviceName>
     <ebs>
       <snapshotId>snap-a08912c9</snapshotId>
       <volumeSize>15</volumeSize>
       <deleteOnTermination>true</deleteOnTermination>
     </ebs>
   </item>
</blockDeviceMapping>
...
```
This example response shows that the root device is /dev/sda1, and it's mapped to a 15GiB volume created from the snap-a08912c9 snapshot. The volume is set to delete when the instance terminates.

To view the block device mapping for an instance

Issue the following Query request to get a description of the instance's block device mapping.
```
https://ec2.amazonaws.com/
?Action=DescribeInstances
&...auth parameters...
```
In the output XML, locate the rootDeviceName and blockDeviceMapping elements for the instance (they're right next to each other in the response). Following is an example of that part of the response.
```
<rootDeviceName>/dev/sda1</rootDeviceName>
<blockDeviceMapping>
  <item>
    <deviceName>/dev/sda1</deviceName>
    <ebs>
      <volumeId>vol-818843e8</volumeId>
      <status>attached</status>
      <attachTime>2010-02-22T20:36:18.000Z</attachTime>
      <deleteOnTermination>true</deleteOnTermination>
    </ebs>
  </item>
  <item>
    <deviceName>/dev/sdk</deviceName>
    <ebs>
      <volumeId>vol-b7ae65de</volumeId>
      <status>attached</status>
      <attachTime>2010-02-23T22:58:31.000Z</attachTime>
      <deleteOnTermination>false</deleteOnTermination>
    </ebs>
  </item>
</blockDeviceMapping>
```
The response shows the root device is /dev/sda1, and it's mapped to vol-818843e8. The volume was attached on February 22 at 20:36 UTC and is currently attached. The root device volume is set to be deleted when the instance terminates.
The second mapped device is /dev/sdk, and it's mapped to vol-b7ae65de. The volume was attached on on February 23 at 22:58 UTC and is currently attached. This volume will not be deleted when the instance terminates.

Overriding the AMI's Block Device Mapping

Any instance you launch automatically includes any storage devices in the AMI's block device mapping. You can override that mapping by specifying a block device mapping with the changes that you want at launch time. In your overrides, you can modify the mapping for any of the storage devices except the root device volume.

	Note
	If you want an Amazon EBS-backed instance to have an instance store (i.e., ephemeral storage), you must add it at launch time (using either the procedure described in this section, or the procedure described in Adding A Default Instance Store ). You can't add instance storage to an instance after you've launched it.

For example, let's say you have an Amazon EBS-backed AMI that has a block device mapping that maps /dev/sdc to ephemeral1, and has two additional Amazon EBS volumes (beyond the root device volume). We'll call the snapshots for these extra volumes ExtraSnapshot1 and ExtraSnapshot2. Assume ExtraSnapshot1 is mapped to /dev/sdh and ExtraSnapshot2 is mapped to /dev/sdj. You've set the DeleteOnTermination flag to false for both volumes. The following figure illustrates this block device mapping for the AMI.

Let's say you want to launch a single instance that:

Includes an 80GiB version of ExtraSnapshot1 with DeleteOnTermination=true
Doesn't include ExtraSnapshot2
Includes the instance storage device ephemeral0 at /dev/sdb
Doesn't include the instance storage device ephemeral1 at /dev/sdc

The following figure includes the changes you want to make when you launch the instance.

The examples in the following section show how to make these changes when you launch the instance.

	Note
	Although you can use the AWS Management Console to launch instances, you can't specify a block device mapping as part of the launch request. That functionality is available only through the command line tools or API.

Command Line Tools

Use ec2-run-instances and specify a block device mapping that includes the changes you want to make.

To override the AMI's block device mapping

Use the ec2-run-instances command with your changes to the block device mapping. For each storage device you want to modify, include a separate -b switch.
```
PROMPT>  ec2-run-instances ami-12345678 -b /dev/sdh=:80:true -b /dev/sdj=none -b /dev/sdb=ephemeral0 -b /dev/sdc=none
```
The first -b switch in the example increases the size of the volume created from ExtraSnapshot1 to 80GiB and sets DeleteOnTermination to true. Notice that you don't need to specify the ID for ExtraSnapshot1. Specifying the mapped storage device name (/dev/sdh) is enough.
The second -b switch prevents a volume of ExtraSnapshot2 from attaching to the instance at /dev/sdj at launch time. Again, you don't need to specify the ID for ExtraSnapshot2.
The third -b switch maps local storage device /dev/sdb to ephemeral0.
The fourth -b switch prevents local storage device /dev/sdc from mapping to ephemeral1.
The instance launches with your changes.

You can view an AMI's or instance's block device mapping at any time. For more information, see Viewing Block Device Mappings.

API

You use RunInstances and specify a block device mapping that includes the changes you want to make.

To override the AMI's block device mapping

Issue the following Query request to run an instance with your desired block device mapping overrides.
- The first item element in the block device mapping increases the size of the volume created from ExtraSnapshot1 to 80GiB and sets deleteOnTermination to true. Notice that you don't need to specify the ID for ExtraSnapshot1. Specifying the mapped storage device name (/dev/sdh) is enough.
- The second item element prevents a volume of ExtraSnapshot2 from attaching to the instance at launch time. Again, you don't need to specify the ID for ExtraSnapshot2.
- The third item element maps instance storage device /dev/sdb to ephemeral0.
- The fourth item element prevents instance storage device /dev/sdc from mapping to ephemeral1.
```
https://ec2.amazonaws.com/
?Action=RunInstances
&ImageId=ami-cb4aa6a2
...
&BlockDeviceMapping.1.DeviceName=/dev/sdh
&BlockDeviceMapping.1.Ebs.VolumeSize=80
&BlockDeviceMapping.1.Ebs.DeleteOnTermination=true
&BlockDeviceMapping.2.DeviceName=/dev/sdj
&BlockDeviceMapping.2.Ebs.NoDevice=true
&BlockDeviceMapping.3.DeviceName=/dev/sdb
&BlockDeviceMapping.3.VirtualName=ephemeral0
&BlockDeviceMapping.4.DeviceName=/dev/sdc
&BlockDeviceMapping.4.Ebs.NoDevice=true
...
&...auth parameters...
```
The instance launches with your changes.

You can view an AMI's or instance's block device mapping at any time. For more information, see Viewing Block Device Mappings.

Document Conventions
Terms of Use

Did this page help you? Yes No Tell us about it...