api/services: define the container metadata service

Working from feedback on the existing implementation, we have now
introduced a central metadata object to represent the lifecycle and pin
the resources required to implement what people today know as
containers. This includes the runtime specification and the root
filesystem snapshots. We also allow arbitrary labeling of the container.
Such provisions will bring the containerd definition of container closer
to what is expected by users.

The objects that encompass today's ContainerService, centered around the
runtime, will be known as tasks. These tasks take on the existing
lifecycle behavior of containerd's containers, which means that they are
deleted when they exit. Largely, there are no other changes except for
naming.

The `Container` object will operate purely as a metadata object. No
runtime state will be held on `Container`. It only informs the execution
service on what is required for creating tasks and the resources in use
by that container. The resources referenced by that container will be
deleted when the container is deleted, if not in use. In this sense,
users can create, list, label and delete containers in a similar way as
they do with docker today, without the complexity of runtime locks that
plagues current implementations.

Signed-off-by: Stephen J Day <[email protected]>

api/services/containers/containers.proto

@@ -0,0 +1,116 @@
+syntax = "proto3";
+
+package containerd.v1;
+
+import "gogoproto/gogo.proto";
+import "google/protobuf/any.proto";
+import "google/protobuf/empty.proto";
+import "google/protobuf/field_mask.proto";
+import "github.com/containerd/containerd/api/types/descriptor/descriptor.proto";
+
+// Containers provides metadata storage for containers used in the execution
+// service.
+//
+// The objects here provide an state-independent view of containers for use in
+// management and resource pinning. From that perspective, contaienrs do not
+// have a "state" but rather this is the set of resources that will be
+// considered in use by the container.
+//
+// From the perspective of the execution service, these objects represent the
+// base parameters for creating a container process.
+//
+// In general, when looking to add fields for this type, first ask yourself
+// whether or not the function of the field has to do with runtime execution or
+// is invariant of the runtime state of the container. If it has to do with
+// runtime, or changes as the "container" is started and stops, it probably
+// doesn't belong on this object.
+service Containers {
+	rpc Get(GetContainerRequest) returns (GetContainerResponse);
+	rpc List(ListContainersRequest) returns (ListContainersResponse);
+	rpc Create(CreateContainerRequest) returns (CreateContainerResponse);
+	rpc Update(UpdateContainerRequest) returns (UpdateContainerResponse);
+	rpc Delete(DeleteContainerRequest) returns (google.protobuf.Empty);
+}
+
+message Container {
+	// ID is the user-specified identifier.
+	//
+	// This field may not be updated.
+	string id = 1;
+
+	// Labels provides an area to include arbitrary data on containers.
+	//
+	// Note that to add a new value to this field, read the existing set and
+	// include the entire result in the update call.
+	map<string, string> labels  = 2;
+
+	// Image contains the reference of the image used to build the
+	// specification and snapshots for running this container.
+	//
+	// If this field is updated, the spec and rootfs needed to updated, as well.
+	string image = 3;
+
+	// Runtime specifies which runtime to use for executing this container.
+	string runtime = 4;
+
+	// Spec to be used when creating the container. This is runtime specific.
+	google.protobuf.Any spec = 6;
+
+	// RootFS specifies the snapshot key to use for the container's root
+	// filesystem. When starting a task from this container, a caller should
+	// look up the mounts from the snapshot service and include those on the
+	// task create request.
+	//
+	// Snapshots referenced in this field will not be garbage collected.
+	//
+	// This field may be updated.
+	string rootfs = 7 [(gogoproto.customname) = "RootFS"];
+}
+
+message GetContainerRequest {
+	string id = 1;
+}
+
+message GetContainerResponse {
+	Container container = 1 [(gogoproto.nullable) = false];
+}
+
+message ListContainersRequest {
+	string filter = 1; // TODO(stevvooe): Define a filtering syntax to make these queries.
+}
+
+message ListContainersResponse {
+	repeated Container containers = 1 [(gogoproto.nullable) = false];
+}
+
+message CreateContainerRequest {
+	Container container = 1 [(gogoproto.nullable) = false];
+}
+
+message CreateContainerResponse {
+	Container container = 1 [(gogoproto.nullable) = false];
+}
+
+// UpdateContainerRequest updates the metadata on one or more container.
+//
+// The operation should follow semantics described in
+// https://developers.google.com/protocol-buffers/docs/reference/csharp/class/google/protobuf/well-known-types/field-mask,
+// unless otherwise qualified.
+message UpdateContainerRequest {
+	// Container provides the target values, as declared by the mask, for the update.
+	//
+	// The ID field must be set.
+	Container container = 1 [(gogoproto.nullable) = false];
+
+	// UpdateMask specifies which fields to perform the update on. If empty,
+	// the operation applies to all fields.
+	google.protobuf.FieldMask update_mask = 2;
+}
+
+message UpdateContainerResponse {
+	Container container = 1 [(gogoproto.nullable) = false];
+}
+
+message DeleteContainerRequest {
+	string id = 1;
+}

api/services/execution/execution.proto

@@ -1,20 +1,20 @@
 syntax = "proto3";
 
-package containerd.v1.services;
+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/container/container.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 ContainerService {
+service Tasks {
 	rpc Create(CreateRequest) returns (CreateResponse);
 	rpc Start(StartRequest) returns (google.protobuf.Empty);
 	rpc Delete(DeleteRequest) returns (DeleteResponse);
-	rpc Info(InfoRequest) returns (containerd.v1.types.Container);
+	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);
@@ -28,49 +28,76 @@ service ContainerService {
 }
 
 message CreateRequest {
-	string id = 1;
-	google.protobuf.Any spec = 2;
+	// 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 runtime = 4;
+
 	string stdin = 5;
 	string stdout = 6;
 	string stderr = 7;
 	bool terminal = 8;
+
 	types.Descriptor checkpoint = 9;
 }
 
 message CreateResponse {
-	string id = 1;
-	uint32 pid = 2;
+	// 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 id = 1;
+	string container_id = 1;
 }
 
 message DeleteRequest {
-	string id = 1;
+	string container_id = 1;
 }
 
 message DeleteResponse {
-	string id = 1;
+	string container_id = 1;
 	uint32 exit_status = 2;
 	google.protobuf.Timestamp exited_at = 3 [(gogoproto.stdtime) = true, (gogoproto.nullable) = false];
 }
 
 message InfoRequest {
-	string id = 1;
+	string container_id = 1;
+}
+
+message InfoResponse {
+	types.Task task = 1;
 }
 
 message ListRequest {
 }
 
 message ListResponse {
-	repeated containerd.v1.types.Container containers = 1;
+	repeated containerd.v1.types.Task tasks = 1;
 }
 
 message KillRequest {
-	string id = 1;
+	string container_id = 1;
 	uint32 signal = 2;
 	oneof pid_or_all {
 	    bool all = 3;
@@ -82,11 +109,16 @@ message EventsRequest {
 }
 
 message ExecRequest {
-	string id = 1;
+	// 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;
 }
 
@@ -95,35 +127,35 @@ message ExecResponse {
 }
 
 message PtyRequest {
-	string id = 1;
+	string container_id = 1;
 	uint32 pid = 2;
 	uint32 width = 3;
 	uint32 height = 4;
 }
 
 message CloseStdinRequest {
-	string id = 1;
+	string container_id = 1;
 	uint32 pid = 2;
 }
 
 message PauseRequest {
-	string id = 1;
+	string container_id = 1;
 }
 
 message ResumeRequest {
-	string id = 1;
+	string container_id = 1;
 }
 
 message ProcessesRequest {
-	string id = 1;
+	string container_id = 1;
 }
 
 message ProcessesResponse{
 	repeated containerd.v1.types.Process processes = 1;
 }
 
 message CheckpointRequest {
-	string id = 1;
+	string container_id = 1;
 	bool allow_tcp = 2;
 	bool allow_unix_sockets = 3;
 	bool allow_terminal = 4;