Neuwerk

Single Node

Run one Neuwerk node with local control-plane state and no cluster replication.

Use this guide when you want the smallest supported deployment shape.

Read Requirements first if you need the runtime assumptions around the image, DPDK linkage, capabilities, or custom binary deployment.

Single-node mode means:

  • one Neuwerk process
  • no cluster replication
  • local control-plane state on disk
  • the normal split between control plane and dataplane

Even in this smallest shape, the node still runs both the management and enforcement parts of the system.

Required Inputs

A single-node deployment requires:

  • --management-interface
  • --data-plane-interface
  • at least one --dns-target-ip
  • at least one --dns-upstream

Important constraints:

  • the management and data-plane interfaces must be different
  • the management interface must have an IPv4 address

Default Listener Layout

Unless you override it, a single node listens on:

  • <management-ip>:8443 for the web UI and management API
  • <management-ip>:8080 for metrics
  • <management-ip>:53 for the DNS proxy

Cluster listeners are not started in this mode.

Example Startup Shape

neuwerk \
  --management-interface mgmt0 \
  --data-plane-interface data0 \
  --dns-target-ip 10.0.0.53 \
  --dns-upstream 1.1.1.1:53

Common optional overrides include:

  • --data-plane-mode tun|tap|dpdk
  • --internal-cidr <cidr>
  • --snat none|auto|<ipv4>
  • --http-bind <ip:port>
  • --metrics-bind <ip:port>
  • --http-tls-dir <path>

Persistent State

By default, local control-plane state lives under:

/var/lib/neuwerk

That root contains local policy state, service-account data, integrations, audit data, management TLS material, and node identity files.

If you need to preserve a node completely, back up the whole local data root rather than only the policy files.

Health Checks

After startup, verify:

GET /health
GET /metrics
GET /ready
GET /api/v1/stats

A healthy single node becomes ready only after the dataplane, policy state, DNS proxy, and service plane are all ready.

When To Use This Shape

Single-node mode is the right fit when you want:

  • one-node deployments
  • local-only control-plane state
  • a simpler operational model than cluster mode

If you need replicated control-plane state or leader-aware management, move to High Availability.