client

The Go client embeddable into other programs. Located at client/. In v1 this was the containerd package at the repo root; the v2 reorg moved it here and renamed the import path to github.com/containerd/containerd/v2/client.

Purpose

• Provide a Go-native abstraction over the daemon's gRPC API.
• Manage the underlying *grpc.ClientConn and the per-namespace context plumbing.
• Offer typed helpers for the common workflows (pull image, run container, fetch logs).

Directory layout

client/
├── client.go            # Client struct: dial, Close, accessors for each service
├── client_opts.go       # Functional options for New (TLS, timeout, default ns)
├── grpc.go              # gRPC dial helpers
├── namespaces.go        # NewNamespaceClient, ListNamespaces
├── container.go         # Container CRUD
├── container_opts.go / container_opts_unix.go
├── containerstore.go    # Containers() returns a Store
├── task.go              # Task lifecycle
├── task_opts.go / task_opts_unix.go
├── process.go           # Exec process inside a task
├── pull.go              # High-level Pull
├── import.go            # Import OCI tar
├── export.go            # Export OCI tar
├── image.go             # Image type and operations
├── image_store.go       # Images() returns a Store
├── snapshotter_opts_*.go
├── lease.go             # Lease creation
├── events.go            # Subscribe to the events service
├── services.go          # Direct access to each service's gRPC client
├── transfer.go          # Wraps the Transfer service
├── sandbox.go           # Sandbox client
├── signals.go           # Helper for forwarding host signals into the container
├── install.go / install_opts.go  # Install precompiled binaries from images
└── diff.go

Key abstractions

Type	File	Purpose
Client	client/client.go	The top-level handle; holds the gRPC connection and exposes accessors
Container	client/container.go	A container record + methods (Update, NewTask, Spec, Image, ...)
Task	client/task.go	A running task; supports Start, Kill, Wait, Pause, Resume, Exec, Checkpoint
Process	client/process.go	An exec'd process inside a task
Image	client/image.go	An image and its operations (Unpack, RootFS, Size)
Snapshotter	accessor on Client	Returns core/snapshots.Snapshotter over gRPC
LeasesService	accessor	Lease manager

Typical usage

cli, err := containerd.New("/run/containerd/containerd.sock")
defer cli.Close()
ctx := namespaces.WithNamespace(context.Background(), "default")

img, err := cli.Pull(ctx, "docker.io/library/alpine:3.19", containerd.WithPullUnpack)
container, err := cli.NewContainer(ctx, "demo",
    containerd.WithImage(img),
    containerd.WithNewSnapshot("demo-snapshot", img),
    containerd.WithNewSpec(oci.WithImageConfig(img), oci.WithProcessArgs("echo", "hi")),
)
defer container.Delete(ctx, containerd.WithSnapshotCleanup)

task, _ := container.NewTask(ctx, cio.NewCreator(cio.WithStdio))
defer task.Delete(ctx)
exitStatusCh, _ := task.Wait(ctx)
task.Start(ctx)
status := <-exitStatusCh
fmt.Println(status.ExitCode())

This pattern (Pull → NewContainer → NewTask → Start → Wait) is the canonical embed.

Where the boundaries are

• client.New opens a gRPC connection and lazily initializes service clients on first access. The connection uses the pkg/dialer cross-platform helpers so the same code works on Linux and Windows.
• All API calls require a namespace in the context; helper containerd.WithDefaultNamespace("default") is provided for convenience.
• Most "options" are functional (Opt func(*Client) error); see client/client_opts.go for the full list.

Relationship to the daemon

client/ is shared in-process with the daemon: the CRI plugin, ctr, integration tests, and external embedders all use the same code. The CRI plugin specifically is built on top of client.Client rather than going through the gRPC stack — this is what services.go provides.

Stability

The package follows the deprecation rules in RELEASES.md. Removed APIs are marked // Deprecated: first and stay for at least one minor version before being deleted.

Entry points for modification

• New high-level helper: add a method on Client (e.g. pull.go-style) and reuse the lower-level service accessors.
• New container option: add an Opt to container_opts.go (or a _unix.go / _windows.go variant if it's platform-specific).
• New task option: same, in task_opts.go.
• New default option: append to defaultRemoteContext or similar accumulator on Client.