containerd_shim.md

Overview

containerd defines a simple runtime shim API (v2) for container runtimes (kata, runc, etc) to interface with.

The goal of this API is to abstract container operations from the actual runtime operations, and e.g. avoid assumptions on how containers are going to run (inside a VM vs as a bare metal process for example).

With that architecture, a container runtime becomes a shim v2 implementation, which is a binary that:

1. Implements the gRPC shim service
2. Supports 2 commands: delete and start

However, in practice a shim v2 implementation only needs to:

• Implement the Shim server golang interface
• Implement an init function:

// Init func for the creation of a shim server
type Init func(context.Context, string, Publisher, func()) (Shim, error)

• Implement itself as a binary that calls into containerd's shim.Run()

shim.Run() does the whole gRPC plumbing, starts the shim as a gRPC server and starts clients that connect to it.

Flow

The Kata shim v2 binary calls into containerd's shim top level Run routine and passes an init function that creates a shim v2 object.

The shim v2 object does not implement the gRPC protocol itself, it implements the containerd Shim server interface:

// Shim server interface
type Shim interface {
	shimapi.TaskService
	Cleanup(ctx context.Context) (*shimapi.DeleteResponse, error)
	StartShim(ctx context.Context, opts StartOpts) (string, error)
}

And that includes the TaskService interface which is generated from the shim server gRPC definitions:

type TaskService interface {
	State(ctx context.Context, req *StateRequest) (*StateResponse, error)
	Create(ctx context.Context, req *CreateTaskRequest) (*CreateTaskResponse, error)
	Start(ctx context.Context, req *StartRequest) (*StartResponse, error)
	Delete(ctx context.Context, req *DeleteRequest) (*DeleteResponse, error)
	Pids(ctx context.Context, req *PidsRequest) (*PidsResponse, error)
	Pause(ctx context.Context, req *PauseRequest) (*types1.Empty, error)
	Resume(ctx context.Context, req *ResumeRequest) (*types1.Empty, error)
	Checkpoint(ctx context.Context, req *CheckpointTaskRequest) (*types1.Empty, error)
	Kill(ctx context.Context, req *KillRequest) (*types1.Empty, error)
	Exec(ctx context.Context, req *ExecProcessRequest) (*types1.Empty, error)
	ResizePty(ctx context.Context, req *ResizePtyRequest) (*types1.Empty, error)
	CloseIO(ctx context.Context, req *CloseIORequest) (*types1.Empty, error)
	Update(ctx context.Context, req *UpdateTaskRequest) (*types1.Empty, error)
	Wait(ctx context.Context, req *WaitRequest) (*WaitResponse, error)
	Stats(ctx context.Context, req *StatsRequest) (*StatsResponse, error)
	Connect(ctx context.Context, req *ConnectRequest) (*ConnectResponse, error)
	Shutdown(ctx context.Context, req *ShutdownRequest) (*types1.Empty, error)
}

CLI: main.go -> shim.Run(containerdShim.new)