Defining Block Device Mappings

Using block device mappings, you can directly attach Block Storage Unit (BSU) volumes to a virtual machine (VM) at creation through the block device mapping of the OMI or create an OMI from a snapshot.

Block device mapping enables you to:

  • Define the device name assigned to the BSU volume

  • Prevent a BSU volume defined by the OMI from being assigned to a device name

  • Specify whether a BSU volume is created from a snapshot or from scratch, and whether it is deleted or detached when terminating the VM

Defining Block Device Mappings Using OSC CLI

See the CreateVms and CreateImage command samples in the documentation of the OUTSCALE API.

Defining Block Device Mappings Using oapi-cli

See the CreateVms and CreateImage command samples in the documentation of the OUTSCALE API.

Defining Block Device Mappings Using AWS CLI

Before you begin: Install and configure AWS CLI. For more information, see Installing and Configuring AWS CLI.

To define a block device mapping, set the block-device-mappings attribute of the run-instances or register-image command following this syntax:

Request sample
  {
    "DeviceName": "string",
    "Ebs": {
      "SnapshotId": "string",
      "VolumeSize": integer,
      "DeleteOnTermination": true or false,
      "VolumeType": "standard",
      "Iops": integer,
    },
    "NoDevice": "string"
  }

You can set this attribute either inline (directly in the command), or via a text file (by specifying file://MAP_PATH, where MAP_PATH is the path to your block device mapping file).

This attribute contains the following elements that you need to specify:

  • DeviceName: The device name assigned to the volume

    The device name for the root device must be /dev/sda1. For any other volume you must use the /dev/xvdX or /dev/xvdXX format. For more information, see About Volumes > Volumes Attachment and Device Names.

  • (optional) Ebs: Information to map a volume to DeviceName. This element requires the following information:

    • (optional) SnapshotId: The ID of a snapshot if you want to create a volume from it.

    • (optional) VolumeSize: The size of the volume to create, in gibibytes (GiB).

      • If you specify a snapshot ID, the volume size must be at least equal to the snapshot size.

      • If you specify a snapshot ID but no volume size, the volume is created with a size similar to the snapshot one.

    • (optional) DeleteOnTermination: By default or if set to true, the volume is deleted when terminating the instance. If false, the volume is not deleted when terminating the instance.

    • (optional) VolumeType: The type of volume (standard | gp2 | io1). For more information, see About Volumes > Volume Types and IOPS. By default, a standard volume is created.

    • (optional) Iops: The number of IOPS.

      The maximum number of IOPS allowed for io1 volumes is 13000 with a maximum performance ratio of 300 IOPS per gibibyte.

      This parameter must be specified only if you create an io1 volume.

  • (optional) NoDevice: Prevents a volume from being mapped to DeviceName, if the OMI used contains a mapping for DeviceName.

    To use this parameter, specify any value other than null, for example an empty string ("").

In the following example, the block device mappings:

  • Attach a volume created from the snap-123456789 snapshot, assigned to /dev/xvdb

  • Attach an empty Magnetic volume with a size of 100 GiB, assigned to /dev/xvdc and that is deleted when terminating the instance

  • Prevent a volume defined by the OMI from being assigned to /dev/xvde at launch

Block device mapping example
[
   {
    "DeviceName": "/dev/xvdb",
    "Ebs": {
            "SnapshotId": "snap-123456789"
           }
    },
   {
    "DeviceName": "/dev/xvdc",
    "Ebs": {
            "VolumeSize": 100,
            "DeleteOnTermination": true
           }
    },
   {
    "DeviceName": "/dev/xvde",
    "NoDevice": ""
   }
]

Related Pages

Corresponding API Methods

AWS™ and Amazon Web Services™ are trademarks of Amazon Technologies, Inc or its affiliates in the United States and/or other countries.

Export to PDF