The website uses cookies. By using this site, you agree to our use of cookies as described in the Privacy Policy.
I Agree
blank_error__heading
blank_error__body
Text direction?

Shim API for Runtimes

Authors:

More VM based runtimes have internal state and more abstract actions.
A CLI approach introduces issues with state management.
This proposal introduces a shim API for solving these state issues at the shim layer in containerd.
The goals is to provide an API that various runtimes can implement to add support in containerd while
still having control of state and abstract actions.

v2 Task(shim) API

Previous Shim API

syntax = "proto3";

package containerd.runtime.linux.shim.v1;

service Shim {
	rpc State(StateRequest) returns (StateResponse);
	rpc Create(CreateTaskRequest) returns (CreateTaskResponse);
	rpc Start(StartRequest) returns (StartResponse);
	rpc Delete(google.protobuf.Empty) returns (DeleteResponse);
	rpc DeleteProcess(DeleteProcessRequest) returns (DeleteResponse);
	rpc ListPids(ListPidsRequest) returns (ListPidsResponse);
	rpc Pause(google.protobuf.Empty) returns (google.protobuf.Empty);
	rpc Resume(google.protobuf.Empty) returns (google.protobuf.Empty);
	rpc Checkpoint(CheckpointTaskRequest) returns (google.protobuf.Empty);
	rpc Kill(KillRequest) returns (google.protobuf.Empty);
	rpc Exec(ExecProcessRequest) returns (google.protobuf.Empty);
	rpc ResizePty(ResizePtyRequest) returns (google.protobuf.Empty);
	rpc CloseIO(CloseIORequest) returns (google.protobuf.Empty);
	rpc ShimInfo(google.protobuf.Empty) returns (ShimInfoResponse);
	rpc Update(UpdateTaskRequest) returns (google.protobuf.Empty);
	rpc Wait(WaitRequest) returns (WaitResponse);
}

New API

syntax = "proto3";

package containerd.task.v2;

service Task {
        rpc State(StateRequest) returns (StateResponse);
        rpc Create(CreateTaskRequest) returns (CreateTaskResponse);
        rpc Start(StartRequest) returns (StartResponse);
        rpc Delete(DeleteRequest) returns (DeleteResponse);
        rpc Pids(PidsRequest) returns (PidsResponse);
        rpc Pause(google.protobuf.Empty) returns (google.protobuf.Empty);
        rpc Resume(google.protobuf.Empty) returns (google.protobuf.Empty);
        rpc Checkpoint(CheckpointTaskRequest) returns (google.protobuf.Empty);
        rpc Kill(KillRequest) returns (google.protobuf.Empty);
        rpc Exec(ExecProcessRequest) returns (google.protobuf.Empty);
        rpc ResizePty(ResizePtyRequest) returns (google.protobuf.Empty);
        rpc CloseIO(CloseIORequest) returns (google.protobuf.Empty);
        rpc Update(UpdateTaskRequest) returns (google.protobuf.Empty);
        rpc Wait(WaitRequest) returns (WaitResponse);
        rpc Stats(StatsRequest) returns (StatsResponse);
}

Shim Inputs

Bundle

The OCI bundle is still the main source of configuration for shims.
The shim should not write to any other location on disk except the bundle.
The bundle can be used as a workspace for the shim with any additional state.

├── io.containerd.runtime.v2
│   └── default
│       └── redis
│           ├── config.json
│           └── rootfs/

Configuration

Configuration for shims can be passed via Opts or defaults defined within
the containerd /etc/containerd/config.toml.

Shim Outputs

GRPC

The shim grpc service is the main source of interaction with the shim.
The shim is also expected to write a shim.pid file for containerd to read in case
it is no longer able to access the shim via the GRPC api.
This pid will be used to SIGKILL the shim in case of a forceful shutdown.

UX

> ctr run --runtime io.containerd.runtime.v2.process
> ctr run --runtime io.containerd.runtime.v2.gvisor
> ctr run --runtime io.containerd.runtime.v2.kata
> ctr run --runtime io.containerd.runtime.v2.oci

The existing runtime will continue to work for upgrades where containers are running under v1 shims.

Measure
Measure
Related Notes
Get a free MyMarkup account to save this article and view it later on any device.
Create account

End User License Agreement

Summary | 11 Annotations
More VM based runtimes have internal state and more abstract actions
2020/06/19 11:41
state management
2020/06/19 11:42
a shim API
2020/06/19 11:42
The goals is to provide an API that various runtimes can implement to add support in containerd while still having control of state and abstract actions
2020/06/19 11:42
various runtimes
2020/06/19 11:43
state and abstract actions
2020/06/19 11:44
OCI bundle is still the main source of configuration for shims
2020/06/19 11:49
shim should not write to any other location on disk except the bundle
2020/06/19 11:49
Inputs
2020/06/19 11:50
Outputs
2020/06/19 11:50
shim grpc service is the main source of interaction with the shim
2020/06/19 11:50