Restoring CubeSandbox Configuration from a Backup: Complete Disaster Recovery Guide

To restore CubeSandbox from a backup, extract your archive to a temporary directory, copy the YAML files to configs/single-node/, import the MySQL dumps into the ossdb_config and instance_db_config databases, optionally restore the Redis RDB snapshot, and restart the CubeMaster and Cubelet services.

Restoring CubeSandbox configuration from a backup requires handling three distinct persistence layers: static YAML files in configs/single-node/, MySQL databases for runtime metadata, and optional Redis snapshots for metric caches. The TencentCloud/CubeSandbox repository structures its operational state across these components, necessitating a coordinated restoration process to recover from hardware failures or migrate to new infrastructure. This guide provides the exact commands and file paths required to execute a complete disaster recovery based on the source code implementation.

What Your Backup Archive Must Contain

A complete CubeSandbox backup consists of four critical components. Verify your archive includes these before beginning restoration:

• Static YAML configurations – cubemaster.yaml, cubelet.yaml, and network-agent.yaml from configs/single-node/. These define HTTP ports, gRPC timeouts, resource limits, and database connection strings.
• Environment overrides – The optional .env file containing custom ports, feature toggles (WEB_UI_ENABLE), and credentials.
• MySQL dumps – SQL exports of the ossdb_config database (template snapshots and sandbox metadata) and instance_db_config database (runtime state and resource allocation tables).
• Redis RDB snapshot – Optional binary dump of the Redis data directory for point-in-time metric recovery.

Step-by-Step Restoration Process

1. Prepare the Restoration Environment

Create a temporary directory and extract your backup archive:

mkdir -p /restore/cubesandbox
tar -xzf cubesandbox-backup-YYYY-MM-DD.tar.gz -C /restore/cubesandbox

Verify the extracted structure contains config/, mysql/, and optionally redis/ subdirectories.

2. Restore Static Configuration Files

Copy the three core YAML files to their original location in the repository:

cp /restore/cubesandbox/config/cubemaster.yaml configs/single-node/
cp /restore/cubesandbox/config/cubelet.yaml configs/single-node/
cp /restore/cubesandbox/config/network-agent.yaml configs/single-node/

If your backup includes a custom .env file, restore it to the repository root to preserve runtime overrides:

cp /restore/cubesandbox/config/.env .

These files reference one another via the configs/single-node/ path as implemented in the CubeMaster initialization logic.

3. Import MySQL Databases

Extract the database credentials from the restored cubemaster.yaml to avoid manual entry:

MYSQL_USER=$(grep -A1 'ossdb_config' configs/single-node/cubemaster.yaml | grep 'user' | head -1 | cut -d':' -f2 | tr -d ' "')
MYSQL_PASS=$(grep -A1 'ossdb_config' configs/single-node/cubemaster.yaml | grep 'pwd' | head -1 | cut -d':' -f2 | tr -d ' "')
DB_OSS=$(grep -A1 'ossdb_config' configs/single-node/cubemaster.yaml | grep 'db_name' | head -1 | cut -d':' -f2 | tr -d ' "')
DB_INSTANCE=$(grep -A1 'instance_db_config' configs/single-node/cubemaster.yaml | grep 'db_name' | head -1 | cut -d':' -f2 | tr -d ' "')

Import the ossdb_config database (stores template snapshots and credential vault data):

mysql -u"$MYSQL_USER" -p"$MYSQL_PASS" "$DB_OSS" < /restore/cubesandbox/mysql/ossdb.sql

Import the instance_db_config database (holds per-instance runtime state):

mysql -u"$MYSQL_USER" -p"$MYSQL_PASS" "$DB_INSTANCE" < /restore/cubesandbox/mysql/instance.sql

4. Restore Redis State (Optional)

If your backup includes a Redis RDB snapshot, stop the Redis service, replace the data file, and restart:

# Stop the Redis container or service

sudo systemctl stop cube-sandbox-redis

# Replace the RDB file (adjust path for your installation)

sudo cp /restore/cubesandbox/redis/dump.rdb /var/lib/redis/dump.rdb
sudo chown redis:redis /var/lib/redis/dump.rdb

# Restart Redis

sudo systemctl start cube-sandbox-redis

Redis stores node-metric keys and sandbox-proxy routing information. While the system can rebuild these metrics on restart, restoring the RDB preserves historical data and routing tables.

5. Restart CubeSandbox Services

With configurations and databases restored, restart the services using the systemd units defined in CubeMaster/scripts/:

sudo systemctl restart cube-sandbox-cubemaster
sudo systemctl restart cube-sandbox-cubelet
sudo systemctl restart cube-sandbox-network-agent

For Docker-based deployments, restart the composition:

docker-compose down
docker-compose up -d

Automated Restoration Script

Below is a complete bash script that automates the restoration process assuming your backup is extracted to /restore/cubesandbox:

#!/usr/bin/env bash
set -euo pipefail

RESTORE_DIR=/restore/cubesandbox
CONFIG_DIR=configs/single-node

# 1. Restore YAML configs

cp "$RESTORE_DIR"/config/*.yaml "$CONFIG_DIR/"

# 2. Restore .env if present

[[ -f "$RESTORE_DIR"/config/.env ]] && cp "$RESTORE_DIR"/config/.env .

# 3. Extract credentials and restore MySQL

MYSQL_USER=$(grep -A1 'ossdb_config' "$CONFIG_DIR"/cubemaster.yaml | grep 'user' | head -1 | cut -d':' -f2 | tr -d ' "')
MYSQL_PASS=$(grep -A1 'ossdb_config' "$CONFIG_DIR"/cubemaster.yaml | grep 'pwd' | head -1 | cut -d':' -f2 | tr -d ' "')
DB_OSS=$(grep -A1 'ossdb_config' "$CONFIG_DIR"/cubemaster.yaml | grep 'db_name' | head -1 | cut -d':' -f2 | tr -d ' "')
DB_INSTANCE=$(grep -A1 'instance_db_config' "$CONFIG_DIR"/cubemaster.yaml | grep 'db_name' | head -1 | cut -d':' -f2 | tr -d ' "')

mysql -u"$MYSQL_USER" -p"$MYSQL_PASS" "$DB_OSS" < "$RESTORE_DIR"/mysql/ossdb.sql
mysql -u"$MYSQL_USER" -p"$MYSQL_PASS" "$DB_INSTANCE" < "$RESTORE_DIR"/mysql/instance.sql

# 4. Restore Redis (optional)

if [[ -f "$RESTORE_DIR"/redis/dump.rdb ]]; then
    REDIS_DATA_DIR=$(grep -A1 'redis:' "$CONFIG_DIR"/cubemaster.yaml | grep 'data_dir' | head -1 | cut -d':' -f2 | tr -d ' "' || echo "/var/lib/redis")
    sudo cp "$RESTORE_DIR"/redis/dump.rdb "$REDIS_DATA_DIR/"
fi

# 5. Restart services

sudo systemctl restart cube-sandbox-cubemaster cube-sandbox-cubelet

Summary

Restoring CubeSandbox configuration from a backup involves coordinated recovery across multiple persistence layers:

• Static configuration is restored by copying cubemaster.yaml, cubelet.yaml, and network-agent.yaml to configs/single-node/.
• Runtime state is recovered by importing MySQL dumps into ossdb_config and instance_db_config using credentials extracted from the restored YAML files.
• Environment overrides are preserved by restoring the .env file to the repository root.
• Metric data can be optionally recovered by replacing the Redis dump.rdb file before restarting services.

Frequently Asked Questions

How do I restore CubeSandbox to a new host?

Restoring to a new host requires installing the CubeSandbox binaries or Docker images first, then extracting your backup to a temporary directory. Copy the YAML files to the same relative path (configs/single-node/), ensure the MySQL and Redis endpoints are accessible from the new host, and execute the import commands. Update the .env file if the new host uses different service endpoints or credentials.

Can I restore only the YAML configuration without the databases?

You can restore only the static YAML files, but the system will fail to start or will initialize with empty state if the MySQL databases are missing. The ossdb_config database contains essential template definitions and authentication data referenced by CubeMaster at startup. Without it, the service will lose all sandbox definitions and user credentials.

What happens if I skip the Redis snapshot restoration?

Skipping Redis restoration is safe for functional recovery. The Redis cache stores node-metric keys and sandbox-proxy routing information as implemented in the storage layer. If omitted, CubeSandbox will rebuild these entries automatically as nodes re-register and new metrics are collected, though historical metric data will be lost.

How do I verify the restoration was successful?

Verify restoration by checking the MySQL database tables contain expected row counts, ensuring the CubeMaster service responds on its configured HTTP port (default defined in cubemaster.yaml), and confirming the Web UI loads if WEB_UI_ENABLE is set. Check the Cubelet logs to verify reconnection to the restored CubeMaster instance.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}