github/kata-containers
1
0
Fork 2
mirror of https://github.com/kata-containers/kata-containers.git synced 2025-09-13 04:49:36 +00:00
Code Issues Projects Releases Wiki Activity

runtime: update virtcontainers API documentation

Browse Source 
Virtcontainers API documentation is outdated, update documentation from the latest
source.

Fixes: #1455

Signed-off-by: bin <bin@hyper.sh>
This commit is contained in:
bin
2021-02-25 10:38:57 +08:00
parent b9489e6c6e
commit 532ff7c909
6 changed files with 417 additions and 273 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
src/runtime/virtcontainers/README.md
View File

@@ -9,14 +9,10 @@ Table of Contents
* [Sandboxes](#sandboxes)
* [Hypervisors](#hypervisors)
* [Agents](#agents)
* [Shim](#shim)
* [API](#api)
* [Sandbox API](#sandbox-api)
* [Container API](#container-api)
* [Networking](#networking)
* [CNM](#cnm)
* [Storage](#storage)
* [How to check if container uses devicemapper block device as its rootfs](#how-to-check-if-container-uses-devicemapper-block-device-as-its-rootfs)
* [Devices](#devices)
* [How to pass a device using VFIO-PCI passthrough](#how-to-pass-a-device-using-vfio-pci-passthrough)
* [How to pass a device using VFIO-AP passthrough](#how-to-pass-a-device-using-vfio-ap-passthrough)
@@ -92,66 +88,9 @@ error output, and so on.
There are many existing and potential solutions to resolve that problem and `virtcontainers` abstracts
this through the Agent interface.
## Shim
In some cases the runtime will need a translation shim between the higher level container
stack (e.g. Docker) and the virtual machine holding the container workload. This is needed
for container stacks that make strong assumptions on the nature of the container they're
monitoring. In cases where they assume containers are simply regular host processes, a shim
layer is needed to translate host specific semantics into e.g. agent controlled virtual
machine ones.
# API
The high level `virtcontainers` API is the following one:
## Sandbox API
* `CreateSandbox(sandboxConfig SandboxConfig)` creates a Sandbox.
The virtual machine is started and the Sandbox is prepared.
* `DeleteSandbox(sandboxID string)` deletes a Sandbox.
The virtual machine is shut down and all information related to the Sandbox are removed.
The function will fail if the Sandbox is running. In that case `StopSandbox()` has to be called first.
* `StartSandbox(sandboxID string)` starts an already created Sandbox.
The Sandbox and all its containers are started.
* `RunSandbox(sandboxConfig SandboxConfig)` creates and starts a Sandbox.
This performs `CreateSandbox()` + `StartSandbox()`.
* `StopSandbox(sandboxID string)` stops an already running Sandbox.
The Sandbox and all its containers are stopped.
* `PauseSandbox(sandboxID string)` pauses an existing Sandbox.
* `ResumeSandbox(sandboxID string)` resume a paused Sandbox.
* `StatusSandbox(sandboxID string)` returns a detailed Sandbox status.
* `ListSandbox()` lists all Sandboxes on the host.
It returns a detailed status for every Sandbox.
## Container API
* `CreateContainer(sandboxID string, containerConfig ContainerConfig)` creates a Container on an existing Sandbox.
* `DeleteContainer(sandboxID, containerID string)` deletes a Container from a Sandbox.
If the Container is running it has to be stopped first.
* `StartContainer(sandboxID, containerID string)` starts an already created Container.
The Sandbox has to be running.
* `StopContainer(sandboxID, containerID string)` stops an already running Container.
* `EnterContainer(sandboxID, containerID string, cmd Cmd)` enters an already running Container and runs a given command.
* `StatusContainer(sandboxID, containerID string)` returns a detailed Container status.
* `KillContainer(sandboxID, containerID string, signal syscall.Signal, all bool)` sends a signal to all or one container inside a Sandbox.
An example tool using the `virtcontainers` API is provided in the `hack/virtc` package.
The high level `virtcontainers` API includes `Sandbox API` and `Container API`.
For further details, see the [API documentation](documentation/api/1.0/api.md).
# Networking
@@ -218,23 +157,7 @@ There are three drawbacks about using CNM instead of CNI:
# Storage
Container workloads are shared with the virtualized environment through 9pfs.
The devicemapper storage driver is a special case. The driver uses dedicated block devices rather than formatted filesystems, and operates at the block level rather than the file level. This knowledge has been used to directly use the underlying block device instead of the overlay file system for the container root file system. The block device maps to the top read-write layer for the overlay. This approach gives much better I/O performance compared to using 9pfs to share the container file system.
The approach above does introduce a limitation in terms of dynamic file copy in/out of the container via `docker cp` operations.
The copy operation from host to container accesses the mounted file system on the host side. This is not expected to work and may lead to inconsistencies as the block device will be simultaneously written to, from two different mounts.
The copy operation from container to host will work, provided the user calls `sync(1)` from within the container prior to the copy to make sure any outstanding cached data is written to the block device.
```
docker cp [OPTIONS] CONTAINER:SRC_PATH HOST:DEST_PATH
docker cp [OPTIONS] HOST:SRC_PATH CONTAINER:DEST_PATH
```
Ability to hotplug block devices has been added, which makes it possible to use block devices for containers started after the VM has been launched.
## How to check if container uses devicemapper block device as its rootfs
Start a container. Call `mount(8)` within the container. You should see `/` mounted on `/dev/vda` device.
See [Kata Containers Architecture](../../../docs/design/architecture.md#storage).
# Devices

2
src/runtime/virtcontainers/container.go
View File

@@ -805,7 +805,7 @@ func (c *Container) checkBlockDeviceSupport(ctx context.Context) bool {
return false
}
// createContainer creates and start a container inside a Sandbox. It has to be
// create creates and starts a container inside a Sandbox. It has to be
// called only when a new container, not known by the sandbox, has to be created.
func (c *Container) create(ctx context.Context) (err error) {
// In case the container creation fails, the following takes care

600
src/runtime/virtcontainers/documentation/api/1.0/api.md
View File

@@ -14,13 +14,10 @@ The virtcontainers 1.0 sandbox API manages hardware virtualized
semantics strictly follow the
[Kubernetes](https://kubernetes.io/docs/concepts/workloads/pods/pod-overview/) ones.
The sandbox API allows callers to [create](#createsandbox), [delete](#deletesandbox),
[start](#startsandbox), [stop](#stopsandbox), [run](#runsandbox), [pause](#pausesandbox),
[resume](#resumesandbox) and [list](#listsandbox) VM (Virtual Machine) based sandboxes.
The sandbox API allows callers to [create](#createsandbox) VM (Virtual Machine) based sandboxes.
To initially create a sandbox, the API caller must prepare a
[`SandboxConfig`](#sandboxconfig) and pass it to either [`CreateSandbox`](#createsandbox)
or [`RunSandbox`](#runsandbox). Upon successful sandbox creation, the virtcontainers
[`SandboxConfig`](#sandboxconfig) and pass it to either [`CreateSandbox`](#createsandbox). Upon successful sandbox creation, the virtcontainers
API will return a [`VCSandbox`](#vcsandbox) interface back to the caller.
The `VCSandbox` interface is a sandbox abstraction hiding the internal and private
@@ -33,12 +30,8 @@ sandbox lifecycle through the rest of the [sandbox API](#sandbox-functions).
### Sandbox Structures
* [`SandboxConfig`](#sandboxconfig)
* [`Resources`](#resources)
* [`HypervisorType`](#hypervisortype)
* [`HypervisorConfig`](#hypervisorconfig)
* [`ProxyType`](#proxytype)
* [`ProxyConfig`](#proxyconfig)
* [`ShimType`](#shimtype)
* [`NetworkConfig`](#networkconfig)
* [`NetInterworkingModel`](#netinterworkingmodel)
* [`Volume`](#volume)
@@ -56,27 +49,15 @@ type SandboxConfig struct {
Hostname string
// Field specific to OCI specs, needed to setup all the hooks
Hooks Hooks
// VMConfig is the VM configuration to set for this sandbox.
VMConfig Resources
HypervisorType HypervisorType
HypervisorConfig HypervisorConfig
AgentConfig interface{}
ProxyType ProxyType
ProxyConfig ProxyConfig
ShimType ShimType
ShimConfig interface{}
AgentConfig KataAgentConfig
NetworkConfig NetworkConfig
// Volumes is a list of shared volumes between the host and the Sandbox.
Volumes []Volume
Volumes []types.Volume
// Containers describe the list of containers within a Sandbox.
// This list can be empty and populated by adding containers
@@ -86,17 +67,26 @@ type SandboxConfig struct {
// Annotations keys must be unique strings and must be name-spaced
// with e.g. reverse domain notation (org.clearlinux.key).
Annotations map[string]string
}
```
##### `Resources`
```Go
// Resources describes VM resources configuration.
type Resources struct {
// VCPUs is the number of available virtual CPUs.
VCPUs uint
// Memory is the amount of available memory in MiB.
Memory uint
ShmSize uint64
// SharePidNs sets all containers to share the same sandbox level pid namespace.
SharePidNs bool
// SystemdCgroup enables systemd cgroup support
SystemdCgroup bool
// SandboxCgroupOnly enables cgroup only at podlevel in the host
SandboxCgroupOnly bool
DisableGuestSeccomp bool
// Experimental features enabled
Experimental []exp.Feature
// Cgroups specifies specific cgroup settings for the various subsystems that the container is
// placed into to limit the resources the container has available
Cgroups *configs.Cgroup
}
```
@@ -106,9 +96,18 @@ type Resources struct {
type HypervisorType string
const (
// FirecrackerHypervisor is the FC hypervisor.
FirecrackerHypervisor HypervisorType = "firecracker"
// QemuHypervisor is the QEMU hypervisor.
QemuHypervisor HypervisorType = "qemu"
// AcrnHypervisor is the ACRN hypervisor.
AcrnHypervisor HypervisorType = "acrn"
// ClhHypervisor is the ICH hypervisor.
ClhHypervisor HypervisorType = "clh"
// MockHypervisor is a mock hypervisor for testing purposes
MockHypervisor HypervisorType = "mock"
)
@@ -118,12 +117,47 @@ const (
```Go
// HypervisorConfig is the hypervisor configuration.
type HypervisorConfig struct {
// NumVCPUs specifies default number of vCPUs for the VM.
NumVCPUs uint32
//DefaultMaxVCPUs specifies the maximum number of vCPUs for the VM.
DefaultMaxVCPUs uint32
// DefaultMem specifies default memory size in MiB for the VM.
MemorySize uint32
// DefaultBridges specifies default number of bridges for the VM.
// Bridges can be used to hot plug devices
DefaultBridges uint32
// Msize9p is used as the msize for 9p shares
Msize9p uint32
// MemSlots specifies default memory slots the VM.
MemSlots uint32
// MemOffset specifies memory space for nvdimm device
MemOffset uint32
// VirtioFSCacheSize is the DAX cache size in MiB
VirtioFSCacheSize uint32
// KernelParams are additional guest kernel parameters.
KernelParams []Param
// HypervisorParams are additional hypervisor parameters.
HypervisorParams []Param
// KernelPath is the guest kernel host path.
KernelPath string
// ImagePath is the guest image host path.
ImagePath string
// InitrdPath is the guest initrd image host path.
// ImagePath and InitrdPath cannot be set at the same time.
InitrdPath string
// FirmwarePath is the bios host path
FirmwarePath string
@@ -136,8 +170,40 @@ type HypervisorConfig struct {
// HypervisorPath is the hypervisor executable host path.
HypervisorPath string
// DisableBlockDeviceUse disallows a block device from being used.
DisableBlockDeviceUse bool
// HypervisorPathList is the list of hypervisor paths names allowed in annotations
HypervisorPathList []string
// HypervisorCtlPathList is the list of hypervisor control paths names allowed in annotations
HypervisorCtlPathList []string
// HypervisorCtlPath is the hypervisor ctl executable host path.
HypervisorCtlPath string
// JailerPath is the jailer executable host path.
JailerPath string
// JailerPathList is the list of jailer paths names allowed in annotations
JailerPathList []string
// BlockDeviceDriver specifies the driver to be used for block device
// either VirtioSCSI or VirtioBlock with the default driver being defaultBlockDriver
BlockDeviceDriver string
// HypervisorMachineType specifies the type of machine being
// emulated.
HypervisorMachineType string
// MemoryPath is the memory file path of VM memory. Used when either BootToBeTemplate or
// BootFromTemplate is true.
MemoryPath string
// DevicesStatePath is the VM device state file path. Used when either BootToBeTemplate or
// BootFromTemplate is true.
DevicesStatePath string
// EntropySource is the path to a host source of
// entropy (/dev/random, /dev/urandom or real hardware RNG device)
EntropySource string
// Shared file system type:
// - virtio-9p (default)
@@ -147,44 +213,67 @@ type HypervisorConfig struct {
// VirtioFSDaemon is the virtio-fs vhost-user daemon path
VirtioFSDaemon string
// VirtioFSCacheSize is the virtio-fs DAX cache size in MiB
VirtioFSCacheSize uint32
// VirtioFSDaemonList is the list of valid virtiofs names for annotations
VirtioFSDaemonList []string
// VirtioFSCache cache mode for fs version cache or "none"
VirtioFSCache string
// KernelParams are additional guest kernel parameters.
KernelParams []Param
// VirtioFSExtraArgs passes options to virtiofsd daemon
VirtioFSExtraArgs []string
// HypervisorParams are additional hypervisor parameters.
HypervisorParams []Param
// File based memory backend root directory
FileBackedMemRootDir string
// HypervisorMachineType specifies the type of machine being
// emulated.
HypervisorMachineType string
// FileBackedMemRootList is the list of valid root directories values for annotations
FileBackedMemRootList []string
// PFlash image paths
PFlash []string
// customAssets is a map of assets.
// Each value in that map takes precedence over the configured assets.
// For example, if there is a value for the "kernel" key in this map,
// it will be used for the sandbox's kernel path instead of KernelPath.
customAssets map[types.AssetType]*types.Asset
// BlockDeviceCacheSet specifies cache-related options will be set to block devices or not.
BlockDeviceCacheSet bool
// BlockDeviceCacheDirect specifies cache-related options for block devices.
// Denotes whether use of O_DIRECT (bypass the host page cache) is enabled.
BlockDeviceCacheDirect bool
// BlockDeviceCacheNoflush specifies cache-related options for block devices.
// Denotes whether flush requests for the device are ignored.
BlockDeviceCacheNoflush bool
// DisableBlockDeviceUse disallows a block device from being used.
DisableBlockDeviceUse bool
// EnableIOThreads enables IO to be processed in a separate thread.
// Supported currently for virtio-scsi driver.
EnableIOThreads bool
// Debug changes the default hypervisor and kernel parameters to
// enable debug output where available.
Debug bool
// NumVCPUs specifies default number of vCPUs for the VM.
// Sandbox configuration VMConfig.VCPUs overwrites this.
NumVCPUs uint32
// DefaultMem specifies default memory size in MiB for the VM.
// Sandbox configuration VMConfig.Memory overwrites this.
MemorySize uint32
// DefaultBridges specifies default number of bridges for the VM.
// Bridges can be used to hot plug devices
DefaultBridges uint32
// MemPrealloc specifies if the memory should be pre-allocated
MemPrealloc bool
// HugePages specifies if the memory should be pre-allocated from huge pages
HugePages bool
// VirtioMem is used to enable/disable virtio-mem
VirtioMem bool
// IOMMU specifies if the VM should have a vIOMMU
IOMMU bool
// IOMMUPlatform is used to indicate if IOMMU_PLATFORM is enabled for supported devices
IOMMUPlatform bool
// Realtime Used to enable/disable realtime
Realtime bool
@@ -196,55 +285,77 @@ type HypervisorConfig struct {
// DisableNestingChecks is used to override customizations performed
// when running on top of another VMM.
DisableNestingChecks bool
// DisableImageNvdimm is used to disable guest rootfs image nvdimm devices
DisableImageNvdimm bool
// HotplugVFIOOnRootBus is used to indicate if devices need to be hotplugged on the
// root bus instead of a bridge.
HotplugVFIOOnRootBus bool
// PCIeRootPort is used to indicate the number of PCIe Root Port devices
// The PCIe Root Port device is used to hot-plug the PCIe device
PCIeRootPort uint32
// BootToBeTemplate used to indicate if the VM is created to be a template VM
BootToBeTemplate bool
// BootFromTemplate used to indicate if the VM should be created from a template VM
BootFromTemplate bool
// DisableVhostNet is used to indicate if host supports vhost_net
DisableVhostNet bool
// EnableVhostUserStore is used to indicate if host supports vhost-user-blk/scsi
EnableVhostUserStore bool
// VhostUserStorePath is the directory path where vhost-user devices
// related folders, sockets and device nodes should be.
VhostUserStorePath string
// VhostUserStorePathList is the list of valid values for vhost-user paths
VhostUserStorePathList []string
// GuestHookPath is the path within the VM that will be used for 'drop-in' hooks
GuestHookPath string
// VMid is the id of the VM that create the hypervisor if the VM is created by the factory.
// VMid is "" if the hypervisor is not created by the factory.
VMid string
// SELinux label for the VM
SELinuxProcessLabel string
// RxRateLimiterMaxRate is used to control network I/O inbound bandwidth on VM level.
RxRateLimiterMaxRate uint64
// TxRateLimiterMaxRate is used to control network I/O outbound bandwidth on VM level.
TxRateLimiterMaxRate uint64
// SGXEPCSize specifies the size in bytes for the EPC Section.
// Enable SGX. Hardware-based isolation and memory encryption.
SGXEPCSize int64
// Enable annotations by name
EnableAnnotations []string
// GuestCoredumpPath is the path in host for saving guest memory dump
GuestMemoryDumpPath string
// GuestMemoryDumpPaging is used to indicate if enable paging
// for QEMU dump-guest-memory command
GuestMemoryDumpPaging bool
}
```
##### `ProxyType`
```Go
// ProxyType describes a proxy type.
type ProxyType string
const (
// NoopProxyType is the noopProxy.
NoopProxyType ProxyType = "noopProxy"
// NoProxyType is the noProxy.
NoProxyType ProxyType = "noProxy"
// KataProxyType is the kataProxy.
KataProxyType ProxyType = "kataProxy"
)
```
##### `ProxyConfig`
```Go
// ProxyConfig is a structure storing information needed from any
// proxy in order to be properly initialized.
type ProxyConfig struct {
Path string
Debug bool
}
```
##### `ShimType`
```Go
// ShimType describes a shim type.
type ShimType string
const (
// NoopShimType is the noopShim.
NoopShimType ShimType = "noopShim"
// KataShimType is the Kata Containers shim type.
KataShimType ShimType = "kataShim"
)
```
##### `NetworkConfig`
```Go
// NetworkConfig is the network configuration related to a network.
type NetworkConfig struct {
NetNSPath string
NetNsCreated bool
DisableNewNetNs bool
NetmonConfig NetmonConfig
InterworkingModel NetInterworkingModel
}
```
@@ -262,6 +373,14 @@ const (
// interface can be bridged using macvtap
NetXConnectMacVtapModel
// NetXConnectTCFilterModel redirects traffic from the network interface
// provided by the network plugin to a tap interface.
// This works for ipvlan and macvlan as well.
NetXConnectTCFilterModel
// NetXConnectNoneModel can be used when the VM is in the host network namespace
NetXConnectNoneModel
// NetXConnectInvalidModel is the last item to check valid values by IsValid()
NetXConnectInvalidModel
)
@@ -287,13 +406,13 @@ type ContainerConfig struct {
ID string
// RootFs is the container workload image on the host.
RootFs string
RootFs RootFs
// ReadOnlyRootfs indicates if the rootfs should be mounted readonly
ReadonlyRootfs bool
// Cmd specifies the command to run on a container
Cmd Cmd
Cmd types.Cmd
// Annotations allow clients to store arbitrary values,
// for example to add additional status values required
@@ -303,7 +422,13 @@ type ContainerConfig struct {
Mounts []Mount
// Device configuration for devices that must be available within the container.
DeviceInfos []DeviceInfo
DeviceInfos []config.DeviceInfo
// Resources container resources
Resources specs.LinuxResources
// Raw OCI specification, it won't be saved to disk.
CustomSpec *specs.Spec `json:"-"`
}
```
@@ -311,9 +436,9 @@ type ContainerConfig struct {
```Go
// Cmd represents a command to execute in a running container.
type Cmd struct {
Args []string
Envs []EnvVar
WorkDir string
Args []string
Envs []EnvVar
SupplementaryGroups []string
// Note that these fields *MUST* remain as strings.
//
@@ -337,15 +462,15 @@ type Cmd struct {
// all the user and group mapping is handled by the container manager
// and specified to the runtime in terms of UID/GID's in the
// configuration file generated by the container manager.
User string
PrimaryGroup string
SupplementaryGroups []string
User string
PrimaryGroup string
WorkDir string
Console string
Capabilities *specs.LinuxCapabilities
Interactive bool
Console string
Detach bool
NoNewPrivileges bool
Capabilities LinuxCapabilities
}
```
@@ -367,6 +492,11 @@ type Mount struct {
// ReadOnly specifies if the mount should be read only or not
ReadOnly bool
// BlockDeviceID represents block device that is attached to the
// VM in case this mount is a block device file or a directory
// backed by a block device.
BlockDeviceID string
}
```
@@ -374,11 +504,11 @@ type Mount struct {
```Go
// DeviceInfo is an embedded type that contains device data common to all types of devices.
type DeviceInfo struct {
// Device path on host
// Hostpath is device path on host
HostPath string
// Device path inside the container
ContainerPath string
// ContainerPath is device path inside container
ContainerPath string `json:"-"`
// Type of device: c, b, u or p
// c , u - character(unbuffered)
@@ -391,6 +521,17 @@ type DeviceInfo struct {
Major int64
Minor int64
// Pmem enabled persistent memory. Use HostPath as backing file
// for a nvdimm device in the guest.
Pmem bool
// If applicable, should this device be considered RO
ReadOnly bool
// ColdPlug specifies whether the device must be cold plugged (true)
// or hot plugged (false).
ColdPlug bool
// FileMode permission bits for the device.
FileMode os.FileMode
@@ -400,12 +541,12 @@ type DeviceInfo struct {
// id of the device group.
GID uint32
// Hotplugged is used to store device state indicating if the
// device was hotplugged.
Hotplugged bool
// ID for the device that is passed to the hypervisor.
ID string
// DriverOptions is specific options for each device driver
// for example, for BlockDevice, we can set DriverOptions["blockDriver"]="virtio-blk"
DriverOptions map[string]string
}
```
@@ -415,25 +556,60 @@ type DeviceInfo struct {
// (required since virtcontainers.Sandbox only contains private fields)
type VCSandbox interface {
Annotations(key string) (string, error)
GetNetNs() string
GetAllContainers() []VCContainer
GetAnnotations() map[string]string
GetContainer(containerID string) VCContainer
ID() string
SetAnnotations(annotations map[string]string) error
Stats() (SandboxStats, error)
Start() error
Stop(force bool) error
Release() error
Monitor() (chan error, error)
Delete() error
Status() SandboxStatus
CreateContainer(contConfig ContainerConfig) (VCContainer, error)
DeleteContainer(containerID string) (VCContainer, error)
StartContainer(containerID string) (VCContainer, error)
StopContainer(containerID string, force bool) (VCContainer, error)
KillContainer(containerID string, signal syscall.Signal, all bool) error
StatusContainer(containerID string) (ContainerStatus, error)
StatsContainer(containerID string) (ContainerStats, error)
PauseContainer(containerID string) error
ResumeContainer(containerID string) error
EnterContainer(containerID string, cmd types.Cmd) (VCContainer, *Process, error)
UpdateContainer(containerID string, resources specs.LinuxResources) error
ProcessListContainer(containerID string, options ProcessListOptions) (ProcessList, error)
WaitProcess(containerID, processID string) (int32, error)
SignalProcess(containerID, processID string, signal syscall.Signal, all bool) error
WinsizeProcess(containerID, processID string, height, width uint32) error
IOStream(containerID, processID string) (io.WriteCloser, io.Reader, io.Reader, error)
AddDevice(info config.DeviceInfo) (api.Device, error)
AddInterface(inf *pbTypes.Interface) (*pbTypes.Interface, error)
RemoveInterface(inf *pbTypes.Interface) (*pbTypes.Interface, error)
ListInterfaces() ([]*pbTypes.Interface, error)
UpdateRoutes(routes []*pbTypes.Route) ([]*pbTypes.Route, error)
ListRoutes() ([]*pbTypes.Route, error)
GetOOMEvent() (string, error)
UpdateRuntimeMetrics() error
GetAgentMetrics() (string, error)
GetAgentURL() (string, error)
}
```
### Sandbox Functions
* [`CreateSandbox`](#createsandbox)
* [`DeleteSandbox`](#deletesandbox)
* [`StartSandbox`](#startsandbox)
* [`StopSandbox`](#stopsandbox)
* [`RunSandbox`](#runsandbox)
* [`ListSandbox`](#listsandbox)
* [`StatusSandbox`](#statussandbox)
* [`PauseSandbox`](#pausesandbox)
* [`ResumeSandbox`](#resumesandbox)
* [`CleanupContainer`](#cleanupcontainer)
* [`SetFactory`](#setfactory)
* [`SetLogger`](#setlogger)
#### `CreateSandbox`
```Go
@@ -442,60 +618,24 @@ type VCSandbox interface {
func CreateSandbox(sandboxConfig SandboxConfig) (VCSandbox, error)
```
#### `DeleteSandbox`
#### `CleanupContainer`
```Go
// DeleteSandbox is the virtcontainers sandbox deletion entry point.
// DeleteSandbox will stop an already running container and then delete it.
func DeleteSandbox(sandboxID string) (VCSandbox, error)
// CleanupContainer is used by shimv2 to stop and delete a container exclusively, once there is no container
// in the sandbox left, do stop the sandbox and delete it. Those serial operations will be done exclusively by
// locking the sandbox.
func CleanupContainer(ctx context.Context, sandboxID, containerID string, force bool) error
```
#### `StartSandbox`
#### `SetFactory`
```Go
// StartSandbox is the virtcontainers sandbox starting entry point.
// StartSandbox will talk to the given hypervisor to start an existing
// sandbox and all its containers.
func StartSandbox(sandboxID string) (VCSandbox, error)
// SetFactory implements the VC function of the same name.
func SetFactory(ctx context.Context, factory Factory)
```
#### `StopSandbox`
#### `SetLogger`
```Go
// StopSandbox is the virtcontainers sandbox stopping entry point.
// StopSandbox will talk to the given agent to stop an existing sandbox
// and destroy all containers within that sandbox.
func StopSandbox(sandboxID string) (VCSandbox, error)
```
#### `RunSandbox`
```Go
// RunSandbox is the virtcontainers sandbox running entry point.
// RunSandbox creates a sandbox and its containers and then it starts them.
func RunSandbox(sandboxConfig SandboxConfig) (VCSandbox, error)
```
#### `ListSandbox`
```Go
// ListSandbox is the virtcontainers sandbox listing entry point.
func ListSandbox() ([]SandboxStatus, error)
```
#### `StatusSandbox`
```Go
// StatusSandbox is the virtcontainers sandbox status entry point.
func StatusSandbox(sandboxID string) (SandboxStatus, error)
```
#### `PauseSandbox`
```Go
// PauseSandbox is the virtcontainers pausing entry point which pauses an
// already running sandbox.
func PauseSandbox(sandboxID string) (VCSandbox, error)
```
#### `ResumeSandbox`
```Go
// ResumeSandbox is the virtcontainers resuming entry point which resumes
// (or unpauses) and already paused sandbox.
func ResumeSandbox(sandboxID string) (VCSandbox, error)
// SetLogger implements the VC function of the same name.
func SetLogger(ctx context.Context, logger *logrus.Entry)
```
## Container API
@@ -555,13 +695,13 @@ type ContainerConfig struct {
ID string
// RootFs is the container workload image on the host.
RootFs string
RootFs RootFs
// ReadOnlyRootfs indicates if the rootfs should be mounted readonly
ReadonlyRootfs bool
// Cmd specifies the command to run on a container
Cmd Cmd
Cmd types.Cmd
// Annotations allow clients to store arbitrary values,
// for example to add additional status values required
@@ -571,7 +711,13 @@ type ContainerConfig struct {
Mounts []Mount
// Device configuration for devices that must be available within the container.
DeviceInfos []DeviceInfo
DeviceInfos []config.DeviceInfo
// Resources container resources
Resources specs.LinuxResources
// Raw OCI specification, it won't be saved to disk.
CustomSpec *specs.Spec `json:"-"`
}
```
@@ -579,9 +725,9 @@ type ContainerConfig struct {
```Go
// Cmd represents a command to execute in a running container.
type Cmd struct {
Args []string
Envs []EnvVar
WorkDir string
Args []string
Envs []EnvVar
SupplementaryGroups []string
// Note that these fields *MUST* remain as strings.
//
@@ -605,15 +751,15 @@ type Cmd struct {
// all the user and group mapping is handled by the container manager
// and specified to the runtime in terms of UID/GID's in the
// configuration file generated by the container manager.
User string
PrimaryGroup string
SupplementaryGroups []string
User string
PrimaryGroup string
WorkDir string
Console string
Capabilities *specs.LinuxCapabilities
Interactive bool
Console string
Detach bool
NoNewPrivileges bool
Capabilities LinuxCapabilities
}
```
@@ -635,6 +781,11 @@ type Mount struct {
// ReadOnly specifies if the mount should be read only or not
ReadOnly bool
// BlockDeviceID represents block device that is attached to the
// VM in case this mount is a block device file or a directory
// backed by a block device.
BlockDeviceID string
}
```
@@ -642,11 +793,11 @@ type Mount struct {
```Go
// DeviceInfo is an embedded type that contains device data common to all types of devices.
type DeviceInfo struct {
// Device path on host
// Hostpath is device path on host
HostPath string
// Device path inside the container
ContainerPath string
// ContainerPath is device path inside container
ContainerPath string `json:"-"`
// Type of device: c, b, u or p
// c , u - character(unbuffered)
@@ -659,6 +810,17 @@ type DeviceInfo struct {
Major int64
Minor int64
// Pmem enabled persistent memory. Use HostPath as backing file
// for a nvdimm device in the guest.
Pmem bool
// If applicable, should this device be considered RO
ReadOnly bool
// ColdPlug specifies whether the device must be cold plugged (true)
// or hot plugged (false).
ColdPlug bool
// FileMode permission bits for the device.
FileMode os.FileMode
@@ -668,12 +830,12 @@ type DeviceInfo struct {
// id of the device group.
GID uint32
// Hotplugged is used to store device state indicating if the
// device was hotplugged.
Hotplugged bool
// ID for the device that is passed to the hypervisor.
ID string
// DriverOptions is specific options for each device driver
// for example, for BlockDevice, we can set DriverOptions["blockDriver"]="virtio-blk"
DriverOptions map[string]string
}
```
@@ -702,10 +864,11 @@ type Process struct {
// ContainerStatus describes a container status.
type ContainerStatus struct {
ID string
State State
State types.ContainerState
PID int
StartTime time.Time
RootFs string
Spec *specs.Spec
// Annotations allow clients to store arbitrary values,
// for example to add additional status values required
@@ -754,6 +917,14 @@ type VCContainer interface {
* [`StatusContainer`](#statuscontainer)
* [`KillContainer`](#killcontainer)
* [`ProcessListContainer`](#processlistcontainer)
* [`StatsContainer`](#statscontainer)
* [`PauseContainer`](#pausecontainer)
* [`ResumeContainer`](#resumecontainer)
* [`UpdateContainer`](#updatecontainer)
* [`WaitProcess`](#waitprocess)
* [`SignalProcess`](#signalprocess)
* [`WinsizeProcess`](#winsizeprocess)
* [`IOStream`](#iostream)
#### `CreateContainer`
```Go
@@ -813,6 +984,55 @@ func KillContainer(sandboxID, containerID string, signal syscall.Signal, all boo
func ProcessListContainer(sandboxID, containerID string, options ProcessListOptions) (ProcessList, error)
```
#### `StatsContainer`
```Go
// StatsContainer return the stats of a running container
func StatsContainer(containerID string) (ContainerStats, error)
```
#### `PauseContainer`
```Go
// PauseContainer pauses a running container.
func PauseContainer(containerID string) error
```
#### `ResumeContainer`
```Go
// ResumeContainer resumes a paused container.
func ResumeContainer(containerID string) error
```
#### `UpdateContainer`
```Go
// UpdateContainer update a running container.
func UpdateContainer(containerID string, resources specs.LinuxResources) error
```
#### `WaitProcess`
```Go
// WaitProcess waits on a container process and return its exit code
func WaitProcess(containerID, processID string) (int32, error)
```
#### `SignalProcess`
```Go
// SignalProcess sends a signal to a process of a container when all is false.
// When all is true, it sends the signal to all processes of a container.
func SignalProcess(containerID, processID string, signal syscall.Signal, all bool) error
```
#### `WinsizeProcess`
```Go
// WinsizeProcess resizes the tty window of a process
func WinsizeProcess(containerID, processID string, height, width uint32) error
```
#### `IOStream`
```Go
// IOStream returns stdin writer, stdout reader and stderr reader of a process
func IOStream(containerID, processID string) (io.WriteCloser, io.Reader, io.Reader, error)
```
## Examples
### Preparing and running a sandbox
@@ -859,6 +1079,7 @@ func Example_createAndStartSandbox() {
ImagePath: "/usr/share/kata-containers/clear-containers.img",
HypervisorPath: "/usr/bin/qemu-system-x86_64",
MemorySize: 1024,
MemSlots: 10,
}
// Use kata default values for the agent.
@@ -869,6 +1090,7 @@ func Example_createAndStartSandbox() {
// - Hypervisor is QEMU
// - Agent is kata
sandboxConfig := vc.SandboxConfig{
ID: "sandbox-abc",
HypervisorType: vc.QemuHypervisor,
HypervisorConfig: hypervisorConfig,

2
src/runtime/virtcontainers/interfaces.go
View File

@@ -47,7 +47,7 @@ type VCSandbox interface {
Delete(ctx context.Context) error
Status() SandboxStatus
CreateContainer(ctx context.Context, contConfig ContainerConfig) (VCContainer, error)
DeleteContainer(ctx context.Context, contID string) (VCContainer, error)
DeleteContainer(ctx context.Context, containerID string) (VCContainer, error)
StartContainer(ctx context.Context, containerID string) (VCContainer, error)
StopContainer(ctx context.Context, containerID string, force bool) (VCContainer, error)
KillContainer(ctx context.Context, containerID string, signal syscall.Signal, all bool) error

1
src/runtime/virtcontainers/persist/api/config.go
View File

@@ -251,7 +251,6 @@ type SandboxConfig struct {
// only one agent config can be non-nil according to agent type
KataAgentConfig *KataAgentConfig `json:",omitempty"`
ShimType string
KataShimConfig *ShimConfig
NetworkConfig NetworkConfig