kata-containers/virtcontainers/hack/virtc

virtc

virtc is a simple command-line tool that serves to demonstrate typical usage of the virtcontainers API. This is example software; unlike other projects like runc, runv, or rkt, virtcontainers is not a full container runtime.

Virtc example

Here we explain how to use the sandbox and container 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.1/Fedora_25/home:clearlinux:preview:clear-containers-2.1.repo
$ sudo dnf install linux-container 

Ubuntu

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

Get your image

Retrieve a recent Clear Containers image to make sure it contains a recent version of hyperstart agent.

To download and install the latest image:

$ latest_version=$(curl -sL https://download.clearlinux.org/latest)
$ curl -LO "https://download.clearlinux.org/current/clear-${latest_version}-containers.img.xz"
$ unxz clear-${latest_version}-containers.img.xz
$ sudo mkdir -p /usr/share/clear-containers/
$ sudo install --owner root --group root --mode 0644 clear-${latest_version}-containers.img /usr/share/clear-containers/
$ sudo ln -fs /usr/share/clear-containers/clear-${latest_version}-containers.img /usr/share/clear-containers/clear-containers.img

Get virtc

Download virtcontainers project

$ go get github.com/kata-containers/runtime/virtcontainers

Build and setup your environment

$ cd $GOPATH/src/github.com/kata-containers/runtime/virtcontainers
$ go build -o virtc hack/virtc/main.go
$ sudo -E bash ./utils/virtcontainers-setup.sh

virtcontainers-setup.sh setup your environment performing different tasks. Particularly, it creates a busybox bundle, and it creates CNI configuration files needed to run virtc with CNI plugins.

Get cc-proxy (optional)

If you plan to start virtc with the hyperstart agent, you will have to use cc-proxy as a proxy, meaning you have to perform extra steps to setup your environment.

$ go get github.com/clearcontainers/proxy
$ cd $GOPATH/src/github.com/clearcontainers/proxy
$ make
$ sudo make install

If you want to see the traces from the proxy when virtc will run, you can manually start it with appropriate debug level:

$ sudo /usr/libexec/clearcontainers/cc-proxy -v 3

This will generate output similar to the following:

I0410 08:58:49.058881    5384 proxy.go:521] listening on /var/run/clearcontainers/proxy.sock
I0410 08:58:49.059044    5384 proxy.go:566] proxy started

The proxy socket specified in the example log output has to be used as virtc's --proxy-url option.

Get cc-shim (optional)

If you plan to start virtc with the hyperstart agent (implying the use of cc-proxy as a proxy), you will have to rely on cc-shim in order to interact with the process running inside your container. First, you will have to perform extra steps to setup your environment.

$ go get github.com/clearcontainers/shim
$ cd $GOPATH/src/github.com/clearcontainers/shim && ./autogen.sh
$ make
$ sudo make install

The shim will be installed at the following location: /usr/libexec/clear-containers/cc-shim. There will be three cases where you will be able to interact with your container's process through cc-shim:

Start a new container

# ./virtc container start --id=1 --sandbox-id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8

Execute a new process on a running container

# ./virtc container enter --id=1 --sandbox-id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8

Start a sandbox with container(s) previously created

# ./virtc sandbox start --id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8

Notice that in both cases, the --sandbox-id and --id options have been defined when previously creating a sandbox and a container.

Run virtc

All following commands MUST be run as root. By default, and unless you decide to modify it and rebuild it, virtc starts empty sandboxes (no container started).

Run a new sandbox (Create + Start)

# ./virtc sandbox run --agent="hyperstart" --network="CNI" --proxy="ccProxy" --proxy-url="unix:///var/run/clearcontainers/proxy.sock" --shim="ccShim" --shim-path="/usr/libexec/cc-shim"

Create a new sandbox

# ./virtc sandbox run --agent="hyperstart" --network="CNI" --proxy="ccProxy" --proxy-url="unix:///var/run/clearcontainers/proxy.sock" --shim="ccShim" --shim-path="/usr/libexec/cc-shim"

This will generate output similar to the following:

Sandbox 306ecdcf-0a6f-4a06-a03e-86a7b868ffc8 created

Start an existing sandbox

# ./virtc sandbox start --id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8

This will generate output similar to the following:

Sandbox 306ecdcf-0a6f-4a06-a03e-86a7b868ffc8 started

Stop an existing sandbox

# ./virtc sandbox stop --id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8

This will generate output similar to the following:

Sandbox 306ecdcf-0a6f-4a06-a03e-86a7b868ffc8 stopped

Get the status of an existing sandbox and its containers

# ./virtc sandbox status --id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8

This will generate output similar to the following (assuming the sandbox has been started):

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

CONTAINER ID    STATE

Delete an existing sandbox

# ./virtc sandbox delete --id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8

This will generate output similar to the following:

Sandbox 306ecdcf-0a6f-4a06-a03e-86a7b868ffc8 deleted

List all existing sandboxes

# ./virtc sandbox list

This should generate that kind of output

SB 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

Create a new container

# ./virtc container create --id=1 --sandbox-id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8 --rootfs="/tmp/bundles/busybox/rootfs" --cmd="/bin/ifconfig" --console="/dev/pts/30"

This will generate output similar to the following:

Container 1 created

Note: The option --console can be any existing console. Don't try to provide $(tty) as it is your current console, and you would not be able to get your console back as the shim would be listening to this indefinitely. Instead, you would prefer to open a new shell and get the $(tty) from this shell. That way, you make sure you have a dedicated input/output terminal.

Start an existing container

# ./virtc container start --id=1 --sandbox-id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8

This will generate output similar to the following:

Container 1 started

Run a new process on an existing container

# ./virtc container enter --id=1 --sandbox-id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8 --cmd="/bin/ps" --console="/dev/pts/30"

This will generate output similar to the following:

Container 1 entered

Note: The option --console can be any existing console. Don't try to provide $(tty) as it is your current console, and you would not be able to get your console back as the shim would be listening to this indefinitely. Instead, you would prefer to open a new shell and get the $(tty) from this shell. That way, you make sure you have a dedicated input/output terminal.

Stop an existing container

# ./virtc container stop --id=1 --sandbox-id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8

This will generate output similar to the following:

Container 1 stopped

Delete an existing container

# ./virtc container delete --id=1 --sandbox-id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8

This will generate output similar to the following:

Container 1 deleted

Get the status of an existing container

# ./virtc container status --id=1 --sandbox-id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8

This will generate output similar to the following (assuming the container has been started):

CONTAINER ID    STATE
1               running