Skip to content

Commit 5397428

Browse files
stevvooestevvooe
committed
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]>
1 parent 8f3b89c commit 5397428

47 files changed

Lines changed: 4057 additions & 1105 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎api/services/containers/containers.pb.go‎

Lines changed: 2206 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎api/services/containers/containers.proto‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
syntax = "proto3";
2+
3+
package containerd.v1;
4+
5+
import "gogoproto/gogo.proto";
6+
import "google/protobuf/any.proto";
7+
import "google/protobuf/empty.proto";
8+
import "google/protobuf/field_mask.proto";
9+
import "github.com/containerd/containerd/api/types/descriptor/descriptor.proto";
10+
11+
// Containers provides metadata storage for containers used in the execution
12+
// service.
13+
//
14+
// The objects here provide an state-independent view of containers for use in
15+
// management and resource pinning. From that perspective, contaienrs do not
16+
// have a "state" but rather this is the set of resources that will be
17+
// considered in use by the container.
18+
//
19+
// From the perspective of the execution service, these objects represent the
20+
// base parameters for creating a container process.
21+
//
22+
// In general, when looking to add fields for this type, first ask yourself
23+
// whether or not the function of the field has to do with runtime execution or
24+
// is invariant of the runtime state of the container. If it has to do with
25+
// runtime, or changes as the "container" is started and stops, it probably
26+
// doesn't belong on this object.
27+
service Containers {
28+
rpc Get(GetContainerRequest) returns (GetContainerResponse);
29+
rpc List(ListContainersRequest) returns (ListContainersResponse);
30+
rpc Create(CreateContainerRequest) returns (CreateContainerResponse);
31+
rpc Update(UpdateContainerRequest) returns (UpdateContainerResponse);
32+
rpc Delete(DeleteContainerRequest) returns (google.protobuf.Empty);
33+
}
34+
35+
message Container {
36+
// ID is the user-specified identifier.
37+
//
38+
// This field may not be updated.
39+
string id = 1;
40+
41+
// Labels provides an area to include arbitrary data on containers.
42+
//
43+
// Note that to add a new value to this field, read the existing set and
44+
// include the entire result in the update call.
45+
map<string, string> labels = 2;
46+
47+
// Image contains the reference of the image used to build the
48+
// specification and snapshots for running this container.
49+
//
50+
// If this field is updated, the spec and rootfs needed to updated, as well.
51+
string image = 3;
52+
53+
// Runtime specifies which runtime to use for executing this container.
54+
string runtime = 4;
55+
56+
// Spec to be used when creating the container. This is runtime specific.
57+
google.protobuf.Any spec = 6;
58+
59+
// RootFS specifies the snapshot key to use for the container's root
60+
// filesystem. When starting a task from this container, a caller should
61+
// look up the mounts from the snapshot service and include those on the
62+
// task create request.
63+
//
64+
// Snapshots referenced in this field will not be garbage collected.
65+
//
66+
// This field may be updated.
67+
string rootfs = 7 [(gogoproto.customname) = "RootFS"];
68+
}
69+
70+
message GetContainerRequest {
71+
string id = 1;
72+
}
73+
74+
message GetContainerResponse {
75+
Container container = 1 [(gogoproto.nullable) = false];
76+
}
77+
78+
message ListContainersRequest {
79+
string filter = 1; // TODO(stevvooe): Define a filtering syntax to make these queries.
80+
}
81+
82+
message ListContainersResponse {
83+
repeated Container containers = 1 [(gogoproto.nullable) = false];
84+
}
85+
86+
message CreateContainerRequest {
87+
Container container = 1 [(gogoproto.nullable) = false];
88+
}
89+
90+
message CreateContainerResponse {
91+
Container container = 1 [(gogoproto.nullable) = false];
92+
}
93+
94+
// UpdateContainerRequest updates the metadata on one or more container.
95+
//
96+
// The operation should follow semantics described in
97+
// https://developers.google.com/protocol-buffers/docs/reference/csharp/class/google/protobuf/well-known-types/field-mask,
98+
// unless otherwise qualified.
99+
message UpdateContainerRequest {
100+
// Container provides the target values, as declared by the mask, for the update.
101+
//
102+
// The ID field must be set.
103+
Container container = 1 [(gogoproto.nullable) = false];
104+
105+
// UpdateMask specifies which fields to perform the update on. If empty,
106+
// the operation applies to all fields.
107+
google.protobuf.FieldMask update_mask = 2;
108+
}
109+
110+
message UpdateContainerResponse {
111+
Container container = 1 [(gogoproto.nullable) = false];
112+
}
113+
114+
message DeleteContainerRequest {
115+
string id = 1;
116+
}

‎api/services/execution/execution.pb.go‎

Lines changed: 546 additions & 476 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎api/services/execution/execution.proto‎

Lines changed: 54 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
11
syntax = "proto3";
22

3-
package containerd.v1.services;
3+
package containerd.v1.services.execution;
44

55
import "google/protobuf/empty.proto";
66
import "google/protobuf/any.proto";
77
import "gogoproto/gogo.proto";
88
import "github.com/containerd/containerd/api/types/mount/mount.proto";
9-
import "github.com/containerd/containerd/api/types/container/container.proto";
109
import "github.com/containerd/containerd/api/types/descriptor/descriptor.proto";
10+
import "github.com/containerd/containerd/api/types/task/task.proto";
1111
import "google/protobuf/timestamp.proto";
1212

13-
service ContainerService {
13+
service Tasks {
1414
rpc Create(CreateRequest) returns (CreateResponse);
1515
rpc Start(StartRequest) returns (google.protobuf.Empty);
1616
rpc Delete(DeleteRequest) returns (DeleteResponse);
17-
rpc Info(InfoRequest) returns (containerd.v1.types.Container);
17+
rpc Info(InfoRequest) returns (InfoResponse);
1818
rpc List(ListRequest) returns (ListResponse);
1919
rpc Kill(KillRequest) returns (google.protobuf.Empty);
2020
rpc Events(EventsRequest) returns (stream containerd.v1.types.Event);
@@ -28,49 +28,76 @@ service ContainerService {
2828
}
2929

3030
message CreateRequest {
31-
string id = 1;
32-
google.protobuf.Any spec = 2;
31+
// ContainerID specifies the container to use for creating this task.
32+
//
33+
// The spec from the provided container id will be used to create the
34+
// task associated with this container. Only one task can be run at a time
35+
// per container.
36+
//
37+
// This should be created using the Containers service.
38+
string container_id = 2;
39+
40+
// RootFS provides the pre-chroot mounts to perform in the shim before
41+
// executing the container task.
42+
//
43+
// These are for mounts that cannot be performed in the user namespace.
44+
// Typically, these mounts should be resolved from snapshots specified on
45+
// the container object.
3346
repeated containerd.v1.types.Mount rootfs = 3;
34-
string runtime = 4;
47+
3548
string stdin = 5;
3649
string stdout = 6;
3750
string stderr = 7;
3851
bool terminal = 8;
52+
3953
types.Descriptor checkpoint = 9;
4054
}
4155

4256
message CreateResponse {
43-
string id = 1;
44-
uint32 pid = 2;
57+
// TODO(stevvooe): We no longer have an id for a task since they are bound
58+
// to a single container. Although, we should represent each new task with
59+
// an ID so one can differentiate between each instance of a container
60+
// running.
61+
//
62+
// Hence, we are leaving this here and reserving the field number in case
63+
// we need to move in this direction.
64+
// string id = 1;
65+
66+
string container_id = 2;
67+
uint32 pid = 3;
4568
}
4669

4770
message StartRequest {
48-
string id = 1;
71+
string container_id = 1;
4972
}
5073

5174
message DeleteRequest {
52-
string id = 1;
75+
string container_id = 1;
5376
}
5477

5578
message DeleteResponse {
56-
string id = 1;
79+
string container_id = 1;
5780
uint32 exit_status = 2;
5881
google.protobuf.Timestamp exited_at = 3 [(gogoproto.stdtime) = true, (gogoproto.nullable) = false];
5982
}
6083

6184
message InfoRequest {
62-
string id = 1;
85+
string container_id = 1;
86+
}
87+
88+
message InfoResponse {
89+
types.Task task = 1;
6390
}
6491

6592
message ListRequest {
6693
}
6794

6895
message ListResponse {
69-
repeated containerd.v1.types.Container containers = 1;
96+
repeated containerd.v1.types.Task tasks = 1;
7097
}
7198

7299
message KillRequest {
73-
string id = 1;
100+
string container_id = 1;
74101
uint32 signal = 2;
75102
oneof pid_or_all {
76103
bool all = 3;
@@ -82,11 +109,16 @@ message EventsRequest {
82109
}
83110

84111
message ExecRequest {
85-
string id = 1;
112+
// ContainerID specifies the container in which to exec the process.
113+
string container_id = 1;
86114
bool terminal = 2;
87115
string stdin = 3;
88116
string stdout = 4;
89117
string stderr = 5;
118+
119+
// Spec for starting a process in the target container.
120+
//
121+
// For runc, this is a process spec, for example.
90122
google.protobuf.Any spec = 6;
91123
}
92124

@@ -95,35 +127,35 @@ message ExecResponse {
95127
}
96128

97129
message PtyRequest {
98-
string id = 1;
130+
string container_id = 1;
99131
uint32 pid = 2;
100132
uint32 width = 3;
101133
uint32 height = 4;
102134
}
103135

104136
message CloseStdinRequest {
105-
string id = 1;
137+
string container_id = 1;
106138
uint32 pid = 2;
107139
}
108140

109141
message PauseRequest {
110-
string id = 1;
142+
string container_id = 1;
111143
}
112144

113145
message ResumeRequest {
114-
string id = 1;
146+
string container_id = 1;
115147
}
116148

117149
message ProcessesRequest {
118-
string id = 1;
150+
string container_id = 1;
119151
}
120152

121153
message ProcessesResponse{
122154
repeated containerd.v1.types.Process processes = 1;
123155
}
124156

125157
message CheckpointRequest {
126-
string id = 1;
158+
string container_id = 1;
127159
bool allow_tcp = 2;
128160
bool allow_unix_sockets = 3;
129161
bool allow_terminal = 4;

0 commit comments

Comments
 (0)