[sandbox] Add basic sandbox structures and interfaces

Signed-off-by: Maksym Pavlenko <pavlenko.maksym@gmail.com>

sandbox/controller.go

@@ -0,0 +1,60 @@
+/*
+   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.
+*/
+
+package sandbox
+
+import (
+	"context"
+
+	"github.com/gogo/protobuf/types"
+)
+
+// Controller is an interface to manage a runtime sandbox instance (runtimes's SandboxManager)
+// SandboxRuntime is responsible for the sandbox instances lifecycle management.
+// When running the traditional containerd shim, the workflow looks as follows:
+// For each new task we're about to run:
+// 	1. Invoke `shim_binary --start` to obtain `TaskService` address (printed in stdout)
+// 	2. Call TaskService.RunContainer(id=1)
+// 	3. Exec `shim_binary --delete` to stop shim
+// 	4. Exec `shim_binary --start` again to obtain another `TaskService` address
+// 	5. TaskService.RunContainer(id=2)
+// 	6. Exec `shim_binary --delete` to stop shim
+//
+// When running in sandbox mode, shim must implement `SandboxService`. In sandbox mode shim lifetimes are managed manually.
+// 	1. Client calls `client.Controller.Start()` to launch new shim and create sandbox process
+// 	2. Run containers with `shim.TaskService.RunContainer(id=1)` and another one `shim.TaskService.RunContainer(id=2)`
+//	3. ... usual container lifecycle calls to `shim.TaskService`
+// 	4. Client calls shim to stop the VM with `client.SandboxService.Shutdown()`
+//  5. Shim implementation will perform cleanup similar to regular task service (e.g. shutdown, clean, and `shim_binary --delete`)
+type Controller interface {
+	// Start will start new sandbox instance.
+	// containerd will run new shim runtime instance and will invoke Start to create a sandbox process.
+	// This routine must be invoked before scheduling containers on this instance.
+	// Once started clients may run containers via Task service (additionally specifying sandbox id the container will belong to).
+	Start(ctx context.Context, sandboxID string) error
+	// Shutdown deletes and cleans all tasks and sandbox instance.
+	Shutdown(ctx context.Context, sandboxID string) error
+	// Pause will freeze running sandbox instance.
+	// Shim implementations may return ErrNotImplemented if this is out of scope of a given sandbox.
+	Pause(ctx context.Context, sandboxID string) error
+	// Resume will unfreeze previously paused sandbox instance
+	Resume(ctx context.Context, sandboxID string) error
+	// Ping is a lightweight API call to check whether sandbox instance is still alive.
+	// This should not involve any complex logic and containerd will not debug log it as it might be called quite often.
+	Ping(ctx context.Context, sandboxID string) error
+	// Status will query sandbox process status
+	Status(ctx context.Context, sandboxID string) (*types.Any, error)
+}