Back to guides list

13.10. Attaching volumes to virtual machines

POST /servers/{server_id}/os-volume_attachments

Attach a volume to the given virtual machine.

Note

This is an asynchronous API, callers should poll the status and list of volume attachments within the volume API, to determine when the attachment has completed successfully.

Source: https://docs.openstack.org/api-ref/compute/?expanded=attach-a-volume-to-an-instance-detail

13.10.1. Request

Name In Type Description
server_id path string The UUID of the server.
volumeAttachment body object A dictionary representation of a volume attachment containing the fields device and volumeId.
volumeId body string The UUID of the volume to attach.
device (Optional) body string Name of the device such as, /dev/vdb. Omit or set this parameter to null for auto-assignment, if supported. If you specify this parameter, the device must not exist in the guest operating system. Note that as of the 12.0.0 Liberty release, the Nova libvirt driver no longer honors a user-supplied device name. This is the same behavior as if the device name parameter is not supplied on the request.
tag (Optional) body string

A device role tag that can be applied to a volume when attaching it to the VM. The guest OS of a server that has devices tagged in this manner can access hardware metadata about the tagged devices from the metadata API and on the config drive, if enabled.

Note

Tagged volume attachment is not supported for shelved-offloaded instances.

New in version 2.49
delete_on_termination (Optional) body boolean

To delete the attached volume when the server is destroyed, specify true. Otherwise, specify false. Default: false

New in version 2.79

13.10.1.1. Examples

Attach an exisitng volume with the specified ID to a VM with the specified ID.

# curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' -d '
{
    "volumeAttachment": {
        "volumeId": "16cd801e-f3c1-4cac-aa6c-aecf22642a89",
        "device": "/dev/sdb"
    }
}' https://<node_IP_addr>:8774/v2.1/b906404c55bb44729da99987536ac5bc/servers/0785ee80-1eca-426b-b8c4-5b499fc7f614/os-volume_attachments

13.10.2. Response

Name In Type Description
volumeAttachment body object A dictionary representation of a volume attachment containing the fields device, id, serverId and volumeId.
device body string Name of the device such as, /dev/vdb.
id body string The UUID of the volume.
serverId (Optional) body string The UUID of the server.
volumeId (Optional) body string The UUID of the attached volume.
tag body string

The device tag applied to the volume block device or null.

New in version 2.70
delete_on_termination body boolean

A flag indicating if the attached volume will be deleted when the server is deleted.

New in version 2.79

13.10.2.1. Status codes

13.10.2.1.1. Success

Code Reason
200 - OK Request was successful.

13.10.2.1.2. Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.
404 - Not Found The requested resource could not be found.
409 - Conflict This operation conflicted with another operation on this resource.

13.10.2.2. Example

{
  "volumeAttachment": {
    "device": "/dev/vdb",
    "serverId": "0785ee80-1eca-426b-b8c4-5b499fc7f614",
    "id": "16cd801e-f3c1-4cac-aa6c-aecf22642a89",
    "volumeId": "16cd801e-f3c1-4cac-aa6c-aecf22642a89"
  }
}
Version 5.0.0 — Feb 01, 2022
Print