What Is the Role of CubeMaster in CubeSandbox? Central Control Plane Explained

CubeMaster serves as the central metadata and control plane for CubeSandbox, operating as a lightweight HTTP service that stores declarative sandbox state and provides RPC endpoints for lifecycle orchestration, node registration, and garbage collection.

In the TencentCloud/CubeSandbox ecosystem, understanding the role of CubeMaster in CubeSandbox is essential for operating the distributed sandbox platform. CubeMaster functions as the single source of truth for all sandbox metadata, managing everything from template definitions to runtime lifecycle transitions while serving as the coordination hub for Cubelet agents and sidecar components.

Core Responsibilities of CubeMaster in CubeSandbox

CubeMaster operates as a lightweight HTTP service (defaulting to 127.0.0.1:8089) that maintains the declarative state of every sandbox in the system. Its architecture decouples the control plane from the data plane, enabling reliable operation of distributed components.

Metadata Store for Templates and Sandbox Descriptors

CubeMaster maintains the authoritative registry of template and sandbox descriptors that define a sandbox's container image, resource limits, and runtime configuration. This data is persisted in Redis and mirrored in the CubeMaster process memory for fast access.

The protocol definitions for these requests reside in CubeMaster/pkg/templatecenter/template_request.go, which implements the protobuf-based structures used for all metadata operations. The template center implementation in CubeMaster/pkg/templatecenter/* handles the storage and retrieval of these declarative configurations.

Lifecycle Orchestration and State Machine Management

CubeMaster exposes the /cube/sandbox/update endpoint to drive sandbox state transitions. Sidecars such as the cube-lifecycle-manager invoke this endpoint to execute actions including pause, resume, and kill, moving sandboxes through their defined state machine.

According to the source in cube-lifecycle-manager/internal/cubemasterclient/client.go, the Pause method "asks CubeMaster to pause the given sandbox" (see line 119). Similarly, the resumer.go file in the same package demonstrates how resume operations coordinate with CubeMaster to restore sandbox execution.

Node Registration and Heartbeat Aggregation

Cubelet agents register themselves with CubeMaster and periodically push node status updates. CubeMaster aggregates these reports into a global cluster view utilized by the scheduler for placement decisions.

The registration logic is implemented in Cubelet/pkg/masterclient/client.go, which handles both initial registration and ongoing heartbeat transmissions to maintain node liveness.

Garbage Collection Coordination

When a sandbox terminates, CubeMaster triggers the garbage collection of template artifacts to reclaim storage resources. The CubeMaster/pkg/templatecenter/artifact_gc.go file implements the logic that ensures safe cleanup of obsolete artifacts while respecting in-flight operations.

HTTP Interface and Error Code Contracts

CubeMaster communicates via a simple HTTP interface with strict error-code contracts. The service returns fixed ret_code values (such as RetCodeSuccess and RetCodeInvalidParamFormat) that sidecars translate into idempotent actions.

As documented in cube-lifecycle-manager/internal/cubemasterclient/client.go (lines 24-31), these return codes enable components to distinguish between transient failures and permanent errors, implementing appropriate retry logic or fast-fail behaviors.

Configuration and Default Endpoints

The CubeMaster endpoint is configurable via the CubeMasterURL field, with a default value of http://127.0.0.1:8089 defined in cube-lifecycle-manager/internal/config/config.go (lines 88-90). This allows operators to deploy CubeMaster on alternative ports or hosts while maintaining compatibility with client components.

Implementing CubeMaster Clients in Go

Components interact with CubeMaster using a minimal HTTP client. Below is a runnable example demonstrating how to pause a sandbox using the client library defined in the repository.

package main

import (
	"context"
	"time"

	cmm "github.com/tencentcloud/CubeSandbox/cube-lifecycle-manager/internal/cubemasterclient"
)

func main() {
	// The URL defaults to 127.0.0.1:8089; you can override it via config.
	master := cmm.New("http://127.0.0.1:8089", 5*time.Second)

	// Pause sandbox "sandbox-123" of instance type "cubenode".
	if err := master.Pause(context.Background(), "sandbox-123", "cubenode"); err != nil {
		// The client translates CubeMaster ret-codes into Go errors:
		// - AlreadyPausedError → no-op (idempotent)
		// - NotFoundError     → sandbox has been deleted
		// - other errors       → retry or abort
		panic(err)
	}
}

The cubemasterclient.New constructor (defined in cube-lifecycle-manager/internal/cubemasterclient/client.go) accepts the base URL and timeout parameters. The client handles the translation of CubeMaster's ret_codes into typed Go errors, allowing callers to handle AlreadyPausedError as a no-op while treating NotFoundError as a terminal state.

Summary

• CubeMaster acts as the central metadata and control plane for the CubeSandbox system, maintaining the single source of truth for all sandbox state.
• It stores template definitions and runtime metadata in CubeMaster/pkg/templatecenter/*, persisting data to Redis while exposing it via HTTP endpoints.
• The /cube/sandbox/update endpoint (consumed by cube-lifecycle-manager/internal/cubemasterclient/client.go) orchestrates lifecycle transitions including pause, resume, and kill operations.
• Cubelet agents register and heartbeat through Cubelet/pkg/masterclient/client.go, allowing CubeMaster to maintain a global cluster view for scheduling.
• Garbage collection of template artifacts is coordinated through CubeMaster/pkg/templatecenter/artifact_gc.go following sandbox termination.
• Error handling relies on fixed ret_code values (documented in lines 24-31 of the lifecycle manager client) to ensure idempotent operations across distributed components.

Frequently Asked Questions

What is the default network address for CubeMaster in CubeSandbox?

By default, CubeMaster listens on 127.0.0.1:8089. This endpoint is configurable via the CubeMasterURL field in cube-lifecycle-manager/internal/config/config.go (lines 88-90), allowing deployment in multi-node configurations where the control plane runs on a dedicated host.

How does CubeMaster handle sandbox lifecycle transitions?

CubeMaster exposes the /cube/sandbox/update endpoint to drive state machine transitions. Sidecars such as the cube-lifecycle-manager invoke this endpoint with actions like pause or resume, as implemented in cube-lifecycle-manager/internal/cubemasterclient/client.go (line 119). CubeMaster validates the request against current state and returns standardized ret_codes that the client translates into idempotent operations.

Which CubeSandbox components communicate directly with CubeMaster?

The primary clients include the cube-lifecycle-manager (for pause/resume operations via cube-lifecycle-manager/internal/cubemasterclient/client.go), Cubelet agents (for node registration and heartbeats via Cubelet/pkg/masterclient/client.go), and the Cube Proxy CLI. These components rely on CubeMaster as the single source of truth for sandbox metadata and cluster state.

How does CubeMaster ensure consistency during garbage collection?

When a sandbox exits, CubeMaster triggers the garbage collection logic in CubeMaster/pkg/templatecenter/artifact_gc.go to clean up template artifacts. The system ensures that any in-flight operations complete safely before removing resources, preventing race conditions between active sandboxes and cleanup processes.

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