cinder — Summary

Reverse-specification of Cinder — branch stable/2026.2

Branch stable/2026.2 @ c117f9cf08b4 (29.0.0-1-gc117f9cf0) — repository https://opendev.org/openstack/cinder — analysed on 2026-10-28

• Scope: the Block Storage service without its vendor drivers: the v3 REST API and its middlewares, the volume/backup/group/transfer APIs, the scheduler, the volume and backup managers, quotas, user messages, the database, RPC and notifications, outbound calls (Keystone, Glance, Nova, Barbican), coordination, and a rewrite pack. About 89,000 lines of core code out of 326,000; the 229,000 lines of cinder/volume/drivers/* are covered only through the driver interface. No change history (step 7) was requested.
• References are file:line relative to the repository root; nova: refers to Nova stable/2026.2 @ 8df1922926dd. [inferred] marks a statement that was not followed to the end in the code.

Files of this specification

Overview

Cinder provides block volumes to instances: it creates, snapshots, backs up, extends, retypes, migrates, transfers and deletes volumes, and gives Nova the connection information to attach them. It does not move data on the request path itself:

• cinder-api validates, checks policies and quotas, records the intent in the database and sends an RPC message;
• cinder-scheduler chooses a backend pool from capacities that every backend reports each minute;
• cinder-volume (one per host and backend) drives the storage through a driver and moves resources from transient statuses (creating, extending…) to final ones;
• cinder-backup copies volumes to an object store.

Clients observe the outcome by polling statuses and reading user messages. Nova is the main client: it attaches volumes with the attachments API (3.44) and receives volume-extended/volume-reimaged events from Cinder.

flowchart LR
  subgraph clients[Clients]
    U[Users / CLI / Horizon / Skyline]
    N[Nova]
    GL[Glance cinder store]
  end
  subgraph cinder[Cinder]
    API[cinder-api<br/>paste pipeline, v3 router]
    SCH[cinder-scheduler<br/>filters + weighers]
    VOL[cinder-volume<br/>one per host@backend]
    BK[cinder-backup]
  end
  U -->|HTTPS /v3| API
  N -->|/v3 attachments 3.44| API
  GL -->|/v3| API
  API -->|token validation| KS[Keystone]
  API -->|SQL| DB[(MariaDB<br/>35 tables)]
  SCH --> DB
  VOL --> DB
  BK --> DB
  API -->|AMQP cast/call| MQ{{RabbitMQ}}
  MQ --> SCH
  MQ --> VOL
  MQ --> BK
  VOL -->|fanout capabilities| MQ
  VOL -->|driver| ARR[(Storage arrays / LVM / Ceph)]
  VOL -->|images| G[Glance]
  VOL -->|external events| N
  API -->|keys| KM[Barbican]
  BK -->|objects| OS[(Swift / S3 / NFS…)]
  API -. notifications .-> MQ

Processes

External dependencies

Key figures

218 HTTP operations (166 paths and verbs plus 52 body actions), microversions 3.0–3.71 (72), 112 request schemas, 167 default policy rules; 83 RPC client methods (scheduler 3.12, volume 3.20, backup 2.4) and about 90 RPC server methods; 5 periodic tasks and 2 service timers in the core services; 35 tables; 218 core exception classes (110 more in drivers); 16 user-message actions and 30 details; about 40 notification event types; 967 recorded HTTP exchanges from 196 functional tests.

Points of attention

1. **Everything is asynchronous after 202**: failures show up as error* statuses and user messages, not HTTP codes. A volume stuck in a transient status points to a dead or unreachable service; workers and POST /workers/cleanup exist to recover.
2. Default microversion is 3.0: clients that do not send OpenStack-API-Version get the oldest behaviour and response shape.
3. Synchronous RPC on the request path (attachment_update, initialize_connection, accept_transfer…): a slow or dead volume service gives 500 after rpc_response_timeout (60 s); Nova retries attachment calls up to 5 times.
4. Masked 500s: non-safe exceptions lose their message at the API; read the API log Caught error:.
5. Encrypted volume deletion deletes the Barbican key before the backend volume: later failures leave an undecryptable volume.
6. Locks default to local files ([coordination]/backend_url = file://$state_path): active-active volume clusters need a distributed tooz backend.
7. Inconsistent translations: InvalidVolume is 400 everywhere but 409 on revert; QoSSpecsInUse is 400 or 500 depending on force; QoS associate/disassociate change data with GET.
8. 3.71 not enforced for os-extend_volume_completion; 13 policy operations entries refer to non-existent routes.
9. Attachment deletion by a user on a connected attachment is refused (409) unless the request carries Nova's service token: deployments must configure [service_user] in Nova.

Blind spots / [inferred]

• Vendor drivers (cinder/volume/drivers/*, 229,000 lines), their polling loops and their exceptions are not described; only cinder/interface/volume_driver.py and the LVM default are referred to.
• Backup drivers: the chunked protocol (object names, metadata JSON, compression, SHA-256 lists) was not specified; restore compatibility between implementations would need it.
• Replication, failover, groups and consistency groups: described by their API and RPC names, not followed through the managers.
• Migration and retype with data copy (_migrate_volume_generic, cinder/volume/manager.py) and image upload paths: summarised, not traced step by step.
• Versioned object formats on the bus (cinder/objects/*.py versions and compatibility code) are not tabulated; the sample frame of 03 is reconstructed.
• Notification payload of groups and capacity, and the exact names of type-access notifications, are [inferred].
• The exchanges carry no test IDs and were not replayed against an empty service; the response schemas cover 102 of 218 operations.

Source: reverse-spec-cinder/00-summary_stable-2026.2.md. The _rewrite/ and _inventory/ files are not published on the site.