How CubeSandbox Integrates with containerd and Ensures OCI Specification Compliance

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/master/Cubelet/services/images/service.go#L84-L90), the initialization code instantiates the client:

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/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/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/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:

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/master/Cubelet/services/cubebox/cube_container_create.go#L272-L304), the code creates the container entity:

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 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/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 using platform-specific and in-memory service configurations.
• Plugin Integration: Custom storage plugins are registered via imports in Cubelet/storage/plugin.go, extending containerd’s snapshotter capabilities.
• OCI Runtime Selection: The ociRuntime struct in 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, ensuring valid Linux capabilities, mounts, and resource limits.
• Lifecycle Management: Container creation in cube_container_create.go and event subscription in 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/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/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/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/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.

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