containerd/api/services/execution/execution.proto

syntax = "proto3";

package containerd.services.tasks.v1;

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 {
	// Create a task.
	rpc Create(CreateTaskRequest) returns (CreateTaskResponse);

	// Start a task.
	rpc Start(StartTaskRequest) returns (google.protobuf.Empty);

	// Delete a task and on disk state.
	rpc Delete(DeleteTaskRequest) returns (DeleteResponse);

	rpc DeleteProcess(DeleteProcessRequest) returns (DeleteResponse);

	rpc Get(GetTaskRequest) returns (GetTaskResponse);

	rpc List(ListTasksRequest) returns (ListTasksResponse);

	// Kill a task or process.
	rpc Kill(KillRequest) returns (google.protobuf.Empty);

	rpc Exec(ExecProcessRequest) returns (ExecProcessResponse);

	rpc ResizePty(ResizePtyRequest) returns (google.protobuf.Empty);

	rpc CloseIO(CloseIORequest) returns (google.protobuf.Empty);

	rpc Pause(PauseTaskRequest) returns (google.protobuf.Empty);

	rpc Resume(ResumeTaskRequest) returns (google.protobuf.Empty);

	rpc ListProcesses(ListProcessesRequest) returns (ListProcessesResponse);

	rpc Checkpoint(CheckpointTaskRequest) returns (CheckpointTaskResponse);
}

message CreateTaskRequest {
	// NOTE: reserve field 1 for task id.

	// 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.
	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 = 4;
	string stdout = 5;
	string stderr = 6;
	bool terminal = 7;

	containerd.v1.types.Descriptor checkpoint = 8;
}

message CreateTaskResponse {
	// 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 StartTaskRequest {
	string container_id = 1;
}

message DeleteTaskRequest {
	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 DeleteProcessRequest {
	string container_id = 1;
	uint32 pid = 2;
}

message GetTaskRequest {
	string container_id = 1;
}

message GetTaskResponse {
	containerd.v1.types.Task task = 1;
}

message ListTasksRequest {
	string filter = 1;
}

message ListTasksResponse {
	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 ExecProcessRequest {
	// ContainerID specifies the container in which to exec the process.
	string container_id = 1;

	string stdin = 2;
	string stdout = 3;
	string stderr = 4;
	bool terminal = 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 ExecProcessResponse {
	uint32 pid = 1;
}

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

message CloseIORequest {
	string container_id = 1;
	uint32 pid = 2;
	bool stdin = 3;
}

message PauseTaskRequest {
	string container_id = 1;
}

message ResumeTaskRequest {
	string container_id = 1;
}

message ListProcessesRequest {
	string container_id = 1;
}

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

message CheckpointTaskRequest {
	string container_id = 1;
	string parent_checkpoint = 2 [(gogoproto.customtype) = "github.com/opencontainers/go-digest.Digest", (gogoproto.nullable) = false];
	map<string, string> options = 3;
}

message CheckpointTaskResponse {
	repeated containerd.v1.types.Descriptor descriptors = 1;
}