mirror of
https://github.com/kata-containers/kata-containers.git
synced 2025-06-26 23:38:31 +00:00
runtime: update virtcontainers API documentation
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
parent
b9489e6c6e
commit
532ff7c909
@ -47,8 +47,8 @@ pub fn online_device(path: &str) -> Result<()> {
|
||||
Ok(())
|
||||
}
|
||||
|
||||
// pciPathToSysfs fetches the sysfs path for a PCI path, relative to
|
||||
// the syfs path for the PCI host bridge, based on the PCI path
|
||||
// pcipath_to_sysfs fetches the sysfs path for a PCI path, relative to
|
||||
// the sysfs path for the PCI host bridge, based on the PCI path
|
||||
// provided.
|
||||
fn pcipath_to_sysfs(root_bus_sysfs: &str, pcipath: &pci::Path) -> Result<String> {
|
||||
let mut bus = "0000:00".to_string();
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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,
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user