How to Configure containerd to Use CubeSandbox: Complete Integration Guide

Configure containerd to use CubeSandbox by installing the CubeShim binary, registering the io.containerd.cube.v2 runtime type in containerd's configuration, and updating Cubelet to request the cube runtime class.

CubeSandbox is a Micro-VM-based sandbox runtime developed by TencentCloud that integrates with containerd through a custom Shim v2 implementation. This guide walks you through the exact configuration steps required to route container workloads through the CubeShim binary, enabling KVM-backed sandbox execution alongside standard containers.

Understanding the CubeShim Architecture

CubeSandbox integrates with containerd via CubeShim, a custom shim binary named containerd-shim-cube-rs that implements the containerd Shim v2 API. This shim exposes the lifecycle of a Micro-VM-based sandbox to containerd, managing the transition from container specification to KVM virtual machine execution.

The communication flow follows this path: Cubelet ↔ containerd ↔ CubeShim ↔ CubeHypervisor ↔ guest VM. When containerd receives a request for the cube runtime, it spawns the shim process, which then prepares the root filesystem, memory file, and kernel before launching the VM via the CubeHypervisor. The architecture is documented in /docs/zh/architecture/overview.md within the TencentCloud/CubeSandbox repository.

Step-by-Step Configuration Guide

Step 1: Install the CubeShim Binary

The CubeShim binary (containerd-shim-cube-rs) is built as part of the one-click release deployment. By default, the installer places the binary at /usr/local/services/cubetoolbox/cube-shim/bin/containerd-shim-cube-rs and creates a symbolic link in /usr/local/bin to ensure containerd can locate the executable.

According to the installation script at deploy/one-click/install.sh, this setup happens automatically during the one-click installation process. Verify the binary exists and is accessible in your system path:

ls -la /usr/local/bin/containerd-shim-cube-rs
ls -la /usr/local/services/cubetoolbox/cube-shim/bin/containerd-shim-cube-rs

Step 2: Register the Cube Runtime in containerd

You must register the CubeSandbox runtime in containerd's configuration file, typically located at /etc/containerd/config.toml. This registration tells containerd how to locate and spawn the shim when a workload requests the cube runtime.

Add the following runtime configuration to your containerd config file:

[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.cube]
  runtime_type = "io.containerd.cube.v2"

The runtime_type value io.containerd.cube.v2 corresponds to the shim's registration name as defined in the CubeShim source code (CubeShim/README.md). After updating the configuration, restart containerd to apply the changes:

sudo systemctl restart containerd

Step 3: Configure Cubelet to Use the Runtime

Cubelet must be configured to request the cube runtime when creating sandboxes. In the Cubelet configuration file (Cubelet/config/config.toml), set the runtime_type to io.containerd.cube.rs and ensure the shim configuration path points to the on-disk configuration file:

# Cubelet/config/config.toml

runtime_type = "io.containerd.cube.rs"

The config-cube.toml file (located at deploy/one-click/config-cube.toml) contains default paths for the shim binary, guest kernel, and guest image. Ensure this configuration file exists at the path referenced by Cubelet, as it provides the CubeShim with essential parameters for VM initialization.

Verification and Testing

Once configured, verify that containerd recognizes the CubeSandbox runtime:

# Check registered runtimes

containerd info | grep cube

You should see io.containerd.cube.v2 in the output, confirming the shim is properly registered.

To launch a sandbox using the CubeSandbox runtime, create a pod specification with the runtimeClassName set to cube:

apiVersion: v1
kind: Pod
metadata:
  name: cubesandbox-demo
spec:
  runtimeClassName: cube
  containers:
  - name: demo
    image: alpine:latest
    command: ["sleep", "3600"]

Apply the configuration:

kubectl apply -f pod.yaml

You can verify the shim is running by inspecting the process list:

pgrep -a containerd-shim-cube-rs

The output should show the shim process with arguments including --runtime io.containerd.cube.v2 and the sandbox ID.

Summary

• CubeShim (containerd-shim-cube-rs) is the custom Shim v2 implementation that bridges containerd and CubeSandbox's Micro-VM architecture.
• Install the binary at /usr/local/services/cubetoolbox/cube-shim/bin/containerd-shim-cube-rs with a symlink to /usr/local/bin.
• Register the runtime in /etc/containerd/config.toml using runtime_type = "io.containerd.cube.v2".
• Configure Cubelet in Cubelet/config/config.toml to use io.containerd.cube.rs and reference config-cube.toml for VM parameters.
• Use runtimeClassName: cube in pod specifications to trigger Micro-VM sandbox execution.

Frequently Asked Questions

What is the exact runtime type name for CubeSandbox in containerd?

The runtime type name registered in containerd's configuration is io.containerd.cube.v2. This value must be specified as the runtime_type in /etc/containerd/config.toml under the runtimes.cube section. Note that Cubelet uses a slightly different internal reference (io.containerd.cube.rs), but containerd itself recognizes the .v2 suffix for Shim v2 API compatibility.

Where does the CubeShim binary get installed by default?

The default installation path is /usr/local/services/cubetoolbox/cube-shim/bin/containerd-shim-cube-rs. The one-click installer (deploy/one-click/install.sh) creates a symbolic link at /usr/local/bin/containerd-shim-cube-rs to ensure containerd can locate the binary without requiring modifications to the system PATH.

How does Cubelet communicate with CubeShim through containerd?

Cubelet sends sandbox creation requests to containerd, which then spawns the containerd-shim-cube-rs process as the runtime handler. The shim implements the ttrpc API to communicate with the cube-agent running inside the guest VM via a vsock channel. This flow is documented in the architecture overview at docs/zh/architecture/overview.md.

Can I run CubeSandbox alongside standard runc containers?

Yes, CubeSandbox is designed to run alongside standard container runtimes like runc. By using Kubernetes RuntimeClasses or Docker's --runtime flag, you can specify which workloads use the cube runtime versus the default runtime. This allows hybrid deployments where some pods run as Micro-VMs while others run as traditional containers on the same node.

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