How to Configure CubeSandbox Using Environment Variables: Complete Component Guide

Yes, CubeSandbox supports full configuration via environment variables, allowing you to control every component—including CubeMaster, CubeProxy, Cubelet, the lifecycle manager, and the SDK—without modifying configuration files or recompiling code.

TencentCloud/CubeSandbox is a container sandbox platform designed for flexible deployment across diverse environments. Understanding CubeSandbox configuration through environment variables is essential for DevOps teams managing containerized workloads, as this approach eliminates dependencies on YAML parsers and enables seamless integration with CI/CD pipelines.

How CubeSandbox Configuration Works

The platform implements a flat mapping system where each environment variable corresponds directly to a field in the component's Config struct. This design pattern appears consistently across the codebase, from the lifecycle manager to the SDK clients, with each component reading its configuration at startup.

Lifecycle Manager (CLM) Configuration

The lifecycle manager reads configuration from environment variables that map 1-to-1 to its Config struct fields. The default values are defined in the Default() function, and each field can be overridden at runtime.

Key CLM Environment Variables

In cube-lifecycle-manager/internal/config/config.go, the loading logic implements direct environment variable reads:

• CUBE_LCM_REDIS_ADDR: Redis server address for state management
• CUBE_LCM_PROXY_ADMIN_URLS: Comma-separated list of CubeProxy admin endpoints
• CUBE_LCM_USE_STATIC_FLEET: Boolean flag to enable static fleet mode (set to 1 to enable)

SDK Client Configuration

The Go SDK retrieves settings from environment variables defined in sdk/go/config.go. The Load() function reads these variables at initialization and falls back to empty strings if not set.

Required SDK Environment Variables

• CUBE_TEMPLATE_ID: Template identifier for sandbox provisioning
• CUBE_PROXY_NODE_IP: IP address of the CubeProxy node
• CUBE_PROXY_SCHEME: Protocol scheme (http or https)
• CUBE_SANDBOX_DOMAIN: Domain name for sandbox endpoints

// sdk/go/config.go
type Config struct {
    TemplateID     string
    ProxyNodeIP    string
    ProxyScheme    string
    SandboxDomain  string
}

func Load() *Config {
    return &Config{
        TemplateID:    strings.TrimSpace(os.Getenv("CUBE_TEMPLATE_ID")),
        ProxyNodeIP:   strings.TrimSpace(os.Getenv("CUBE_PROXY_NODE_IP")),
        ProxyScheme:   strings.TrimSpace(os.Getenv("CUBE_PROXY_SCHEME")),
        SandboxDomain: strings.TrimSpace(os.Getenv("CUBE_SANDBOX_DOMAIN")),
    }
}

CubeProxy and Cubelet Network Settings

Additional components like CubeProxy and Cubelet rely on environment variables for network addresses and runtime flags. In Cubelet/pkg/networkagentclient/client.go, the system checks for CUBE_PROXY_ENABLE_HTTP_CLIENT to conditionally enable the HTTP client.

Other critical variables include:

• CUBE_MASTER_CONFIG_PATH: Path to master configuration files
• CUBE_SANDBOX_NODE_IP: Node IP address for sandbox networking

Deployment Examples

You can inject these variables through systemd EnvironmentFile, Docker -e flags, or Kubernetes ConfigMap mounts.

Bash Command Line

export CUBE_LCM_REDIS_ADDR=10.0.0.5:6379
export CUBE_LCM_USE_STATIC_FLEET=1
export CUBE_LCM_PROXY_ADMIN_URLS="http://127.0.0.1:8082"
export CUBE_TEMPLATE_ID=my-template
export CUBE_PROXY_SCHEME=https
export CUBE_SANDBOX_DOMAIN=sandbox.example.com

./cube-lifecycle-manager

Kubernetes ConfigMap

apiVersion: v1
kind: ConfigMap
metadata:
  name: cubesandbox-config
data:
  CUBE_LCM_REDIS_ADDR: "redis:6379"
  CUBE_LCM_USE_STATIC_FLEET: "1"
  CUBE_LCM_PROXY_ADMIN_URLS: "http://cube-proxy:8082"
  CUBE_TEMPLATE_ID: "my-template"
---
apiVersion: v1
kind: Pod
metadata:
  name: cubesandbox
spec:
  containers:
  - name: clm
    image: tencentcloud/cubesandbox:latest
    envFrom:
    - configMapRef:
        name: cubesandbox-config

Summary

• CubeSandbox configuration relies entirely on environment variables, eliminating the need for configuration files or runtime parsers.
• The lifecycle manager uses CUBE_LCM_* prefixed variables defined in cube-lifecycle-manager/internal/config/config.go.
• SDK clients require CUBE_TEMPLATE_ID, CUBE_PROXY_NODE_IP, and related variables loaded via sdk/go/config.go.
• CubeProxy supports boolean flags like CUBE_PROXY_ENABLE_HTTP_CLIENT for conditional feature enablement.
• All components read configuration at startup, supporting deployment via Docker, Kubernetes, or systemd without code changes.

Frequently Asked Questions

Can I mix environment variables with configuration files for CubeSandbox?

No, CubeSandbox is designed to be configured entirely through environment variables. While some components check for paths like CUBE_MASTER_CONFIG_PATH, the primary configuration mechanism relies on direct environment variable injection rather than traditional configuration file parsing.

What happens if I omit optional environment variables like CUBE_LCM_USE_STATIC_FLEET?

Optional variables fall back to their default values defined in the Default() function of each component's configuration package. For example, in cube-lifecycle-manager/internal/config/config.go, the Default() method provides safe defaults for all settings, ensuring the service starts even with minimal configuration.

How do I configure TLS certificates for CubeSandbox components?

TLS configuration is handled through environment variables that specify certificate paths and validation settings. Components like CubeMaster and Cubelet reference variables such as CUBE_MASTER_CONFIG_PATH to locate certificate files, though specific TLS variable names vary by component and should be verified in the respective source files containing os.Getenv calls.

Is there a complete list of all CubeSandbox environment variables?

While there is no single documentation file listing all variables, you can discover the complete set by searching for os.Getenv calls throughout the TencentCloud/CubeSandbox repository. Key files to examine include cube-lifecycle-manager/internal/config/config.go for lifecycle manager variables, sdk/go/config.go for SDK settings, and Cubelet/pkg/networkagentclient/client.go for networking flags.

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