add containerd.services.sandbox.v1

crates/client/build.rs

@@ -22,6 +22,7 @@ const PROTO_FILES: &[&str] = &[
     "vendor/github.com/containerd/containerd/api/types/metrics.proto",
     "vendor/github.com/containerd/containerd/api/types/mount.proto",
     "vendor/github.com/containerd/containerd/api/types/platform.proto",
+    "vendor/github.com/containerd/containerd/api/types/sandbox.proto",
     "vendor/github.com/containerd/containerd/api/types/task/task.proto",
     // Services
     "vendor/github.com/containerd/containerd/api/services/containers/v1/containers.proto",
@@ -32,6 +33,7 @@ const PROTO_FILES: &[&str] = &[
     "vendor/github.com/containerd/containerd/api/services/introspection/v1/introspection.proto",
     "vendor/github.com/containerd/containerd/api/services/leases/v1/leases.proto",
     "vendor/github.com/containerd/containerd/api/services/namespaces/v1/namespace.proto",
+    "vendor/github.com/containerd/containerd/api/services/sandbox/v1/sandbox.proto",
     "vendor/github.com/containerd/containerd/api/services/snapshots/v1/snapshots.proto",
     "vendor/github.com/containerd/containerd/api/services/version/v1/version.proto",
     "vendor/github.com/containerd/containerd/api/services/tasks/v1/tasks.proto",
@@ -48,6 +50,7 @@ const FIXUP_MODULES: &[&str] = &[
     "containerd.services.diff.v1",
     "containerd.services.images.v1",
     "containerd.services.introspection.v1",
+    "containerd.services.sandbox.v1",
     "containerd.services.snapshots.v1",
     "containerd.services.tasks.v1",
 ];

crates/client/src/lib.rs

@@ -49,6 +49,7 @@ pub mod services {
         tonic::include_proto!("containerd.services.introspection.v1");
         tonic::include_proto!("containerd.services.leases.v1");
         tonic::include_proto!("containerd.services.namespaces.v1");
+        tonic::include_proto!("containerd.services.sandbox.v1");
         tonic::include_proto!("containerd.services.tasks.v1");
 
         // Snapshot's `Info` conflicts with Content's `Info`, so wrap it into a separate sub module.

crates/client/vendor/github.com/containerd/containerd/api/services/sandbox/v1/sandbox.proto

@@ -0,0 +1,163 @@
+/*
+	Copyright The containerd Authors.
+
+	Licensed under the Apache License, Version 2.0 (the "License");
+	you may not use this file except in compliance with the License.
+	You may obtain a copy of the License at
+
+		http://www.apache.org/licenses/LICENSE-2.0
+
+	Unless required by applicable law or agreed to in writing, software
+	distributed under the License is distributed on an "AS IS" BASIS,
+	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	See the License for the specific language governing permissions and
+	limitations under the License.
+*/
+
+syntax = "proto3";
+
+// Sandbox is a v2 runtime extension that allows more complex execution environments for containers.
+// This adds a notion of groups of containers that share same lifecycle and/or resources.
+// A few good fits for sandbox can be:
+// - A "pause" container in k8s, that acts as a parent process for child containers to hold network namespace.
+// - (micro)VMs that launch a VM process and executes containers inside guest OS.
+// containerd in this case remains implementation agnostic and delegates sandbox handling to runtimes.
+// See proposal and discussion here: https://github.com/containerd/containerd/issues/4131
+package containerd.services.sandbox.v1;
+
+import "google/protobuf/any.proto";
+import "google/protobuf/timestamp.proto";
+
+import "github.com/containerd/containerd/api/types/sandbox.proto";
+import "github.com/containerd/containerd/api/types/mount.proto";
+import "github.com/containerd/containerd/api/types/platform.proto";
+
+option go_package = "github.com/containerd/containerd/api/services/sandbox/v1;sandbox";
+
+// Store provides a metadata storage interface for sandboxes. Similarly to `Containers`,
+// sandbox object includes info required to start a new instance, but no runtime state.
+// When running a new sandbox instance, store objects are used as base type to create from.
+service Store {
+	rpc Create(StoreCreateRequest) returns (StoreCreateResponse);
+	rpc Update(StoreUpdateRequest) returns (StoreUpdateResponse);
+	rpc Delete(StoreDeleteRequest) returns (StoreDeleteResponse);
+	rpc List(StoreListRequest) returns (StoreListResponse);
+	rpc Get(StoreGetRequest) returns (StoreGetResponse);
+}
+
+message StoreCreateRequest {
+	containerd.types.Sandbox sandbox = 1;
+}
+
+message StoreCreateResponse {
+	containerd.types.Sandbox sandbox = 1;
+}
+
+message StoreUpdateRequest {
+	containerd.types.Sandbox sandbox = 1;
+	repeated string fields = 2;
+}
+
+message StoreUpdateResponse {
+	containerd.types.Sandbox sandbox = 1;
+}
+
+message StoreDeleteRequest {
+	string sandbox_id = 1;
+}
+
+message StoreDeleteResponse {}
+
+message StoreListRequest {
+	repeated string filters = 1;
+}
+
+message StoreListResponse {
+	repeated containerd.types.Sandbox list = 1;
+}
+
+message StoreGetRequest {
+	string sandbox_id = 1;
+}
+
+message StoreGetResponse {
+	containerd.types.Sandbox sandbox = 1;
+}
+
+// Controller is an interface to manage runtime sandbox instances.
+service Controller {
+	rpc Create(ControllerCreateRequest) returns (ControllerCreateResponse);
+	rpc Start(ControllerStartRequest) returns (ControllerStartResponse);
+	rpc Platform(ControllerPlatformRequest) returns (ControllerPlatformResponse);
+	rpc Stop(ControllerStopRequest) returns (ControllerStopResponse);
+	rpc Wait(ControllerWaitRequest) returns (ControllerWaitResponse);
+	rpc Status(ControllerStatusRequest) returns (ControllerStatusResponse);
+	rpc Shutdown(ControllerShutdownRequest) returns (ControllerShutdownResponse);
+}
+
+message ControllerCreateRequest {
+	string sandbox_id = 1;
+	repeated containerd.types.Mount rootfs = 2;
+	google.protobuf.Any options = 3;
+	string netns_path = 4;
+}
+
+message ControllerCreateResponse {
+	string sandbox_id = 1;
+}
+
+message ControllerStartRequest {
+	string sandbox_id = 1;
+}
+
+message ControllerStartResponse {
+	string sandbox_id = 1;
+	uint32 pid = 2;
+	google.protobuf.Timestamp created_at = 3;
+	map<string, string> labels = 4;
+}
+
+message ControllerPlatformRequest {
+	string sandbox_id = 1;
+}
+
+message ControllerPlatformResponse {
+	containerd.types.Platform platform = 1;
+}
+
+message ControllerStopRequest {
+	string sandbox_id = 1;
+	uint32 timeout_secs = 2;
+}
+
+message ControllerStopResponse {}
+
+message ControllerWaitRequest {
+	string sandbox_id = 1;
+}
+
+message ControllerWaitResponse {
+	uint32 exit_status = 1;
+	google.protobuf.Timestamp exited_at = 2;
+}
+
+message ControllerStatusRequest {
+	string sandbox_id = 1;
+	bool verbose = 2;
+}
+
+message ControllerStatusResponse {
+	string sandbox_id = 1;
+	uint32 pid = 2;
+	string state = 3;
+	map<string, string> info = 4;
+	google.protobuf.Timestamp created_at = 5;
+	google.protobuf.Timestamp exited_at = 6;
+	google.protobuf.Any extra = 7;
+}
+
+message ControllerShutdownRequest {
+	string sandbox_id = 1;
+}
+
+message ControllerShutdownResponse {}

crates/client/vendor/github.com/containerd/containerd/api/types/sandbox.proto

@@ -0,0 +1,51 @@
+/*
+	Copyright The containerd Authors.
+
+	Licensed under the Apache License, Version 2.0 (the "License");
+	you may not use this file except in compliance with the License.
+	You may obtain a copy of the License at
+
+		http://www.apache.org/licenses/LICENSE-2.0
+
+	Unless required by applicable law or agreed to in writing, software
+	distributed under the License is distributed on an "AS IS" BASIS,
+	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	See the License for the specific language governing permissions and
+	limitations under the License.
+*/
+
+syntax = "proto3";
+
+package containerd.types;
+
+import "google/protobuf/any.proto";
+import "google/protobuf/timestamp.proto";
+
+option go_package = "github.com/containerd/containerd/api/types;types";
+
+// Sandbox represents a sandbox metadata object that keeps all info required by controller to
+// work with a particular instance.
+message Sandbox {
+    // SandboxID is a unique instance identifier within namespace
+    string sandbox_id = 1;
+    message Runtime {
+        // Name is the name of the runtime.
+        string name = 1;
+        // Options specify additional runtime initialization options for the shim (this data will be available in StartShim).
+        // Typically this data expected to be runtime shim implementation specific.
+        google.protobuf.Any options = 2;
+    }
+    // Runtime specifies which runtime to use for executing this container.
+    Runtime runtime = 2;
+    // Spec is sandbox configuration (kin of OCI runtime spec), spec's data will be written to a config.json file in the
+    // bundle directory (similary to OCI spec).
+    google.protobuf.Any spec = 3;
+    // Labels provides an area to include arbitrary data on containers.
+    map<string, string> labels  = 4;
+    // CreatedAt is the time the container was first created.
+    google.protobuf.Timestamp created_at = 5;
+    // UpdatedAt is the last time the container was mutated.
+    google.protobuf.Timestamp updated_at = 6;
+    // Extensions allow clients to provide optional blobs that can be handled by runtime.
+    map<string, google.protobuf.Any> extensions = 7;
+}