nova — Summary

Reverse-specification of 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

• Repository: https://opendev.org/openstack/nova (local clone nova/) — specified branch: stable/2026.2 @ 8df1922926dd — analysed on: 2026-10-28
• Scope: full service, in five parts agreed with the user: (1) compute REST API and errors; (2) conductor and scheduler flows and RPC contracts; (3) nova-compute endpoints, periodic tasks and the virt driver interface (libvirt internals out of scope: OpenKeel uses KubeVirt); (4) databases, cells, outbound REST, notifications, scenarios; (5) rewrite pack. Change history (step 7) was not requested.
• Companion spec: a flavors-scoped spec of the same branch sits in this directory (00-flavors-summary_stable-2026.2.md … 07-flavors-kubevirt-mapping_stable-2026.2.md); it goes deeper on flavors, extra specs and their KubeVirt mapping.

Overview

Nova is the OpenStack compute service: it turns API requests for servers into virtual machines on hypervisor hosts. nova-api validates and records requests in the API database and hands them over RPC to nova-conductor, which asks nova-scheduler for hosts (Placement does the resource accounting), creates the instance in the right cell database and casts the work to nova-compute on the chosen host. nova-compute drives the hypervisor through a virt driver and talks to Neutron (ports), Cinder (volumes) and Glance (images). Almost every mutating API call is asynchronous (202), and the result is observed through the server's status, its instance actions and notifications.

Architecture

flowchart LR
  client[Client / CLI] -->|HTTPS REST /v2.1| api[nova-api]
  guest[Guest VM] -->|HTTP 169.254.169.254| nmeta[Neutron metadata proxy] -->|HTTP + HMAC| meta[nova-metadata-api]
  api -->|SQL| apidb[(nova_api)]
  api -->|SQL via mappings| celldb[(cell DBs + cell0)]
  api -->|AMQP cast/call| mq{{RabbitMQ per cell}}
  mq --> cond[nova-conductor]
  cond -->|AMQP call select_destinations| sched[nova-scheduler]
  sched -->|REST| placement[Placement]
  cond -->|SQL| apidb
  cond -->|SQL| celldb
  cond -->|AMQP cast build_and_run_instance| cmp[nova-compute]
  cmp -->|RPC object_action| cond
  cmp -->|REST| placement
  cmp -->|REST| neutron[Neutron]
  cmp -->|REST| cinder[Cinder]
  cmp -->|REST| glance[Glance]
  cmp -->|virt driver| hv[Hypervisor / KubeVirt]
  neutron -->|POST os-server-external-events| api
  api -->|REST token validation| ks[Keystone]

Processes

External dependencies

Key figures

• REST: 265 operations (201 routes + 64 body actions), 211 live and 54 removed (410); microversions 2.1–2.104; 214 default policy rules; 39 live server actions.
• Errors: 539 NovaException subclasses; 345 explicit exception → HTTP conversions in handlers.
• RPC: 90 client methods (compute 6.5, conductor 3.0 + compute_task 1.26, scheduler 4.5); 130 RPC server methods; 4 topics (conductor, scheduler, compute, compute-alt).
• Async: 44 periodic tasks (19 in the compute manager), 1 notification subscription; 141 versioned notification samples.
• Database: 20 API tables, 30 cell tables (+ shadow_*), 3 + 10 Alembic revisions.

Points of attention

1. Default microversion is 2.1: clients that send no OpenStack-API-Version get the oldest behaviour; a method called outside its range returns a bare 404, not 406 (01 § 1.3).
2. **The exception class code is not the API contract**: conversions are per handler, OverQuota (413) becomes 403, and any unconverted exception — including MessagingTimeout on synchronous RPC calls — becomes 500 while the operation may still complete (02 § 1.2, § 3).
3. Scheduling errors are asynchronous: POST /servers never fails with "no valid host"; the server goes to ERROR in cell0 (02 § 4).
4. Notifications are unversioned by default on this branch ([notifications]/notification_format = unversioned); consumers expecting versioned payloads must configure it (03 § 1.4).
5. **New compute-alt RPC topic** (compute RPC 6.5) for graceful shutdown: an implementation of the compute side must listen on both topics or old clients fall back (03 § 1.1).
6. User tokens travel in RPC messages (serialised context) and admin_password is sent in clear in the schedule_and_build_instances body; RabbitMQ must be TLS-protected and access-controlled (03 § 1.5).
7. Quotas are counted, not reserved: races are only closed by [quota]/recheck_quota (02 § 2, 03 § 2.2).
8. Default timeouts that silently disable safeguards: instance_build_timeout, reboot_timeout, rescue_timeout, resize_confirm_window, shelved_offload_time all default to 0, and heal_instance_info_cache_interval to -1 (05 § 4.3).
9. Policy documentation gap: os_compute_api:os-hypervisors:list-detail documents /os-hypervisors/details while the route is /os-hypervisors/detail (01 § 8).
10. Metadata API trust: behind the Neutron proxy the instance identity is only an HMAC over the instance id with a shared secret; a leaked metadata_proxy_shared_secret exposes every instance's metadata (01 § 9).

Blind spots / [inferred]

• Virt drivers: libvirt, VMware, Ironic and z/VM internals were not analysed (KubeVirt replaces them); only the ComputeDriver interface and which drivers implement each method are documented.
• Compute RPC handler table: driver and external calls are found up to two helper levels deep; work done in spawned threads or deeper helpers is not listed (05 § 4.2).
• Neutron/Cinder/Glance call details are summarised per operation rather than call by call; Placement and Glance client expectations are covered in their own reverse-specs.
• Statements marked [inferred] in 01–05: token serialisation by oslo.context, security-group action fan-out per port, Cinder multiattach microversion, Glance signature verification, and the COMPUTE_STATUS_DISABLED trait toggling.
• nova-manage commands (cells v2, placement heal/audit, db archive) are only mentioned.
• No change history (step 7 not requested).

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