diff --git a/sandbox/controller.go b/sandbox/controller.go new file mode 100644 index 000000000..dd5f11547 --- /dev/null +++ b/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) +} diff --git a/sandbox/helpers.go b/sandbox/helpers.go new file mode 100644 index 000000000..420589cca --- /dev/null +++ b/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, + } +} diff --git a/sandbox/store.go b/sandbox/store.go new file mode 100644 index 000000000..fd467aadb --- /dev/null +++ b/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 +}