Skip to main content

Concepts

This page explains the core ideas behind KubeNDT. They map directly onto the API Reference, so understanding them makes the endpoints self-explanatory.

Topology​

A topology is a declarative JSON description of a virtual network:

  • Nodes - each node is a container image (a host, router, switch, or any image you like) deployed as a Kubernetes StatefulSet, optionally with multiple replicas.
  • Links - point-to-point connections between node interfaces, realized as L2/L3 overlays via the Meshnet CNI.

An abbreviated topology looks like this:

{
  "nodes": [
    {"name": "pc", "image": "alpine", "type": "host", "replicas": 4},
    {"name": "r1", "image": "frrouting/frr", "type": "router"}
  ],
  "links": [
    {
      "node": "pc-0", "localIntf": "eth1", "localIp": "10.0.1.11/24",
      "peerNode": "r1-0", "peerIntf": "eth1"
    }
  ]
}

See the reference topologies for complete, runnable examples.

Topologies are reproducible: you can save and re-import the JSON to recreate the exact same network.

Namespaces​

Every topology lives in a Kubernetes namespace labelled kubendt/enabled=true. Namespaces provide isolation: you can run multiple independent topologies side by side, each with its own nodes, links, and configuration. The API exposes namespace lifecycle (create / list / delete) and an aggregated operational summary per namespace.

Drivers and capabilities​

KubeNDT abstracts network configuration behind a driver and capability system. Instead of issuing image-specific commands, you declare what you want (assign this IP, add this route, enable OSPF, set up NAT…) and the driver for that node type translates it into the right commands.

  • A driver knows how to operate a particular node type (e.g. a plain Linux host, an FRRouting router, or a VyOS appliance).
  • A capability is a declarative action a driver supports (L2 interface ops, L3 addressing/routing, routing protocols, traffic control, NAT…).

This is why the same network/configure request works across heterogeneous nodes - the declarative intent is constant; the driver fills in the details.

Configuration and persistence​

Operations applied through the configuration API are persisted per pod and replayed after a restart or reconcile, so your network state survives pod churn.

note

Manual changes made directly inside a pod (ad-hoc shell commands not sent through the KubeNDT API) are intentionally not tracked for replay. Persist state by applying changes through the API, mounted config files, or startup scripts.

Authentication​

The dashboard and API are gated by a password login (which opens a browser session) plus revocable API tokens for scripts and CI. Auth can be disabled on trusted networks. See Getting started to set it up.

The dashboard and the API​

Everything you can do in the React dashboard is backed by the REST API. The dashboard is one client; your scripts and CI can be another. The API Reference documents every endpoint, grouped by area:

auth · cluster · namespaces · pods · network · drivers · files · shell · capture · trace · kubeconfig · system