api/services/execution/execution.proto

syntax = "proto3";

package containerd.v1.services.execution;

import "google/protobuf/empty.proto";
import "google/protobuf/any.proto";
import "gogoproto/gogo.proto";
import "github.com/containerd/containerd/api/types/mount/mount.proto";
import "github.com/containerd/containerd/api/types/descriptor/descriptor.proto";
import "github.com/containerd/containerd/api/types/task/task.proto";
import "google/protobuf/timestamp.proto";

service Tasks {
	rpc Create(CreateRequest) returns (CreateResponse);
	rpc Start(StartRequest) returns (google.protobuf.Empty);
	rpc Delete(DeleteRequest) returns (DeleteResponse);
	rpc Info(InfoRequest) returns (InfoResponse);
	rpc List(ListRequest) returns (ListResponse);
	rpc Kill(KillRequest) returns (google.protobuf.Empty);
	rpc Events(EventsRequest) returns (stream containerd.v1.types.Event);
	rpc Exec(ExecRequest) returns (ExecResponse);
	rpc Pty(PtyRequest) returns (google.protobuf.Empty);
	rpc CloseStdin(CloseStdinRequest) returns (google.protobuf.Empty);
	rpc Pause(PauseRequest) returns (google.protobuf.Empty);
	rpc Resume(ResumeRequest) returns (google.protobuf.Empty);
	rpc Processes(ProcessesRequest) returns (ProcessesResponse);
	rpc Checkpoint(CheckpointRequest) returns (CheckpointResponse);
}

message CreateRequest {
	// ContainerID specifies the container to use for creating this task.
	//
	// The spec from the provided container id will be used to create the
	// task associated with this container. Only one task can be run at a time
	// per container.
	//
	// This should be created using the Containers service.
	string container_id = 2;

	// RootFS provides the pre-chroot mounts to perform in the shim before
	// executing the container task.
	//
	// These are for mounts that cannot be performed in the user namespace.
	// Typically, these mounts should be resolved from snapshots specified on
	// the container object.
	repeated containerd.v1.types.Mount rootfs = 3;

	string stdin = 5;
	string stdout = 6;
	string stderr = 7;
	bool terminal = 8;

	types.Descriptor checkpoint = 9;
}

message CreateResponse {
	// TODO(stevvooe): We no longer have an id for a task since they are bound
	// to a single container. Although, we should represent each new task with
	// an ID so one can differentiate between each instance of a container
	// running.
	//
	// Hence, we are leaving this here and reserving the field number in case
	// we need to move in this direction.
	// string id = 1;

	string container_id = 2;
	uint32 pid = 3;
}

message StartRequest {
	string container_id = 1;
}

message DeleteRequest {
	string container_id = 1;
}

message DeleteResponse {
	string container_id = 1;
	uint32 exit_status = 2;
	google.protobuf.Timestamp exited_at = 3 [(gogoproto.stdtime) = true, (gogoproto.nullable) = false];
}

message InfoRequest {
	string container_id = 1;
}

message InfoResponse {
	types.Task task = 1;
}

message ListRequest {
}

message ListResponse {
	repeated containerd.v1.types.Task tasks = 1;
}

message KillRequest {
	string container_id = 1;
	uint32 signal = 2;
	oneof pid_or_all {
	    bool all = 3;
	    uint32 pid = 4;
	}
}

message EventsRequest {
}

message ExecRequest {
	// ContainerID specifies the container in which to exec the process.
	string container_id = 1;
	bool terminal = 2;
	string stdin = 3;
	string stdout = 4;
	string stderr = 5;

	// Spec for starting a process in the target container.
	//
	// For runc, this is a process spec, for example.
	google.protobuf.Any spec = 6;
}

message ExecResponse {
	uint32 pid = 1;
}

message PtyRequest {
	string container_id = 1;
	uint32 pid = 2;
	uint32 width = 3;
	uint32 height = 4;
}

message CloseStdinRequest {
	string container_id = 1;
	uint32 pid = 2;
}

message PauseRequest {
	string container_id = 1;
}

message ResumeRequest {
	string container_id = 1;
}

message ProcessesRequest {
	string container_id = 1;
}

message ProcessesResponse{
	repeated containerd.v1.types.Process processes = 1;
}

message CheckpointRequest {
	string container_id = 1;
	bool allow_tcp = 2;
	bool allow_unix_sockets = 3;
	bool allow_terminal = 4;
	bool file_locks = 5;
	repeated string empty_namespaces = 6;
	string parent_checkpoint = 7 [(gogoproto.customtype) = "github.com/opencontainers/go-digest.Digest", (gogoproto.nullable) = false];
	bool exit = 8;
}

message CheckpointResponse {
	repeated types.Descriptor descriptors = 1;
}