containerd-runtime.md

Containerd runtimes

A runtime in containerd does not stand at the runc level, but at the platform one. There are separate Linux and Windows runtimes, and they register as plugins:

const (
	runtimeName    = "linux"
	configFilename = "config.json"
	defaultRuntime = "runc"
	defaultShim    = "containerd-shim"
)

	plugin.Register(runtimeName, &plugin.Registration{
		Type: plugin.RuntimePlugin,
		Init: New,
		Config: &Config{
			Shim:    defaultShim,
			Runtime: defaultRuntime,
		},
	})

There are many diffent types of plugins, and RuntimePlugin is only one of them:

const (
	// AllPlugins declares that the plugin should be initialized after all others.
	AllPlugins Type = "*"
	// RuntimePlugin implements a runtime
	RuntimePlugin Type = "io.containerd.runtime.v1"
	// GRPCPlugin implements a grpc service
	GRPCPlugin Type = "io.containerd.grpc.v1"
	// SnapshotPlugin implements a snapshotter
	SnapshotPlugin Type = "io.containerd.snapshotter.v1"
	// TaskMonitorPlugin implements a task monitor
	TaskMonitorPlugin Type = "io.containerd.monitor.v1"
	// DiffPlugin implements a differ
	DiffPlugin Type = "io.containerd.differ.v1"
	// MetadataPlugin implements a metadata store
	MetadataPlugin Type = "io.containerd.metadata.v1"
	// ContentPlugin implements a content store
	ContentPlugin Type = "io.containerd.content.v1"
	// GCPlugin implements garbage collection policy
	GCPlugin Type = "io.containerd.gc.v1"
)

The Linux containerd runtime is identified as io.containerd.runtime.v1.linux and can be configured:

type Config struct {
	// Shim is a path or name of binary implementing the Shim GRPC API
	Shim string `toml:"shim,omitempty"`
	// Runtime is a path or name of an OCI runtime used by the shim
	Runtime string `toml:"runtime,omitempty"`
	// NoShim calls runc directly from within the pkg
	NoShim bool `toml:"no_shim,omitempty"`
}

Containerd containers

Each container is associated with a RuntimeInfo structure:

type Container struct {
[...]
	// Runtime specifies which runtime should be used when launching container
	// tasks.
	//
	// This property is required and immutable.
	Runtime RuntimeInfo
[...]
}

// RuntimeInfo holds runtime specific information
type RuntimeInfo struct {
	Name    string
	Options *types.Any
}

For the default Linux runtime (i.e. runc), the RuntimeInfo options is a RuncOptions instance:

type RuncOptions struct {
	Runtime       string `protobuf:"bytes,1,opt,name=runtime,proto3" json:"runtime,omitempty"`
	RuntimeRoot   string `protobuf:"bytes,2,opt,name=runtime_root,json=runtimeRoot,proto3" json:"runtime_root,omitempty"`
	CriuPath      string `protobuf:"bytes,3,opt,name=criu_path,json=criuPath,proto3" json:"criu_path,omitempty"`
	SystemdCgroup bool   `protobuf:"varint,4,opt,name=systemd_cgroup,json=systemdCgroup,proto3" json:"systemd_cgroup,omitempty"`
}

where Runtime is the runc path or left empty for using the default path. It is not the containerd runtime as in io.containerd.runtime.v1.linux, but will be used to configure the io.containerd.runtime.v1.linux runtime comfiguration (Config.Runtime). Confusing, at least to me...

cri-containerd containers

When creating a sandbox, cri-containerd associates the sandbox container with a runtime. In RunPodSandbox(), this will be Linux by default and the runtime options will be the runc ones:

		containerd.WithRuntime(
			c.config.ContainerdConfig.Runtime,
			&runctypes.RuncOptions{
				Runtime:       c.config.ContainerdConfig.RuntimeEngine,
				RuntimeRoot:   c.config.ContainerdConfig.RuntimeRoot,
				SystemdCgroup: c.config.SystemdCgroup})} // TODO (mikebrow): add CriuPath when we add support for pause

cri-contained configuration is defined as follows:

// ContainerdConfig contains toml config related to containerd
type ContainerdConfig struct {
	// RootDir is the root directory path for containerd.
	// TODO(random-liu): Remove this field when no longer support cri-containerd standalone mode.
	RootDir string `toml:"root_dir" json:"rootDir,omitempty"`
	// Snapshotter is the snapshotter used by containerd.
	Snapshotter string `toml:"snapshotter" json:"snapshotter,omitempty"`
	// Endpoint is the containerd endpoint path.
	// TODO(random-liu): Remove this field when no longer support cri-containerd standalone mode.
	Endpoint string `toml:"endpoint" json:"endpoint,omitempty"`
	// Runtime is the runtime to use in containerd. We may support
	// other runtimes in the future.
	Runtime string `toml:"runtime" json:"runtime,omitempty"`
	// RuntimeEngine is the name of the runtime engine used by containerd.
	// Containerd default should be "runc"
	// We may support other runtime engines in the future.
	RuntimeEngine string `toml:"runtime_engine" json:"runtimeEngine,omitempty"`
	// RuntimeRoot is the directory used by containerd for runtime state.
	// Containerd default should be "/run/containerd/runc"
	RuntimeRoot string `toml:"runtime_root" json:"runtimeRoot,omitempty"`
}

Typically, cri-containerd will be configured with the following default runtime options:

runtime: "io.containerd.runtime.v1.linux"
runtime_engine: "" (default is "runc")
runtime_path: ""