virtcontainers

package module
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Nov 22, 2016 License: Apache-2.0 Imports: 19 Imported by: 0

README

Build Status Go Report Card Coverage Status GoDoc

VirtContainers

VirtContainers is a Go package for building hardware virtualized container runtimes.

Scope

VirtContainers is not a container runtime implementation, but aims at factorizing hardware virtualization code in order to build VM based container runtimes.

The few existing VM based container runtimes (Clear Containers, RunV, Rkt kvm stage 1) all share the same hardware virtualization semantics but use different code bases to implement them. VirtContainers 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 to the VirtContainers API.

Out of scope

Implementing yet another container runtime is out of VirtContainers scope. Any tools or executables provided with VirtContainers are only provided for demonstration or testing purposes.

VirtContainers and CRI

VirtContainers API is inspired by Kubernetes CRI runtime API because we believe it provides the right level of abstractions for containerized pods. Here we want to emphasize that despite the API similarities between those 2 projects, VirtContainers primary goal is not to build a Kubernetes CRI runtime server but to provide a generic, runtime specification agnostic, hardware virtualized containers library.

Design

Goals

VirtContainers is a container specification agnostic Go package and thus tries to abstract the various container runtime specifications (OCI, AppC and CRI) and present that as its high level API.

Pods

The VirtContainers execution unit is a Pod, i.e. VirtContainers callers 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 abstract 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.

Virtc example

Here we explain how to use the pod API from virtc command line.

Prepare your environment
Get your kernel

Fedora

$ sudo -E dnf config-manager --add-repo http://download.opensuse.org/repositories/home:clearlinux:preview:clear-containers-2.0/Fedora_24/home:clearlinux:preview:clear-containers-2.0.repo
$ sudo dnf install linux-container

Ubuntu

$ sudo sh -c "echo 'deb http://download.opensuse.org/repositories/home:/clearlinux:/preview:/clear-containers-2.0/xUbuntu_16.04/ /' >> /etc/apt/sources.list.d/cc-oci-runtime.list"
$ sudo apt install linux-container
Get your image

It has to be a recent Clear Linux image to make sure it contains hyperstart binary. You can dowload the following tested image, or any version more recent.

$ wget https://download.clearlinux.org/releases/11130/clear/clear-11130-containers.img.xz
$ unxz clear-11130-containers.img.xz
$ sudo cp clear-11130-containers.img /usr/share/clear-containers/clear-containers.img
Get virtc

Download virtc

$ go get github.com/sameo/virtcontainers

Build virtc

$ cd $GOPATH/src/github.com/sameo/virtcontainers
$ cd virtc && go build
Run virtc

All following commands needs to be run as root. Currently, virtc only starts single container pods.

Create your container bundle

As an example we will create a busybox bundle:

$ mkdir -p /tmp/bundles/busybox/
$ docker pull busybox
$ cd /tmp/bundles/busybox/
$ mkdir rootfs
$ docker export $(docker create busybox) | tar -C rootfs -xvf -
$ echo -e '#!/bin/sh\ncd "\"\n"sh"' > rootfs/.containerexec
$ echo -e 'HOME=/root\nPATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin\nTERM=xterm' > rootfs/.containerenv
Run a new pod (Create + Start)
./virtc pod run --bundle="/tmp/bundles/busybox/rootfs" --agent="hyperstart" --init-cmd="/bin/sh"
Create a new pod
./virtc pod create --bundle="/tmp/bundles/busybox/rootfs" --agent="hyperstart" --init-cmd="/bin/sh"

This should generate that kind of output

Created pod 306ecdcf-0a6f-4a06-a03e-86a7b868ffc8
Start an existing pod
./virtc pod start --id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8
Stop an existing pod
./virtc pod stop --id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8
Get the status of an existing pod and its containers
./virtc pod status --id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8

This should generate the following output:

POD ID                                  STATE   HYPERVISOR      AGENT
306ecdcf-0a6f-4a06-a03e-86a7b868ffc8    running qemu            hyperstart

CONTAINER ID    STATE
1               ready
Delete an existing pod
./virtc pod delete --id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8
List all existing pods
./virtc pod list

This should generate that kind of output

POD ID                                  STATE   HYPERVISOR      AGENT
306ecdcf-0a6f-4a06-a03e-86a7b868ffc8    running qemu            hyperstart
92d73f74-4514-4a0d-81df-db1cc4c59100    running qemu            hyperstart
7088148c-049b-4be7-b1be-89b3ae3c551c    ready   qemu            hyperstart
6d57654e-4804-4a91-b72d-b5fe375ed3e1    ready   qemu            hyperstart

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 pod.

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

The virtcontainers package manages both pods and containers lifecycles.

Example (CreateAndStartPod)

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

package main

import (
	"fmt"
	"strings"

	vc "github.com/sameo/virtcontainers"
)

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

// This example creates and starts a single container pod,
// 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/clear-containers/vmlinux.container",
		ImagePath:      "/usr/share/clear-containers/clear-containers.img",
		HypervisorPath: "/usr/bin/qemu-lite-system-x86_64",
	}

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

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

	// The pod configuration:
	// - One container
	// - Hypervisor is QEMU
	// - Agent is hyperstart
	podConfig := vc.PodConfig{
		VMConfig: vmConfig,

		HypervisorType:   vc.QemuHypervisor,
		HypervisorConfig: hypervisorConfig,

		AgentType:   vc.HyperstartAgent,
		AgentConfig: agConfig,

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

	_, err := vc.RunPod(podConfig)
	if err != nil {
		fmt.Printf("Could not run pod: %s", err)
	}

	return
}

Index

Examples

Constants

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

	// SSHdAgent is the SSH daemon agent.
	SSHdAgent = "sshd"

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

Variables

This section is empty.

Functions

func ListPod 

func ListPod() error

ListPod is the virtcontainers pod listing entry point.

func StatusContainer 

func StatusContainer(podID, containerID string) error

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

func StatusPod 

func StatusPod(podID string) error

StatusPod is the virtcontainers pod status entry point.

Types

type AgentType 

type AgentType string

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

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 Cmd 

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

	User  string
	Group string
}

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 CreateContainer 

func CreateContainer(podID string, containerConfig ContainerConfig) (*Container, error)

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

func DeleteContainer 

func DeleteContainer(podID, containerID string) (*Container, error)

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

func EnterContainer 

func EnterContainer(podID, containerID string, cmd Cmd) (*Container, error)

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

func StartContainer 

func StartContainer(podID, containerID string) (*Container, error)

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

func StopContainer 

func StopContainer(podID, containerID string) (*Container, error)

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

func (*Container) ID 

func (c *Container) ID() string

ID returns the container identifier string.

type ContainerConfig 

type ContainerConfig struct {
	ID string

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

	// Interactive specifies if the container runs in the foreground.
	Interactive bool

	// Console is a console path provided by the caller.
	Console string

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

ContainerConfig describes one container runtime configuration.

type EnvVar 

type EnvVar struct {
	Var   string
	Value string
}

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

type ExecInfo 

type ExecInfo struct {
	Container string            `json:"container"`
	Process   hyperJson.Process `json:"process"`
}

ExecInfo is the structure corresponding to the format expected by hyperstart to execute a command on the guest.

type HyperConfig 

type HyperConfig struct {
	SockCtlName string
	SockTtyName string
	Volumes     []Volume
	Sockets     []Socket
}

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

type HypervisorConfig 

type HypervisorConfig struct {
	// KernelPath is the guest kernel host path.
	KernelPath string

	// ImagePath is the guest image host path.
	ImagePath string

	// HypervisorPath is the hypervisor executable host path.
	HypervisorPath string

	// KernelParams are additional guest kernel parameters.
	KernelParams []Param

	// HypervisorParams are additional hypervisor parameters.
	HypervisorParams []Param
}

HypervisorConfig is the hypervisor configuration.

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 Param 

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

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

type Pod 

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

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

func CreatePod 

func CreatePod(podConfig PodConfig) (*Pod, error)

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

func DeletePod 

func DeletePod(podID string) (*Pod, error)

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

func RunPod 

func RunPod(podConfig PodConfig) (*Pod, error)

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

func StartPod 

func StartPod(podID string) (*Pod, error)

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

func StopPod 

func StopPod(podID string) (*Pod, error)

StopPod is the virtcontainers pod stopping entry point. StopPod will talk to the given agent to stop an existing pod and destroy all containers within that pod.

func (*Pod) ID 

func (p *Pod) ID() string

ID returns the pod identifier string.

type PodConfig 

type PodConfig struct {
	ID string

	// VMConfig is the VM configuration to set for this pod.
	VMConfig Resources

	HypervisorType   HypervisorType
	HypervisorConfig HypervisorConfig

	AgentType   AgentType
	AgentConfig interface{}

	// Rootfs is the pod root file system in the host.
	// This can be left empty if we only have a set of containers
	// workload images and expect the agent to aggregate them into
	// a pod from the guest.
	RootFs string

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

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

PodConfig is a Pod configuration.

type Resources 

type Resources struct {
	// VCPUs is the number of available virtual CPUs.
	VCPUs uint

	// Memory is the amount of available memory in MiB.
	Memory uint
}

Resources describes VM resources configuration.

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 Pod 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 SshdConfig 

type SshdConfig struct {
	Username    string
	PrivKeyFile string
	Server      string
	Port        string
	Protocol    string

	Spawner SpawnerType
}

SshdConfig is a structure storing information needed for sshd agent initialization.

type State 

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

State is a pod state structure.

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
mock

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.