Categorygithub.com/containers/virtcontainers
modulepackage
0.2.3
Repository: https://github.com/containers/virtcontainers.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
27
Dependents
1
Files
3.6k SLOC

# README

Build Status Go Report Card Coverage Status GoDoc

virtcontainers

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.

Out of scope

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

virtcontainers and CRI

virtcontainers's API is loosely inspired by the Kubernetes CRI because we believe it provides the right level of abstractions for containerized pods. 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

Pods

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

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

Hypervisors

The virtcontainers package relies on hypervisors to start and stop virtual machine where pods 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.

API

The high level virtcontainers API is the following one:

Pod API

  • CreatePod(podConfig PodConfig) creates a Pod. The Pod is prepared and will run into a virtual machine. It is not started, i.e. the VM is not running after CreatePod() is called.

  • DeletePod(podID string) deletes a Pod. The function will fail if the Pod is running. In that case StopPod() needs to be called first.

  • StartPod(podID string) starts an already created Pod.

  • StopPod(podID string) stops an already running Pod.

  • ListPod() lists all running Pods on the host.

  • EnterPod(cmd Cmd) enters a Pod root filesystem and runs a given command.

  • PodStatus(podID string) returns a detailed Pod status.

Container API

  • CreateContainer(podID string, container ContainerConfig) creates a Container on a given Pod.

  • DeleteContainer(podID, containerID string) deletes a Container from a Pod. If the container is running it needs to be stopped first.

  • StartContainer(podID, containerID string) starts an already created container.

  • StopContainer(podID, containerID string) stops an already running container.

  • EnterContainer(podID, containerID string, cmd Cmd) enters an already running container and runs a given command.

  • ContainerStatus(podID, containerID string) returns a detailed container status.

An example tool using the virtcontainers API is provided in the hack/virtc package.

# Packages

No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author

# Functions

CreateContainer is the virtcontainers container creation entry point.
CreatePod is the virtcontainers pod creation entry point.
DeleteContainer is the virtcontainers container deletion entry point.
DeletePod is the virtcontainers pod deletion entry point.
EnterContainer is the virtcontainers container command execution entry point.
ListPod is the virtcontainers pod listing entry point.
RunPod is the virtcontainers pod running entry point.
StartContainer is the virtcontainers container starting entry point.
StartPod is the virtcontainers pod starting entry point.
StatusContainer is the virtcontainers container status entry point.
StatusPod is the virtcontainers pod status entry point.
StopContainer is the virtcontainers container stopping entry point.
StopPod is the virtcontainers pod stopping entry point.

# Constants

CNINetworkModel is the CNI network.
CNMNetworkModel is the CNM network.
HyperstartAgent is the Hyper hyperstart agent.
MockHypervisor is a mock hypervisor for testing purposes.
NoopAgentType is the No-Op agent.
NoopNetworkModel is the No-Op network.
NsEnter is the nsenter spawner type.
QemuHypervisor is the QEMU hypervisor.
SSHdAgent is the SSH daemon agent.

# Structs

Cmd represents a command to execute in a running container.
Container is composed of a set of containers and a runtime environment.
ContainerConfig describes one container runtime configuration.
Endpoint gathers a network pair and its properties.
EnvVar is a key/value structure representing a command environment variable.
ExecInfo is the structure corresponding to the format expected by hyperstart to execute a command on the guest.
HyperConfig is a structure storing information needed for hyperstart agent initialization.
HypervisorConfig is the hypervisor configuration.
NetworkConfig is the network configuration related to a network.
NetworkInterface defines a network interface.
NetworkInterfacePair defines a pair between TAP and virtual network interfaces.
NetworkNamespace contains all data related to its network namespace.
Param is a key/value representation for hypervisor and kernel parameters.
Pod is composed of a set of containers and a runtime environment.
PodConfig is a Pod configuration.
Resources describes VM resources configuration.
Socket defines a socket to communicate between the host and any process inside the VM.
SshdConfig is a structure storing information needed for sshd agent initialization.
State is a pod state structure.
Volume is a shared volume between the host and the VM, defined by its mount tag and its host path.

# Type aliases

AgentType describes the type of guest agent a Pod should run.
HypervisorType describes an hypervisor type.
NetworkModel describes the type of network specification.
Sockets is a Socket list.
SpawnerType describes the type of guest agent a Pod should run.
Volumes is a Volume list.