[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)
+}

sandbox/helpers.go

@@ -0,0 +1,53 @@
+/*
+   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 (
+	"github.com/containerd/containerd/api/types"
+)
+
+// ToProto will map Sandbox struct to it's protobuf definition
+func ToProto(s *Sandbox) types.Sandbox {
+	return types.Sandbox{
+		SandboxID: s.ID,
+		Runtime: types.Sandbox_Runtime{
+			Name:    s.Runtime.Name,
+			Options: s.Runtime.Options,
+		},
+		Labels:     s.Labels,
+		CreatedAt:  s.CreatedAt,
+		UpdatedAt:  s.UpdatedAt,
+		Extensions: s.Extensions,
+	}
+}
+
+// FromProto map protobuf sandbox definition to Sandbox struct
+func FromProto(p *types.Sandbox) Sandbox {
+	runtime := RuntimeOpts{
+		Name:    p.Runtime.Name,
+		Options: p.Runtime.Options,
+	}
+
+	return Sandbox{
+		ID:         p.SandboxID,
+		Labels:     p.Labels,
+		Runtime:    runtime,
+		CreatedAt:  p.CreatedAt,
+		UpdatedAt:  p.UpdatedAt,
+		Extensions: p.Extensions,
+	}
+}

sandbox/store.go

@@ -0,0 +1,66 @@
+/*
+   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"
+	"time"
+
+	"github.com/gogo/protobuf/types"
+)
+
+// Sandbox is an object stored in metadata database
+type Sandbox struct {
+	// ID uniquely identifies the sandbox in a namespace
+	ID string
+	// Labels provide metadata extension for a sandbox
+	Labels map[string]string
+	// Runtime shim to use for this sandbox
+	Runtime RuntimeOpts
+	// Spec carries the runtime specification used to implement the sandbox
+	Spec *types.Any
+	// CreatedAt is the time at which the sandbox was created
+	CreatedAt time.Time
+	// UpdatedAt is the time at which the sandbox was updated
+	UpdatedAt time.Time
+	// Extensions stores client-specified metadata
+	Extensions map[string]types.Any
+}
+
+// RuntimeOpts holds runtime specific information
+type RuntimeOpts struct {
+	Name    string
+	Options *types.Any
+}
+
+// Store is a storage interface for sandbox metadata objects
+type Store interface {
+	// Create a sandbox record in the store
+	Create(ctx context.Context, sandbox Sandbox) (Sandbox, error)
+
+	// Update the sandbox with the provided sandbox object and fields
+	Update(ctx context.Context, sandbox Sandbox, fieldpaths ...string) (Sandbox, error)
+
+	// Get sandbox metadata using the id
+	Get(ctx context.Context, id string) (Sandbox, error)
+
+	// List returns sandboxes that match one or more of the provided filters
+	List(ctx context.Context, filters ...string) ([]Sandbox, error)
+
+	// Delete a sandbox from metadata store using the id
+	Delete(ctx context.Context, id string) error
+}