github/kata-containers
1
0
Fork 1
mirror of https://github.com/kata-containers/kata-containers.git synced 2025-08-02 08:17:01 +00:00
Code Issues Projects Releases Wiki Activity

Merge pull request #27 from bergwolf/api-design

Browse Source 
design: add api design doc
This commit is contained in:
Eric Ernst 2018-03-27 07:06:25 -07:00 committed by GitHub
commit 33ade410f3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 114 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

114
design/kata-api-design.md Normal file
View File

@ -0,0 +1,114 @@
# Kata API Design
To fulfill the [kata design requirements](kata-design-requirements.md), and based on the disscusion on [Virtcontainers API extentions](https://docs.google.com/presentation/d/1dbGrD1h9cpuqAPooiEgtiwWDGCYhVPdatq7owsKHDEQ), the kata runtime library features the following APIs:
- Sandbox based top API
- Storage and network hotplug API
- Plugin frameworks for external proprietary Kata runtime extensions
- Built-in shim and proxy types and capabilities
## Sandbox Based API
### Sandbox Management API
|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 standboxes with status. |
### 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.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 Hotplug API
|Name|Description|
|---|---|
|sandbox.AddStorage()| Add new storage to the sandbox.|
|sandbox.AddNetwork()| Add new nic to the sandbox.|
|sandbox.ListNetwork()| List all nics and their configurations in the sandbox.|
|sandbox.UpdateNetwork()| Update the configuration of an existing network interface.|
|sandbox.UpdateRoute()| Update the sandbox route table (e.g. for portmapping support).|
### Sandbox Relay API
|Name|Description|
|---|---|
|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.|
## Plugin framework for external proprietary Kata runtime extensions
### Hypervisor plugin
TBD.
### Metadata storage plugin
The metadata storage plugin controls where sandbox metadata is saved.
All metadata storage plugins must implement the following API:
|Name|Description|
|---|---|
|storage.Save(key, value)| Save a record.|
|storage.Load(key)| Load a record.|
|storage.Delete(key)| Delete a record.|
Built-in implementations include:
- Filesystem storage
- LevelDB storage
### VM Factory plugin
The VM factory plugin controls how a sandbox factory creates new VMs.
All VM factory plugins must implement following API:
|Name|Description|
|---|---|
|VMFactory.NewVM(HypervisorConfig)|Create a new VM based on `HypervisorConfig`.|
Built-in implementations include:
|Name|Description|
|---|---|
|CreateNew()| Create brand new VM based on 'HypervisorConfig'.|
|CreateFromTemplate()| Create new VM from template.|
|CreateFromCache()| Create new VM from VM caches.|
### Sandbox Creation Plugin Workflow
![Sandbox Creation Plugin Workflow](https://raw.githubusercontent.com/bergwolf/raw-contents/master/kata/Kata-sandbox-creation.png "Sandbox Creation Plugin Workflow")
### Sandbox Connection Plugin Workflow
![Sandbox Connection Plugin Workflow](https://raw.githubusercontent.com/bergwolf/raw-contents/master/kata/Sandbox-Connection.png "Sandbox Connection Plugin Workflow")
## Built-in Shim and Proxy Types and Capabilities
### Built-in shim/proxy sandbox configurations
- Supported shim configurations:
|Name|Description|
|---|---|
|noopshim|Do not start any shim process.|
|ccshim| Start the cc-shim binary.|
|katashim| Start the kata-shim binary.|
|katashimbuiltin|No standalone shim process but shim functionality APIs are exported.|
- Supported proxy configurations:
|Name|Description|
|---|---|
|noopProxy| a dummy proxy implementation of the proxy interface, only used for testing purpose.|
|noProxy|generic implementation for any case where no actual proxy is needed.|
|ccProxy|run ccProxy to proxy between runtime and agent.|
|kataProxy|run kata-proxy to translate yamux connections between runtime and kata agent. |
|kataProxyBuiltin| no standalone proxy process and connect to kata agent with internal yamux translation.|
### Built-in Shim Capability
Built-in shim capability is implemented by removing standalone shim process, and
supporting the shim related APIs.
### Built-in Proxy Capability
Built-in proxy capability is achieved by removing standalone proxy process, and
connecting to kata agent with a custom grpc dialer that is internal yamux translation.
The behavior is enabled when proxy is configured as `kataProxyBuiltin`.