Merge pull request #145 from wllenyj/sandbox

shim: add Sandbox API support

crates/shim-protos/Cargo.toml

@@ -28,6 +28,7 @@ tokio = { workspace = true, features = ["full"] }
 [features]
 default = []
 async = ["ttrpc/async", "async-trait"]
+sandbox = []
 
 [[example]]
 name = "shim-proto-server"

crates/shim-protos/build.rs

@@ -32,6 +32,8 @@ fn main() {
             "vendor/github.com/containerd/containerd/protobuf/plugin/fieldpath.proto",
             "vendor/github.com/containerd/containerd/api/types/mount.proto",
             "vendor/github.com/containerd/containerd/api/types/task/task.proto",
+            #[cfg(feature = "sandbox")]
+            "vendor/github.com/containerd/containerd/api/types/platform.proto",
         ],
         false,
     );
@@ -77,6 +79,22 @@ fn main() {
             true,
         );
     }
+
+    #[cfg(feature = "sandbox")]
+    {
+        genmodule(
+            "sandbox",
+            &["vendor/github.com/containerd/containerd/runtime/sandbox/v1/sandbox.proto"],
+            false,
+        );
+
+        #[cfg(feature = "async")]
+        genmodule(
+            "sandbox_async",
+            &["vendor/github.com/containerd/containerd/runtime/sandbox/v1/sandbox.proto"],
+            true,
+        );
+    }
 }
 
 fn genmodule(name: &str, inputs: &[&str], async_all: bool) {

crates/shim-protos/src/lib.rs

@@ -67,6 +67,8 @@ pub use ttrpc;
 
 pub mod cgroups;
 pub mod events;
+#[cfg(feature = "sandbox")]
+mod sandbox;
 pub mod shim;
 pub mod types;
 
@@ -100,3 +102,16 @@ pub mod shim_async {
 pub mod api {
     pub use crate::shim::{empty::*, events::*, mount::*, shim::*, task::*};
 }
+
+#[cfg(feature = "sandbox")]
+pub use sandbox::sandbox as sandbox_api;
+
+#[cfg(feature = "sandbox")]
+pub mod sandbox_sync {
+    pub use crate::sandbox::sandbox_ttrpc::*;
+}
+
+#[cfg(all(feature = "sandbox", feature = "async"))]
+pub mod sandbox_async {
+    pub use crate::sandbox::sandbox_async::*;
+}

crates/shim-protos/src/sandbox.rs

@@ -0,0 +1,36 @@
+/*
+   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.
+*/
+
+pub mod sandbox {
+    include!(concat!(env!("OUT_DIR"), "/sandbox/sandbox.rs"));
+}
+
+pub mod sandbox_ttrpc {
+    include!(concat!(env!("OUT_DIR"), "/sandbox/sandbox_ttrpc.rs"));
+}
+
+#[cfg(feature = "async")]
+pub mod sandbox_async {
+    include!(concat!(env!("OUT_DIR"), "/sandbox_async/sandbox_ttrpc.rs"));
+}
+
+pub(crate) mod mount {
+    pub use crate::types::mount::*;
+}
+
+pub(crate) mod platform {
+    pub use crate::types::platform::*;
+}

crates/shim-protos/src/types.rs

@@ -33,3 +33,8 @@ pub mod task {
 pub mod fieldpath {
     include!(concat!(env!("OUT_DIR"), "/types/fieldpath.rs"));
 }
+
+#[cfg(feature = "sandbox")]
+pub mod platform {
+    include!(concat!(env!("OUT_DIR"), "/types/platform.rs"));
+}

crates/shim-protos/vendor/github.com/containerd/containerd/runtime/sandbox/v1/sandbox.proto

@@ -0,0 +1,136 @@
+/*
+	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.runtime.sandbox.v1;
+
+import "google/protobuf/any.proto";
+import "google/protobuf/timestamp.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/runtime/sandbox/v1;sandbox";
+
+// Sandbox is an optional interface that shim may implement to support sandboxes environments.
+// A typical example of sandbox is microVM or pause container - an entity that groups containers and/or
+// holds resources relevant for this group.
+service Sandbox {
+	// CreateSandbox will be called right after sandbox shim instance launched.
+	// It is a good place to initialize sandbox environment.
+	rpc CreateSandbox(CreateSandboxRequest) returns (CreateSandboxResponse);
+
+	// StartSandbox will start previsouly created sandbox.
+	rpc StartSandbox(StartSandboxRequest) returns (StartSandboxResponse);
+
+	// Platform queries the platform the sandbox is going to run containers on.
+	// containerd will use this to generate a proper OCI spec.
+	rpc Platform(PlatformRequest) returns (PlatformResponse);
+
+	// StopSandbox will stop existing sandbox instance
+	rpc StopSandbox(StopSandboxRequest) returns (StopSandboxResponse);
+
+	// WaitSandbox blocks until sanbox exits.
+	rpc WaitSandbox(WaitSandboxRequest) returns (WaitSandboxResponse);
+
+	// SandboxStatus will return current status of the running sandbox instance
+	rpc SandboxStatus(SandboxStatusRequest) returns (SandboxStatusResponse);
+
+	// PingSandbox is a lightweight API call to check whether sandbox alive.
+	rpc PingSandbox(PingRequest) returns (PingResponse);
+
+	// ShutdownSandbox must shutdown shim instance.
+	rpc ShutdownSandbox(ShutdownSandboxRequest) returns (ShutdownSandboxResponse);
+}
+
+message CreateSandboxRequest {
+	string sandbox_id = 1;
+	string bundle_path = 2;
+	repeated containerd.types.Mount rootfs = 3;
+	google.protobuf.Any options = 4;
+	string netns_path = 5;
+}
+
+message CreateSandboxResponse {}
+
+message StartSandboxRequest {
+	string sandbox_id = 1;
+}
+
+message StartSandboxResponse {
+	uint32 pid = 1;
+	google.protobuf.Timestamp created_at = 2;
+}
+
+message PlatformRequest {
+	string sandbox_id = 1;
+}
+
+message PlatformResponse {
+	containerd.types.Platform platform = 1;
+}
+
+message StopSandboxRequest {
+	string sandbox_id = 1;
+	uint32 timeout_secs = 2;
+}
+
+message StopSandboxResponse {}
+
+message UpdateSandboxRequest {
+	string sandbox_id = 1;
+	google.protobuf.Any resources = 2;
+	map<string, string> annotations = 3;
+}
+
+message WaitSandboxRequest {
+	string sandbox_id = 1;
+}
+
+message WaitSandboxResponse {
+	uint32 exit_status = 1;
+	google.protobuf.Timestamp exited_at = 2;
+}
+
+message UpdateSandboxResponse {}
+
+message SandboxStatusRequest {
+	string sandbox_id = 1;
+	bool verbose = 2;
+}
+
+message SandboxStatusResponse {
+	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 PingRequest {
+	string sandbox_id = 1;
+}
+
+message PingResponse {}
+
+message ShutdownSandboxRequest {
+	string sandbox_id = 1;
+}
+
+message ShutdownSandboxResponse {}