Neuwerk

Backup & Restore

Back up the full control-plane state, and restore cluster state together with node identity and secret material.

Neuwerk does not currently ship a dedicated backup or restore command. Recovery planning is based on the state that the Neuwerk persists.

What Must Be Preserved

The control plane persists more than just policy:

  • policy records and active policy selection
  • service accounts and auth material
  • integrations
  • SSO configuration
  • audit history
  • management HTTPS material
  • TLS intercept CA material
  • cluster state and cluster TLS material
  • node identity and bootstrap token files

If you back up only policy, you will not preserve full operational continuity.

Single-Node Backup Scope

In single-node mode, the authoritative control-plane state is local. Back up the full local data root:

/var/lib/neuwerk

If you use NEUWERK_LOCAL_DATA_DIR, back up that override path instead.

Cluster Backup Scope

In cluster mode, think in two layers:

  1. replicated cluster state
  2. per-node identity and recovery material

At minimum, preserve:

  • the cluster data store
  • cluster TLS material
  • node_id
  • bootstrap-token

The simplest operational rule is to back up the entire Neuwerk data root on every node and keep those backups labeled by node and timestamp.

Restore Guidance

For single-node recovery:

  1. restore the full local data root
  2. preserve file ownership and secret-file permissions
  3. restart the node
  4. verify /ready and /api/v1/stats

For cluster recovery:

  1. restore cluster state together with the matching node identity and bootstrap-token material
  2. avoid mixing files from different backup points unless you are prepared to repair secret state
  3. restart the nodes
  4. verify leader health and policy replication

What Not To Treat As A Backup

Sysdump is for diagnostics, not recovery. Sensitive files are redacted or omitted, so sysdump archives are not sufficient for disaster recovery.

Warning

The biggest restore risk is mismatched secret material. If restored cluster state depends on keys or bootstrap-token data that you did not restore, the node may start but fail to read protected records correctly.