Skip to main content
Version: 5.2

Restoring NeuVector Configuration

Restoring NeuVector Configuration​

You can restore a previous NeuVector configuration by applying a configuration backup file. You can generate the backup manually or export it from the NeuVector console by navigating to Settings > Configuration and selecting one of the following options:

  • All configuration – Includes registry configurations, integrations, system settings, and policy.
  • Policy only – Includes rules and security policy.

You can also automate backups by using the REST API. For an example, see Export and import configuration files.

If all controllers stop running and real-time configuration state is lost, NeuVector can automatically restore configuration when persistent storage is properly configured.

Security advisory

Starting with NeuVector v5.4.7, sensitive configuration data is encrypted using a Kubernetes Secret named neuvector-store-secret in the neuvector namespace.

Versions 5.3.0 through 5.4.6 used a fixed, hard-coded encryption key. During an upgrade or restore, NeuVector automatically detects data encrypted with the legacy key and re-encrypts it using a new key derived from neuvector-store-secret.

Always upgrade to v5.4.7 or later before restoring configuration data.

For details, refer to the security advisory:
https://github.com/neuvector/neuvector/security/advisories/GHSA-h773-7gf7-9m2x

note

NeuVector does not support partial restores (for example, restoring only network rules) or point-in-time restores. Use automation scripts to regularly back up configuration files and manage timestamped backups. For more information, see Export and import configuration files.

important

Do not modify backup configuration files. Editing a backup file after export can cause restore failures or result in an unpredictable system state.

caution

Use backup configuration files only to restore NeuVector on the same cluster from which they were exported. Restoring a backup to a different cluster may result in unpredictable behavior.

Encryption key management​

The neuvector-store-secret contains the Key Encryption Key (KEK). NeuVector uses the KEK to generate Data Encryption Keys (DEKs) that encrypt sensitive configuration data.

Key behavior:

  • You must maintain and back up the neuvector-store-secret.
  • If the secret is missing or the key value does not meet length requirements, NeuVector automatically creates or updates it.
  • When NeuVector creates or updates the secret, it generates an alert reminding you to back it up.
  • If the KEK changes or is lost, previously encrypted data cannot be decrypted.

During rolling upgrades or restores:

  1. Data encrypted with the legacy hard-coded key is re-encrypted using a DEK derived from the KEK.
  2. Data encrypted using a DEK derived from the KEK can be decrypted only by NeuVector using the same KEK.

Rolling upgrade event

If re-encryption occurs, NeuVector records the action and generates an event.

Sensitive data protected by encryption​

NeuVector encrypts sensitive data stored under the following key-value paths:

  • object/config/server/ldap1
  • object/config/server/oidc1
  • object/config/server/saml1
  • object/config/system
  • object/config/registry
  • object/config/federation/membership
  • object/config/federation/clusters/...
  • object/cert/...

Neuvector store secret

Backup and restore requirement

Always back up the neuvector-store-secret together with NeuVector configuration data.

When restoring NeuVector to a new cluster or after data loss, you must restore the same secret. Configuration backups without the corresponding secret cannot be decrypted.

Manual backup and restore of configuration should be planned only as a last resort. The following steps are recommended for high availability.

  1. Use Helm with a ConfigMap for initial deployment and configuration.
  2. Use CRDs for defining policy such as network/process, admission control, and other rules.
  3. Run multiple controllers (minimum 3) to auto-sync configuration between running pods, and ensure they run on different hosts.
  4. Configure persistent storage (as part of step 1) to recover from any cluster wide failures where all controllers stop running.
  5. Regularly backup configuration to timestamped backup files.
  6. Restore a cluster's NeuVector configuration from a backup file as a last resort, applying any CRDs after restoration that were new or changed since the previous backup.