Skip to content
StratumStratum Docs

Read the OVN substrate topology as a graph.

GET
/v1/admin/network/ovn/topology
Code sample: Shell / cURL
curl --request GET \
  --url 'https://stratum.example.com/v1/admin/network/ovn/topology?includeSouthbound=false&includeOvs=false' \
  --header 'Authorization: Bearer <token>'

Install-scope admin endpoint (network:GetOvnTopology, bootstrap-admin only) returning a structured graph of the OVN substrate as the controlplane sees it via the NB DB.

Each Stratum resource (VPC, subnet, NIC, security group, floating IP, NAT gateway) appears as a typed node; the relationships between them (belongsTo, attachedTo, applies, associates) are typed edges. A special implicitSnat node surfaces the implicit-SNAT-via-IGW row installs per IGW-enabled VPC — the substrate-level proof of the AWS-vs-Stratum delta documented in [docs/operator/09-reference/aws-semantic-deltas.md].

Correlation back to Stratum IDs is via the external_ids column the OVN driver stamps on every NB row (stratum-vpc-id, stratum-subnet-id, stratum-nic-id, stratum-fip-id, stratum-natgw-id, stratum-igw-vpc-id); rows without a Stratum tag are silently skipped.

(slice 1) wired NB DB. (slice 2) wires the SB DB read-side (includeSouthbound=true adds chassis nodes + boundTo edges from Port_Binding) and a local OVS shell-out (includeOvs=true attaches ovs-vsctl show + ovs-ofctl dump-flows br-int to the local chassis node). At v1 there’s one chassis; multi-chassis fan-out is.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
vpcId
string
/^vpc-[a-z0-9-]+$/

When set, restricts the response to a single VPC’s subgraph (the VPC + its subnets, NICs, SGs, FIPs, NAT gateways, and the implicit-SNAT node).

chassisId
string

When set, restricts the SB DB pass to ports + chassis matching the given OVN chassis name. No effect on the NB DB pass (logical-topology nodes have no per-chassis affinity at v1)..

includeSouthbound
boolean

When true, queries the OVN Southbound DB. Adds chassis nodes (one per registered hypervisor) + boundTo edges (NIC → chassis) from Port_Binding. Populates raw.ovnSb row counts..

includeOvs
boolean

When true, runs ovs-vsctl show + ovs-ofctl dump-flows br-int on the local host and attaches the summary (bridges + port counts + flow count) to the corresponding chassis node’s attributes. At v1 the controlplane and OVS run on the same host, so this is a single local shell-out; multi-chassis fan-out is ..

Responses

Section titled “Responses”

200

Section titled “200”

The OVN topology graph snapshot.

Media typeapplication/json

graph snapshot of the OVN substrate. Stable shape: the future web UI admin panel keys per-kind renderers on the node/edge kind enums, so adding a value is a SemVer-relevant change.

object
nodes
required
Array<object>
object
id
required

For Stratum-resource nodes (vpc/subnet/nic/securityGroup/ floatingIp/natGateway) this is the Stratum resource ID. For implicitSnat nodes the ID format is implicit-snat-<vpcId>. For chassis (slice 2) the chassis ID from the SB DB.

string
kind
required
string
Allowed values: vpc subnet nic securityGroup floatingIp natGateway implicitSnat chassis
name

Human-readable label (resource name or address).

string
attributes

Per-kind free-form attributes. Common keys:

  • vpcId, subnetId, projectId — owner / parent IDs.
  • address, privateIp, transitIp, sourceCidr IP-bearing attributes (FIPs / implicit-SNAT).
  • aclCount — number of ACLs attached (securityGroup).
  • ovnNatType — NAT row type (snat / dnat_and_snat).

adds the OVN-side names so a Stratum resource + its OVN object can be correlated at a glance:

  • ovnLogicalRouter (vpc, natGateway) — NB Logical_Router.name.
  • ovnLogicalSwitch (subnet) — NB Logical_Switch.name.
  • ovnLspName (nic, floatingIp, natGateway) — NB Logical_Switch_Port.name (the NIC LSP is a UUIDv5 derived from the NIC ID).
  • ovnPortGroup (securityGroup) — NB Port_Group.name.

All ovn* keys are stable strings the UI can render unconditionally as “Stratum name + OVN name.”

object
key
additional properties
any
edges
required
Array<object>
object
from
required
string
to
required
string
kind
required
string
Allowed values: belongsTo attachedTo applies associates appliesAt boundTo datapathOn
raw
required
object
ovnNb
required
object
logicalSwitches
required
integer
logicalRouters
required
integer
nat
required
integer
portGroups
required
integer
acls
required
integer
ovnSb
required

SB DB row counts. Zeroed when the caller didn’t set includeSouthbound=true or when no SB querier is wired. .

object
chassis
required
integer
portBindings
required
integer
datapathBindings
required
integer
diagnostics
required

Non-fatal signal: empty-graph reason, runtime read failures, options that aren’t yet implemented in this slice. Empty object when nothing’s notable.

object
warning

Set when the whole snapshot is empty for a known reason (no NB querier wired, etc.). Singular by intent — one reason, not several.

string
warnings

Runtime read failures where the graph is still useful but a slice is missing (e.g. SB DB read failed, OVS shell-out timed out)..

Array<string>
notImplemented

Options the caller set that aren’t honored on this install (e.g. includeOvs=true with no OVS querier wired).

Array<string>

Example 

{
  "nodes": [
    {
      "kind": "vpc"
    }
  ],
  "edges": [
    {
      "kind": "belongsTo"
    }
  ]
}

403

Section titled “403”

Authenticated but not authorized.

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
>= 400 <= 599
detail
string
instance
string format: uri-reference
requestId
required
string
code
required
string
issues

The findings of a rejected IAM policy document (custom and resource policies).

Array<object>

One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.

object
code
required

The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.

string
statement
required

Index of the statement at fault; -1 for the document as a whole.

integer
>= -1
detail
required
string
action

The offending action, where one is at fault (ACTION_NOT_APPLICABLE).

string
errors

Field errors, for codes that carry them: each problem at its field (see FieldError). Documented on the responses that set it, e.g. approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED. Absent otherwise.

Array<object>

One field’s problem, the stage-2 installer API’s shape. field is the field’s path, message what is wrong with it.

object
field
required

The field’s path, e.g. links[0].interface, disks[1].confirm, mgmt.address or role; empty for the whole request.

string
message
required
string
details

Structured facts about the refusal, for codes that carry them. The shape is fixed per code and documented on the response that answers it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and IMAGE_IN_USE. Absent for codes that carry none.

object
key
additional properties
any

Example 

{
  "issues": [
    {
      "code": "ACTION_NOT_APPLICABLE",
      "action": "compute:CreateVpc"
    }
  ]
}