Preview — pending review
This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.
Rename a block volume (mutable metadata)
Applies a partial update to a block volume's mutable metadata — its display name and its
free-text description — exactly as the Rename action in the volume detail page's header drives it
(the copy of compute.instance.update). Only fields present in the body are changed;
omitted fields keep their current values. name IS Cinder's display_name, so the new name
is PROGRAMMED into Cinder first and persisted only after the provider accepts it: the read
model can never report a name the cloud does not carry, and a provider refusal leaves the
row exactly as it was. (Compute needs that ordering to survive its own collector, which
rewrites name every tick; the storage collector does not write name back, so here the
ordering buys the guarantee itself rather than protection from a revert.) Nothing else
about the volume moves: size, type, encryption and, in particular, an existing ATTACHMENT
are untouched, so an IN_USE volume is renamed live.
Validation: the volume must exist, be visible in the scope and not be soft-deleted → 404
NOT_FOUND; the body must carry at least one updatable field → 422 VALIDATION_FAILED; name
(when present) must satisfy ResourceName (non-empty, ≤255 chars, printable, no leading or
trailing whitespace) and be unique among the project's LIVE volumes → 422 VALIDATION_FAILED /
409 CONFLICT field=name; neither field may be sent as null (there is nothing to clear a
required display name to — omit it instead, or send "" to blank a description) → 422.
Async & state: Synchronous. The provider rename is applied inline and the 200 body is the
full updated Volume read model; status never changes. The write opens an immediately
terminal audit Operation (storage.volume.update), so the rename is visible in the scope's
Activity feed. No SSE frame is emitted (those are published by the worker, and this write
never reaches it): the caller refreshes from the 200 body and invalidates its cached list.
Errors: 401 UNAUTHENTICATED; 403 FORBIDDEN (reader/billing roles cannot mutate storage);
404 NOT_FOUND for an unknown/deleted volume; 409 CONFLICT when the name is already taken by a
live volume in the project, or when the volume has not finished provisioning (no provider
volume to rename yet); 412 PRECONDITION_FAILED on a missing or stale If-Match; 422
VALIDATION_FAILED; 500 INTERNAL.
Idempotency/Concurrency: No idempotency key — the PATCH is naturally idempotent. If-Match
with the ETag from the detail read is REQUIRED; a missing or stale validator returns 412 and
the client must re-read before retrying.
bearerTokenAuthorizationBearer <token>An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.
scopeId*stringOpaque ownership+authorization scope resolving to tenant + subscription + project.
volumeId*stringIdentifier of the block volume.
If-Match?stringETag for optimistic concurrency on mutations/deletes; mismatch results in 412.
application/json- body
Partial update of a volume's mutable metadata; only provided fields are changed. Neither field is nullable: name is required on the resource and has nothing to be cleared to, and a description is blanked by sending "", so a present-with-null is rejected 422 rather than silently ignored.
name?stringNew volume display name; unique among the project's live volumes.
^[^\p{C}\p{Z}\x{10000}-\x{10FFFF}](?:[^\p{C}\p{Zl}\p{Zp}\x{10000}-\x{10FFFF}]*[^\p{C}\p{Z}\x{10000}-\x{10FFFF}])?$1 <= length <= 255description?stringNew free-text description; send an empty string to blank it.
length <= 255deletionProtection?booleanTurn the volume's deletion protection on/off. Synchronous, no Cinder call: the guard covers the console and this API only, not direct OpenStack (Cinder) access. null is rejected 422 (omit the field to leave it unchanged).
The updated Volume read model.
application/json- response
Block volume read model as rendered by the Volumes page and the volume detail page.
origin?stringWhere the resource was made -- portal for a create on the console, api for an object made straight against the OpenStack API (CLI, Terraform, the Kubernetes cloud provider) that discovery adopted. Informational; nothing behaves differently. Absent from a backend that predates it, which means portal.
"portal""api""system""imported"id*stringVolume identifier (e.g. vol-0a1b2c3d).
name*stringVolume display name.
status*stringLifecycle status of the volume.
"CREATING""AVAILABLE""IN_USE""AWAITING_TRANSFER""ERROR"statusReason*|Human-readable, customer-facing reason for the current status when it is a failure (e.g. "This request exceeds the quota available to this project. Free up existing resources or request a quota increase." on an ERROR volume); never raw provider text. Null while the volume is healthy or the failure carried no detail.
statusReasonCode*|Machine-readable companion to statusReason: a small, OPEN vocabulary of codes the console can branch on without parsing the human text, deliberately a plain string rather than a closed enum so a code the client does not recognize yet degrades to the generic failure message. Today the only value is cancelled: the resource is in its failure state because its create operation was CANCELLED; a provider object the create had already built may be left in place, and the resource's DELETE removes it. Reported only while the resource is in that failure state; null otherwise.
sizeGb*integerProvisioned size in GB (1–16,384).
type*|Volume performance tier. Null when the volume sits on a provider volume type no platform tier maps to (e.g. a volume adopted from an imported project): the tier is then UNKNOWN and unpriced, never reported as a tier it is not. providerVolumeType carries the provider's own type name in that case.
providerVolumeType*|The provider's (Cinder's) own volume type name, present only when type is null because no platform tier maps to it (an adopted volume on a legacy type). Null for a volume on a platform tier. Display-only: it has no price and cannot be requested.
attachedTo*|nullInstance attachment (instance id, name, device), or null when detached.
bootable*booleanWhether the volume carries a bootable OS image.
encrypted*booleanWhether the volume is encrypted at rest, DERIVED from the provider's own view of the volume (the volume type's encryption spec) — never from the create request. False until the provider confirms encryption, so this field never asserts a security property the platform did not actually deliver.
multiAttach*booleanAllow attaching to more than one instance (RWX).
availabilityZone*stringAvailability zone the volume lives in (e.g. ist-1a).
description*stringOperator-supplied description.
source*Provenance of a block volume — empty, created from an image, restored from a snapshot, or cloned from another volume.
kmsKeyId*|Customer-managed KMS key for envelope encryption; null when platform-managed or encryption is off.
keyRotationDays*integerAutomatic key-rotation period in days (0 = manual).
pricePerGbMonthlyCents*|Price per GB per month in hundredths of the currency unit (an integer, not a Money object): the rate billing meters this volume's tier at for the volume's subscription, rounded down to the hundredth. Null when no price applies to the tier: there is no per-type default figure.
deletionProtection*booleanPlatform-owned deletion guard. While true, storage.volume.delete is refused with 409 DELETION_PROTECTED before any work starts; turn it off with the metadata PATCH, then delete. It guards the console and this API ONLY: Cinder has no lock, so an OpenStack API credential with Full access can still delete the volume directly. False for every volume unless a caller turned it on; the collector never writes it.
tags*array<>Key-value pairs shown on the Tags tab; double as Cost Explorer dimensions.
createdAt*stringCreation timestamp (ISO 8601).
date-timeupdatedAt*stringLast modification timestamp (ISO 8601).
date-timecurl -X PATCH "https://example.com/scopes/string/storage/volumes/string" \ -H "Content-Type: application/json" \ -d '{}'{ "origin": "portal", "id": "string", "name": "string", "status": "CREATING", "statusReason": "string", "statusReasonCode": "string", "sizeGb": 0, "type": "Standard SSD", "providerVolumeType": "string", "attachedTo": { "instanceId": "string", "instanceName": "string", "device": "string" }, "bootable": true, "encrypted": true, "multiAttach": true, "availabilityZone": "string", "description": "string", "source": { "kind": "empty", "ref": "string" }, "kmsKeyId": "string", "keyRotationDays": 0, "pricePerGbMonthlyCents": 0, "deletionProtection": true, "tags": [ { "key": "string", "value": "string" } ], "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z"}