cinder — Interactions

Interactions — 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

Cinder is four cooperating processes around one SQL database and one RabbitMQ bus (see summary): cinder-api (REST), cinder-scheduler, cinder-volume (one per host, one backend per enabled_backends entry) and cinder-backup. The API never touches storage itself: it writes the database and sends RPC messages.

1. RabbitMQ (oslo.messaging)

1.1 Transport and serialisation

• Transport from [DEFAULT]/transport_url; rpc.init creates the RPC transport, the notification transport and the notifier (cinder/rpc.py:58-76). The exchange is oslo.messaging's default **openstack**: rpc.set_defaults(control_exchange) exists but no Cinder process calls it (cinder/rpc.py:91-92) [inferred: confirmed by grep, the default comes from oslo.messaging].
• Arguments travel as versioned objects (cinder_object.name, cinder_object.version, cinder_object.data…) through CinderObjectSerializer, pinned to the oldest object version of the running services (cinder/rpc.py:216-224, cinder/service.py:234-240).
• Rolling upgrades: each client caps its RPC version to the minimum rpc_current_version recorded in the services table for that binary (cinder/rpc.py:250-264); methods newer than the cap raise ServiceTooOld (cinder/rpc.py:183-199). The volume client falls back to the pre-3.6 addressing when the cap is lower (cinder/volume/rpcapi.py:150-168).
• Remote exceptions allowed to be re-raised on the caller side: cinder.exception (get_allowed_exmods, cinder/rpc.py:58-62).

1.2 Topology

The address of a volume is its host field, host@backend#pool; service_topic_queue is the cluster name when the volume belongs to a cluster, otherwise the host (cinder/volume/rpcapi.py:150-168).

1.3 RPC methods (clients in this repository)

RPC API versions: scheduler 3.12, volume 3.20, backup 2.4 (cinder/scheduler/rpcapi.py:78, cinder/volume/rpcapi.py:145, cinder/backup/rpcapi.py:54). "Version sent" — means the default 3.0 (2.0 for backup), capped as above. The server side is the method of the same name in cinder/scheduler/manager.py, cinder/volume/manager.py and cinder/backup/manager.py (async processing).

Timeouts: a call waits [DEFAULT]/rpc_response_timeout (oslo.messaging default 60 s) and raises MessagingTimeout; the synchronous calls on the request path of the API are initialize_connection, terminate_connection, attach_volume, detach_volume, attachment_update, attachment_delete, accept_transfer, get_capabilities, get_manageable_*, get_pools, migrate_volume_completion, freeze_host/thaw_host, list_replication_targets, export_record.

1.4 Sample frame — create_volume cast from the scheduler to cinder-volume

{"oslo.version": "2.0",
 "oslo.message": "{\"method\": \"create_volume\", \"version\": \"3.0\", \"namespace\": null,
   \"args\": {\"volume\": {\"cinder_object.name\": \"Volume\", \"cinder_object.namespace\": \"cinder\",
              \"cinder_object.version\": \"1.9\", \"cinder_object.data\": {\"id\": \"…\", \"size\": 10, \"status\": \"creating\", \"host\": \"node1@lvm#lvm\", …}},
            \"request_spec\": {\"cinder_object.name\": \"RequestSpec\", …},
            \"filter_properties\": {\"retry\": {\"num_attempts\": 1, \"backends\": [\"node1@lvm#lvm\"], \"hosts\": [\"node1@lvm#lvm\"]}, …},
            \"allow_reschedule\": true},
   \"_unique_id\": \"…\", \"_context_request_id\": \"req-…\", \"_context_project_id\": \"…\", \"_context_user_id\": \"…\",
   \"_context_is_admin\": false, \"_context_roles\": [\"member\", \"reader\"], \"_context_auth_token\": \"…\", …}"}

Routing key cinder-volume.node1@lvm, server node1. [inferred] The object versions depend on cinder/objects/*.py (VERSION), and the context fields on RequestContext.to_dict (cinder/context.py); the user token travels in the message (_context_auth_token), because the volume service calls Glance, Nova and Barbican on the user's behalf.

1.5 Notifications

Published with priority INFO unless stated, publisher_id = "<service>.<host>" (cinder/rpc.py:172-179), only when [oslo_messaging_notifications]/driver is set (cinder/rpc.py:69-75).

2. Database (oslo.db, SQLAlchemy)

[database]/connection; 35 tables plus alembic_version. The model DDL is in [_rewrite/schema-mysql_stable-2026.2.sql](_rewrite/schema-mysql_stable-2026.2.sql); the schema produced by the migrations, in [_rewrite/schema-sqlite-migrated_stable-2026.2.sql](_rewrite/schema-sqlite-migrated_stable-2026.2.sql). They differ only by two leftover columns (§ 2.3). Every model has created_at, updated_at, deleted_at and deleted (soft delete) through CinderBase (cinder/db/models.py:40-62).

2.1 Tables

2.2 Notable transactions and patterns

• Compare-and-swap status changes: conditional_update(values, expected, filters) issues one UPDATE … WHERE <expected> AND <filters> and returns the number of rows (cinder/db/api.py:551, cinder/objects/base.py:368). Every state transition of the API uses it (delete, extend, attach, revert…), which makes concurrent API workers safe without locks. Example (volume deletion, cinder/volume/api.py:503-520): sql UPDATE volumes SET status='deleting', terminated_at=:now, updated_at=:now WHERE id=:id AND deleted=0 AND (attach_status IS NULL OR attach_status != 'attached') AND (migration_status IS NULL OR migration_status IN ('success','error')) AND consistencygroup_id IS NULL AND group_id IS NULL AND status IN ('available','error','error_restoring','error_extending','error_managing') AND NOT EXISTS (SELECT 1 FROM snapshots WHERE snapshots.volume_id = volumes.id AND snapshots.deleted = 0); [inferred] The exact migration_status and NOT EXISTS clauses come from AVAILABLE_MIGRATION_STATUS and volume_has_snapshots_filter in cinder/db/api.py.
• Quotas: reserve locks the project's quota_usages rows FOR UPDATE, refreshes them when until_refresh/max_age say so, inserts reservations (expiry [DEFAULT]/reservation_expire, 86,400 s), then commit moves reserved into in_use and rollback cancels (cinder/quota.py:319-440). Retries on deadlock through oslo_db.api.wrap_db_retry [inferred].
• Soft delete: rows are marked deleted=1; cinder-manage db purge <age> removes them physically.

2.3 Models versus migrations

The real migrations (Alembic, cinder/db/migrations/versions/) add two columns that the models no longer declare: quotas.allocated and reservations.allocated_id (with an index and a foreign key to quotas.id), leftovers of the removed nested-quota driver. See [_rewrite/schema-diff_stable-2026.2.md](_rewrite/schema-diff_stable-2026.2.md).

3. Outbound REST calls

Request IDs: global_request_id is propagated to Nova and Glance (cinder/compute/nova.py:119-131).

4. Coordination and locks (tooz)

• cinder.coordination.COORDINATOR (prefix cinder-) uses tooz with [coordination]/backend_url, default **file://$state_path** — local file locks, only valid on one host (cinder/coordination.py:38-41, cinder/coordination.py:127). Active-active volume clusters need a distributed backend (etcd, Redis…).
• Locks held: cinder-<volume_id>-delete_volume, cinder-<snapshot_id>-delete_snapshot, cinder-<volume_id> (attach), cinder-<volume_id>-detach_volume, cinder-attachment_update-<volume_id>-<host>, cinder-<image_id> (image download into a cache entry), declared by @coordination.synchronized decorators on delete_volume, delete_snapshot, attach_volume, detach_volume, attachment_update and _prepare_image_cache_entry (cinder/volume/manager.py:929, cinder/volume/manager.py:1314, cinder/volume/manager.py:1399, cinder/volume/manager.py:1488, cinder/volume/api.py:2527; cinder/volume/flows/manager/create_volume.py:875).
• oslo.concurrency file locks (lock_path) are used by drivers and by utils.api_clean_volume_file_locks.

5. Other interactions

• Storage backends: each cinder-volume loads volume_driver per backend section (default cinder.volume.drivers.lvm.LVMVolumeDriver); drivers talk to arrays over vendor REST/SSH APIs or local tools (LVM, rbd…). Data copy and attach on the volume host go through os-brick connectors (iSCSI, FC, NVMe-oF, RBD) and privsep/rootwrap (etc/cinder/rootwrap.d/volume.filters). Only the driver interface (cinder/interface/volume_driver.py) is in scope here.
• Image conversion: qemu-img through privsep for image ↔ volume copies, with format_inspector checks of the image header (cinder/image/image_utils.py, cinder/image/format_inspector.py).
• Files: state_path, lock_path, image conversion directory image_conversion_dir.

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