[proposal] Shim API v2 #2426
Description
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.ociThe existing runtime will continue to work for upgrades where containers are running under v1 shims.