neutron — Summary

Reverse-specification of neutron — branch stable/2026.2

• Repository: https://opendev.org/openstack/neutron (local clone ../neutron) — specified branch: stable/2026.2 @ eef1a0f7ee36 (29.0.0 + 29 commits) — analysed on: 2026-10-28
• Library: neutron-lib stable/2026.2 @ 1ee72052 (cited as neutron-lib:)
• Scope: OVN-focused, as agreed: the API server (pecan and the extension middleware), ML2 with the OVN mechanism driver, the OVN maintenance worker and DB sync, the OVN metadata agent, the OVN L3 plugin and the service plugins usable with OVN (QoS, trunk, segments, port forwarding, logging, segment ranges, Placement reporting), in the ML2/OVN reference profile _rewrite/tools/neutron-ovn.conf. Plus the rewrite pack (step 8). The change history (step 7) was not requested.

Overview

Neutron is OpenStack's networking service: it stores the logical network model (networks, subnets, ports, routers, floating IPs, security groups, QoS…) in MariaDB and exposes it through the Networking API v2.0. With ML2/OVN, it does not program the data plane itself: after each database commit it writes the equivalent objects into the OVN Northbound database (logical switches and ports, logical routers, NAT, ACLs, DHCP options), and ovn-northd and the ovn-controller of each node do the rest. Neutron listens to OVN (OVSDB monitor) to learn when ports go up, which chassis exist and where router gateways run, reports port status to Nova, keeps OVN consistent with a revision-number repair loop, and schedules router gateways on gateway chassis. On each compute node, the OVN metadata agent gives VMs the Nova metadata service through per-network namespaces and haproxy. Under OVN no agent needs RabbitMQ.

Architecture

flowchart LR
  client[Nova, Octavia, Horizon/Skyline, CLI] -->|HTTPS /v2.0| api[neutron API workers]
  api -->|token check| ks[Keystone]
  api -->|SQL| db[(MariaDB)]
  maint[neutron-ovn-maintenance-worker] -->|SQL| db
  api -->|OVSDB transact + monitor| nb[(OVN NB)]
  api -->|OVSDB monitor| sb[(OVN SB)]
  maint -->|OVSDB + lock| nb
  nb --> northd[ovn-northd] --> sb
  sb --> ctl[ovn-controller per node]
  meta[OVN metadata agent per node] -->|OVSDB| sb
  meta -->|HTTP + HMAC| novameta[nova-metadata-api]
  api -->|external events| nova[Nova API]
  api -->|resource providers| placement[Placement]
  api -.->|notifications, optional| mq{{RabbitMQ}}

Processes

External dependencies

Key figures

• API: 280 implemented operations over 40 collections (+ tags on 10 resource types), 110 extensions loaded by the profile, 15 plugins; 54 registered operations without implementation (500); 375 default policy rules.
• Errors: 318 exception classes raised in scope (82 → 400, 59 → 404, 104 → 409, 3 → 403, 4 → 503, 66 → 500).
• Background: 17 OVSDB event handlers in the server (7 on NB, 10 on SB), 5 in the metadata agent; 28 maintenance periodics (1 repair loop every 300 s, 27 one-shot/daily tasks); hash-ring heartbeat every 15 s; Nova events batched every 2 s.
• Database: 117 model tables (122 after migrations, with 5 legacy bgp_* tables).
• Conformance data: 2 728 recorded exchanges (985 unit tests, 0 failures), 40 pipeline probes.
• References: see the final check in _verification_stable-2026.2.md.

Points of attention

1. Two web stacks serve one API (01 § 1.2): extension resources go through the legacy Routes middleware and neutron/api/v2/base.py, core resources through pecan, and paths the middleware does not match fall through to pecan's own extension controllers. Results: two spellings of dashed collections both work, unprefixed QoS rule paths exist, JSON formatting and some 400 types differ by layer. The unit tests use only pecan, so they do not cover production routing.
2. 54 routes answer 500 (registered without implementation, including /v2.0/qos/ports, /v2.0/qos/networks, GET …/new) (01 § 3.1).
3. OVN is written after the SQL commit (02 § 4): a failed network update returns 500 although it is stored; port updates, router and floating-IP changes and deletes hide OVN failures; the repair loop fixes them within ~5 minutes, port statuses are not repaired by it.
4. OVSDB events are handled by one worker chosen by the hash ring; with an empty ring events are dropped, so port status can stay DOWN and Nova boots time out (05 § 3, 04 § 1).
5. Agent liveness is computed in memory per worker from SB nb_cfg (05 § 3.2).
6. Metadata agent: deprecated but still shipped; metadata_workers defaults to 0 with OVN (requests served one at a time per node); each request scans every SB Port_Binding row (05 § 5.4).
7. Router gateway scheduling silently creates routers without external connectivity when no gateway chassis matches; existing gateways are not rebalanced; the tie-break is non-deterministic across processes (05 § 7).
8. **Error type names are a client contract** (python-neutronclient, Nova) (07 § 2.2).
9. **OVN object names and external_ids are an interface** for ovn-bgp-agent and ovn-octavia-provider (07 § 3.1).
10. The legacy network-ownership check of neutron/api/v2/base.py is dead code for the API (subnets and ports are served by pecan), [inferred] (02 § 2).

Blind spots / [inferred]

• Out of scope: OVS, Linux bridge, SR-IOV, macvtap agents; DHCP, L3 and metering agents; DVR and L3 HA with agents; BGP, EVPN, local IP, NDP proxy, conntrack helpers, PVLAN, VPNaaS/FWaaS (separate reverse-specs), neutron-ovn-agent extensions other than metadata.
• OVN NB/SB contents are described from the code; no OVN database was run (no ovsdb-server binaries), so the exact transactions per API call were not recorded.
• QoS and logging OVN drivers are described at the level of rows and columns, not every match expression.
• External DNS (Designate) integration is not loaded by the profile; only mentioned.
• Behaviour that depends on configuration (distributed floating IPs, broadcast_arps_to_all_routers, localnet_learn_fdb…) is described for the defaults and marked where it changes.
• Statements marked [inferred] in the files were deduced without a complete trace or test.
• The unit-test exchanges went through pecan only; production routing is covered by 40 probes, not by a test suite.

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