pkg/oci

Helpers for building OCI runtime specs. The largest and most-used package in pkg/. It's where almost every "configure this aspect of the container" option ends up.

Purpose

• Construct an oci-runtime-spec Spec from defaults.
• Provide composable SpecOpts to layer in image config, mounts, namespaces, capabilities, cgroup constraints, …
• Hide platform differences behind a single Spec type.

Directory layout

pkg/oci/ contains roughly a hundred files split per-platform:

• spec.go — Spec type alias and constructors (GenerateSpec, WithDefaultSpec, etc.)
• spec_opts.go — cross-platform options
• spec_opts_linux.go / spec_opts_windows.go / spec_opts_freebsd.go — platform options
• mounts*.go — mount option helpers (RO, propagation, tmpfs)
• client.go — minimal Client interface so that pkg/oci can fetch image config without depending on client/

Key API

The spec is built by chaining SpecOpts:

spec, err := oci.GenerateSpec(ctx, client, container,
    oci.WithImageConfig(image),
    oci.WithProcessArgs("/bin/sh", "-c", "echo hi"),
    oci.WithCapabilities([]string{"CAP_NET_ADMIN"}),
    oci.WithMounts([]specs.Mount{...}),
    oci.WithLinuxNamespace(specs.LinuxNamespace{Type: specs.UserNamespace, Path: "/proc/123/ns/user"}),
)

Each SpecOpts is a func(ctx, client, container, *Spec) error. The composition is order-sensitive — later opts can override earlier ones.

Common opts

Opt	What it sets
WithImageConfig	Pulls user, env, working dir, cmd from the image config
WithProcessArgs	The container's argv
WithEnv	Append env vars
WithMounts	Add mounts (with conflict resolution)
WithRootFSPath	Set the root path in the spec
WithLinuxNamespace / WithoutLinuxNamespace	Add or remove a Linux namespace
WithCapabilities / WithAllCapabilities / WithDroppedCapabilities	Capability set tweaks
WithCgroup	Set the cgroup path
WithMemoryLimit, WithCPUShares, ...	Resource constraints
WithSeccompUnconfined	Drop the default seccomp filter
WithUserNamespace	Add a userns and remap mounts

Mount opt edge cases

pkg/oci's mount handling deduplicates by destination, applies propagation flags, and merges options. The tests in pkg/oci/spec_opts_test.go cover the corner cases (overlapping mounts, source resolution, etc.).

Used by

• client/container_opts.go's WithNewSpec factory.
• internal/cri/sputil/ to construct specs from CRI requests.
• cmd/ctr/commands/run/run.go for ctr run.
• Third-party embedders directly (the most common use case in nerdctl, kata-containers, etc.).

Entry points for modification

• New cross-platform option: add to spec_opts.go and document.
• New Linux-specific option: add to spec_opts_linux.go. Add a no-op or appropriate stub in spec_opts_other.go if you want the option to be cross-platform-callable.
• New mount option: see mounts.go for the dedup logic.
• Spec defaults: edit populateDefaultUnixSpec / populateDefaultWindowsSpec in spec.go.

For how the spec is consumed downstream, see runtime v2.