virtcontainers

package
v0.0.0-...-1586018 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 2, 2018 License: Apache-2.0, Apache-2.0 Imports: 50 Imported by: 0

README

Table of Contents

What is it ?

virtcontainers is a Go library that can be used to build hardware-virtualized container runtimes.

Background

The few existing VM-based container runtimes (Clear Containers, runv, rkt's kvm stage 1) all share the same hardware virtualization semantics but use different code bases to implement them. virtcontainers's goal is to factorize this code into a common Go library.

Ideally, VM-based container runtime implementations would become translation layers from the runtime specification they implement (e.g. the OCI runtime-spec or the Kubernetes CRI) to the virtcontainers API.

virtcontainers is Clear Containers's runtime foundational package for their runtime implementation

Out of scope

Implementing a container runtime is out of scope for this project. Any tools or executables in this repository are only provided for demonstration or testing purposes.

virtcontainers and Kubernetes CRI

virtcontainers's API is loosely inspired by the Kubernetes CRI because we believe it provides the right level of abstractions for containerized sandboxes. However, despite the API similarities between the two projects, the goal of virtcontainers is not to build a CRI implementation, but instead to provide a generic, runtime-specification agnostic, hardware-virtualized containers library that other projects could leverage to implement CRI themselves.

Design

Sandboxes

The virtcontainers execution unit is a sandbox, i.e. virtcontainers users start sandboxes where containers will be running.

virtcontainers creates a sandbox by starting a virtual machine and setting the sandbox up within that environment. Starting a sandbox means launching all containers with the VM sandbox runtime environment.

Hypervisors

The virtcontainers package relies on hypervisors to start and stop virtual machine where sandboxes will be running. An hypervisor is defined by an Hypervisor interface implementation, and the default implementation is the QEMU one.

Agents

During the lifecycle of a container, the runtime running on the host needs to interact with the virtual machine guest OS in order to start new commands to be executed as part of a given container workload, set new networking routes or interfaces, fetch a container standard or 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.

Proxy

When hardware virtualized containers have limited I/O multiplexing capabilities, runtimes may decide to rely on an external host proxy to support cases where several runtime instances are talking to the same container.

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.

Networking

virtcontainers supports the 2 major container networking models: the Container Network Model (CNM) and the Container Network Interface (CNI).

Typically the former is the Docker default networking model while the later is used on Kubernetes deployments.

virtcontainers callers can select one or the other, on a per sandbox basis, by setting their SandboxConfig's NetworkModel field properly.

CNM

High-level CNM Diagram

CNM lifecycle

  1. RequestPool

  2. CreateNetwork

  3. RequestAddress

  4. CreateEndPoint

  5. CreateContainer

  6. Create config.json

  7. Create PID and network namespace

  8. ProcessExternalKey

  9. JoinEndPoint

  10. LaunchContainer

  11. Launch

  12. Run container

Detailed CNM Diagram

Runtime network setup with CNM

  1. Read config.json

  2. Create the network namespace (code)

  3. Call the prestart hook (from inside the netns) (code)

  4. Scan network interfaces inside netns and get the name of the interface created by prestart hook (code)

  5. Create bridge, TAP, and link all together with network interface previously created (code)

  6. Start VM inside the netns and start the container (code)

Drawbacks of CNM

There are three drawbacks about using CNM instead of CNI:

  • The way we call into it is not very explicit: Have to re-exec dockerd binary so that it can accept parameters and execute the prestart hook related to network setup.
  • Implicit way to designate the network namespace: Instead of explicitely giving the netns to dockerd, we give it the PID of our runtime so that it can find the netns from this PID. This means we have to make sure being in the right netns while calling the hook, otherwise the veth pair will be created with the wrong netns.
  • No results are back from the hook: We have to scan the network interfaces to discover which one has been created inside the netns. This introduces more latency in the code because it forces us to scan the network in the CreateSandbox path, which is critical for starting the VM as quick as possible.

CNI

CNI Diagram

Runtime network setup with CNI

  1. Create the network namespace (code)

  2. Get CNI plugin information (code)

  3. Start the plugin (providing previously created netns) to add a network described into /etc/cni/net.d/ directory. At that time, the CNI plugin will create the cni0 network interface and a veth pair between the host and the created netns. It links cni0 to the veth pair before to exit. (code)

  4. Create bridge, TAP, and link all together with network interface previously created (code)

  5. Start VM inside the netns and start the container (code)

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.

Devices

Support has been added to pass VFIO assigned devices on the docker command line with --device. Support for passing other devices including block devices with --device has not been added added yet.

How to pass a device using VFIO-passthrough

  1. Requirements

IOMMU group represents the smallest set of devices for which the IOMMU has visibility and which is isolated from other groups. VFIO uses this information to enforce safe ownership of devices for userspace.

You will need Intel VT-d capable hardware. Check if IOMMU is enabled in your host kernel by verifying CONFIG_VFIO_NOIOMMU is not in the kernel config. If it is set, you will need to rebuild your kernel.

The following kernel configs need to be enabled:

CONFIG_VFIO_IOMMU_TYPE1=m 
CONFIG_VFIO=m
CONFIG_VFIO_PCI=m

In addition, you need to pass intel_iommu=on on the kernel command line.

  1. Identify BDF(Bus-Device-Function) of the PCI device to be assigned.
$ lspci -D | grep -e Ethernet -e Network
0000:01:00.0 Ethernet controller: Intel Corporation Ethernet Controller 10-Gigabit X540-AT2 (rev 01)

$ BDF=0000:01:00.0
  1. Find vendor and device id.
$ lspci -n -s $BDF
01:00.0 0200: 8086:1528 (rev 01)
  1. Find IOMMU group.
$ readlink /sys/bus/pci/devices/$BDF/iommu_group
../../../../kernel/iommu_groups/16
  1. Unbind the device from host driver.
$ echo $BDF | sudo tee /sys/bus/pci/devices/$BDF/driver/unbind
  1. Bind the device to vfio-pci.
$ sudo modprobe vfio-pci
$ echo 8086 1528 | sudo tee /sys/bus/pci/drivers/vfio-pci/new_id
$ echo $BDF | sudo tee --append /sys/bus/pci/drivers/vfio-pci/bind
  1. Check /dev/vfio
$ ls /dev/vfio
16 vfio
  1. Start a Clear Containers container passing the VFIO group on the docker command line.
docker run -it --device=/dev/vfio/16 centos/tools bash
  1. Running lspci within the container should show the device among the PCI devices. The driver for the device needs to be present within the Clear Containers kernel. If the driver is missing, you can add it to your custom container kernel using the osbuilder tooling.

Developers

For information on how to build, develop and test virtcontainers, see the developer documentation.

Documentation

Overview

Package virtcontainers manages hardware virtualized containers. Each container belongs to a set of containers sharing the same networking namespace and storage, also known as a sandbox.

Virtcontainers sandboxes are hardware virtualized, i.e. they run on virtual machines. Virtcontainers will create one VM per sandbox, and containers will be created as processes within the sandbox VM.

The virtcontainers package manages both sandboxes and containers lifecycles.

Example (CreateAndStartSandbox)

This example creates and starts a single container sandbox, using qemu as the hypervisor and hyperstart as the VM agent. 

package main

import (
	"fmt"
	"strings"

	vc "github.com/kata-containers/runtime/virtcontainers"
)

const containerRootfs = "/var/lib/container/bundle/"

// This example creates and starts a single container sandbox,
// using qemu as the hypervisor and hyperstart as the VM agent.
func main() {
	envs := []vc.EnvVar{
		{
			Var:   "PATH",
			Value: "/bin:/usr/bin:/sbin:/usr/sbin",
		},
	}

	cmd := vc.Cmd{
		Args:    strings.Split("/bin/sh", " "),
		Envs:    envs,
		WorkDir: "/",
	}

	// Define the container command and bundle.
	container := vc.ContainerConfig{
		ID:     "1",
		RootFs: containerRootfs,
		Cmd:    cmd,
	}

	// Sets the hypervisor configuration.
	hypervisorConfig := vc.HypervisorConfig{
		KernelPath:     "/usr/share/kata-containers/vmlinux.container",
		ImagePath:      "/usr/share/kata-containers/kata-containers.img",
		HypervisorPath: "/usr/bin/qemu-system-x86_64",
	}

	// Use hyperstart default values for the agent.
	agConfig := vc.HyperConfig{}

	// VM resources
	vmConfig := vc.Resources{
		Memory: 1024,
	}

	// The sandbox configuration:
	// - One container
	// - Hypervisor is QEMU
	// - Agent is hyperstart
	sandboxConfig := vc.SandboxConfig{
		VMConfig: vmConfig,

		HypervisorType:   vc.QemuHypervisor,
		HypervisorConfig: hypervisorConfig,

		AgentType:   vc.HyperstartAgent,
		AgentConfig: agConfig,

		Containers: []vc.ContainerConfig{container},
	}

	_, err := vc.RunSandbox(sandboxConfig, nil)
	if err != nil {
		fmt.Printf("Could not run sandbox: %s", err)
	}

	return
}

Index

Examples

Constants

View Source 
const (
	// VirtioBlock means use virtio-blk for hotplugging drives
	VirtioBlock = "virtio-blk"

	// VirtioSCSI means use virtio-scsi for hotplugging drives
	VirtioSCSI = "virtio-scsi"
)
View Source 
const (
	// QemuPCLite is the QEMU pc-lite machine type for amd64
	QemuPCLite = "pc-lite"

	// QemuPC is the QEMU pc machine type for amd64
	QemuPC = "pc"

	// QemuQ35 is the QEMU Q35 machine type for amd64
	QemuQ35 = "q35"

	// QemuVirt is the QEMU virt machine type for aarch64
	QemuVirt = "virt"

	// QemuPseries is a QEMU virt machine type for for ppc64le
	QemuPseries = "pseries"
)
View Source 
const (
	// StateReady represents a sandbox/container that's ready to be run
	StateReady stateString = "ready"

	// StateRunning represents a sandbox/container that's currently running.
	StateRunning stateString = "running"

	// StatePaused represents a sandbox/container that has been paused.
	StatePaused stateString = "paused"

	// StateStopped represents a sandbox/container that has been stopped.
	StateStopped stateString = "stopped"
)
View Source 
const CniPrimaryInterface = "eth0"

CniPrimaryInterface Name chosen for the primary interface If CNI ever support multiple primary interfaces this should be revisited

View Source 
const DefaultShmSize = 65536 * 1024

DefaultShmSize is the default shm size to be used in case host IPC is used.

Variables

View Source 
var DefaultNetInterworkingModel = NetXConnectMacVtapModel

DefaultNetInterworkingModel is a package level default that determines how the VM should be connected to the the container network interface

View Source 
var RunVMStoragePath = filepath.Join("/run", storagePathSuffix, vmPathSuffix)

RunVMStoragePath is the vm directory. It will contain all guest vm sockets and shared mountpoints.

Functions

func CreateContainer 

func CreateContainer(sandboxID string, containerConfig ContainerConfig) (VCSandbox, VCContainer, error)

CreateContainer is the virtcontainers container creation entry point. CreateContainer creates a container on a given sandbox.

func EnterContainer 

func EnterContainer(sandboxID, containerID string, cmd Cmd) (VCSandbox, VCContainer, *Process, error)

EnterContainer is the virtcontainers container command execution entry point. EnterContainer enters an already running container and runs a given command.

func KillContainer 

func KillContainer(sandboxID, containerID string, signal syscall.Signal, all bool) error

KillContainer is the virtcontainers entry point to send a signal to a container running inside a sandbox. If all is true, all processes in the container will be sent the signal.

func MaxQemuVCPUs 

func MaxQemuVCPUs() uint32

MaxQemuVCPUs returns the maximum number of vCPUs supported

func PauseContainer 

func PauseContainer(sandboxID, containerID string) error

PauseContainer is the virtcontainers container pause entry point.

func ResumeContainer 

func ResumeContainer(sandboxID, containerID string) error

ResumeContainer is the virtcontainers container resume entry point.

func RunningOnVMM 

func RunningOnVMM(cpuInfoPath string) (bool, error)

RunningOnVMM checks if the system is running inside a VM.

func SerializeParams 

func SerializeParams(params []Param, delim string) []string

SerializeParams converts []Param to []string

func SetLogger 

func SetLogger(logger *logrus.Entry)

SetLogger sets the logger for virtcontainers package.

func UpdateContainer 

func UpdateContainer(sandboxID, containerID string, resources specs.LinuxResources) error

UpdateContainer is the virtcontainers entry point to update container's resources.

Types

type AgentType 

type AgentType string

AgentType describes the type of guest agent a Sandbox should run. 

const (
	// NoopAgentType is the No-Op agent.
	NoopAgentType AgentType = "noop"

	// HyperstartAgent is the Hyper hyperstart agent.
	HyperstartAgent AgentType = "hyperstart"

	// KataContainersAgent is the Kata Containers agent.
	KataContainersAgent AgentType = "kata"

	// SocketTypeVSOCK is a VSOCK socket type for talking to an agent.
	SocketTypeVSOCK = "vsock"

	// SocketTypeUNIX is a UNIX socket type for talking to an agent.
	// It typically means the agent is living behind a host proxy.
	SocketTypeUNIX = "unix"
)

func (*AgentType) Set 

func (agentType *AgentType) Set(value string) error

Set sets an agent type based on the input string.

func (*AgentType) String 

func (agentType *AgentType) String() string

String converts an agent type to a string.

type BlkioStatEntry 

type BlkioStatEntry struct {
	Major uint64 `json:"major,omitempty"`
	Minor uint64 `json:"minor,omitempty"`
	Op    string `json:"op,omitempty"`
	Value uint64 `json:"value,omitempty"`
}

BlkioStatEntry gather date related to a block device

type BlkioStats 

type BlkioStats struct {
	// number of bytes tranferred to and from the block device
	IoServiceBytesRecursive []BlkioStatEntry `json:"io_service_bytes_recursive,omitempty"`
	IoServicedRecursive     []BlkioStatEntry `json:"io_serviced_recursive,omitempty"`
	IoQueuedRecursive       []BlkioStatEntry `json:"io_queue_recursive,omitempty"`
	IoServiceTimeRecursive  []BlkioStatEntry `json:"io_service_time_recursive,omitempty"`
	IoWaitTimeRecursive     []BlkioStatEntry `json:"io_wait_time_recursive,omitempty"`
	IoMergedRecursive       []BlkioStatEntry `json:"io_merged_recursive,omitempty"`
	IoTimeRecursive         []BlkioStatEntry `json:"io_time_recursive,omitempty"`
	SectorsRecursive        []BlkioStatEntry `json:"sectors_recursive,omitempty"`
}

BlkioStats describes block io stats

type Bridge 

type Bridge struct {
	// Address contains information about devices plugged and its address in the bridge
	Address map[uint32]string

	// Type is the type of the bridge (pci, pcie, etc)
	Type bridgeType

	//ID is used to identify the bridge in the hypervisor
	ID string

	// Addr is the PCI/e slot of the bridge
	Addr int
}

Bridge is a bridge where devices can be hot plugged

type CPUDevice 

type CPUDevice struct {
	// ID is used to identify this CPU in the hypervisor options.
	ID string
}

CPUDevice represents a CPU device which was hot-added in a running VM

type CPUStats 

type CPUStats struct {
	CPUUsage       CPUUsage       `json:"cpu_usage,omitempty"`
	ThrottlingData ThrottlingData `json:"throttling_data,omitempty"`
}

CPUStats describes the cpu stats

type CPUUsage 

type CPUUsage struct {
	// Total CPU time consumed.
	// Units: nanoseconds.
	TotalUsage uint64 `json:"total_usage,omitempty"`
	// Total CPU time consumed per core.
	// Units: nanoseconds.
	PercpuUsage []uint64 `json:"percpu_usage,omitempty"`
	// Time spent by tasks of the cgroup in kernel mode.
	// Units: nanoseconds.
	UsageInKernelmode uint64 `json:"usage_in_kernelmode"`
	// Time spent by tasks of the cgroup in user mode.
	// Units: nanoseconds.
	UsageInUsermode uint64 `json:"usage_in_usermode"`
}

CPUUsage denotes the usage of a CPU. All CPU stats are aggregate since container inception.

type CgroupStats 

type CgroupStats struct {
	CPUStats    CPUStats    `json:"cpu_stats,omitempty"`
	MemoryStats MemoryStats `json:"memory_stats,omitempty"`
	PidsStats   PidsStats   `json:"pids_stats,omitempty"`
	BlkioStats  BlkioStats  `json:"blkio_stats,omitempty"`
	// the map is in the format "size of hugepage: stats of the hugepage"
	HugetlbStats map[string]HugetlbStats `json:"hugetlb_stats,omitempty"`
}

CgroupStats describes all cgroup subsystem stats

type Cmd 

type Cmd struct {
	Args                []string
	Envs                []EnvVar
	SupplementaryGroups []string

	// Note that these fields *MUST* remain as strings.
	//
	// The reason being that we want runtimes to be able to support CLI
	// operations like "exec --user=". That option allows the
	// specification of a user (either as a string username or a numeric
	// UID), and may optionally also include a group (groupame or GID).
	//
	// Since this type is the interface to allow the runtime to specify
	// the user and group the workload can run as, these user and group
	// fields cannot be encoded as integer values since that would imply
	// the runtime itself would need to perform a UID/GID lookup on the
	// user-specified username/groupname. But that isn't practically
	// possible given that to do so would require the runtime to access
	// the image to allow it to interrogate the appropriate databases to
	// convert the username/groupnames to UID/GID values.
	//
	// Note that this argument applies solely to the _runtime_ supporting
	// a "--user=" option when running in a "standalone mode" - there is
	// no issue when the runtime is called by a container manager since
	// 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
	WorkDir      string
	Console      string
	Capabilities LinuxCapabilities

	Interactive     bool
	Detach          bool
	NoNewPrivileges bool
}

Cmd represents a command to execute in a running container.

type Container 

type Container struct {
	// contains filtered or unexported fields
}

Container is composed of a set of containers and a runtime environment. A Container can be created, deleted, started, stopped, listed, entered, paused and restored.

func (*Container) GetAnnotations 

func (c *Container) GetAnnotations() map[string]string

GetAnnotations returns container's annotations

func (*Container) GetPid 

func (c *Container) GetPid() int

GetPid returns the pid related to this container's process.

func (*Container) GetToken 

func (c *Container) GetToken() string

GetToken returns the token related to this container's process.

func (*Container) ID 

func (c *Container) ID() string

ID returns the container identifier string.

func (*Container) Logger 

func (c *Container) Logger() *logrus.Entry

Logger returns a logrus logger appropriate for logging Container messages

func (*Container) Process 

func (c *Container) Process() Process

Process returns the container process.

func (*Container) Sandbox 

func (c *Container) Sandbox() VCSandbox

Sandbox returns the sandbox handler related to this container.

func (*Container) SetPid 

func (c *Container) SetPid(pid int) error

SetPid sets and stores the given pid as the pid of container's process.

type ContainerConfig 

type ContainerConfig struct {
	ID string

	// RootFs is the container workload image on the host.
	RootFs string

	// ReadOnlyRootfs indicates if the rootfs should be mounted readonly
	ReadonlyRootfs bool

	// Cmd specifies the command to run on a container
	Cmd Cmd

	// Annotations allow clients to store arbitrary values,
	// for example to add additional status values required
	// to support particular specifications.
	Annotations map[string]string

	Mounts []Mount

	// Device configuration for devices that must be available within the container.
	DeviceInfos []config.DeviceInfo

	// Resources container resources
	Resources ContainerResources
}

ContainerConfig describes one container runtime configuration.

type ContainerResources 

type ContainerResources struct {
	// VCPUs are the number of vCPUs that are being used by the container
	VCPUs uint32

	// Mem is the memory that is being used by the container
	Mem uint32
}

ContainerResources describes container resources

type ContainerStats 

type ContainerStats struct {
	CgroupStats *CgroupStats
}

ContainerStats describes a container stats.

func StatsContainer 

func StatsContainer(sandboxID, containerID string) (ContainerStats, error)

StatsContainer is the virtcontainers container stats entry point. StatsContainer returns a detailed container stats.

type ContainerStatus 

type ContainerStatus struct {
	ID        string
	State     State
	PID       int
	StartTime time.Time
	RootFs    string

	// Annotations allow clients to store arbitrary values,
	// for example to add additional status values required
	// to support particular specifications.
	Annotations map[string]string
}

ContainerStatus describes a container status.

func StatusContainer 

func StatusContainer(sandboxID, containerID string) (ContainerStatus, error)

StatusContainer is the virtcontainers container status entry point. StatusContainer returns a detailed container status.

type ContainerType 

type ContainerType string

ContainerType defines a type of container. 

const (
	PodContainer         ContainerType = "pod_container"
	PodSandbox           ContainerType = "pod_sandbox"
	UnknownContainerType ContainerType = "unknown_container_type"
)

List different types of containers

func (ContainerType) IsSandbox 

func (cType ContainerType) IsSandbox() bool

IsSandbox determines if the container type can be considered as a sandbox. We can consider a sandbox in case we have a PodSandbox or a RegularContainer.

type DNSInfo 

type DNSInfo struct {
	Servers  []string
	Domain   string
	Searches []string
	Options  []string
}

DNSInfo describes the DNS setup related to a network interface.

type Endpoint 

type Endpoint interface {
	Properties() NetworkInfo
	Name() string
	HardwareAddr() string
	Type() EndpointType

	SetProperties(NetworkInfo)
	Attach(hypervisor) error
	Detach(netNsCreated bool, netNsPath string) error
}

Endpoint represents a physical or virtual network interface.

type EndpointType 

type EndpointType string

EndpointType identifies the type of the network endpoint. 

const (
	// PhysicalEndpointType is the physical network interface.
	PhysicalEndpointType EndpointType = "physical"

	// VirtualEndpointType is the virtual network interface.
	VirtualEndpointType EndpointType = "virtual"

	// VhostUserEndpointType is the vhostuser network interface.
	VhostUserEndpointType EndpointType = "vhost-user"
)

func (*EndpointType) Set 

func (endpointType *EndpointType) Set(value string) error

Set sets an endpoint type based on the input string.

func (*EndpointType) String 

func (endpointType *EndpointType) String() string

String converts an endpoint type to a string.

type EnvVar 

type EnvVar struct {
	Var   string
	Value string
}

EnvVar is a key/value structure representing a command environment variable.

type Factory 

type Factory interface {
	// GetVM gets a new VM from the factory.
	GetVM(config VMConfig) (*VM, error)

	// CloseFactory closes and cleans up the factory.
	CloseFactory()
}

Factory controls how a new VM is created.

type Hook 

type Hook struct {
	Path    string
	Args    []string
	Env     []string
	Timeout int
}

Hook represents an OCI hook, including its required parameters.

type Hooks 

type Hooks struct {
	PreStartHooks  []Hook
	PostStartHooks []Hook
	PostStopHooks  []Hook
}

Hooks gathers all existing OCI hooks list.

func (*Hooks) Logger 

func (h *Hooks) Logger() *logrus.Entry

Logger returns a logrus logger appropriate for logging Hooks messages

type HugetlbStats 

type HugetlbStats struct {
	// current res_counter usage for hugetlb
	Usage uint64 `json:"usage,omitempty"`
	// maximum usage ever recorded.
	MaxUsage uint64 `json:"max_usage,omitempty"`
	// number of times hugetlb usage allocation failure.
	Failcnt uint64 `json:"failcnt"`
}

HugetlbStats describes hugetable memory stats

type HyperAgentState 

type HyperAgentState struct {
	ProxyPid int
	URL      string
}

HyperAgentState is the structure describing the data stored from this agent implementation.

type HyperConfig 

type HyperConfig struct {
	SockCtlName string
	SockTtyName string
}

HyperConfig is a structure storing information needed for hyperstart agent initialization.

type HypervisorConfig 

type HypervisorConfig struct {
	// 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

	// MachineAccelerators are machine specific accelerators
	MachineAccelerators string

	// HypervisorPath is the hypervisor executable host path.
	HypervisorPath 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

	// DefaultVCPUs specifies default number of vCPUs for the VM.
	DefaultVCPUs uint32

	//DefaultMaxVCPUs specifies the maximum number of vCPUs for the VM.
	DefaultMaxVCPUs uint32

	// DefaultMem specifies default memory size in MiB for the VM.
	// Sandbox configuration VMConfig.Memory overwrites this.
	DefaultMemSz uint32

	// DefaultBridges specifies default number of bridges for the VM.
	// Bridges can be used to hot plug devices
	DefaultBridges uint32

	// 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

	// 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

	// Realtime Used to enable/disable realtime
	Realtime bool

	// Mlock is used to control memory locking when Realtime is enabled
	// Realtime=true and Mlock=false, allows for swapping out of VM memory
	// enabling higher density
	Mlock bool

	// DisableNestingChecks is used to override customizations performed
	// when running on top of another VMM.
	DisableNestingChecks bool

	// Msize9p is used as the msize for 9p shares
	Msize9p uint32

	// UseVSock use a vsock for agent communication
	UseVSock bool

	// 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

	// 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
	// contains filtered or unexported fields
}

HypervisorConfig is the hypervisor configuration.

func (*HypervisorConfig) AddKernelParam 

func (conf *HypervisorConfig) AddKernelParam(p Param) error

AddKernelParam allows the addition of new kernel parameters to an existing hypervisor configuration.

func (*HypervisorConfig) CustomFirmwareAsset 

func (conf *HypervisorConfig) CustomFirmwareAsset() bool

CustomFirmwareAsset returns true if the firmware asset is a custom one, false otherwise.

func (*HypervisorConfig) CustomHypervisorAsset 

func (conf *HypervisorConfig) CustomHypervisorAsset() bool

CustomHypervisorAsset returns true if the hypervisor asset is a custom one, false otherwise.

func (*HypervisorConfig) CustomImageAsset 

func (conf *HypervisorConfig) CustomImageAsset() bool

CustomImageAsset returns true if the image asset is a custom one, false otherwise.

func (*HypervisorConfig) CustomInitrdAsset 

func (conf *HypervisorConfig) CustomInitrdAsset() bool

CustomInitrdAsset returns true if the initrd asset is a custom one, false otherwise.

func (*HypervisorConfig) CustomKernelAsset 

func (conf *HypervisorConfig) CustomKernelAsset() bool

CustomKernelAsset returns true if the kernel asset is a custom one, false otherwise.

func (*HypervisorConfig) FirmwareAssetPath 

func (conf *HypervisorConfig) FirmwareAssetPath() (string, error)

FirmwareAssetPath returns the guest firmware path

func (*HypervisorConfig) HypervisorAssetPath 

func (conf *HypervisorConfig) HypervisorAssetPath() (string, error)

HypervisorAssetPath returns the VM hypervisor path

func (*HypervisorConfig) ImageAssetPath 

func (conf *HypervisorConfig) ImageAssetPath() (string, error)

ImageAssetPath returns the guest image path

func (*HypervisorConfig) InitrdAssetPath 

func (conf *HypervisorConfig) InitrdAssetPath() (string, error)

InitrdAssetPath returns the guest initrd path

func (*HypervisorConfig) KernelAssetPath 

func (conf *HypervisorConfig) KernelAssetPath() (string, error)

KernelAssetPath returns the guest kernel path

type HypervisorType 

type HypervisorType string

HypervisorType describes an hypervisor type. 

const (
	// QemuHypervisor is the QEMU hypervisor.
	QemuHypervisor HypervisorType = "qemu"

	// MockHypervisor is a mock hypervisor for testing purposes
	MockHypervisor HypervisorType = "mock"
)

func (*HypervisorType) Set 

func (hType *HypervisorType) Set(value string) error

Set sets an hypervisor type based on the input string.

func (*HypervisorType) String 

func (hType *HypervisorType) String() string

String converts an hypervisor type to a string.

type KataAgentConfig 

type KataAgentConfig struct {
	LongLiveConn bool
	UseVSock     bool
}

KataAgentConfig is a structure storing information needed to reach the Kata Containers agent.

type KataAgentState 

type KataAgentState struct {
	ProxyPid int
	URL      string
}

KataAgentState is the structure describing the data stored from this agent implementation.

type KataShimConfig 

type KataShimConfig struct {
	Path  string
	Debug bool
}

KataShimConfig is the structure providing specific configuration for kataShim implementation.

type LinuxCapabilities 

type LinuxCapabilities struct {
	// Bounding is the set of capabilities checked by the kernel.
	Bounding []string
	// Effective is the set of capabilities checked by the kernel.
	Effective []string
	// Inheritable is the capabilities preserved across execve.
	Inheritable []string
	// Permitted is the limiting superset for effective capabilities.
	Permitted []string
	// Ambient is the ambient set of capabilities that are kept.
	Ambient []string
}

LinuxCapabilities specify the capabilities to keep when executing the process inside the container.

type MemoryData 

type MemoryData struct {
	Usage    uint64 `json:"usage,omitempty"`
	MaxUsage uint64 `json:"max_usage,omitempty"`
	Failcnt  uint64 `json:"failcnt"`
	Limit    uint64 `json:"limit"`
}

MemoryData gather the data related to memory

type MemoryStats 

type MemoryStats struct {
	// memory used for cache
	Cache uint64 `json:"cache,omitempty"`
	// usage of memory
	Usage MemoryData `json:"usage,omitempty"`
	// usage of memory  swap
	SwapUsage MemoryData `json:"swap_usage,omitempty"`
	// usage of kernel memory
	KernelUsage MemoryData `json:"kernel_usage,omitempty"`
	// usage of kernel TCP memory
	KernelTCPUsage MemoryData `json:"kernel_tcp_usage,omitempty"`
	// if true, memory usage is accounted for throughout a hierarchy of cgroups.
	UseHierarchy bool `json:"use_hierarchy"`

	Stats map[string]uint64 `json:"stats,omitempty"`
}

MemoryStats describes the memory stats

type Mount 

type Mount struct {
	Source      string
	Destination string

	// Type specifies the type of filesystem to mount.
	Type string

	// Options list all the mount options of the filesystem.
	Options []string

	// HostPath used to store host side bind mount path
	HostPath string

	// ReadOnly specifies if the mount should be read only or not
	ReadOnly bool

	// BlockDevice 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.
	BlockDevice *drivers.BlockDevice
}

Mount describes a container mount.

type NetInterworkingModel 

type NetInterworkingModel int

NetInterworkingModel defines the network model connecting the network interface to the virtual machine. 

const (
	// NetXConnectDefaultModel Ask to use DefaultNetInterworkingModel
	NetXConnectDefaultModel NetInterworkingModel = iota

	// NetXConnectBridgedModel uses a linux bridge to interconnect
	// the container interface to the VM. This is the
	// safe default that works for most cases except
	// macvlan and ipvlan
	NetXConnectBridgedModel

	// NetXConnectMacVtapModel can be used when the Container network
	// interface can be bridged using macvtap
	NetXConnectMacVtapModel

	// NetXConnectEnlightenedModel can be used when the Network plugins
	// are enlightened to create VM native interfaces
	// when requested by the runtime
	// This will be used for vethtap, macvtap, ipvtap
	NetXConnectEnlightenedModel

	// NetXConnectInvalidModel is the last item to check valid values by IsValid()
	NetXConnectInvalidModel
)

func (NetInterworkingModel) IsValid 

func (n NetInterworkingModel) IsValid() bool

IsValid checks if a model is valid

func (*NetInterworkingModel) SetModel 

func (n *NetInterworkingModel) SetModel(modelName string) error

SetModel change the model string value

type NetlinkIface 

type NetlinkIface struct {
	netlink.LinkAttrs
	Type string
}

NetlinkIface describes fully a network interface.

type NetworkConfig 

type NetworkConfig struct {
	NetNSPath         string
	NumInterfaces     int
	InterworkingModel NetInterworkingModel
}

NetworkConfig is the network configuration related to a network.

type NetworkInfo 

type NetworkInfo struct {
	Iface  NetlinkIface
	Addrs  []netlink.Addr
	Routes []netlink.Route
	DNS    DNSInfo
}

NetworkInfo gathers all information related to a network interface. It can be used to store the description of the underlying network.

type NetworkInterface 

type NetworkInterface struct {
	Name     string
	HardAddr string
	Addrs    []netlink.Addr
}

NetworkInterface defines a network interface.

type NetworkInterfacePair 

type NetworkInterfacePair struct {
	ID        string
	Name      string
	VirtIface NetworkInterface
	TAPIface  NetworkInterface
	NetInterworkingModel
	VMFds    []*os.File
	VhostFds []*os.File
}

NetworkInterfacePair defines a pair between VM and virtual network interfaces.

type NetworkModel 

type NetworkModel string

NetworkModel describes the type of network specification. 

const (
	// NoopNetworkModel is the No-Op network.
	NoopNetworkModel NetworkModel = "noop"

	// CNINetworkModel is the CNI network.
	CNINetworkModel NetworkModel = "CNI"

	// CNMNetworkModel is the CNM network.
	CNMNetworkModel NetworkModel = "CNM"
)

func (*NetworkModel) Set 

func (networkType *NetworkModel) Set(value string) error

Set sets a network type based on the input string.

func (*NetworkModel) String 

func (networkType *NetworkModel) String() string

String converts a network type to a string.

type NetworkNamespace 

type NetworkNamespace struct {
	NetNsPath    string
	NetNsCreated bool
	Endpoints    []Endpoint
}

NetworkNamespace contains all data related to its network namespace.

func (NetworkNamespace) MarshalJSON 

func (n NetworkNamespace) MarshalJSON() ([]byte, error)

MarshalJSON is the custom NetworkNamespace JSON marshalling routine. This is needed to properly marshall Endpoints array.

func (*NetworkNamespace) UnmarshalJSON 

func (n *NetworkNamespace) UnmarshalJSON(b []byte) error

UnmarshalJSON is the custom NetworkNamespace unmarshalling routine. This is needed for unmarshalling the Endpoints interfaces array.

type Param 

type Param struct {
	Key   string
	Value string
}

Param is a key/value representation for hypervisor and kernel parameters.

func DeserializeParams 

func DeserializeParams(parameters []string) []Param

DeserializeParams converts []string to []Param

type PhysicalEndpoint 

type PhysicalEndpoint struct {
	IfaceName          string
	HardAddr           string
	EndpointProperties NetworkInfo
	EndpointType       EndpointType
	BDF                string
	Driver             string
	VendorDeviceID     string
}

PhysicalEndpoint gathers a physical network interface and its properties

func (*PhysicalEndpoint) Attach 

func (endpoint *PhysicalEndpoint) Attach(h hypervisor) error

Attach for physical endpoint binds the physical network interface to vfio-pci and adds device to the hypervisor with vfio-passthrough.

func (*PhysicalEndpoint) Detach 

func (endpoint *PhysicalEndpoint) Detach(netNsCreated bool, netNsPath string) error

Detach for physical endpoint unbinds the physical network interface from vfio-pci and binds it back to the saved host driver.

func (*PhysicalEndpoint) HardwareAddr 

func (endpoint *PhysicalEndpoint) HardwareAddr() string

HardwareAddr returns the mac address of the physical network interface.

func (*PhysicalEndpoint) Name 

func (endpoint *PhysicalEndpoint) Name() string

Name returns name of the physical interface.

func (*PhysicalEndpoint) Properties 

func (endpoint *PhysicalEndpoint) Properties() NetworkInfo

Properties returns the properties of the physical interface.

func (*PhysicalEndpoint) SetProperties 

func (endpoint *PhysicalEndpoint) SetProperties(properties NetworkInfo)

SetProperties sets the properties of the physical endpoint.

func (*PhysicalEndpoint) Type 

func (endpoint *PhysicalEndpoint) Type() EndpointType

Type indentifies the endpoint as a physical endpoint.

type PidsStats 

type PidsStats struct {
	// number of pids in the cgroup
	Current uint64 `json:"current,omitempty"`
	// active pids hard limit
	Limit uint64 `json:"limit,omitempty"`
}

PidsStats describes the pids stats

type Process 

type Process struct {
	// Token is the process execution context ID. It must be
	// unique per sandbox.
	// Token is used to manipulate processes for containers
	// that have not started yet, and later identify them
	// uniquely within a sandbox.
	Token string

	// Pid is the process ID as seen by the host software
	// stack, e.g. CRI-O, containerd. This is typically the
	// shim PID.
	Pid int

	StartTime time.Time
}

Process gathers data related to a container process.

type ProcessList 

type ProcessList []byte

ProcessList represents the list of running processes inside the container

func ProcessListContainer 

func ProcessListContainer(sandboxID, containerID string, options ProcessListOptions) (ProcessList, error)

ProcessListContainer is the virtcontainers entry point to list processes running inside a container

type ProcessListOptions 

type ProcessListOptions struct {
	// Format describes the output format to list the running processes.
	// Formats are unrelated to ps(1) formats, only two formats can be specified:
	// "json" and "table"
	Format string

	// Args contains the list of arguments to run ps(1) command.
	// If Args is empty the agent will use "-ef" as options to ps(1).
	Args []string
}

ProcessListOptions contains the options used to list running processes inside the container

type ProxyConfig 

type ProxyConfig struct {
	Path  string
	Debug bool
}

ProxyConfig is a structure storing information needed from any proxy in order to be properly initialized.

type ProxyType 

type ProxyType string

ProxyType describes a proxy type. 

const (
	// NoopProxyType is the noopProxy.
	NoopProxyType ProxyType = "noopProxy"

	// NoProxyType is the noProxy.
	NoProxyType ProxyType = "noProxy"

	// CCProxyType is the ccProxy.
	CCProxyType ProxyType = "ccProxy"

	// KataProxyType is the kataProxy.
	KataProxyType ProxyType = "kataProxy"

	// KataBuiltInProxyType is the kataBuiltInProxy.
	KataBuiltInProxyType ProxyType = "kataBuiltInProxy"
)

func (*ProxyType) Set 

func (pType *ProxyType) Set(value string) error

Set sets a proxy type based on the input string.

func (*ProxyType) String 

func (pType *ProxyType) String() string

String converts a proxy type to a string.

type QemuState 

type QemuState struct {
	Bridges []Bridge
	// HotpluggedCPUs is the list of CPUs that were hot-added
	HotpluggedVCPUs  []CPUDevice
	HotpluggedMemory int
	UUID             string
}

QemuState keeps Qemu's state

type Resources 

type Resources struct {
	// Memory is the amount of available memory in MiB.
	Memory uint
}

Resources describes VM resources configuration.

type Sandbox 

type Sandbox struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Sandbox is composed of a set of containers and a runtime environment. A Sandbox can be created, deleted, started, paused, stopped, listed, entered, and restored.

func (*Sandbox) AddVhostUserDevice 

func (s *Sandbox) AddVhostUserDevice(devInfo api.VhostUserDevice, devType config.DeviceType) error

AddVhostUserDevice adds a vhost user device to sandbox Sandbox implement DeviceReceiver interface from device/api/interface.go

func (*Sandbox) Annotations 

func (s *Sandbox) Annotations(key string) (string, error)

Annotations returns any annotation that a user could have stored through the sandbox.

func (*Sandbox) CreateContainer 

func (s *Sandbox) CreateContainer(contConfig ContainerConfig) (VCContainer, error)

CreateContainer creates a new container in the sandbox

func (*Sandbox) DecrementSandboxBlockIndex 

func (s *Sandbox) DecrementSandboxBlockIndex() error

DecrementSandboxBlockIndex decrease block indexes Sandbox implement DeviceReceiver interface from device/api/interface.go

func (*Sandbox) Delete 

func (s *Sandbox) Delete() error

Delete deletes an already created sandbox. The VM in which the sandbox is running will be shut down.

func (*Sandbox) DeleteContainer 

func (s *Sandbox) DeleteContainer(containerID string) (VCContainer, error)

DeleteContainer deletes a container from the sandbox

func (*Sandbox) EnterContainer 

func (s *Sandbox) EnterContainer(containerID string, cmd Cmd) (VCContainer, *Process, error)

EnterContainer is the virtcontainers container command execution entry point. EnterContainer enters an already running container and runs a given command.

func (*Sandbox) GetAllContainers 

func (s *Sandbox) GetAllContainers() []VCContainer

GetAllContainers returns all containers.

func (*Sandbox) GetAndSetSandboxBlockIndex 

func (s *Sandbox) GetAndSetSandboxBlockIndex() (int, error)

GetAndSetSandboxBlockIndex is used for getting and setting virtio-block indexes Sandbox implement DeviceReceiver interface from device/api/interface.go

func (*Sandbox) GetAnnotations 

func (s *Sandbox) GetAnnotations() map[string]string

GetAnnotations returns sandbox's annotations

func (*Sandbox) GetContainer 

func (s *Sandbox) GetContainer(containerID string) VCContainer

GetContainer returns the container named by the containerID.

func (*Sandbox) HotplugAddDevice 

func (s *Sandbox) HotplugAddDevice(device api.Device, devType config.DeviceType) error

HotplugAddDevice is used for add a device to sandbox Sandbox implement DeviceReceiver interface from device/api/interface.go

func (*Sandbox) HotplugRemoveDevice 

func (s *Sandbox) HotplugRemoveDevice(device api.Device, devType config.DeviceType) error

HotplugRemoveDevice is used for removing a device from sandbox Sandbox implement DeviceReceiver interface from device/api/interface.go

func (*Sandbox) ID 

func (s *Sandbox) ID() string

ID returns the sandbox identifier string.

func (*Sandbox) IOStream 

func (s *Sandbox) IOStream(containerID, processID string) (io.WriteCloser, io.Reader, io.Reader, error)

IOStream returns stdin writer, stdout reader and stderr reader of a process

func (*Sandbox) Logger 

func (s *Sandbox) Logger() *logrus.Entry

Logger returns a logrus logger appropriate for logging Sandbox messages

func (*Sandbox) Monitor 

func (s *Sandbox) Monitor() (chan error, error)

Monitor returns a error channel for watcher to watch at

func (*Sandbox) Pause 

func (s *Sandbox) Pause() error

Pause pauses the sandbox

func (*Sandbox) Release 

func (s *Sandbox) Release() error

Release closes the agent connection and removes sandbox from internal list.

func (*Sandbox) Resume 

func (s *Sandbox) Resume() error

Resume resumes the sandbox

func (*Sandbox) SetAnnotations 

func (s *Sandbox) SetAnnotations(annotations map[string]string) error

SetAnnotations sets or adds an annotations

func (*Sandbox) SignalProcess 

func (s *Sandbox) SignalProcess(containerID, processID string, signal syscall.Signal, all bool) error

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 (*Sandbox) StartContainer 

func (s *Sandbox) StartContainer(containerID string) (VCContainer, error)

StartContainer starts a container in the sandbox

func (*Sandbox) StatsContainer 

func (s *Sandbox) StatsContainer(containerID string) (ContainerStats, error)

StatsContainer return the stats of a running container

func (*Sandbox) Status 

func (s *Sandbox) Status() SandboxStatus

Status gets the status of the sandbox TODO: update container status properly, see kata-containers/runtime#253

func (*Sandbox) StatusContainer 

func (s *Sandbox) StatusContainer(containerID string) (ContainerStatus, error)

StatusContainer gets the status of a container TODO: update container status properly, see kata-containers/runtime#253

func (*Sandbox) UpdateContainer 

func (s *Sandbox) UpdateContainer(containerID string, resources specs.LinuxResources) error

UpdateContainer update a running container.

func (*Sandbox) WaitProcess 

func (s *Sandbox) WaitProcess(containerID, processID string) (int32, error)

WaitProcess waits on a container process and return its exit code

func (*Sandbox) WinsizeProcess 

func (s *Sandbox) WinsizeProcess(containerID, processID string, height, width uint32) error

WinsizeProcess resizes the tty window of a process

type SandboxConfig 

type SandboxConfig struct {
	ID string

	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

	AgentType   AgentType
	AgentConfig interface{}

	ProxyType   ProxyType
	ProxyConfig ProxyConfig

	ShimType   ShimType
	ShimConfig interface{}

	NetworkModel  NetworkModel
	NetworkConfig NetworkConfig

	// Volumes is a list of shared volumes between the host and the Sandbox.
	Volumes []Volume

	// Containers describe the list of containers within a Sandbox.
	// This list can be empty and populated by adding containers
	// to the Sandbox a posteriori.
	Containers []ContainerConfig

	// Annotations keys must be unique strings and must be name-spaced
	// with e.g. reverse domain notation (org.clearlinux.key).
	Annotations map[string]string

	ShmSize uint64

	// SharePidNs sets all containers to share the same sandbox level pid namespace.
	SharePidNs bool

	// Stateful keeps sandbox resources in memory across APIs. Users will be responsible
	// for calling Release() to release the memory resources.
	Stateful bool
}

SandboxConfig is a Sandbox configuration.

type SandboxStatus 

type SandboxStatus struct {
	ID               string
	State            State
	Hypervisor       HypervisorType
	HypervisorConfig HypervisorConfig
	Agent            AgentType
	ContainersStatus []ContainerStatus

	// Annotations allow clients to store arbitrary values,
	// for example to add additional status values required
	// to support particular specifications.
	Annotations map[string]string
}

SandboxStatus describes a sandbox status.

func ListSandbox 

func ListSandbox() ([]SandboxStatus, error)

ListSandbox is the virtcontainers sandbox listing entry point.

func StatusSandbox 

func StatusSandbox(sandboxID string) (SandboxStatus, error)

StatusSandbox is the virtcontainers sandbox status entry point.

type ShimConfig 

type ShimConfig struct {
	Path  string
	Debug bool
}

ShimConfig is the structure providing specific configuration for shim implementations.

type ShimParams 

type ShimParams struct {
	Container string
	Token     string
	URL       string
	Console   string
	Terminal  bool
	Detach    bool
	PID       int
	CreateNS  []ns.NSType
	EnterNS   []ns.Namespace
}

ShimParams is the structure providing specific parameters needed for the execution of the shim binary.

type ShimType 

type ShimType string

ShimType describes a shim type. 

const (
	// CCShimType is the ccShim.
	CCShimType ShimType = "ccShim"

	// NoopShimType is the noopShim.
	NoopShimType ShimType = "noopShim"

	// KataShimType is the Kata Containers shim type.
	KataShimType ShimType = "kataShim"

	// KataBuiltInShimType is the Kata Containers builtin shim type.
	KataBuiltInShimType ShimType = "kataBuiltInShim"
)

func (*ShimType) Set 

func (pType *ShimType) Set(value string) error

Set sets a shim type based on the input string.

func (*ShimType) String 

func (pType *ShimType) String() string

String converts a shim type to a string.

type Socket 

type Socket struct {
	DeviceID string
	ID       string
	HostPath string
	Name     string
}

Socket defines a socket to communicate between the host and any process inside the VM.

type Sockets 

type Sockets []Socket

Sockets is a Socket list.

func (*Sockets) Set 

func (s *Sockets) Set(sockStr string) error

Set assigns socket values from string to a Socket.

func (*Sockets) String 

func (s *Sockets) String() string

String converts a Socket to a string.

type SpawnerType 

type SpawnerType string

SpawnerType describes the type of guest agent a Sandbox should run. 

const (
	// NsEnter is the nsenter spawner type
	NsEnter SpawnerType = "nsenter"
)

func (*SpawnerType) Set 

func (spawnerType *SpawnerType) Set(value string) error

Set sets an agent type based on the input string.

func (*SpawnerType) String 

func (spawnerType *SpawnerType) String() string

String converts an agent type to a string.

type State 

type State struct {
	State stateString `json:"state"`

	// Index of the block device passed to hypervisor.
	BlockIndex int `json:"blockIndex"`

	// File system of the rootfs incase it is block device
	Fstype string `json:"fstype"`

	// Bool to indicate if the drive for a container was hotplugged.
	HotpluggedDrive bool `json:"hotpluggedDrive"`

	// PCI slot at which the block device backing the container rootfs is attached.
	RootfsPCIAddr string `json:"rootfsPCIAddr"`

	// Pid is the process id of the sandbox container which is the first
	// container to be started.
	Pid int `json:"pid"`
}

State is a sandbox state structure.

type SystemMountsInfo 

type SystemMountsInfo struct {
	// Indicates if /dev has been passed as a bind mount for the host /dev
	BindMountDev bool

	// Size of /dev/shm assigned on the host.
	DevShmSize uint
}

SystemMountsInfo describes additional information for system mounts that the agent needs to handle

type ThrottlingData 

type ThrottlingData struct {
	// Number of periods with throttling active
	Periods uint64 `json:"periods,omitempty"`
	// Number of periods when the container hit its throttling limit.
	ThrottledPeriods uint64 `json:"throttled_periods,omitempty"`
	// Aggregate time the container was throttled for in nanoseconds.
	ThrottledTime uint64 `json:"throttled_time,omitempty"`
}

ThrottlingData gather the date related to container cpu throttling.

type TypedDevice 

type TypedDevice struct {
	Type string

	// Data is assigned the Device object.
	// This being declared as RawMessage prevents it from being  marshalled/unmarshalled.
	// We do that explicitly depending on Type.
	Data json.RawMessage
}

TypedDevice is used as an intermediate representation for marshalling and unmarshalling Device implementations.

type TypedJSONEndpoint 

type TypedJSONEndpoint struct {
	Type EndpointType
	Data json.RawMessage
}

TypedJSONEndpoint is used as an intermediate representation for marshalling and unmarshalling Endpoint objects.

type VC 

type VC interface {
	SetLogger(logger *logrus.Entry)
	SetFactory(Factory)

	CreateSandbox(sandboxConfig SandboxConfig) (VCSandbox, error)
	DeleteSandbox(sandboxID string) (VCSandbox, error)
	FetchSandbox(sandboxID string) (VCSandbox, error)
	ListSandbox() ([]SandboxStatus, error)
	PauseSandbox(sandboxID string) (VCSandbox, error)
	ResumeSandbox(sandboxID string) (VCSandbox, error)
	RunSandbox(sandboxConfig SandboxConfig) (VCSandbox, error)
	StartSandbox(sandboxID string) (VCSandbox, error)
	StatusSandbox(sandboxID string) (SandboxStatus, error)
	StopSandbox(sandboxID string) (VCSandbox, error)

	CreateContainer(sandboxID string, containerConfig ContainerConfig) (VCSandbox, VCContainer, error)
	DeleteContainer(sandboxID, containerID string) (VCContainer, error)
	EnterContainer(sandboxID, containerID string, cmd Cmd) (VCSandbox, VCContainer, *Process, error)
	KillContainer(sandboxID, containerID string, signal syscall.Signal, all bool) error
	StartContainer(sandboxID, containerID string) (VCContainer, error)
	StatusContainer(sandboxID, containerID string) (ContainerStatus, error)
	StatsContainer(sandboxID, containerID string) (ContainerStats, error)
	StopContainer(sandboxID, containerID string) (VCContainer, error)
	ProcessListContainer(sandboxID, containerID string, options ProcessListOptions) (ProcessList, error)
	UpdateContainer(sandboxID, containerID string, resources specs.LinuxResources) error
	PauseContainer(sandboxID, containerID string) error
	ResumeContainer(sandboxID, containerID string) error
}

VC is the Virtcontainers interface

type VCContainer 

type VCContainer interface {
	GetAnnotations() map[string]string
	GetPid() int
	GetToken() string
	ID() string
	Sandbox() VCSandbox
	Process() Process
	SetPid(pid int) error
}

VCContainer is the Container interface (required since virtcontainers.Container only contains private fields)

func DeleteContainer 

func DeleteContainer(sandboxID, containerID string) (VCContainer, error)

DeleteContainer is the virtcontainers container deletion entry point. DeleteContainer deletes a Container from a Sandbox. If the container is running, it needs to be stopped first.

func StartContainer 

func StartContainer(sandboxID, containerID string) (VCContainer, error)

StartContainer is the virtcontainers container starting entry point. StartContainer starts an already created container.

func StopContainer 

func StopContainer(sandboxID, containerID string) (VCContainer, error)

StopContainer is the virtcontainers container stopping entry point. StopContainer stops an already running container.

type VCImpl 

type VCImpl struct {
	// contains filtered or unexported fields
}

VCImpl is the official virtcontainers function of the same name.

func (*VCImpl) CreateContainer 

func (impl *VCImpl) CreateContainer(sandboxID string, containerConfig ContainerConfig) (VCSandbox, VCContainer, error)

CreateContainer implements the VC function of the same name.

func (*VCImpl) CreateSandbox 

func (impl *VCImpl) CreateSandbox(sandboxConfig SandboxConfig) (VCSandbox, error)

CreateSandbox implements the VC function of the same name.

func (*VCImpl) DeleteContainer 

func (impl *VCImpl) DeleteContainer(sandboxID, containerID string) (VCContainer, error)

DeleteContainer implements the VC function of the same name.

func (*VCImpl) DeleteSandbox 

func (impl *VCImpl) DeleteSandbox(sandboxID string) (VCSandbox, error)

DeleteSandbox implements the VC function of the same name.

func (*VCImpl) EnterContainer 

func (impl *VCImpl) EnterContainer(sandboxID, containerID string, cmd Cmd) (VCSandbox, VCContainer, *Process, error)

EnterContainer implements the VC function of the same name.

func (*VCImpl) FetchSandbox 

func (impl *VCImpl) FetchSandbox(sandboxID string) (VCSandbox, error)

FetchSandbox will find out and connect to an existing sandbox and return the sandbox structure.

func (*VCImpl) KillContainer 

func (impl *VCImpl) KillContainer(sandboxID, containerID string, signal syscall.Signal, all bool) error

KillContainer implements the VC function of the same name.

func (*VCImpl) ListSandbox 

func (impl *VCImpl) ListSandbox() ([]SandboxStatus, error)

ListSandbox implements the VC function of the same name.

func (*VCImpl) PauseContainer 

func (impl *VCImpl) PauseContainer(sandboxID, containerID string) error

PauseContainer implements the VC function of the same name.

func (*VCImpl) PauseSandbox 

func (impl *VCImpl) PauseSandbox(sandboxID string) (VCSandbox, error)

PauseSandbox implements the VC function of the same name.

func (*VCImpl) ProcessListContainer 

func (impl *VCImpl) ProcessListContainer(sandboxID, containerID string, options ProcessListOptions) (ProcessList, error)

ProcessListContainer implements the VC function of the same name.

func (*VCImpl) ResumeContainer 

func (impl *VCImpl) ResumeContainer(sandboxID, containerID string) error

ResumeContainer implements the VC function of the same name.

func (*VCImpl) ResumeSandbox 

func (impl *VCImpl) ResumeSandbox(sandboxID string) (VCSandbox, error)

ResumeSandbox implements the VC function of the same name.

func (*VCImpl) RunSandbox 

func (impl *VCImpl) RunSandbox(sandboxConfig SandboxConfig) (VCSandbox, error)

RunSandbox implements the VC function of the same name.

func (*VCImpl) SetFactory 

func (impl *VCImpl) SetFactory(factory Factory)

SetFactory implements the VC function of the same name.

func (*VCImpl) SetLogger 

func (impl *VCImpl) SetLogger(logger *logrus.Entry)

SetLogger implements the VC function of the same name.

func (*VCImpl) StartContainer 

func (impl *VCImpl) StartContainer(sandboxID, containerID string) (VCContainer, error)

StartContainer implements the VC function of the same name.

func (*VCImpl) StartSandbox 

func (impl *VCImpl) StartSandbox(sandboxID string) (VCSandbox, error)

StartSandbox implements the VC function of the same name.

func (*VCImpl) StatsContainer 

func (impl *VCImpl) StatsContainer(sandboxID, containerID string) (ContainerStats, error)

StatsContainer implements the VC function of the same name.

func (*VCImpl) StatusContainer 

func (impl *VCImpl) StatusContainer(sandboxID, containerID string) (ContainerStatus, error)

StatusContainer implements the VC function of the same name.

func (*VCImpl) StatusSandbox 

func (impl *VCImpl) StatusSandbox(sandboxID string) (SandboxStatus, error)

StatusSandbox implements the VC function of the same name.

func (*VCImpl) StopContainer 

func (impl *VCImpl) StopContainer(sandboxID, containerID string) (VCContainer, error)

StopContainer implements the VC function of the same name.

func (*VCImpl) StopSandbox 

func (impl *VCImpl) StopSandbox(sandboxID string) (VCSandbox, error)

StopSandbox implements the VC function of the same name.

func (*VCImpl) UpdateContainer 

func (impl *VCImpl) UpdateContainer(sandboxID, containerID string, resources specs.LinuxResources) error

UpdateContainer implements the VC function of the same name.

type VCSandbox 

type VCSandbox interface {
	Annotations(key string) (string, error)
	GetAllContainers() []VCContainer
	GetAnnotations() map[string]string
	GetContainer(containerID string) VCContainer
	ID() string
	SetAnnotations(annotations map[string]string) error

	Pause() error
	Resume() error
	Release() error
	Monitor() (chan error, error)
	Delete() error
	Status() SandboxStatus
	CreateContainer(contConfig ContainerConfig) (VCContainer, error)
	DeleteContainer(contID string) (VCContainer, error)
	StartContainer(containerID string) (VCContainer, error)
	StatusContainer(containerID string) (ContainerStatus, error)
	StatsContainer(containerID string) (ContainerStats, error)
	EnterContainer(containerID string, cmd Cmd) (VCContainer, *Process, error)
	UpdateContainer(containerID string, resources specs.LinuxResources) 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)
}

VCSandbox is the Sandbox interface (required since virtcontainers.Sandbox only contains private fields)

func CreateSandbox 

func CreateSandbox(sandboxConfig SandboxConfig, factory Factory) (VCSandbox, error)

CreateSandbox is the virtcontainers sandbox creation entry point. CreateSandbox creates a sandbox and its containers. It does not start them.

func DeleteSandbox 

func DeleteSandbox(sandboxID string) (VCSandbox, error)

DeleteSandbox is the virtcontainers sandbox deletion entry point. DeleteSandbox will stop an already running container and then delete it.

func FetchSandbox 

func FetchSandbox(sandboxID string) (VCSandbox, error)

FetchSandbox is the virtcontainers sandbox fetching entry point. FetchSandbox will find out and connect to an existing sandbox and return the sandbox structure. The caller is responsible of calling VCSandbox.Release() after done with it.

func PauseSandbox 

func PauseSandbox(sandboxID string) (VCSandbox, error)

PauseSandbox is the virtcontainers pausing entry point which pauses an already running sandbox.

func ResumeSandbox 

func ResumeSandbox(sandboxID string) (VCSandbox, error)

ResumeSandbox is the virtcontainers resuming entry point which resumes (or unpauses) and already paused sandbox.

func RunSandbox 

func RunSandbox(sandboxConfig SandboxConfig, factory Factory) (VCSandbox, error)

RunSandbox is the virtcontainers sandbox running entry point. RunSandbox creates a sandbox and its containers and then it starts them.

func StartSandbox 

func StartSandbox(sandboxID string) (VCSandbox, error)

StartSandbox is the virtcontainers sandbox starting entry point. StartSandbox will talk to the given hypervisor to start an existing sandbox and all its containers. It returns the sandbox ID.

func StopSandbox 

func StopSandbox(sandboxID string) (VCSandbox, error)

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.

type VM 

type VM struct {
	// contains filtered or unexported fields
}

VM is abstraction of a virtual machine.

func NewVM 

func NewVM(config VMConfig) (*VM, error)

NewVM creates a new VM based on provided VMConfig.

func (*VM) AddCPUs 

func (v *VM) AddCPUs(num uint32) error

AddCPUs adds num of CPUs to the VM.

func (*VM) AddMemory 

func (v *VM) AddMemory(numMB uint32) error

AddMemory adds numMB of memory to the VM.

func (*VM) OnlineCPUMemory 

func (v *VM) OnlineCPUMemory() error

OnlineCPUMemory puts the hotplugged CPU and memory online.

func (*VM) Pause 

func (v *VM) Pause() error

Pause pauses a VM.

func (*VM) Resume 

func (v *VM) Resume() error

Resume resumes a paused VM.

func (*VM) Save 

func (v *VM) Save() error

Save saves a VM to persistent disk.

func (*VM) Start 

func (v *VM) Start() error

Start kicks off a configured VM.

func (*VM) Stop 

func (v *VM) Stop() error

Stop stops a VM process.

type VMConfig 

type VMConfig struct {
	HypervisorType   HypervisorType
	HypervisorConfig HypervisorConfig

	AgentType   AgentType
	AgentConfig interface{}
}

VMConfig is a collection of all info that a new blackbox VM needs.

func (*VMConfig) Valid 

func (c *VMConfig) Valid() error

Valid check VMConfig validity.

type VhostUserEndpoint 

type VhostUserEndpoint struct {
	// Path to the vhost-user socket on the host system
	SocketPath string
	// MAC address of the interface
	HardAddr           string
	IfaceName          string
	EndpointProperties NetworkInfo
	EndpointType       EndpointType
}

VhostUserEndpoint represents a vhost-user socket based network interface

func (*VhostUserEndpoint) Attach 

func (endpoint *VhostUserEndpoint) Attach(h hypervisor) error

Attach for vhostuser endpoint

func (*VhostUserEndpoint) Detach 

func (endpoint *VhostUserEndpoint) Detach(netNsCreated bool, netNsPath string) error

Detach for vhostuser endpoint

func (*VhostUserEndpoint) HardwareAddr 

func (endpoint *VhostUserEndpoint) HardwareAddr() string

HardwareAddr returns the mac address of the vhostuser network interface

func (*VhostUserEndpoint) Name 

func (endpoint *VhostUserEndpoint) Name() string

Name returns name of the interface.

func (*VhostUserEndpoint) Properties 

func (endpoint *VhostUserEndpoint) Properties() NetworkInfo

Properties returns the properties of the interface.

func (*VhostUserEndpoint) SetProperties 

func (endpoint *VhostUserEndpoint) SetProperties(properties NetworkInfo)

SetProperties sets the properties of the endpoint.

func (*VhostUserEndpoint) Type 

func (endpoint *VhostUserEndpoint) Type() EndpointType

Type indentifies the endpoint as a vhostuser endpoint.

type VirtualEndpoint 

type VirtualEndpoint struct {
	NetPair            NetworkInterfacePair
	EndpointProperties NetworkInfo
	Physical           bool
	EndpointType       EndpointType
}

VirtualEndpoint gathers a network pair and its properties.

func (*VirtualEndpoint) Attach 

func (endpoint *VirtualEndpoint) Attach(h hypervisor) error

Attach for virtual endpoint bridges the network pair and adds the tap interface of the network pair to the hypervisor.

func (*VirtualEndpoint) Detach 

func (endpoint *VirtualEndpoint) Detach(netNsCreated bool, netNsPath string) error

Detach for the virtual endpoint tears down the tap and bridge created for the veth interface.

func (*VirtualEndpoint) HardwareAddr 

func (endpoint *VirtualEndpoint) HardwareAddr() string

HardwareAddr returns the mac address that is assigned to the tap interface in th network pair.

func (*VirtualEndpoint) Name 

func (endpoint *VirtualEndpoint) Name() string

Name returns name of the veth interface in the network pair.

func (*VirtualEndpoint) Properties 

func (endpoint *VirtualEndpoint) Properties() NetworkInfo

Properties returns properties for the veth interface in the network pair.

func (*VirtualEndpoint) SetProperties 

func (endpoint *VirtualEndpoint) SetProperties(properties NetworkInfo)

SetProperties sets the properties for the endpoint.

func (*VirtualEndpoint) Type 

func (endpoint *VirtualEndpoint) Type() EndpointType

Type identifies the endpoint as a virtual endpoint.

type Volume 

type Volume struct {
	// MountTag is a label used as a hint to the guest.
	MountTag string

	// HostPath is the host filesystem path for this volume.
	HostPath string
}

Volume is a shared volume between the host and the VM, defined by its mount tag and its host path.

type Volumes 

type Volumes []Volume

Volumes is a Volume list.

func (*Volumes) Set 

func (v *Volumes) Set(volStr string) error

Set assigns volume values from string to a Volume.

func (*Volumes) String 

func (v *Volumes) String() string

String converts a Volume to a string.

Source Files

View all Source files

Directories

Path Synopsis
device
api
config
drivers
manager
base
cache
direct
template
hack
virtc command
hook
mock command
pkg
annotations
annotations/dockershim
cni
hyperstart
hyperstart/mock
mock
nsenter
oci
uuid
Package uuid can be used to generate 128 bit UUIDs compatible with rfc4122.
 Package uuid can be used to generate 128 bit UUIDs compatible with rfc4122.
vcmock
shim
mock/cc-shim command
mock/kata-shim command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.