# Kubernetes-Native Deployment and Volume Support in CubeSandbox: Official Roadmap and Architecture

> Explore the CubeSandbox roadmap for Kubernetes-native deployment using CRDs and Operators. Discover persistent volume support for stateful sandbox workloads.

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

---

**CubeSandbox will soon support Kubernetes-native deployment via Custom Resource Definitions (CRDs) and an Operator, alongside E2B-compatible persistent volume support for stateful sandbox workloads.**

TencentCloud/CubeSandbox is evolving toward full cloud-native operation according to the project's public roadmap documentation. The planned features will allow the secure sandbox runtime to deploy as standard Kubernetes workloads using native scheduling primitives and persistent storage capabilities.

## Roadmap Overview

The [official roadmap](https://github.com/TencentCloud/CubeSandbox/blob/master/docs/guide/roadmap.md) lists two closely-related milestones currently in the "Coming Soon" phase:

### Kubernetes-Native Deployment

This feature enables deploying and running CubeSandbox entirely within a Kubernetes cluster using **CRDs**, an **Operator**, and native scheduling. According to the source documentation in [`docs/guide/roadmap.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/docs/guide/roadmap.md), this removes the need for external orchestration components and makes CubeSandbox a first-class citizen in cloud-native environments.

### Persistent Volume Support

The roadmap specifies adding **persistent and shared volume** capabilities compatible with the **E2B volume protocol**. This extends the existing `cubecow` copy-on-write engine to support stateful workloads that survive sandbox restarts and enable data sharing across multiple sandbox instances.

## Architectural Design

The implementation plan documented in the repository outlines a four-layer architecture:

### CRD-Based API

CubeSandbox will expose Custom Resource Definitions that model sandbox lifecycles, including `CubeSandbox`, `CubeSnapshot`, and `CubeVolume` resources. These CRDs allow the Kubernetes control plane to store desired state and drive reconciliation loops through standard etcd storage.

### Operator Reconciliation

An operator written in Go using the controller-runtime library will watch the CRDs and translate them into internal CubeSandbox actions. As implemented in the architecture plans, the operator encapsulates the existing `cube-lifecycle-manager` functionality to create VMs, manage snapshots, and handle storage through idempotent, race-free operations.

### Native Scheduling

By registering sandbox pods with the standard Kubernetes scheduler, CubeSandbox can leverage node-level resource constraints, affinity/anti-affinity rules, and priority classes. This aligns sandbox placement with other cluster workloads and enables node-drain-aware migration without custom scheduling logic.

### E2B-Compatible Volumes

The volume support implements the open-source **E2B volume protocol**, exposing the underlying `cubecow` storage engine through standard Kubernetes `PersistentVolume` and `PersistentVolumeClaim` interfaces. The `Cubelet/storage/` directory (containing [`cubecow_engine.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/cubecow_engine.go) and [`pool.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/pool.go)) contains the copy-on-write snapshot logic that will back these persistent volumes.

## Implementation Status

Both features remain in the design phase with no production-ready CRDs or operator code currently merged. However, the storage foundation exists in the `Cubelet/storage/` package, where the `cubecow` engine already provides the copy-on-write functionality required for persistent volume snapshots.

The `cube-lifecycle-manager` source directory contains the core lifecycle management routines that the future operator will invoke to create, pause, resume, and delete sandboxes. When the operator is implemented, it will wrap these existing functions with Kubernetes-specific controllers and RBAC rules.

## Practical Examples

The following manifests demonstrate the intended configuration patterns based on the roadmap documentation:

### CubeSandbox CRD Manifest

```yaml
apiVersion: cubesandbox.cloud.tencent.com/v1
kind: CubeSandbox
metadata:
  name: my-sandbox
spec:
  image: "docker.io/library/ubuntu:22.04"
  resources:
    cpu: "2"
    memory: "4Gi"
  volumeMounts:
    - name: data
      mountPath: /data
  volumes:
    - name: data
      persistentVolumeClaim:
        claimName: sandbox-data-pvc

```

### PersistentVolumeClaim with E2B Storage Class

```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: sandbox-data-pvc
spec:
  accessModes: [ReadWriteOnce]
  storageClassName: e2b-cubesandbox
  resources:
    requests:
      storage: 10Gi

```

### Future Operator Deployment

Once the Helm chart is published, the operator will install via standard Helm commands:

```bash
helm repo add cubesandbox https://tencentcloud.github.io/CubeSandbox/charts
helm install cubesandbox-operator cubesandbox/operator \
  --namespace cubesandbox-system --create-namespace

```

## Key Source Files

- **[`docs/guide/roadmap.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/docs/guide/roadmap.md)** — Lists the upcoming Kubernetes-native deployment and volume support milestones
- **[`Cubelet/storage/cubecow_engine.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/storage/cubecow_engine.go)** — Implements the copy-on-write snapshot logic for future persistent volumes
- **[`Cubelet/storage/pool.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/storage/pool.go)** — Manages storage pools backing the `cubecow` engine
- **`cube-lifecycle-manager/`** — Contains core lifecycle management code that the future operator will invoke
- **[`README.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/README.md)** — Feature matrix highlighting roadmap status

## Summary

- **Kubernetes-native deployment** will use CRDs and an Operator to eliminate external orchestration requirements
- **Volume support** leverages the existing `cubecow` storage engine with E2B protocol compatibility
- **Current status** is "Coming Soon" with storage foundations in `Cubelet/storage/` but no CRDs merged yet
- **Integration** enables standard Kubernetes scheduling, resource constraints, and persistent storage workflows

## Frequently Asked Questions

### When will the Kubernetes-native deployment features be available?

According to the repository's [`docs/guide/roadmap.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/docs/guide/roadmap.md), both the Kubernetes-native deployment and volume support features are currently in the "Coming Soon" phase. No production-ready CRDs or operator code exists in the main branch yet, though the underlying `cubecow` storage engine in `Cubelet/storage/` provides the necessary foundation.

### How will persistent volumes work with existing CubeSandbox storage?

The roadmap specifies that persistent volumes will utilize the existing **E2B volume protocol** and the `cubecow` copy-on-write snapshot system found in [`Cubelet/storage/cubecow_engine.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/storage/cubecow_engine.go). Users will create standard Kubernetes `PersistentVolumeClaim` resources using the `e2b-cubesandbox` storage class, which the future operator will map to the underlying snapshot engine.

### What benefits does the Operator provide over current deployment methods?

The Operator eliminates the need for separate "one-click" deployment scripts by encapsulating the `cube-lifecycle-manager` logic within a Kubernetes-native controller. This enables idempotent reconciliation, native scheduling with node affinity rules, and integration with cluster autoscalers and monitoring stacks.

### Will existingCubeSandbox deployments migrate to CRDs automatically?

The roadmap documentation does not specify automatic migration paths. When the CRD-based API becomes available in `cubesandbox.cloud.tencent.com/v1`, users will likely need to recreate existing sandbox instances using the new Custom Resource Definitions, as the architecture shifts from standalone lifecycle management to Kubernetes-operator-driven reconciliation.