Neutron Architecture — Ports, Agents, and the Path to the Instance

The port is the object that matters

Networks and subnets are configuration. The port is the thing that exists per instance, has a lifecycle, and fails.

A port is a virtual network interface with an address, a security group, and — critically — a binding: a record of which host it is on and which mechanism driver is responsible for wiring it up. Most Neutron troubleshooting is reading a port’s binding fields and working out which stage did not complete.

| binding_host_id | compute-03 || binding_vif_type | ovs || binding_vnic_type | normal || status | ACTIVE || device_id | 6c1e… |

Two of those fields carry almost all the diagnostic weight:

• binding_vif_type — how the port is meant to be attached. ovs or similar means a mechanism driver accepted it. binding_failed means none did, and the instance will never get a network.
• status — ACTIVE means an agent has reported that it actually wired the port up. DOWN means it has not.

The agents, and what each one builds

  neutron-server        API, database, and the decision about which
       │                mechanism driver owns a port
       │  message bus
       ├──────────────► L2 agent (per compute host)
       │                builds the local switching: bridges, flows, VLAN tags
       │
       ├──────────────► DHCP agent
       │                serves addresses to instances on the network
       │
       ├──────────────► L3 agent
       │                routers, floating IPs, and the path outward
       │
       └──────────────► metadata agent
                        serves 169.254.169.254 so cloud-init can configure

The division is worth memorising because each agent’s failure has a distinct signature:

Agent stops	Existing instances	New instances
L2 agent on a host	Keep working — flows are already in place	Get a port that never goes ACTIVE
DHCP agent	Keep their leases until renewal	Boot with no address
L3 agent	Lose external connectivity and floating IPs	Same
Metadata agent	Unaffected	Boot, but cloud-init gets no data: no SSH keys, no hostname

Binding is a negotiation, and it can fail

When Nova needs a port on a host, neutron-server asks each configured mechanism driver in turn whether it can bind this port on this host with this vnic type. The first that accepts wins.

If none accepts, the port gets binding_vif_type: binding_failed, and this is a permanent state for that port — nothing retries it. The instance will sit in networking and then fail.

The causes are all configuration mismatches rather than transient faults:

• The L2 agent on that host is down, so the driver that would have accepted cannot confirm the host is manageable.
• The physical network name in the segment does not exist in that host’s bridge mappings. The network says physnet2, the host only maps physnet1.
• The vnic type is unsupported — a direct or macvtap port on a host without the hardware or driver for it.

# What the network segment requires$ openstack network show provider-net -c provider:physical_network| provider:physical_network | physnet2 |# What the host actually offers (on the compute host)$ grep bridge_mappings /etc/kolla/neutron-openvswitch-agent/openvswitch_agent.inibridge_mappings = physnet1:br-ex

That mismatch produces binding_failed every time, on that host only, for that network only — which is why it so often presents as “instances work except on the new hosts”.

Port DOWN with a successful binding is a different problem

A port that bound successfully but stays DOWN means neutron-server decided who should wire it and that agent never confirmed doing so.

That narrows the problem to exactly one place: the L2 agent on the binding host. Either it is not running, or it is running and not processing, or it cannot report back over the message bus.

openstack network agent list --host compute-03

What the metadata path actually costs when it breaks

The metadata service is the least understood component and produces the most misleading symptom. An instance with a working network, a correct address, and no metadata boots normally and is unreachable — because cloud-init never received the SSH key.

The symptom is “the instance has no network”. The reality is that the network is fine and one specific address on it is not answering. The distinguishing check is whether the instance got an address at all: DHCP working and metadata failing is the signature.

The diagnostic path for an instance with no network

1. Does the port exist and what is its status? openstack port list --device-id <instance-uuid>
2. Is binding_vif_type binding_failed? If so, it is configuration — check bridge mappings against the network’s physical network, and check the vnic type.
3. Is status DOWN with a successful binding? The L2 agent on binding_host_id is the whole problem.
4. Is the agent alive? openstack network agent list --host <host>. Dead agent with a live process means the message bus.
5. Did the instance get an address? No address is DHCP. Address but no cloud-init data is metadata.
6. Address but no external connectivity? L3 agent and floating IP, which is a different path entirely.

Steps 1 to 3 resolve the majority, and all three are answered by a single openstack port show.

Exercise

Create a port explicitly with openstack port create, and inspect its binding fields before it is attached to anything. Note that binding_host_id is empty and status is DOWN — an unattached port is not a broken port.

Boot an instance with that port and inspect it again. Record which fields changed and in what order.

Then stop the L2 agent on a compute host and boot an instance there. Observe how far the port gets, which field reveals the problem, and how long the instance spends in networking before Nova gives up. Compare that failure against an instance on a host with a deliberately wrong bridge mapping — the two look identical from the instance and are distinguished only by the port.