Attaching volumes to virtual machines

POST /servers/{server_id}/os-volume_attachments

Attach a volume to the given virtual machine.

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#attach-a-volume-to-an-instance

Request

Parameters

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.

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.
volumeId body string The UUID of the volume to attach.
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.

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 is false.

New in version 2.79

Example

Attach an existing 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

Response

Parameters

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

Status codes

Success

Code Reason
200 - OK Request was successful.

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.

Example

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