V3.x Migration Guide

📦 Applicable: v2.8.0 → v3.0+ 📅 Updated: March 15, 2025 ⏱️ Est. Read Time: 8 min

ℹ️

Note: This guide applies to CyberVault Threat Detection Engine, Management Console, and CLI tools. Cloud-hosted instances are migrated automatically by our platform team.

Overview

CyberVault v3.x introduces a redesigned threat intelligence pipeline, zero-trust authentication enforcement, and a unified configuration schema. While backward compatibility is maintained for read operations, write endpoints, authentication flows, and configuration files require manual updates before upgrading.

This guide provides a structured, step-by-step migration path to ensure zero downtime and data integrity during the transition from v2.x to v3.x.

Prerequisites

CyberVault v2.8.0 or higher (downgrade not supported)
Node.js 18+ or Python 3.10+ (depending on SDK)
Administrative access to the CyberVault management cluster
Current configuration backup (cv-cli backup --full)
Maintenance window approved (recommended: 2-4 hours)

Breaking Changes

The following changes are non-negotiable in v3.x. Ensure your integration accounts for these before proceeding.

Component	v2.x Behavior	v3.x Change	Status
Authentication	API Key header `X-CV-Key`	JWT + OAuth 2.0 / mTLS required	Removed
Config Format	YAML `config.yaml`	JSON Schema `cv.config.json`	Deprecated
Threat API	`/v2/threats`	`/v3/intelligence/events`	New
TLS Enforcement	TLS 1.2/1.3	TLS 1.3 only	Enforced
CLI Tool	`cyber-vault`	`cv-cli`	Aliased

Migration Steps

Backup & Version Pinning

Create a full state backup and pin your current version to prevent automatic updates during migration.

Terminal

cv-cli backup --full --output /opt/cybervault/backups/pre-v3.tar.gz
cv-cli version pin 2.8.5
cv-cli status --verify-backup

Update Dependencies

Pull the v3.x package and resolve dependency conflicts. The CLI tool has been renamed to cv-cli.

Terminal

npm install @cybervault/sdk@3.0.0
pip install cyber-vault-sdk==3.0.0  # Python users
cv-cli update --channel stable

Schema Migration

Run the built-in migration command to convert your configuration and database schema. This is a read-only validation first, then applies changes.

Terminal

cv-cli migrate --dry-run
cv-cli migrate --apply --confirm

⚠️

Warning: Always run --dry-run first. If conflicts are detected, resolve them before executing --apply.

Configuration Updates

Update your configuration to match the new JSON schema format. Legacy YAML files will cause startup failures.

cv.config.json

{
  "$schema": "https://cybervault.io/schemas/v3/config.json",
  "auth": {
    "mode": "oauth2",
    "issuer": "https://auth.cybervault.io",
    "audience": "api.cybervault.io"
  },
  "threat_engine": {
    "tls_min_version": "1.3",
    "ingestion_batch_size": 500,
    "retention_days": 90
  }
}

Configuration Changes

The v3.x configuration system enforces strict JSON Schema validation. Key changes include:

Authentication: Legacy API keys are replaced by OAuth 2.0 client credentials or mTLS certificates.
TLS Enforcement: TLS 1.3 is now mandatory. Downgraded connections will be terminated immediately.
Threat Pipeline: Ingestion batching is now configurable. Default changed from 100 to 500 events/batch.
Logging: Structured JSON logging is enabled by default. Legacy plain-text logs are deprecated.

Testing & Validation

Before switching production traffic, validate the migration in a staging environment:

Run cv-cli health --verbose to verify service connectivity
Execute the integration test suite: cv-cli test --suite migration
Verify threat ingestion: cv-cli ingest --simulate --count 1000
Confirm auth flow: curl -H "Authorization: Bearer $TOKEN" https://api.cybervault.io/v3/intelligence/events

✅

Expected output: All checks pass, latency < 150ms, 0 auth failures, 100% event ingestion rate.

Rollback Procedure

If critical failures occur, revert to v2.x immediately:

Terminal

cv-cli stop
cv-cli restore --backup /opt/cybervault/backups/pre-v3.tar.gz
cv-cli version pin 2.8.5
cv-cli start

🚨

Important: Rollback does not revert threat database changes. Events ingested via v3.x will remain. Audit logs are preserved.

Support & Feedback

Encountering migration errors? Our Security Operations Center provides dedicated upgrade support:

Documentation: cybervault.io/docs/v3
Migration CLI: cv-cli support --ticket --type migration
Enterprise SLA: 15-minute response for priority support plans
Community: GitHub Discussions & Slack Channel

After successful migration, run cv-cli migrate --complete to register your instance and unlock v3.x features.