nova — Interactions

Interactions — nova — branch stable/2026.2

Branch stable/2026.2 @ 8df1922926dd (34.0.0 + 7 commits) — repository https://opendev.org/openstack/nova — analysed on 2026-10-28

Related files: REST API · errors · scenarios · async processing. Client-side expectations of Glance and Placement are already specified in reverse-spec-glance/07-rewrite-pack_stable-2026.2.md and reverse-spec-placement/07-rewrite-pack_stable-2026.2.md (§ "What the clients expect").

0. Overview

1. RabbitMQ (oslo.messaging RPC)

1.1 Topology

Nova uses one RPC transport per cell plus an optional API-level transport:

• [DEFAULT]/transport_url of each service points at its own cell's broker; nova-api and nova-conductor (super-conductor) reach a cell's broker through cell_mappings.transport_url in the API database. nova.rpc.ClientRouter picks the transport from the request context (context.mq_connection, set by set_target_cell) and falls back to the default client (nova/rpc.py:423-444).
• Exchange: [DEFAULT]/control_exchange (default nova). Topics and servers:

• Graceful shutdown (new in 2026.2, compute RPC 6.5): every compute creates a second RPC server on compute-alt (nova/service.py:267-285). On shutdown it stops consuming compute but keeps compute-alt alive until its ongoing operations end. Calls that belong to an operation already in progress on that host — finish_resize, finish_revert_resize, finish_snapshot_based_resize_at_dest, finish_revert_snapshot_based_resize_at_source, check_instance_shared_storage, validate_console_port, live_migration, pre_live_migration, post_live_migration_at_destination — are sent to compute-alt (nova/compute/rpcapi.py:578-603), with a fallback to compute when the target is pinned below 6.5.

1.2 Versioning and rolling upgrades

• Each client pins a version_cap. For compute it is [upgrade_levels]/compute (auto by default): the minimum nova-compute service version across all cells is read from the services tables and mapped to an RPC version through SERVICE_VERSION_HISTORY (nova/compute/rpcapi.py:496-560); release aliases go from bobcat = 6.2 to hibiscus = 6.5 (nova/compute/rpcapi.py:440-446). Conductor and scheduler use static aliases (nova/conductor/rpcapi.py:203-218).
• Clients downgrade messages with can_send_version() checks, dropping or converting arguments for older servers (nova/conductor/rpcapi.py:331-386 for examples).
• Objects travel as nova_object.* primitives (NovaObjectSerializer); a receiver that is too old asks the conductor to backport them (object_backport_versions).
• call timeouts: [DEFAULT]/rpc_response_timeout (60 s). Long calls (select_destinations, migrate_server, attach_volume, cache_images, check_can_live_migrate_*, prep_snapshot_based_resize_at_*…) use [DEFAULT]/long_rpc_timeout (1800 s) with call_monitor_timeout = rpc_response_timeout, which makes the server send heartbeats so that a dead server is detected early (nova/compute/rpcapi.py:562-575).

1.3 RPC methods

90 client methods (nova/compute/rpcapi.py, nova/conductor/rpcapi.py, nova/scheduler/rpcapi.py), each matched to its server handler. "Mode" is call (request/response) or cast (fire-and-forget); call/cast means the client chooses at run time (e.g. do_cast arguments). Versions are the ones the client may send depending on the pin. Compute messages are always sent to server=<instance.host> or an explicit host (nova/compute/rpcapi.py:61-77 _compute_host). Machine-readable: _rewrite/rpc-contract_stable-2026.2.json.

1.4 Notifications

• Driver and topics come from [oslo_messaging_notifications]; the format is chosen by [notifications]/notification_format, whose default on this branch is **unversioned** (nova/conf/notifications.py:59-60): only legacy compute.instance.* notifications are sent unless it is set to versioned or both. Versioned notifications go to the topics in [notifications]/versioned_notifications_topics (default versioned_notifications, nova/conf/notifications.py:86-87).
• [notifications]/notify_on_state_change (None by default; vm_state or vm_and_task_state, nova/conf/notifications.py:30-40) adds compute.instance.update / instance.update notifications on state transitions.
• Versioned payloads are nova.notifications.objects.* objects; 141 samples in doc/notification_samples/ (101 instance-*, 15 aggregate-*, 6 keypair-*, 3 flavor-*, 3 server_group-*, 3 service-*, 3 compute_task-*, 2 scheduler-*…). Event types follow <object>.<action>[.<phase>] with phase start/end/error, publisher nova-compute:<host>, nova-api:<host>, etc.
• Sample envelope (versioned, AMQP body after oslo.messaging unwrapping):

{"priority": "INFO", "event_type": "instance.pause.end",
 "publisher_id": "nova-compute:compute-1", "timestamp": "2026-10-28 10:00:00.000000",
 "message_id": "…",
 "payload": {"nova_object.name": "InstanceActionPayload", "nova_object.namespace": "nova",
             "nova_object.version": "1.9",
             "nova_object.data": {"uuid": "…", "state": "paused", "power_state": "paused",
                                  "task_state": null, "host": "compute-1", "flavor": {"…": "…"},
                                  "fault": null, "action_initiator_user": "…"}}}

1.5 Sample RPC frame

nova-api → conductor, cast schedule_and_build_instances (AMQP body on exchange nova, routing key conductor):

{"oslo.version": "2.0",
 "oslo.message": "{\"method\": \"schedule_and_build_instances\", \"namespace\": \"compute_task\", \"version\": \"1.17\", \"args\": {\"build_requests\": [{\"nova_object.name\": \"BuildRequest\", \"nova_object.version\": \"1.3\", \"nova_object.data\": {…}}], \"request_specs\": [{\"nova_object.name\": \"RequestSpec\", …}], \"image\": {…}, \"admin_password\": \"…\", \"injected_files\": [], \"requested_networks\": {…}, \"block_device_mapping\": [{…}], \"tags\": []}, \"_unique_id\": \"…\", \"_context_request_id\": \"req-…\", \"_context_global_request_id\": null, \"_context_project_id\": \"…\", \"_context_user_id\": \"…\", \"_context_roles\": [\"member\", \"reader\"], \"_context_service_catalog\": [ … ], \"_context_auth_token\": \"gAAAA…\", \"_context_is_admin\": false, \"_context_read_deleted\": \"no\", \"_context_timestamp\": \"…\"}"}

The serialised context carries the service catalog (nova/context.py:195-211) and, through the oslo.context base class, the user token [inferred: auth_token is part of oslo_context.RequestContext.to_dict], so computes can call Neutron/Cinder/Glance on behalf of the user; admin_password travels in clear in the message body.

2. Databases

2.1 Layout (cells v2)

flowchart LR
  api[nova-api] -->|SQL| apidb[(nova_api)]
  api -->|SQL via instance_mappings| cell0[(nova_cell0)]
  api -->|SQL via instance_mappings| cell1[(nova cell1)]
  sc[super-conductor] --> apidb
  sc --> cell0
  sc --> cell1
  sched[nova-scheduler] -->|read| apidb
  sched -->|read compute_nodes| cell1
  cc[cell conductor] --> cell1
  cpu[nova-compute] -.->|RPC object_action| cc

• API database (nova/db/api/models.py, 20 tables): cell_mappings (name, UUID, transport_url, database_connection, disabled, nova/db/api/models.py:135-147), host_mappings, instance_mappings (instance → cell, queued_for_delete, project/user), build_requests (serialised instance before scheduling), request_specs (serialised RequestSpec reused on every move), flavors, flavor_extra_specs, flavor_projects, aggregates, aggregate_hosts, aggregate_metadata, instance_groups, instance_group_policy, instance_group_member, key_pairs, quotas, project_user_quotas, quota_classes, and the legacy quota_usages / reservations (no longer written: usage is counted). DDL: _rewrite/schema-api-mysql_stable-2026.2.sql.
• Cell databases (nova/db/main/models.py, 30 tables + shadow_* copies created by the migrations): instances, instance_extra (NUMA, PCI requests, flavor copy, vCPU model, keypairs, trusted certs, resources), instance_system_metadata, instance_metadata, instance_info_caches (network info JSON), instance_faults, instance_actions, instance_actions_events, block_device_mapping, migrations, compute_nodes, services, pci_devices, tags, virtual_interfaces, console_auth_tokens, share_mapping, task_log, volume_usage_cache, instance_id_mappings, s3_images, plus legacy security_groups/security_group_rules/security_group_instance_association, certificates, quotas… DDL: _rewrite/schema-mysql_stable-2026.2.sql.
• cell0 has the same schema as a cell; it only holds instances that failed scheduling.
• Migrations: Alembic, nova/db/api/migrations/versions/ (3 revisions) and nova/db/main/migrations/versions/ (10 revisions, the latest adding instances.compute_id, console_auth_tokens.tls_port, share mappings and BDM encryption fields).
• Soft delete: most cell tables have deleted (= id when deleted) and deleted_at; rows are moved to shadow_* tables by nova-manage db archive_deleted_rows (nova/cmd/manage.py:301) and removed by nova-manage db purge (nova/cmd/manage.py:526).

2.2 Notable transactions and locking

2.3 Cross-cell reads

List and lookup operations scatter-gather over all cells in parallel with a per-cell timeout (nova/context.py:456 scatter_gather_cells, CELL_TIMEOUT = 60 at nova/context.py:51); a cell that does not answer is either skipped or returned as a partial record (01 § 1.6).

3. Outbound REST calls

All clients authenticate with keystoneauth sessions built from the service's config group; when [service_user]/send_service_user_token = true the user token is sent with an extra X-Service-Token so that expired user tokens are still accepted during long operations (nova/service_auth.py:73-91). X-OpenStack-Request-ID carries the global request id.

3.1 Placement (nova/scheduler/client/report.py)

Generation conflicts (409 placement.concurrent_update) are retried by the retries decorator (nova/scheduler/client/report.py:149); with safe_connect (nova/scheduler/client/report.py:115-140) an unreachable or misconfigured Placement is logged ("Placement API service is not responding.") and the call returns None, so the resource tracker keeps running; a failed claim makes the scheduler try the next host.

3.2 Neutron (nova/network/neutron.py, python-neutronclient v2.0)

Neutron calls back with POST /os-server-external-events (01 § 3.7). Admin calls use [neutron] credentials; user calls use the user token (nova/network/neutron.py:230 get_client).

3.3 Cinder (nova/volume/cinder.py, python-cinderclient v3)

Minimum version 3.0 (nova/volume/cinder.py:237); the new attachment flow uses 3.44 (attachment_create/update/complete/delete, nova/volume/cinder.py:781-940), multiattach needs 3.48 [inferred], reimage of boot volumes 3.68 (nova/volume/cinder.py:953). Legacy calls (reserve_volume, initialize_connection, attach, detach, begin_detaching, roll_detaching) remain for old BDMs. Cinder calls back with volume-extended/volume-reimaged external events and with /os-assisted-volume-snapshots.

3.4 Glance (nova/image/glance.py, python-glanceclient v2)

show/detail (image metadata, compute and API), download (compute, streamed to the image cache; direct RBD download optional), create/update/upload (snapshot, shelve, backup), delete (backup rotation, failed snapshot), image_import_copy / copy_image_to_store (multi-store), signature verification with Barbican (cursive) when img_signature_verify [inferred].

3.5 Keystone

• keystonemiddleware.auth_token validates each incoming token (GET /v3/auth/tokens, cached in memcached).
• PUT /os-quota-sets/{project} checks that the project exists: GET /v3/projects/{id} (nova/api/openstack/identity.py:26-39).
• Unified limits ([quota]/driver = nova.quota.UnifiedLimitsDriver): registered limits and project limits read through oslo.limit (nova/limit/local.py:18-19, nova/limit/placement.py).

3.6 Cyborg and Manila

• Cyborg (nova/accelerator/cyborg.py:113-114): GET /v2/device_profiles?name= at boot (API), POST /v2/accelerator_requests and PATCH to bind ARQs (conductor), GET/DELETE ARQs (compute). Cyborg notifies accelerator-request-bound.
• Manila (nova/share/manila.py): GET /shares/{id}, access rules list, allow/deny access for the compute host (virtiofs shares, 2.97+).

4. Cache (oslo.cache)

When [cache]/enabled is false, an in-process dictionary is used (nova/cache_utils.py:47-58), so each API worker has its own cache.

5. Other

• Privileged operations: oslo.privsep daemons (nova/privsep/) for file, network and libvirt helpers on the compute host; rootwrap is no longer used for new code.
• Console proxies: nova-novncproxy, nova-spicehtml5proxy, nova-serialproxy validate tokens against the cell DB console_auth_tokens (nova/console/websocketproxy.py) and proxy WebSocket ↔ VNC/SPICE/serial on the compute.
• Hypervisor: libvirt over its UNIX socket (qemu:///system), VMware vCenter SOAP, Ironic REST, z/VM REST — replaced by the KubeVirt API in OpenKeel.

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