How to Backup CubeSandbox Configuration: Complete Guide for TencentCloud/CubeSandbox

To backup CubeSandbox configuration, copy the three YAML config files from configs/single-node/, preserve the .env file, export the MySQL databases (ossdb_config and instance_db_config) using mysqldump, and optionally snapshot Redis with redis-cli --rdb.

CubeSandbox is an open-source sandbox environment maintained by TencentCloud that stores its operational settings across YAML files, environment variables, and persistent data stores. A complete backup strategy must capture static service parameters, runtime overrides, and database state to ensure a full recovery. Below is the authoritative breakdown of where configuration lives and how to archive it correctly.

Where CubeSandbox Stores Configuration

Understanding the three-tier storage architecture is essential before executing any backup commands.

Static YAML Configuration Files

The core service parameters reside in configs/single-node/ within the repository. These files define ports, timeouts, feature flags, and database connections.

• configs/single-node/cubemaster.yaml: Master node settings including HTTP port, Cubelet gRPC endpoints, authentication, and connections to ossdb_config and instance_db_config.
• configs/single-node/cubelet.yaml: Worker-node defaults for resource limits, isolation flags, and sandbox idle TTL.
• configs/single-node/network-agent.yaml: Network-policy parameters and egress control rules.

Environment Variable Overrides (.env)

Runtime overrides and secrets are managed via a hidden .env file (or the equivalent Docker Compose environment block). This file typically contains:

• WEB_UI_ENABLE and WEB_UI_HOST_PORT toggles
• CUBE_SANDBOX_MYSQL_USER and CUBE_SANDBOX_MYSQL_PASSWORD credentials
• External service endpoints

MySQL Databases (Runtime State)

According to the cubemaster.yaml source, CubeSandbox references two logical MySQL databases:

• ossdb_config: Stores template snapshots, sandbox metadata, and credential vault data.
• instance_db_config: Holds per-instance runtime state and resource allocation tables.

Redis Cache (Optional)

Redis maintains node-metric keys and sandbox-proxy routing information. While the system can rebuild metric data on restart, capturing a point-in-time RDB snapshot ensures complete state preservation.

Step-by-Step Backup Procedure

Execute these steps on the host running CubeSandbox to create a portable archive.

Step 1: Archive the YAML Files

Create a backup directory and copy the static configurations:

mkdir -p /backup/cubesandbox/config

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

Step 2: Preserve Environment Variables

If you maintain a custom .env file, secure it alongside the YAMLs:

if [ -f .env ]; then
    cp .env /backup/cubesandbox/config/
fi

Security note: Never commit backups containing passwords to version control. Store the .env backup in a secure location.

Step 3: Export MySQL Databases

Extract credentials from cubemaster.yaml or your .env file, then dump both databases:

# Set variables (replace with actual values from your config)

MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=cube
MYSQL_PASS=your_secure_password

mkdir -p /backup/cubesandbox/mysql

# Export ossdb_config

mysqldump -h $MYSQL_HOST -P $MYSQL_PORT -u $MYSQL_USER -p"$MYSQL_PASS" \
    ossdb_config > /backup/cubesandbox/mysql/ossdb.sql

# Export instance_db_config

mysqldump -h $MYSQL_HOST -P $MYSQL_PORT -u $MYSQL_USER -p"$MYSQL_PASS" \
    instance_db_config > /backup/cubesandbox/mysql/instance.sql

Step 4: Snapshot Redis (Optional)

Capture the Redis RDB dump using the port specified in cubemaster.yaml (default is typically 6379):

mkdir -p /backup/cubesandbox/redis

redis-cli -h 127.0.0.1 -p 6379 --rdb /backup/cubesandbox/redis/dump.rdb

Step 5: Compress the Backup Archive

Bundle all components into a single compressed file:

tar -czvf cubesandbox-backup-$(date +%F).tar.gz \
    -C /backup/cubesandbox \
    config mysql redis

Automated Backup Script

For production environments, automate the workflow with this bash script that parses credentials directly from configs/single-node/cubemaster.yaml:

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

BACKUP_ROOT=/backup/cubesandbox
mkdir -p "$BACKUP_ROOT"/{config,mysql,redis}

# 1. Copy YAML configs

cp configs/single-node/*.yaml "$BACKUP_ROOT/config/"

# 2. Copy .env if present

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

# 3. Extract MySQL credentials from cubemaster.yaml and dump databases

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 ' "')

mysqldump -u"$MYSQL_USER" -p"$MYSQL_PASS" ossdb_config > "$BACKUP_ROOT/mysql/ossdb.sql"
mysqldump -u"$MYSQL_USER" -p"$MYSQL_PASS" instance_db_config > "$BACKUP_ROOT/mysql/instance.sql"

# 4. Snapshot Redis (optional)

REDIS_PORT=$(grep -A1 'redis:' configs/single-node/cubemaster.yaml | grep 'port' | head -1 | cut -d':' -f2 | tr -d ' "')
redis-cli -p "$REDIS_PORT" --rdb "$BACKUP_ROOT/redis/dump.rdb"

# 5. Create archive

tar -czvf "$BACKUP_ROOT/cubesandbox-backup-$(date +%F).tar.gz" -C "$BACKUP_ROOT" .

Restoring from a Backup

To restore a CubeSandbox deployment to a fresh host:

1. Extract the archive: tar -xzf cubesandbox-backup-YYYY-MM-DD.tar.gz -C /restore
2. Replace YAML files: Copy the three files from /restore/config/ to configs/single-node/ in your new installation.
3. Restore environment: Copy /restore/config/.env to the repository root if it exists.
4. Import databases: mysql -u<user> -p<pass> ossdb_config < /restore/mysql/ossdb.sql and repeat for instance_db_config.
5. Load Redis: Stop the Redis container, replace its dump.rdb with /restore/redis/dump.rdb, then restart.
6. Restart services: Reload systemd units (systemctl restart cube-sandbox-cubemaster.service) or rerun the Docker Compose deployment.

Summary

• Backup the three YAML files (cubemaster.yaml, cubelet.yaml, network-agent.yaml) from configs/single-node/ to preserve static service parameters.
• Preserve the .env file to retain runtime overrides and credentials.
• Export both MySQL databases (ossdb_config and instance_db_config) using mysqldump to capture runtime metadata and state.
• Optionally dump Redis with redis-cli --rdb for complete metric history preservation.
• Archive everything into a versioned tar.gz file for portable disaster recovery.

Frequently Asked Questions

What files are essential for a minimal CubeSandbox backup?

The absolute minimum requires the three YAML files in configs/single-node/ and the MySQL dumps for ossdb_config and instance_db_config. The .env file is essential only if you overrode default ports or credentials. Redis is optional unless you require historical metric data.

How do I find the MySQL credentials for mysqldump?

Credentials are defined in configs/single-node/cubemaster.yaml under the ossdb_config and instance_db_config sections. Look for the user, pwd, and db_name keys. Alternatively, check your .env file for CUBE_SANDBOX_MYSQL_USER and CUBE_SANDBOX_MYSQL_PASSWORD variables.

Is Redis data mandatory to backup?

No. According to the TencentCloud/CubeSandbox source code, Redis stores node-metric keys and sandbox-proxy routing information that the system can rebuild automatically on restart. However, backing up Redis ensures you retain point-in-time metric snapshots and avoids cold-start performance penalties.

Can I backup a multi-node CubeSandbox cluster the same way?

Yes, but you must repeat the YAML file backup for each node's configs/ directory (though the files are typically identical). MySQL and Redis are usually centralized services, so a single backup of those databases covers the entire cluster. Ensure you capture the .env file from each host if node-specific overrides exist.

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