From 20a084ae798f4dc02a27afea1dcd1ae770f95824 Mon Sep 17 00:00:00 2001 From: Ychau Wang Date: Thu, 10 Sep 2020 10:55:09 +0800 Subject: [PATCH] docs: update sandbox apis doc for kata 2.0-dev Sync the api from the runtime codes to the documentation. Remove and add some apis in the kata-api-design.md doc. And new table for Sandbox Monitor APIs. Fixes: #701 Signed-off-by: Ychau Wang --- docs/design/kata-api-design.md | 55 +++++++++++++++++++++------------- 1 file changed, 34 insertions(+), 21 deletions(-) diff --git a/docs/design/kata-api-design.md b/docs/design/kata-api-design.md index e14eec85ac..f185043611 100644 --- a/docs/design/kata-api-design.md +++ b/docs/design/kata-api-design.md @@ -10,43 +10,56 @@ To fulfill the [Kata design requirements](kata-design-requirements.md), and base |Name|Description| |---|---| -|`CreateSandbox(SandboxConfig)`| Create and start a sandbox, and return the sandbox structure.| -|`FetchSandbox(ID)`| Connect to an existing sandbox and return the sandbox structure.| -|`ListSandboxes()`| List all existing sandboxes with status. | +|`CreateSandbox(SandboxConfig, Factory)`| Create a sandbox and its containers, base on `SandboxConfig` and `Factory`. Return the `Sandbox` structure, but do not start them.| ### Sandbox Operation API |Name|Description| |---|---| -|`sandbox.Pause()`| Pause the sandbox.| -|`sandbox.Resume()`| Resume the paused sandbox.| -|`sandbox.Release()`| Release a sandbox data structure, close connections to the agent, and quit any goroutines associated with the sandbox. Mostly used for daemon restart.| -|`sandbox.Delete()`| Destroy the sandbox and remove all persistent metadata.| -|`sandbox.Status()`| Get the status of the sandbox and containers.| +|`sandbox.Delete()`| Shut down the VM in which the sandbox, and destroy the sandbox and remove all persistent metadata.| |`sandbox.Monitor()`| Return a context handler for caller to monitor sandbox callbacks such as error termination.| -|`sandbox.CreateContainer()`| Create new container in the sandbox.| -|`sandbox.DeleteContainer()`| Delete a container from the sandbox.| -|`sandbox.StartContainer()`| Start a container in the sandbox.| -|`sandbox.StatusContainer()`| Get the status of a container in the sandbox.| -|`sandbox.EnterContainer()`| Run a new process in a container.| -|`sandbox.WaitProcess()`| Wait on a process to terminate.| +|`sandbox.Release()`| Release a sandbox data structure, close connections to the agent, and quit any goroutines associated with the Sandbox. Mostly used for daemon restart.| +|`sandbox.Start()`| Start a sandbox and the containers making the sandbox.| +|`sandbox.Stats()`| Get the stats of a running sandbox, return a `SandboxStats` structure.| +|`sandbox.Status()`| Get the status of the sandbox and containers, return a `SandboxStatus` structure.| +|`sandbox.Stop(force)`| Stop a sandbox and Destroy the containers in the sandbox. When force is true, ignore guest related stop failures.| +|`sandbox.CreateContainer(contConfig)`| Create new container in the sandbox with the `ContainerConfig` param. It will add new container config to `sandbox.config.Containers`.| +|`sandbox.DeleteContainer(containerID)`| Delete a container from the sandbox by containerID, return a `Container` structure.| +|`sandbox.EnterContainer(containerID, cmd)`| Run a new process in a container, executing customer's `types.Cmd` command.| +|`sandbox.KillContainer(containerID, signal, all)`| Signal a container in the sandbox by the containerID.| +|`sandbox.PauseContainer(containerID)`| Pause a running container in the sandbox by the containerID.| +|`sandbox.ProcessListContainer(containerID, options)`| List every process running inside a specific container in the sandbox, return a `ProcessList` structure.| +|`sandbox.ResumeContainer(containerID)`| Resume a paused container in the sandbox by the containerID.| +|`sandbox.StartContainer(containerID)`| Start a container in the sandbox by the containerID.| +|`sandbox.StatsContainer(containerID)`| Get the stats of a running container, return a `ContainerStats` structure.| +|`sandbox.StatusContainer(containerID)`| Get the status of a container in the sandbox, return a `ContainerStatus` structure.| +|`sandbox.StopContainer(containerID, force)`| Stop a container in the sandbox by the containerID.| +|`sandbox.UpdateContainer(containerID, resources)`| Update a running container in the sandbox.| +|`sandbox.WaitProcess(containerID, processID)`| Wait on a process to terminate.| ### Sandbox Hotplug API |Name|Description| |---|---| -|`sandbox.AddDevice()`| Add new storage device to the sandbox.| -|`sandbox.AddInterface()`| Add new NIC to the sandbox.| -|`sandbox.RemoveInterface()`| Remove a NIC from the sandbox.| -|`sandbox.ListInterfaces()`| List all NICs and their configurations in the sandbox.| -|`sandbox.UpdateRoutes()`| Update the sandbox route table (e.g. for portmapping support).| -|`sandbox.ListRoutes()`| List the sandbox route table.| +|`sandbox.AddDevice(info)`| Add new storage device `DeviceInfo` to the sandbox, return a `Device` structure.| +|`sandbox.AddInterface(inf)`| Add new NIC to the sandbox.| +|`sandbox.RemoveInterface(inf)`| Remove a NIC from the sandbox.| +|`sandbox.ListInterfaces()`| List all NICs and their configurations in the sandbox, return a `pbTypes.Interface` list.| +|`sandbox.UpdateRoutes(routes)`| Update the sandbox route table (e.g. for portmapping support), return a `pbTypes.Route` list.| +|`sandbox.ListRoutes()`| List the sandbox route table, return a `pbTypes.Route` list.| ### Sandbox Relay API |Name|Description| |---|---| -|`sandbox.WinsizeProcess(containerID, processID, Height, Width)`|Relay TTY resize request to a process.| +|`sandbox.WinsizeProcess(containerID, processID, Height, Width)`| Relay TTY resize request to a process.| |`sandbox.SignalProcess(containerID, processID, signalID, signalALL)`| Relay a signal to a process or all processes in a container.| |`sandbox.IOStream(containerID, processID)`| Relay a process stdio. Return stdin/stdout/stderr pipes to the process stdin/stdout/stderr streams.| +### Sandbox Monitor API +|Name|Description| +|---|---| +|`sandbox.GetOOMEvent()`| Monitor the OOM events that occur in the sandbox..| +|`sandbox.UpdateRuntimeMetrics()`| Update the shim/hypervisor's metrics of the running sandbox.| +|`sandbox.GetAgentMetrics()`| Get metrics of the agent and the guest in the running sandbox.| + ## Plugin framework for external proprietary Kata runtime extensions ### Hypervisor plugin