# How CubeSandbox Integrates with containerd and Ensures OCI Specification Compliance

> Discover how CubeSandbox integrates with containerd using its Go client and OCI compliance features for seamless container execution. Learn about its custom storage plugin registration and specification construction.

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

---

**CubeSandbox utilizes the containerd Go client to interface with the containerd daemon, registers custom storage plugins, and constructs fully OCI-compliant container specifications using the `containerd/pkg/oci` package before delegating execution to the containerd runtime.**

The TencentCloud/CubeSandbox project implements a secure container sandbox that relies on **containerd** for low-level container operations. By leveraging the official containerd client library and adhering to the Open Container Initiative (OCI) image and runtime specifications, CubeSandbox guarantees standards-compliant container execution while maintaining its own higher-level sandboxing abstractions for snapshots and volumes.

## Initializing the containerd Client and Plugin Registration

CubeSandbox establishes communication with the containerd daemon by creating a dedicated client instance configured for the default platform and in-memory services. In [[`Cubelet/services/images/service.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/services/images/service.go)](https://github.com/TencentCloud/CubeSandbox/blob/master/Cubelet/services/images/service.go#L84-L90), the initialization code instantiates the client:

```go
client, err := containerd.New(
    containerd.WithDefaultPlatform(platforms.Default()),
    containerd.WithInMemoryServices(ic),
)
if err != nil {
    return fmt.Errorf("init containerd connect failed.%s", err)
}

```

To extend containerd’s functionality with CubeSandbox-specific storage capabilities, the project registers custom plugins using the containerd plugin system. The imports in [[`Cubelet/storage/plugin.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/storage/plugin.go)](https://github.com/TencentCloud/CubeSandbox/blob/master/Cubelet/storage/plugin.go#L16-L18) bring in the necessary containerd plugin packages, enabling the runtime to discover Cube-specific snapshotters and volume managers during daemon initialization.

## OCI Runtime Selection and Configuration

Before creating a container, CubeSandbox determines which OCI runtime to use by constructing an `ociRuntime` configuration structure. This selection happens in [[`Cubelet/services/cubebox/service.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/services/cubebox/service.go)](https://github.com/TencentCloud/CubeSandbox/blob/master/Cubelet/services/cubebox/service.go#L145-L188), where the code defines runtime types and paths passed to `containerd.WithRuntime`.

The runtime configuration specifies the OCI-compliant binary (often a containerd shim) and its associated options, ensuring the subsequent container execution adheres to the OCI runtime specification. This struct is later referenced when invoking container creation APIs.

## Constructing OCI-Compliant Container Specifications

CubeSandbox ensures **OCI specification compliance** by building container specs exclusively through the `containerd/pkg/oci` helper functions. The primary construction logic resides in [[`Cubelet/services/cubebox/runc_container_op.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/services/cubebox/runc_container_op.go)](https://github.com/TencentCloud/CubeSandbox/blob/master/Cubelet/services/cubebox/runc_container_op.go#L247-L332), where the code assembles a slice of `oci.SpecOpts` that configure every aspect of the container:

- `oci.WithDefaultSpec()` – Establishes the base OCI spec structure
- `oci.WithRootFSReadonly()` – Sets the root filesystem to read-only
- `oci.WithMounts(mounts)` – Injects bind mounts and volumes
- `oci.WithCapabilities(addCaps, dropCaps, ambientCaps)` – Configures Linux capabilities
- `oci.WithMemoryLimit(uint64(memQ.Value()))` – Applies cgroup memory constraints
- `oci.WithCPUCFS(quota, period)` – Sets CPU Completely Fair Scheduling quotas
- `oci.WithAnnotations(annotations)` – Adds OCI annotations

The options are composed into a final specification using `oci.Compose`:

```go
opts := []oci.SpecOpts{
    oci.WithDefaultSpec(),
    oci.WithRootFSReadonly(),
    oci.WithMounts(smounts),
    oci.WithCapabilities(caps.AddCapabilities, caps.DropCapabilities, caps.AddAmbientCapabilities),
    oci.WithMemoryLimit(uint64(memQ.Value())),
    oci.WithCPUCFS(quota, period),
    oci.WithAnnotations(containerReq.Annotations),
}

spec, err := oci.Compose(opts...)
if err != nil {
    return fmt.Errorf("compose oci spec failed: %w", err)
}

```

This approach guarantees that every generated spec conforms to the OCI runtime specification, as the `oci` package validates required fields such as the process configuration, rootfs, and namespaces during composition.

## Container Creation and Lifecycle Synchronization

With the OCI spec constructed, CubeSandbox delegates container creation to containerd via the client API. In [[`Cubelet/services/cubebox/cube_container_create.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/services/cubebox/cube_container_create.go)](https://github.com/TencentCloud/CubeSandbox/blob/master/Cubelet/services/cubebox/cube_container_create.go#L272-L304), the code creates the container entity:

```go
c, err := client.NewContainer(
    ctx,
    containerName,
    containerd.WithSandbox(sandboxID),
    containerd.WithRuntime(ociRuntime.Type, &runtimeoptions.Options{}),
    containerd.WithSpec(spec),
)
if err != nil {
    return err
}

task, err := c.NewTask(ctx, cio.NewFIFOHandler(...))

```

If spec generation fails, the error handling in lines [259-271](https://github.com/TencentCloud/CubeSandbox/blob/master/Cubelet/services/cubebox/cube_container_create.go#L259-L271) logs the specific OCI compliance failure and aborts creation before reaching the runtime.

To maintain state consistency, CubeSandbox subscribes to containerd lifecycle events. The event subscription logic in [[`Cubelet/services/cubebox/service.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/services/cubebox/service.go)](https://github.com/TencentCloud/CubeSandbox/blob/master/Cubelet/services/cubebox/service.go#L156-L162) monitors events such as `TaskDeleted` and `TaskExited`, ensuring the sandbox state accurately reflects the OCI runtime’s actual execution status.

## Summary

- **Client Initialization**: CubeSandbox creates a `containerd.Client` in [`Cubelet/services/images/service.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/services/images/service.go) using platform-specific and in-memory service configurations.
- **Plugin Integration**: Custom storage plugins are registered via imports in [`Cubelet/storage/plugin.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/storage/plugin.go), extending containerd’s snapshotter capabilities.
- **OCI Runtime Selection**: The `ociRuntime` struct in [`Cubelet/services/cubebox/service.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/services/cubebox/service.go) configures which OCI-compliant binary executes the container.
- **Spec Compliance**: All OCI specifications are built using `containerd/pkg/oci` helpers in [`runc_container_op.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/runc_container_op.go), ensuring valid Linux capabilities, mounts, and resource limits.
- **Lifecycle Management**: Container creation in [`cube_container_create.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/cube_container_create.go) and event subscription in [`service.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/service.go) keep the sandbox synchronized with containerd’s OCI runtime state.

## Frequently Asked Questions

### How does CubeSandbox establish the connection to the containerd daemon?

CubeSandbox initializes a containerd client using `containerd.New()` configured with `WithDefaultPlatform()` and `WithInMemoryServices()`. This client, created in [[`Cubelet/services/images/service.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/services/images/service.go)](https://github.com/TencentCloud/CubeSandbox/blob/master/Cubelet/services/images/service.go#L84-L90), communicates with the containerd daemon via gRPC to perform all subsequent runtime operations.

### Which specific OCI options ensure compliance in CubeSandbox?

The project uses the `containerd/pkg/oci` package to set standards-compliant options including `WithDefaultSpec`, `WithRootFSReadonly`, `WithMounts`, `WithCapabilities`, `WithMemoryLimit`, and `WithCPUCFS`. These functions populate mandatory OCI fields for process configuration, namespaces, and cgroup resource limits as implemented in [[`Cubelet/services/cubebox/runc_container_op.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/services/cubebox/runc_container_op.go)](https://github.com/TencentCloud/CubeSandbox/blob/master/Cubelet/services/cubebox/runc_container_op.go#L247-L332).

### How does CubeSandbox handle container lifecycle events from containerd?

CubeSandbox subscribes to containerd’s event stream to monitor `TaskDeleted` and `TaskExited` events. The subscription logic in [[`Cubelet/services/cubebox/service.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/services/cubebox/service.go)](https://github.com/TencentCloud/CubeSandbox/blob/master/Cubelet/services/cubebox/service.go#L156-L162) ensures the sandbox controller synchronizes its internal state with the actual OCI runtime status, triggering appropriate cleanup when containers terminate unexpectedly.

### What prevents non-compliant containers from launching in CubeSandbox?

During the spec construction phase in [[`Cubelet/services/cubebox/cube_container_create.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/services/cubebox/cube_container_create.go)](https://github.com/TencentCloud/CubeSandbox/blob/master/Cubelet/services/cubebox/cube_container_create.go#L259-L271), CubeSandbox validates the OCI specification using `oci.Compose`. If the composition fails or required fields are missing, the creation aborts immediately with a logged error, preventing the containerd runtime from attempting to execute an invalid OCI configuration.