Attach and Detach a Volume

POST/v2.1/{project_id}/servers/{server_id}/os-volume_attachments

GET/v2.1/{project_id}/servers/{server_id}/os-volume_attachments

DELETE/v2.1/{project_id}/servers/{server_id}/os-volume_attachments/{attachment_id}

This endpoint belongs to the compute service and links a volume to a VM.

An attachment has its own ID, which is not the volume ID. To detach, use the attachment ID returned by the attach call or by the list call.

info

Source: attach-a-volume-to-an-instance

Attach a volume

Request

project_idstringrequiredpath

The UUID of the project.

server_idstringrequiredpath

The UUID of the VM.

volumeAttachmentobjectrequiredbody

Attachment wrapper containing device and volumeId.

4 fields

volumeIdstringrequiredbody

The UUID of the volume to attach. The volume must be available.

devicestringrequiredbody

Optional device name such as /dev/vdb. Omit or set it to null for auto-assignment. The libvirt driver does not honor a user-supplied device name, so the final path in the guest is assigned by the driver.

tagstringrequiredbody

Optional device role tag. The guest can read it from the metadata API or the config drive. Not supported for shelved-offloaded VMs.

delete_on_terminationbooleanrequiredbody

Delete the volume when the VM is destroyed. Default: false.

Sample Request

curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' \
-d '{
  "volumeAttachment": {
    "volumeId": "16cd801e-f3c1-4cac-aa6c-aecf22642a89",
    "device": "/dev/vdb"
  }
}' https://api.vietnix.cloud:8774/v2.1/{project_id}/servers/{server_id}/os-volume_attachments

Response

{
  "volumeAttachment": {
    "id": "a3d7c1e0-9b1f-4c2e-8a55-7e6d5c4b3a21",
    "serverId": "393210ad-152b-4ac3-a0f0-798ee4e93620",
    "volumeId": "16cd801e-f3c1-4cac-aa6c-aecf22642a89",
    "device": "/dev/vdb",
    "tag": null
  }
}

Status Code	Description
200 - OK	The volume was attached.
400 - Bad Request	The volume is not available, is already attached, or the request is malformed.
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 VM or the volume does not exist.
409 - Conflict	The VM is in a status that does not allow attaching.

List attachments

curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' \
https://api.vietnix.cloud:8774/v2.1/{project_id}/servers/{server_id}/os-volume_attachments

JSON body

{
  "volumeAttachments": [
    {
      "id": "a3d7c1e0-9b1f-4c2e-8a55-7e6d5c4b3a21",
      "serverId": "393210ad-152b-4ac3-a0f0-798ee4e93620",
      "volumeId": "16cd801e-f3c1-4cac-aa6c-aecf22642a89",
      "device": "/dev/vdb",
      "tag": null
    }
  ]
}

Detach a volume

curl -ks -X DELETE -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' \
https://api.vietnix.cloud:8774/v2.1/{project_id}/servers/{server_id}/os-volume_attachments/{attachment_id}

Status Code	Description
202 - Accepted	The detach was accepted and is being processed.
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 VM or the attachment does not exist.
409 - Conflict	The VM is in a status that does not allow detaching.

note

Attaching and detaching are asynchronous. Poll the volume status through the volume API until the attachment completes. Detaching does not delete the volume; it returns to available and keeps its data.