# Volumes

Volume management

## List volumes

> Lists summary information for all Block Storage volumes

```json
{"openapi":"3.0.3","info":{"title":"OpenStack Block Storage API (Cinder)","version":"3.71"},"tags":[{"name":"volumes","description":"Volume management"}],"servers":[{"url":"https://{host}/cinder","description":"PCD Block Storage API v3","variables":{"host":{"default":"example.platform9.com","description":"The PCD controlplane hostname"}}}],"security":[{"pcdAuth":[]}],"components":{"securitySchemes":{"pcdAuth":{"name":"X-Auth-Token","type":"apiKey","in":"header","description":"PCD Identity Service token authentication"}},"parameters":{"AllTenantsQuery":{"name":"all_tenants","description":"Shows details for all project. Admin only.","schema":{"type":"string"},"in":"query"},"SortQuery":{"name":"sort","description":"Comma-separated list of sort keys and optional sort directions","schema":{"type":"string"},"in":"query"},"SortKeyQuery":{"name":"sort_key","description":"Sorts by an attribute","schema":{"type":"string"},"in":"query"},"SortDirQuery":{"name":"sort_dir","description":"Sorts by direction (asc or desc)","schema":{"enum":["asc","desc"],"type":"string"},"in":"query"},"LimitQuery":{"name":"limit","description":"Requests a page size of items","schema":{"minimum":1,"type":"integer"},"in":"query"},"OffsetQuery":{"name":"offset","description":"Used in conjunction with limit to return items starting from the offset position","schema":{"minimum":0,"type":"integer"},"in":"query"},"MarkerQuery":{"name":"marker","description":"The ID of the last-seen item","schema":{"type":"string"},"in":"query"},"WithCountQuery":{"name":"with_count","description":"Whether to show count in response (microversion 3.45+)","schema":{"type":"boolean"},"in":"query"},"CreatedAtQuery":{"name":"created_at","description":"Filters results by creation time with comparison operators","schema":{"type":"string"},"in":"query"},"UpdatedAtQuery":{"name":"updated_at","description":"Filters results by update time with comparison operators","schema":{"type":"string"},"in":"query"},"ConsumesQuotaQuery":{"name":"consumes_quota","description":"Filters results by whether resource consumes quota (microversion 3.65+)","schema":{"type":"boolean"},"in":"query"}},"schemas":{"VolumesSimple":{"type":"object","properties":{"volumes":{"type":"array","items":{"$ref":"#/components/schemas/VolumeSimple"}},"volumes_links":{"type":"array","items":{"$ref":"#/components/schemas/Link"}},"count":{"description":"Total count of volumes (microversion 3.45+)","type":"integer"}}},"VolumeSimple":{"type":"object","properties":{"id":{"format":"uuid","description":"The UUID of the volume","type":"string"},"name":{"type":"string"}}},"Link":{"type":"object","properties":{"href":{"format":"uri","type":"string"},"rel":{"type":"string"},"type":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Some content in the request was invalid"}}},"paths":{"/v3/volumes":{"get":{"tags":["volumes"],"parameters":[{"$ref":"#/components/parameters/AllTenantsQuery"},{"$ref":"#/components/parameters/SortQuery"},{"$ref":"#/components/parameters/SortKeyQuery"},{"$ref":"#/components/parameters/SortDirQuery"},{"$ref":"#/components/parameters/LimitQuery"},{"$ref":"#/components/parameters/OffsetQuery"},{"$ref":"#/components/parameters/MarkerQuery"},{"$ref":"#/components/parameters/WithCountQuery"},{"$ref":"#/components/parameters/CreatedAtQuery"},{"$ref":"#/components/parameters/UpdatedAtQuery"},{"$ref":"#/components/parameters/ConsumesQuotaQuery"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolumesSimple"}}},"description":"OK"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"List volumes","description":"Lists summary information for all Block Storage volumes"}}}}
```

## Create volume

> Creates a volume

```json
{"openapi":"3.0.3","info":{"title":"OpenStack Block Storage API (Cinder)","version":"3.71"},"tags":[{"name":"volumes","description":"Volume management"}],"servers":[{"url":"https://{host}/cinder","description":"PCD Block Storage API v3","variables":{"host":{"default":"example.platform9.com","description":"The PCD controlplane hostname"}}}],"security":[{"pcdAuth":[]}],"components":{"securitySchemes":{"pcdAuth":{"name":"X-Auth-Token","type":"apiKey","in":"header","description":"PCD Identity Service token authentication"}},"schemas":{"VolumeCreateRequest":{"type":"object","properties":{"volume":{"required":["size"],"type":"object","properties":{"size":{"description":"The size of the volume, in gibibytes (GiB)","type":"integer"},"name":{"description":"The volume name","type":"string"},"description":{"description":"The volume description","type":"string"},"availability_zone":{"description":"The name of the availability zone","type":"string"},"volume_type":{"description":"The volume type (either name or ID)","type":"string"},"source_volid":{"format":"uuid","description":"The UUID of the source volume","type":"string"},"snapshot_id":{"format":"uuid","description":"The UUID of the source snapshot","type":"string"},"backup_id":{"format":"uuid","description":"The UUID of the backup (microversion 3.47+)","type":"string"},"imageRef":{"format":"uuid","description":"The UUID of the image to create bootable volume","type":"string"},"metadata":{"description":"Metadata key and value pairs","type":"object","additionalProperties":{"type":"string"}},"consistencygroup_id":{"format":"uuid","description":"The UUID of the consistency group","type":"string"},"multiattach":{"description":"Enable multiattach capability","type":"boolean"}}},"OS-SCH-HNT:scheduler_hints":{"description":"Scheduler hints","type":"object"}}},"VolumeResponse":{"type":"object","properties":{"volume":{"$ref":"#/components/schemas/Volume"}}},"Volume":{"type":"object","properties":{"id":{"format":"uuid","description":"The UUID of the volume","type":"string"},"name":{"nullable":true,"description":"The volume name","type":"string"},"description":{"nullable":true,"description":"The volume description","type":"string"},"size":{"description":"The size of the volume, in gibibytes (GiB)","type":"integer"},"status":{"description":"The volume status","type":"string"},"volume_type":{"description":"The associated volume type name for the volume","type":"string"},"volume_type_id":{"format":"uuid","description":"The associated volume type ID for the volume","type":"string"},"availability_zone":{"nullable":true,"description":"The name of the availability zone","type":"string"},"bootable":{"description":"Enables or disables the bootable attribute","type":"string"},"encrypted":{"description":"If true, this volume is encrypted","type":"boolean"},"encryption_key_id":{"nullable":true,"format":"uuid","description":"The UUID of the encryption key (microversion 3.64+)","type":"string"},"multiattach":{"description":"If true, this volume can attach to more than one instance","type":"boolean"},"attachments":{"description":"Instance attachment information","type":"array","items":{"$ref":"#/components/schemas/VolumeAttachment"}},"metadata":{"description":"Metadata key and value pairs","type":"object","additionalProperties":{"type":"string"}},"created_at":{"format":"date-time","description":"The date and time when the resource was created","type":"string"},"updated_at":{"nullable":true,"format":"date-time","description":"The date and time when the resource was updated","type":"string"},"user_id":{"format":"uuid","description":"The UUID of the user","type":"string"},"consistencygroup_id":{"nullable":true,"format":"uuid","description":"The UUID of the consistency group","type":"string"},"group_id":{"nullable":true,"format":"uuid","description":"The ID of the group (microversion 3.13+)","type":"string"},"snapshot_id":{"nullable":true,"format":"uuid","description":"The UUID of the source snapshot","type":"string"},"source_volid":{"nullable":true,"format":"uuid","description":"The UUID of the source volume","type":"string"},"replication_status":{"nullable":true,"description":"The volume replication status","type":"string"},"migration_status":{"nullable":true,"description":"The volume migration status","type":"string"},"os-vol-host-attr:host":{"nullable":true,"description":"Current back-end of the volume","type":"string"},"os-vol-tenant-attr:tenant_id":{"format":"uuid","description":"The project ID which the volume belongs to","type":"string"},"os-vol-mig-status-attr:migstat":{"nullable":true,"description":"The status of this volume migration","type":"string"},"os-vol-mig-status-attr:name_id":{"nullable":true,"description":"The volume ID that this volume name on the back-end is based on","type":"string"},"volume_image_metadata":{"description":"Image metadata entries","type":"object","additionalProperties":{"type":"string"}},"provider_id":{"nullable":true,"description":"The provider ID for the volume (microversion 3.21+)","type":"string"},"service_uuid":{"nullable":true,"format":"uuid","description":"Service UUID (microversion 3.48+)","type":"string"},"shared_targets":{"description":"Shared targets indicator (microversion 3.48+)","type":"boolean"},"cluster_name":{"nullable":true,"description":"The cluster name of volume backend (microversion 3.61+)","type":"string"},"consumes_quota":{"description":"Whether this resource consumes quota (microversion 3.65+)","type":"boolean"},"links":{"type":"array","items":{"$ref":"#/components/schemas/Link"}}}},"VolumeAttachment":{"type":"object","properties":{"server_id":{"format":"uuid","description":"The UUID of the attached server","type":"string"},"attachment_id":{"format":"uuid","description":"The attachment UUID","type":"string"},"attached_at":{"format":"date-time","description":"The date and time when attached","type":"string"},"host_name":{"nullable":true,"description":"The name of the attached host","type":"string"},"volume_id":{"format":"uuid","description":"The volume UUID","type":"string"},"device":{"description":"The device path","type":"string"},"id":{"format":"uuid","description":"The attachment ID","type":"string"}}},"Link":{"type":"object","properties":{"href":{"format":"uri","type":"string"},"rel":{"type":"string"},"type":{"type":"string"}}}}},"paths":{"/v3/volumes":{"post":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolumeCreateRequest"}}},"required":true},"tags":["volumes"],"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolumeResponse"}}},"description":"Accepted"}},"summary":"Create volume","description":"Creates a volume"}}}}
```

## List volumes with details

> Lists all Block Storage volumes with details

```json
{"openapi":"3.0.3","info":{"title":"OpenStack Block Storage API (Cinder)","version":"3.71"},"tags":[{"name":"volumes","description":"Volume management"}],"servers":[{"url":"https://{host}/cinder","description":"PCD Block Storage API v3","variables":{"host":{"default":"example.platform9.com","description":"The PCD controlplane hostname"}}}],"security":[{"pcdAuth":[]}],"components":{"securitySchemes":{"pcdAuth":{"name":"X-Auth-Token","type":"apiKey","in":"header","description":"PCD Identity Service token authentication"}},"parameters":{"AllTenantsQuery":{"name":"all_tenants","description":"Shows details for all project. Admin only.","schema":{"type":"string"},"in":"query"},"SortQuery":{"name":"sort","description":"Comma-separated list of sort keys and optional sort directions","schema":{"type":"string"},"in":"query"},"SortKeyQuery":{"name":"sort_key","description":"Sorts by an attribute","schema":{"type":"string"},"in":"query"},"SortDirQuery":{"name":"sort_dir","description":"Sorts by direction (asc or desc)","schema":{"enum":["asc","desc"],"type":"string"},"in":"query"},"LimitQuery":{"name":"limit","description":"Requests a page size of items","schema":{"minimum":1,"type":"integer"},"in":"query"},"OffsetQuery":{"name":"offset","description":"Used in conjunction with limit to return items starting from the offset position","schema":{"minimum":0,"type":"integer"},"in":"query"},"MarkerQuery":{"name":"marker","description":"The ID of the last-seen item","schema":{"type":"string"},"in":"query"},"WithCountQuery":{"name":"with_count","description":"Whether to show count in response (microversion 3.45+)","schema":{"type":"boolean"},"in":"query"},"CreatedAtQuery":{"name":"created_at","description":"Filters results by creation time with comparison operators","schema":{"type":"string"},"in":"query"},"UpdatedAtQuery":{"name":"updated_at","description":"Filters results by update time with comparison operators","schema":{"type":"string"},"in":"query"},"ConsumesQuotaQuery":{"name":"consumes_quota","description":"Filters results by whether resource consumes quota (microversion 3.65+)","schema":{"type":"boolean"},"in":"query"}},"schemas":{"VolumesDetail":{"type":"object","properties":{"volumes":{"type":"array","items":{"$ref":"#/components/schemas/Volume"}},"volumes_links":{"type":"array","items":{"$ref":"#/components/schemas/Link"}},"count":{"description":"Total count of volumes (microversion 3.45+)","type":"integer"}}},"Volume":{"type":"object","properties":{"id":{"format":"uuid","description":"The UUID of the volume","type":"string"},"name":{"nullable":true,"description":"The volume name","type":"string"},"description":{"nullable":true,"description":"The volume description","type":"string"},"size":{"description":"The size of the volume, in gibibytes (GiB)","type":"integer"},"status":{"description":"The volume status","type":"string"},"volume_type":{"description":"The associated volume type name for the volume","type":"string"},"volume_type_id":{"format":"uuid","description":"The associated volume type ID for the volume","type":"string"},"availability_zone":{"nullable":true,"description":"The name of the availability zone","type":"string"},"bootable":{"description":"Enables or disables the bootable attribute","type":"string"},"encrypted":{"description":"If true, this volume is encrypted","type":"boolean"},"encryption_key_id":{"nullable":true,"format":"uuid","description":"The UUID of the encryption key (microversion 3.64+)","type":"string"},"multiattach":{"description":"If true, this volume can attach to more than one instance","type":"boolean"},"attachments":{"description":"Instance attachment information","type":"array","items":{"$ref":"#/components/schemas/VolumeAttachment"}},"metadata":{"description":"Metadata key and value pairs","type":"object","additionalProperties":{"type":"string"}},"created_at":{"format":"date-time","description":"The date and time when the resource was created","type":"string"},"updated_at":{"nullable":true,"format":"date-time","description":"The date and time when the resource was updated","type":"string"},"user_id":{"format":"uuid","description":"The UUID of the user","type":"string"},"consistencygroup_id":{"nullable":true,"format":"uuid","description":"The UUID of the consistency group","type":"string"},"group_id":{"nullable":true,"format":"uuid","description":"The ID of the group (microversion 3.13+)","type":"string"},"snapshot_id":{"nullable":true,"format":"uuid","description":"The UUID of the source snapshot","type":"string"},"source_volid":{"nullable":true,"format":"uuid","description":"The UUID of the source volume","type":"string"},"replication_status":{"nullable":true,"description":"The volume replication status","type":"string"},"migration_status":{"nullable":true,"description":"The volume migration status","type":"string"},"os-vol-host-attr:host":{"nullable":true,"description":"Current back-end of the volume","type":"string"},"os-vol-tenant-attr:tenant_id":{"format":"uuid","description":"The project ID which the volume belongs to","type":"string"},"os-vol-mig-status-attr:migstat":{"nullable":true,"description":"The status of this volume migration","type":"string"},"os-vol-mig-status-attr:name_id":{"nullable":true,"description":"The volume ID that this volume name on the back-end is based on","type":"string"},"volume_image_metadata":{"description":"Image metadata entries","type":"object","additionalProperties":{"type":"string"}},"provider_id":{"nullable":true,"description":"The provider ID for the volume (microversion 3.21+)","type":"string"},"service_uuid":{"nullable":true,"format":"uuid","description":"Service UUID (microversion 3.48+)","type":"string"},"shared_targets":{"description":"Shared targets indicator (microversion 3.48+)","type":"boolean"},"cluster_name":{"nullable":true,"description":"The cluster name of volume backend (microversion 3.61+)","type":"string"},"consumes_quota":{"description":"Whether this resource consumes quota (microversion 3.65+)","type":"boolean"},"links":{"type":"array","items":{"$ref":"#/components/schemas/Link"}}}},"VolumeAttachment":{"type":"object","properties":{"server_id":{"format":"uuid","description":"The UUID of the attached server","type":"string"},"attachment_id":{"format":"uuid","description":"The attachment UUID","type":"string"},"attached_at":{"format":"date-time","description":"The date and time when attached","type":"string"},"host_name":{"nullable":true,"description":"The name of the attached host","type":"string"},"volume_id":{"format":"uuid","description":"The volume UUID","type":"string"},"device":{"description":"The device path","type":"string"},"id":{"format":"uuid","description":"The attachment ID","type":"string"}}},"Link":{"type":"object","properties":{"href":{"format":"uri","type":"string"},"rel":{"type":"string"},"type":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Some content in the request was invalid"}}},"paths":{"/v3/volumes/detail":{"get":{"tags":["volumes"],"parameters":[{"$ref":"#/components/parameters/AllTenantsQuery"},{"$ref":"#/components/parameters/SortQuery"},{"$ref":"#/components/parameters/SortKeyQuery"},{"$ref":"#/components/parameters/SortDirQuery"},{"$ref":"#/components/parameters/LimitQuery"},{"$ref":"#/components/parameters/OffsetQuery"},{"$ref":"#/components/parameters/MarkerQuery"},{"$ref":"#/components/parameters/WithCountQuery"},{"$ref":"#/components/parameters/CreatedAtQuery"},{"$ref":"#/components/parameters/UpdatedAtQuery"},{"$ref":"#/components/parameters/ConsumesQuotaQuery"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolumesDetail"}}},"description":"OK"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"List volumes with details","description":"Lists all Block Storage volumes with details"}}}}
```

## Show volumes summary

> Display volumes summary with total number and size (microversion 3.12+)

```json
{"openapi":"3.0.3","info":{"title":"OpenStack Block Storage API (Cinder)","version":"3.71"},"tags":[{"name":"volumes","description":"Volume management"}],"servers":[{"url":"https://{host}/cinder","description":"PCD Block Storage API v3","variables":{"host":{"default":"example.platform9.com","description":"The PCD controlplane hostname"}}}],"security":[{"pcdAuth":[]}],"components":{"securitySchemes":{"pcdAuth":{"name":"X-Auth-Token","type":"apiKey","in":"header","description":"PCD Identity Service token authentication"}},"parameters":{"AllTenantsQuery":{"name":"all_tenants","description":"Shows details for all project. Admin only.","schema":{"type":"string"},"in":"query"}},"schemas":{"VolumesSummary":{"type":"object","properties":{"volume-summary":{"type":"object","properties":{"total_size":{"description":"Total size of volumes in GB","type":"integer"},"total_count":{"description":"Total number of volumes","type":"integer"},"metadata":{"description":"Dictionary of lists containing all volumes' metadata (microversion 3.36+)","type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}},"paths":{"/v3/volumes/summary":{"get":{"tags":["volumes"],"parameters":[{"$ref":"#/components/parameters/AllTenantsQuery"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolumesSummary"}}},"description":"OK"}},"summary":"Show volumes summary","description":"Display volumes summary with total number and size (microversion 3.12+)"}}}}
```

## Show volume details

> Shows details for a volume

```json
{"openapi":"3.0.3","info":{"title":"OpenStack Block Storage API (Cinder)","version":"3.71"},"tags":[{"name":"volumes","description":"Volume management"}],"servers":[{"url":"https://{host}/cinder","description":"PCD Block Storage API v3","variables":{"host":{"default":"example.platform9.com","description":"The PCD controlplane hostname"}}}],"security":[{"pcdAuth":[]}],"components":{"securitySchemes":{"pcdAuth":{"name":"X-Auth-Token","type":"apiKey","in":"header","description":"PCD Identity Service token authentication"}},"schemas":{"VolumeResponse":{"type":"object","properties":{"volume":{"$ref":"#/components/schemas/Volume"}}},"Volume":{"type":"object","properties":{"id":{"format":"uuid","description":"The UUID of the volume","type":"string"},"name":{"nullable":true,"description":"The volume name","type":"string"},"description":{"nullable":true,"description":"The volume description","type":"string"},"size":{"description":"The size of the volume, in gibibytes (GiB)","type":"integer"},"status":{"description":"The volume status","type":"string"},"volume_type":{"description":"The associated volume type name for the volume","type":"string"},"volume_type_id":{"format":"uuid","description":"The associated volume type ID for the volume","type":"string"},"availability_zone":{"nullable":true,"description":"The name of the availability zone","type":"string"},"bootable":{"description":"Enables or disables the bootable attribute","type":"string"},"encrypted":{"description":"If true, this volume is encrypted","type":"boolean"},"encryption_key_id":{"nullable":true,"format":"uuid","description":"The UUID of the encryption key (microversion 3.64+)","type":"string"},"multiattach":{"description":"If true, this volume can attach to more than one instance","type":"boolean"},"attachments":{"description":"Instance attachment information","type":"array","items":{"$ref":"#/components/schemas/VolumeAttachment"}},"metadata":{"description":"Metadata key and value pairs","type":"object","additionalProperties":{"type":"string"}},"created_at":{"format":"date-time","description":"The date and time when the resource was created","type":"string"},"updated_at":{"nullable":true,"format":"date-time","description":"The date and time when the resource was updated","type":"string"},"user_id":{"format":"uuid","description":"The UUID of the user","type":"string"},"consistencygroup_id":{"nullable":true,"format":"uuid","description":"The UUID of the consistency group","type":"string"},"group_id":{"nullable":true,"format":"uuid","description":"The ID of the group (microversion 3.13+)","type":"string"},"snapshot_id":{"nullable":true,"format":"uuid","description":"The UUID of the source snapshot","type":"string"},"source_volid":{"nullable":true,"format":"uuid","description":"The UUID of the source volume","type":"string"},"replication_status":{"nullable":true,"description":"The volume replication status","type":"string"},"migration_status":{"nullable":true,"description":"The volume migration status","type":"string"},"os-vol-host-attr:host":{"nullable":true,"description":"Current back-end of the volume","type":"string"},"os-vol-tenant-attr:tenant_id":{"format":"uuid","description":"The project ID which the volume belongs to","type":"string"},"os-vol-mig-status-attr:migstat":{"nullable":true,"description":"The status of this volume migration","type":"string"},"os-vol-mig-status-attr:name_id":{"nullable":true,"description":"The volume ID that this volume name on the back-end is based on","type":"string"},"volume_image_metadata":{"description":"Image metadata entries","type":"object","additionalProperties":{"type":"string"}},"provider_id":{"nullable":true,"description":"The provider ID for the volume (microversion 3.21+)","type":"string"},"service_uuid":{"nullable":true,"format":"uuid","description":"Service UUID (microversion 3.48+)","type":"string"},"shared_targets":{"description":"Shared targets indicator (microversion 3.48+)","type":"boolean"},"cluster_name":{"nullable":true,"description":"The cluster name of volume backend (microversion 3.61+)","type":"string"},"consumes_quota":{"description":"Whether this resource consumes quota (microversion 3.65+)","type":"boolean"},"links":{"type":"array","items":{"$ref":"#/components/schemas/Link"}}}},"VolumeAttachment":{"type":"object","properties":{"server_id":{"format":"uuid","description":"The UUID of the attached server","type":"string"},"attachment_id":{"format":"uuid","description":"The attachment UUID","type":"string"},"attached_at":{"format":"date-time","description":"The date and time when attached","type":"string"},"host_name":{"nullable":true,"description":"The name of the attached host","type":"string"},"volume_id":{"format":"uuid","description":"The volume UUID","type":"string"},"device":{"description":"The device path","type":"string"},"id":{"format":"uuid","description":"The attachment ID","type":"string"}}},"Link":{"type":"object","properties":{"href":{"format":"uri","type":"string"},"rel":{"type":"string"},"type":{"type":"string"}}}}},"paths":{"/v3/volumes/{volume_id}":{"get":{"tags":["volumes"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolumeResponse"}}},"description":"OK"}},"summary":"Show volume details","description":"Shows details for a volume"}}}}
```

## Update volume

> Updates a volume

```json
{"openapi":"3.0.3","info":{"title":"OpenStack Block Storage API (Cinder)","version":"3.71"},"tags":[{"name":"volumes","description":"Volume management"}],"servers":[{"url":"https://{host}/cinder","description":"PCD Block Storage API v3","variables":{"host":{"default":"example.platform9.com","description":"The PCD controlplane hostname"}}}],"security":[{"pcdAuth":[]}],"components":{"securitySchemes":{"pcdAuth":{"name":"X-Auth-Token","type":"apiKey","in":"header","description":"PCD Identity Service token authentication"}},"schemas":{"VolumeUpdateRequest":{"type":"object","properties":{"volume":{"type":"object","properties":{"name":{"description":"The volume name","type":"string"},"description":{"description":"The volume description","type":"string"},"metadata":{"description":"Metadata key and value pairs","type":"object","additionalProperties":{"type":"string"}}}}}},"VolumeResponse":{"type":"object","properties":{"volume":{"$ref":"#/components/schemas/Volume"}}},"Volume":{"type":"object","properties":{"id":{"format":"uuid","description":"The UUID of the volume","type":"string"},"name":{"nullable":true,"description":"The volume name","type":"string"},"description":{"nullable":true,"description":"The volume description","type":"string"},"size":{"description":"The size of the volume, in gibibytes (GiB)","type":"integer"},"status":{"description":"The volume status","type":"string"},"volume_type":{"description":"The associated volume type name for the volume","type":"string"},"volume_type_id":{"format":"uuid","description":"The associated volume type ID for the volume","type":"string"},"availability_zone":{"nullable":true,"description":"The name of the availability zone","type":"string"},"bootable":{"description":"Enables or disables the bootable attribute","type":"string"},"encrypted":{"description":"If true, this volume is encrypted","type":"boolean"},"encryption_key_id":{"nullable":true,"format":"uuid","description":"The UUID of the encryption key (microversion 3.64+)","type":"string"},"multiattach":{"description":"If true, this volume can attach to more than one instance","type":"boolean"},"attachments":{"description":"Instance attachment information","type":"array","items":{"$ref":"#/components/schemas/VolumeAttachment"}},"metadata":{"description":"Metadata key and value pairs","type":"object","additionalProperties":{"type":"string"}},"created_at":{"format":"date-time","description":"The date and time when the resource was created","type":"string"},"updated_at":{"nullable":true,"format":"date-time","description":"The date and time when the resource was updated","type":"string"},"user_id":{"format":"uuid","description":"The UUID of the user","type":"string"},"consistencygroup_id":{"nullable":true,"format":"uuid","description":"The UUID of the consistency group","type":"string"},"group_id":{"nullable":true,"format":"uuid","description":"The ID of the group (microversion 3.13+)","type":"string"},"snapshot_id":{"nullable":true,"format":"uuid","description":"The UUID of the source snapshot","type":"string"},"source_volid":{"nullable":true,"format":"uuid","description":"The UUID of the source volume","type":"string"},"replication_status":{"nullable":true,"description":"The volume replication status","type":"string"},"migration_status":{"nullable":true,"description":"The volume migration status","type":"string"},"os-vol-host-attr:host":{"nullable":true,"description":"Current back-end of the volume","type":"string"},"os-vol-tenant-attr:tenant_id":{"format":"uuid","description":"The project ID which the volume belongs to","type":"string"},"os-vol-mig-status-attr:migstat":{"nullable":true,"description":"The status of this volume migration","type":"string"},"os-vol-mig-status-attr:name_id":{"nullable":true,"description":"The volume ID that this volume name on the back-end is based on","type":"string"},"volume_image_metadata":{"description":"Image metadata entries","type":"object","additionalProperties":{"type":"string"}},"provider_id":{"nullable":true,"description":"The provider ID for the volume (microversion 3.21+)","type":"string"},"service_uuid":{"nullable":true,"format":"uuid","description":"Service UUID (microversion 3.48+)","type":"string"},"shared_targets":{"description":"Shared targets indicator (microversion 3.48+)","type":"boolean"},"cluster_name":{"nullable":true,"description":"The cluster name of volume backend (microversion 3.61+)","type":"string"},"consumes_quota":{"description":"Whether this resource consumes quota (microversion 3.65+)","type":"boolean"},"links":{"type":"array","items":{"$ref":"#/components/schemas/Link"}}}},"VolumeAttachment":{"type":"object","properties":{"server_id":{"format":"uuid","description":"The UUID of the attached server","type":"string"},"attachment_id":{"format":"uuid","description":"The attachment UUID","type":"string"},"attached_at":{"format":"date-time","description":"The date and time when attached","type":"string"},"host_name":{"nullable":true,"description":"The name of the attached host","type":"string"},"volume_id":{"format":"uuid","description":"The volume UUID","type":"string"},"device":{"description":"The device path","type":"string"},"id":{"format":"uuid","description":"The attachment ID","type":"string"}}},"Link":{"type":"object","properties":{"href":{"format":"uri","type":"string"},"rel":{"type":"string"},"type":{"type":"string"}}}}},"paths":{"/v3/volumes/{volume_id}":{"put":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolumeUpdateRequest"}}},"required":true},"tags":["volumes"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolumeResponse"}}},"description":"OK"}},"summary":"Update volume","description":"Updates a volume"}}}}
```

## Delete volume

> Deletes a volume

```json
{"openapi":"3.0.3","info":{"title":"OpenStack Block Storage API (Cinder)","version":"3.71"},"tags":[{"name":"volumes","description":"Volume management"}],"servers":[{"url":"https://{host}/cinder","description":"PCD Block Storage API v3","variables":{"host":{"default":"example.platform9.com","description":"The PCD controlplane hostname"}}}],"security":[{"pcdAuth":[]}],"components":{"securitySchemes":{"pcdAuth":{"name":"X-Auth-Token","type":"apiKey","in":"header","description":"PCD Identity Service token authentication"}},"responses":{"Accepted":{"description":"Request is accepted, but processing may take some time"}}},"paths":{"/v3/volumes/{volume_id}":{"delete":{"tags":["volumes"],"parameters":[{"name":"cascade","description":"Remove any snapshots along with the volume","schema":{"default":false,"type":"boolean"},"in":"query"},{"name":"force","description":"Force delete even if volume is in deleting or error_deleting state (microversion 3.23+)","schema":{"default":false,"type":"boolean"},"in":"query"}],"responses":{"202":{"$ref":"#/components/responses/Accepted"}},"summary":"Delete volume","description":"Deletes a volume"}}}}
```

## Perform volume action

> Performs various actions on a volume

```json
{"openapi":"3.0.3","info":{"title":"OpenStack Block Storage API (Cinder)","version":"3.71"},"tags":[{"name":"volumes","description":"Volume management"}],"servers":[{"url":"https://{host}/cinder","description":"PCD Block Storage API v3","variables":{"host":{"default":"example.platform9.com","description":"The PCD controlplane hostname"}}}],"security":[{"pcdAuth":[]}],"components":{"securitySchemes":{"pcdAuth":{"name":"X-Auth-Token","type":"apiKey","in":"header","description":"PCD Identity Service token authentication"}},"schemas":{"ExtendVolumeRequest":{"type":"object","properties":{"os-extend":{"required":["new_size"],"type":"object","properties":{"new_size":{"description":"The new size of the volume, in gibibytes (GiB)","type":"integer"}}}}},"ExtendVolumeCompletionRequest":{"type":"object","properties":{"os-extend_volume_completion":{"type":"object","properties":{"error":{"description":"Used to indicate that the extend operation has failed","type":"boolean"}}}}},"ResetStatusRequest":{"type":"object","properties":{"os-reset_status":{"required":["status"],"type":"object","properties":{"status":{"description":"The volume status","type":"string"},"migration_status":{"description":"The volume migration status","type":"string"},"attach_status":{"description":"The volume attach status","type":"string"}}}}},"RevertToSnapshotRequest":{"type":"object","properties":{"revert":{"required":["snapshot_id"],"type":"object","properties":{"snapshot_id":{"format":"uuid","description":"The UUID of the snapshot","type":"string"}}}}},"SetImageMetadataRequest":{"type":"object","properties":{"os-set_image_metadata":{"required":["metadata"],"type":"object","properties":{"metadata":{"description":"Image metadata key and value pairs","type":"object","additionalProperties":{"type":"string"}}}}}},"UnsetImageMetadataRequest":{"type":"object","properties":{"os-unset_image_metadata":{"required":["key"],"type":"object","properties":{"key":{"description":"The metadata key name to remove","type":"string"}}}}},"ShowImageMetadataRequest":{"type":"object","properties":{"os-show_image_metadata":{"type":"object"}}},"AttachVolumeRequest":{"type":"object","properties":{"os-attach":{"required":["mountpoint"],"type":"object","properties":{"instance_uuid":{"format":"uuid","description":"The UUID of the attaching instance","type":"string"},"host_name":{"description":"The name of the attaching host","type":"string"},"mountpoint":{"description":"The attaching mount point","type":"string"}}}}},"DetachVolumeRequest":{"type":"object","properties":{"os-detach":{"type":"object"}}}},"responses":{"Accepted":{"description":"Request is accepted, but processing may take some time"},"BadRequest":{"description":"Some content in the request was invalid"},"Forbidden":{"description":"Policy does not allow current user to do this operation"},"NotFound":{"description":"The requested resource could not be found"},"Conflict":{"description":"This resource has an action in progress that would conflict with this request"}}},"paths":{"/v3/volumes/{volume_id}/action":{"post":{"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ExtendVolumeRequest"},{"$ref":"#/components/schemas/ExtendVolumeCompletionRequest"},{"$ref":"#/components/schemas/ResetStatusRequest"},{"$ref":"#/components/schemas/RevertToSnapshotRequest"},{"$ref":"#/components/schemas/SetImageMetadataRequest"},{"$ref":"#/components/schemas/UnsetImageMetadataRequest"},{"$ref":"#/components/schemas/ShowImageMetadataRequest"},{"$ref":"#/components/schemas/AttachVolumeRequest"},{"$ref":"#/components/schemas/DetachVolumeRequest"}]}}},"required":true},"tags":["volumes"],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK (for show operations)"},"202":{"$ref":"#/components/responses/Accepted"},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}},"summary":"Perform volume action","description":"Performs various actions on a volume"}}}}
```

## Show volume metadata

> Shows metadata for a volume

```json
{"openapi":"3.0.3","info":{"title":"OpenStack Block Storage API (Cinder)","version":"3.71"},"tags":[{"name":"volumes","description":"Volume management"}],"servers":[{"url":"https://{host}/cinder","description":"PCD Block Storage API v3","variables":{"host":{"default":"example.platform9.com","description":"The PCD controlplane hostname"}}}],"security":[{"pcdAuth":[]}],"components":{"securitySchemes":{"pcdAuth":{"name":"X-Auth-Token","type":"apiKey","in":"header","description":"PCD Identity Service token authentication"}},"schemas":{"Metadata":{"type":"object","properties":{"metadata":{"type":"object","additionalProperties":{"type":"string"}}}}}},"paths":{"/v3/volumes/{volume_id}/metadata":{"get":{"tags":["volumes"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Metadata"}}},"description":"OK"}},"summary":"Show volume metadata","description":"Shows metadata for a volume"}}}}
```

## Create or update volume metadata

> Creates or replaces metadata for a volume

```json
{"openapi":"3.0.3","info":{"title":"OpenStack Block Storage API (Cinder)","version":"3.71"},"tags":[{"name":"volumes","description":"Volume management"}],"servers":[{"url":"https://{host}/cinder","description":"PCD Block Storage API v3","variables":{"host":{"default":"example.platform9.com","description":"The PCD controlplane hostname"}}}],"security":[{"pcdAuth":[]}],"components":{"securitySchemes":{"pcdAuth":{"name":"X-Auth-Token","type":"apiKey","in":"header","description":"PCD Identity Service token authentication"}},"schemas":{"Metadata":{"type":"object","properties":{"metadata":{"type":"object","additionalProperties":{"type":"string"}}}}}},"paths":{"/v3/volumes/{volume_id}/metadata":{"post":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Metadata"}}},"required":true},"tags":["volumes"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Metadata"}}},"description":"OK"}},"summary":"Create or update volume metadata","description":"Creates or replaces metadata for a volume"}}}}
```

## Replace volume metadata

> Replaces all the volume's metadata with the provided key-value pairs

```json
{"openapi":"3.0.3","info":{"title":"OpenStack Block Storage API (Cinder)","version":"3.71"},"tags":[{"name":"volumes","description":"Volume management"}],"servers":[{"url":"https://{host}/cinder","description":"PCD Block Storage API v3","variables":{"host":{"default":"example.platform9.com","description":"The PCD controlplane hostname"}}}],"security":[{"pcdAuth":[]}],"components":{"securitySchemes":{"pcdAuth":{"name":"X-Auth-Token","type":"apiKey","in":"header","description":"PCD Identity Service token authentication"}},"schemas":{"Metadata":{"type":"object","properties":{"metadata":{"type":"object","additionalProperties":{"type":"string"}}}}}},"paths":{"/v3/volumes/{volume_id}/metadata":{"put":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Metadata"}}},"required":true},"tags":["volumes"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Metadata"}}},"description":"OK"}},"summary":"Replace volume metadata","description":"Replaces all the volume's metadata with the provided key-value pairs"}}}}
```

## Show volume metadata item

> Shows metadata for a volume for a specific key

```json
{"openapi":"3.0.3","info":{"title":"OpenStack Block Storage API (Cinder)","version":"3.71"},"tags":[{"name":"volumes","description":"Volume management"}],"servers":[{"url":"https://{host}/cinder","description":"PCD Block Storage API v3","variables":{"host":{"default":"example.platform9.com","description":"The PCD controlplane hostname"}}}],"security":[{"pcdAuth":[]}],"components":{"securitySchemes":{"pcdAuth":{"name":"X-Auth-Token","type":"apiKey","in":"header","description":"PCD Identity Service token authentication"}},"schemas":{"MetaItem":{"type":"object","properties":{"meta":{"type":"object","additionalProperties":{"type":"string"}}}}}},"paths":{"/v3/volumes/{volume_id}/metadata/{key}":{"get":{"tags":["volumes"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetaItem"}}},"description":"OK"}},"summary":"Show volume metadata item","description":"Shows metadata for a volume for a specific key"}}}}
```

## Update volume metadata item

> Update metadata for a volume for a specific key

```json
{"openapi":"3.0.3","info":{"title":"OpenStack Block Storage API (Cinder)","version":"3.71"},"tags":[{"name":"volumes","description":"Volume management"}],"servers":[{"url":"https://{host}/cinder","description":"PCD Block Storage API v3","variables":{"host":{"default":"example.platform9.com","description":"The PCD controlplane hostname"}}}],"security":[{"pcdAuth":[]}],"components":{"securitySchemes":{"pcdAuth":{"name":"X-Auth-Token","type":"apiKey","in":"header","description":"PCD Identity Service token authentication"}},"schemas":{"MetaItem":{"type":"object","properties":{"meta":{"type":"object","additionalProperties":{"type":"string"}}}}}},"paths":{"/v3/volumes/{volume_id}/metadata/{key}":{"put":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetaItem"}}},"required":true},"tags":["volumes"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetaItem"}}},"description":"OK"}},"summary":"Update volume metadata item","description":"Update metadata for a volume for a specific key"}}}}
```

## Delete volume metadata item

> Deletes metadata for a volume

```json
{"openapi":"3.0.3","info":{"title":"OpenStack Block Storage API (Cinder)","version":"3.71"},"tags":[{"name":"volumes","description":"Volume management"}],"servers":[{"url":"https://{host}/cinder","description":"PCD Block Storage API v3","variables":{"host":{"default":"example.platform9.com","description":"The PCD controlplane hostname"}}}],"security":[{"pcdAuth":[]}],"components":{"securitySchemes":{"pcdAuth":{"name":"X-Auth-Token","type":"apiKey","in":"header","description":"PCD Identity Service token authentication"}}},"paths":{"/v3/volumes/{volume_id}/metadata/{key}":{"delete":{"tags":["volumes"],"responses":{"200":{"description":"OK"}},"summary":"Delete volume metadata item","description":"Deletes metadata for a volume"}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.platform9.com/api-docs/block-storage-service/volumes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.