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

> Discover CubeMaster's role as the central control plane in CubeSandbox. Learn how this HTTP service manages sandbox state and orchestration for lifecycle management, node registration, and garbage collection.

- Repository: [Tencent Cloud/CubeSandbox](https://github.com/TencentCloud/CubeSandbox)
- Tags: internals
- Published: 2026-07-08

---

**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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/cube-lifecycle-manager/internal/cubemasterclient/client.go), the `Pause` method "asks CubeMaster to pause the given sandbox" (see line 119). Similarly, the [`resumer.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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.

```go
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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/cube-lifecycle-manager/internal/cubemasterclient/client.go)), **Cubelet agents** (for node registration and heartbeats via [`Cubelet/pkg/masterclient/client.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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.