CubeSandbox Lifecycle States and State Transition Rules Explained

CubeSandbox defines four explicit lifecycle states—running, pausing, paused, and resuming—that are persisted in Redis and orchestrated through a state machine with specific transition rules and automatic failure rollback mechanisms.

CubeSandbox manages micro-VM sandboxes through a deterministic lifecycle model tracked in Redis. The system recognizes four distinct sandbox lifecycle states that coordinate pause and resume operations across side-car replicas and the central CubeMaster service. These states are stored under the key cube:v1:shared:sandbox:lifecycle:state:<sandboxID> and enforced by the side-car's validation logic.

The Four Sandbox Lifecycle States

The state machine is defined in cube-lifecycle-manager/internal/lifecycle/schema.go, where the StateKey function enumerates the four valid string values. Each state represents a specific phase of the micro-VM's existence.

Running

The running state indicates the sandbox micro-VM is active and executing user code. This is the primary stable state where compute resources are allocated and the environment is fully operational.

Pausing

The pausing state is a transient intermediate state entered when a pause request is initiated. During this phase, the side-car acquires a distributed lock and coordinates the shutdown of the VM, preventing concurrent modifications while the operation is in-flight.

Paused

The paused state represents a stable stopped condition where the VM has been shut down and compute resources released, though metadata persists. Sandboxes in this state can be resumed later without data loss, making it ideal for cost-saving sleep operations.

Resuming

The resuming state is the transient counterpart to pausing, entered when a resume request is in-flight. The side-car uses this state to signal that the VM is currently booting and not yet ready to accept traffic, protecting against premature health checks.

State Transition Rules and Triggers

Transitions between states follow strict rules enforced by the side-car's Redis-backed coordination mechanism. The system uses SETNX (set if not exists) with a TTL to ensure atomic state updates and prevent race conditions across distributed components.

Pause Operation: Running to Paused

When a Pause request is received for a running sandbox, the side-car first writes pausing using SETNX with a TTL to signal an ongoing operation. After the VM is successfully stopped, the state is updated to paused. This two-phase commit ensures visibility of the transition in progress and prevents duplicate pause attempts.

Resume Operation: Paused to Running

The Resume operation follows the inverse pattern. The side-car writes resuming (via SETNX) and, once the VM boots successfully, flips the state to running. The Resumer component in cube-lifecycle-manager/internal/resumer/resumer.go (lines 61-68) implements this logic, handling idempotency and concurrent calls through the Redis lock mechanism.

Failure Handling and Rollback

If a pause or resume operation fails or exceeds the configured TTL, the side-car rolls back the transient state. The system re-enters the previous stable state—either running or paused—ensuring the sandbox does not remain stuck in pausing or resuming indefinitely.

Termination and Cleanup

A Delete operation triggers sandbox termination and immediately removes the Redis state key. There is no transition to a terminal state; the lifecycle metadata is erased, preventing any further state changes or recovery operations.

Implementation in the Source Code

The state machine is implemented across several components in the cube-lifecycle-manager directory.

The ProxyPush client enforces state validation before transmission. In cube-lifecycle-manager/internal/proxypush/client.go (line 104), the code explicitly checks that pushed states match the allowed set: "running" | "pausing" | "paused" | "resuming".

State persistence uses the StateKey function defined in cube-lifecycle-manager/internal/lifecycle/schema.go (lines 33-35). This function generates the Redis key cube:v1:shared:sandbox:lifecycle:state:<sandboxID> and documents the valid state values in its source comments.

Practical Usage Examples

The following Go SDK examples demonstrate how to trigger state transitions programmatically.

To pause an active sandbox:

sandboxID := "sb-123"
client := cubesandbox.NewClient("http://cube-master.local")
if err := client.Pause(context.Background(), sandboxID); err != nil {
    log.Fatalf("pause failed: %v", err)
}

To resume a paused sandbox:

if err := client.Resume(context.Background(), sandboxID); err != nil {
    log.Fatalf("resume failed: %v", err)
}

Both SDK calls update the Redis state key, driving the side-car's state machine through the pausing or resuming intermediates before reaching the stable target state.

Summary

• CubeSandbox defines four lifecycle states: running, pausing, paused, and resuming.
• Stable states (running and paused) hold the sandbox between operations, while transient states (pausing and resuming) coordinate VM shutdown and startup.
• Transitions use Redis SETNX with TTL to ensure atomic updates and prevent race conditions across side-car replicas.
• Failed operations roll back to the last stable state rather than leaving the sandbox in a transient condition.
• State values are validated in cube-lifecycle-manager/internal/proxypush/client.go and defined in cube-lifecycle-manager/internal/lifecycle/schema.go.

Frequently Asked Questions

What are the valid sandbox lifecycle states in CubeSandbox?

CubeSandbox recognizes four states: running (VM active), pausing (shutdown in progress), paused (VM stopped, metadata retained), and resuming (boot in progress). These are enumerated in the StateKey comments in cube-lifecycle-manager/internal/lifecycle/schema.go.

How does CubeSandbox prevent concurrent state transitions?

The side-car uses Redis SETNX (set if not exists) with a TTL on the state key cube:v1:shared:sandbox:lifecycle:state:<sandboxID>. This creates a distributed lock ensuring only one replica can drive a pause or resume operation at a time, preventing split-brain scenarios.

What happens if a pause or resume operation fails?

If the operation fails or times out, the side-car rolls back the transient state (pausing or resuming) to the previous stable state (running or paused). This prevents the sandbox from remaining in an undefined intermediate state and ensures eventual consistency.

Where is the sandbox state stored in CubeSandbox?

The state is persisted in Redis under the key cube:v1:shared:sandbox:lifecycle:state:<sandboxID>, generated by the StateKey function. The cube-lifecycle-manager components read and write this key to coordinate lifecycle transitions across the distributed system.

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