▤ Stackers Network

Learn OpenStack · core/networking

Neutron Architecture

Neutron Server

The neutron-server process is a WSGI application that exposes the Neutron v2 REST API. It handles no actual packet forwarding — its job is to accept API requests, validate them, persist state to the database, and dispatch configuration to agents via RPC (AMQP/RabbitMQ) or directly to backend SDN controllers.

Internal structure of neutron-server:

neutron-server
├── API layer (Pecan/WSGI, versioned at /v2.0)
│   ├── Resource controllers (networks, subnets, ports, routers, …)
│   └── Policy enforcement (oslo.policy, RBAC)
├── Plugin framework
│   ├── Core plugin  →  ML2Plugin (most deployments)
│   └── Service plugins (L3, QoS, Trunk, Segments, BGP, …)
├── DB layer (oslo.db → SQLAlchemy → MariaDB/PostgreSQL)
├── RPC layer (oslo.messaging → RabbitMQ)
│   ├── Cast/call to agents (OVS agent, DHCP agent, L3 agent, metadata agent)
│   └── Callbacks from agents (port status updates, binding confirmations)
└── Extension manager (loads API extensions from entry points)

neutron-server runs as multiple workers (set api_workers in neutron.conf). All workers share the same DB connection pool and the same RabbitMQ connection.

ML2 Plugin

The Modular Layer 2 (ML2) plugin is the standard core plugin. It replaces the older monolithic plugins (OVS plugin, Linux Bridge plugin). ML2 decomposes network behaviour into two independent driver hierarchies:

Type Drivers

Type drivers manage the allocation and lifecycle of network segment identifiers (VLAN IDs, VXLAN VNIs, etc.).

Type Segment ID Use Case
flat none (untagged) Provider networks on a dedicated physical NIC
vlan 802.1Q VLAN ID (1–4094) Provider networks; isolation via VLAN tagging
vxlan VNI (1–16 777 215) Tenant networks; overlay tunnels between compute nodes
gre tunnel key Tenant overlay; less common than VXLAN
geneve VNI Used by OVN; carries metadata in header extensions
local none Single-node testing; no inter-node connectivity

Type drivers are configured in ml2_conf.ini:

[ml2]
type_drivers = flat,vlan,vxlan,geneve
tenant_network_types = vxlan,geneve

Mechanism Drivers

Mechanism drivers implement the actual wiring of ports to the underlying network infrastructure. Multiple mechanism drivers can be active simultaneously.

Driver Backend Agent Required
openvswitch Open vSwitch neutron-openvswitch-agent on each compute/network node
ovn OVN (ovsdb) ovn-controller on each node; no separate Neutron agent
linuxbridge Linux bridge + VXLAN/VLAN neutron-linuxbridge-agent on each node
l2population Flood/learn optimization Works alongside OVS or Linux Bridge to pre-populate FDB
macvtap SR-IOV macvtap For VMs with direct hardware attachment

Configuration:

[ml2]
mechanism_drivers = ovn,l2population
# or for OVS deployments:
# mechanism_drivers = openvswitch,l2population

Extension Manager

ML2's extension manager loads port binding extensions, port security, VLAN transparency, and others as ML2 extension drivers:

[ml2]
extension_drivers = port_security,qos,dns

Agents

In ML2/OVS deployments, several agents run on each host and communicate with neutron-server over RabbitMQ.

L2 Agent (OVS Agent)

neutron-openvswitch-agent runs on every compute node and network node. Responsibilities:

  • Programs OVS flow rules on br-int and br-tun in response to RPC from neutron-server
  • Manages tunnel endpoints (VTEP) for VXLAN/GRE
  • Handles port binding confirmation
  • Reports agent state (heartbeat) to neutron-server every report_interval seconds (default 30 s)
  • Implements security group rules as OVS flows (OVS firewall driver) or iptables (hybrid driver)

In ML2/OVN deployments the OVS agent is replaced by ovn-controller (see ovn.md).

L3 Agent

neutron-l3-agent runs on dedicated network nodes (or on compute nodes in DVR mode). Responsibilities:

  • Creates Linux network namespaces (qrouter-<uuid>) for each virtual router
  • Configures IP addresses, routing tables, iptables NAT rules inside the namespace
  • Implements SNAT for floating IPs and for instances without floating IPs (centralized SNAT)
  • In HA mode: runs keepalived/VRRP inside the namespace for failover between L3 agent nodes
  • In DVR mode: each compute node hosts a partial router namespace for east-west traffic; only SNAT remains centralized

DHCP Agent

neutron-dhcp-agent runs on network nodes. Responsibilities:

  • Spawns one dnsmasq process per network that has DHCP enabled
  • Each dnsmasq process runs in a Linux network namespace (qdhcp-<uuid>)
  • Passes host/DHCP entries to dnsmasq via a hosts file and opts file
  • Supports HA: multiple DHCP agents can be scheduled to the same network; all serve DHCP simultaneously (active-active)

Metadata Agent

neutron-metadata-agent runs on network nodes (and on compute nodes in DVR mode). Responsibilities:

  • Provides a proxy for the Nova metadata API (http://169.254.169.254)
  • Instances send HTTP to 169.254.169.254; the request enters the router or DHCP namespace, is forwarded to the metadata agent, which adds X-Forwarded-For and X-Neutron-Network-Id headers and proxies to http://<nova-api>:8775/openstack/
  • In OVN deployments a dedicated neutron-ovn-metadata-agent handles this using OVN port binding extensions (see ovn.md)

Network Types

Provider Networks

Provider networks map directly to physical network infrastructure the operator controls. They are typically used for:

  • External/floating IP networks (mapped to an uplink VLAN or untagged interface)
  • Networks shared to tenants that need direct physical access

Key attributes:

--provider-physical-network  physnet1       # maps to bridge_mappings in agent config
--provider-network-type      flat|vlan|...
--provider-segment           200            # VLAN ID (for vlan type)

Provider networks can be --external (used as router gateways / floating IP pools) or shared with --share.

Tenant / Project Networks

Tenant networks are created by end users. They are isolated by VXLAN VNI, GRE key, or GENEVE VNI and live entirely in the overlay. Traffic leaves the overlay only when:

  1. It passes through a virtual router with an external gateway (SNAT/floating IP)
  2. It is destined for another tenant network behind the same router (east-west)

Core Resource Model

Network  (L2 domain)
 └── Subnet  (IP range, gateway, DHCP pool, DNS, routes)
      └── Port  (attachment point; has MAC, one or more fixed IPs)
           └── Bound to: instance, router interface, DHCP tap, load balancer, etc.

Router  (L3 gateway)
 ├── Router interfaces (connect subnets to the router)
 └── External gateway (connects router to provider network)

Floating IP  (1:1 NAT mapping)
 ├── External IP (from provider subnet)
 └── Fixed IP (on a port attached to an instance)

Security Group  (stateful firewall)
 └── Security Group Rules (ingress/egress, protocol, port range, CIDR or remote SG)

Port States and Binding

A port moves through these states:

Status Meaning
DOWN Port created but not bound to a host
BUILD Nova has requested binding; agent is programming the dataplane
ACTIVE Port is fully bound and dataplane is configured
ERROR Binding failed

The binding:vif_type indicates what interface type Nova should plumb (e.g., ovs, vhostuser, hw_veb for SR-IOV).

Extension Framework

Neutron's API is extensible via:

  1. API extensions — add new resources or extend existing ones (e.g., router, security-group, floating-ips, port-security, dns-integration)
  2. Service plugins — loaded at startup, implement entire feature areas with their own DB tables and agents (e.g., router / L3, qos, trunk, segments, bgp, vpnaas, lbaas)

Extensions are discovered from entry points. List loaded extensions:

openstack extension list --network

Nova Integration — Port Binding During Instance Boot

When Nova boots an instance that requests a Neutron port:

  1. Nova calls POST /v2.0/ports (or uses a pre-created port) with binding:host_id set to the compute node hostname
  2. Neutron ML2 iterates mechanism drivers calling bind_port() in order
  3. The winning mechanism driver sets binding:vif_type and binding:vif_details
  4. Nova reads vif_type to determine how to attach the guest NIC (tap, vhostuser, etc.)
  5. The L2 agent on that compute node receives an RPC port_update and programs OVS flows
  6. The agent calls back with update_device_up to set port status to ACTIVE
  7. Nova is notified via the network-changed server event and the instance network is ready

In OVN deployments steps 5-6 are handled by ovn-controller writing directly to the OVN southbound DB; no Neutron RPC round-trip to an agent is needed.