Skip to main content

​
Overview

Polystack Networking distributes work across multiple agents running on compute and network nodes. Monitoring agent health is a core administrative responsibility — a downed agent can silently prevent new port bindings, DHCP assignments, or routing updates. This guide covers how to inspect, manage, and recover agents across your cluster.
Administrator Access Required — This operation requires the admin role. Contact your Polystack administrator if you do not have sufficient permissions.
Prerequisites
  • Admin credentials sourced from openrc.sh
  • openstack CLI installed and configured

​
Inspect Agent Health

Navigate to Network Agents

Navigate to Network > Network Agents (admin view).

Review agent status

Each row represents one agent instance. Review the following columns:

​
Enable and Disable Agents

Disable an agent before performing maintenance on its host to prevent the scheduler from assigning new work to it. Re-enable after maintenance completes.
Disable agent for maintenance
Re-enable agent after maintenance
Disabling an L3 or DHCP agent causes affected routers and subnets to lose that agent’s services. Ensure redundant agents are running before disabling any agent. Verify with openstack network agent list that at least one healthy agent of the same type remains.

​
Agent Type Reference

​
Restart an Agent

When an agent shows Alive: False, restart the service on the affected host. Agents running inside Docker containers are managed by the deployment console:
Restart networking agents via the deployment console
After restarting, allow up to 30 seconds for the agent to re-register and send a heartbeat. Verify recovery:
Confirm agent is alive
Agent shows Alive: True and a recent heartbeat timestamp.

​
Next Steps

DHCP Configuration

Schedule networks to DHCP agents and configure HA for high availability

L3 Router Configuration

Configure HA and distributed routing across L3 agents

Service Architecture

Understand the distributed agent model and message bus communication

Admin Troubleshooting

Diagnose and resolve agent failures and VXLAN connectivity issues