Skip to content
This repository has been archived by the owner on May 12, 2021. It is now read-only.

Developer Guide

Jump to bottom
James O. D. Hunt edited this page Jan 31, 2018 · 22 revisions

Warning

This document is written specifically for developers to allow them to try out this early version of Kata Containers.

Assumptions

  • You are working on a non-critical test or development system.

  • You already have the following installed:

    • Docker.
    • golang version 1.8.3 or newer.
    • make.
    • gcc (required for building the shim and runtime).

  • You have installed the Clear Containers linux-container and qemu-lite packages containing the guest kernel images and hypervisor. These packages are automatically installed when you install Clear Containers, but can be installed separately:

    https://github.com/clearcontainers/runtime/wiki/Installation

Build and install Kata proxy

go get -d -u github.com/kata-containers/proxy
cd $GOPATH/src/github.com/kata-containers/proxy && make && sudo make install

Build and install Kata shim

go get -d -u github.com/kata-containers/shim
cd $GOPATH/src/github.com/kata-containers/shim && make && sudo make install

Build and install a Kata Containers runtime

Currently, there are two available runtimes:

  • The Intel® Clear Containers based-runtime (KATA_RUNTIME=cc).
  • The Hyper runv-based runtime (KATA_RUNTIME=runv).
go get -d -u github.com/kata-containers/runtime
cd $GOPATH/src/github.com/kata-containers/runtime

# Set to either 'cc' or 'runv'.
runtime=

make KATA_RUNTIME=$runtime && sudo -E PATH=$PATH make KATA_RUNTIME=$runtime install

Whichever runtime you build with, the build will create a /usr/local/bin/kata-runtime symlink. This links to the particular build variant you selected using the KATA_RUNTIME variable.

Enable full debug

If you are using a Clear Containers-based runtime (KATA_RUNTIME=cc), enable full debug as follows:

sudo sed -i -e 's/^# *\(enable_debug\).*=.*$/\1 = true/g' /usr/share/defaults/kata-containers/configuration.toml

Create an image

Build a custom Kata agent - OPTIONAL

Note:

  • You only do this step if you wish to test with the latest version of the agent.
go get -d -u github.com/kata-containers/agent
cd $GOPATH/src/github.com/kata-containers/agent && make

Get the osbuilder

go get -d -u github.com/kata-containers/osbuilder

Create a rootfs image

cd $GOPATH/src/github.com/kata-containers/osbuilder/rootfs-builder
script -fec 'sudo -E GOPATH=$GOPATH USE_DOCKER=true ./rootfs.sh clearlinux'

Note:

  • You must ensure that the default Docker runtime is runc to make use of the USE_DOCKER variable. If that is not the case, simply remove the variable from the command above. See Checking Docker default runtime.

Add a custom agent to the image - OPTIONAL

Note:

  • You only do this step if you wish to test with the latest version of the agent.
sudo install -o root -g root -m 0550 -t rootfs/bin ../../agent/kata-agent
sudo install -o root -g root -m 0440 ../../agent/kata-agent.service rootfs/usr/lib/systemd/system/
sudo install -o root -g root -m 0440 ../../agent/kata-containers.target rootfs/usr/lib/systemd/system/

Build the image

cd $GOPATH/src/github.com/kata-containers/osbuilder/image-builder
script -fec 'sudo -E USE_DOCKER=true ./image_builder.sh ../rootfs-builder/rootfs'

Note:

  • You must ensure that the default Docker runtime is runc to make use of the USE_DOCKER variable. If that is not the case, simply remove the variable from the command above. See Checking Docker default runtime.

Install the image

commit=$(git log --format=%h -1 HEAD)
date=$(date +%Y-%m-%d-%T.%N%z)
image="kata-containers-${date}-${commit}"

sudo install -o root -g root -m 0640 -D kata-containers.img "/usr/share/kata-containers/${image}"
(cd /usr/share/kata-containers && sudo ln -sf "$image" kata-containers.img)

Install guest kernel images

Note: these currently come from the Clear Containers linux-container package. See Assumptions.

sudo ln -s /usr/share/clear-containers/vmlinux.container /usr/share/kata-containers/
sudo ln -s /usr/share/clear-containers/vmlinuz.container /usr/share/kata-containers/

Update Docker config

dir=/etc/systemd/system/docker.service.d
file="$dir/kata-containers.conf"
sudo mkdir -p "$dir"
sudo test -e "$file" || echo -e "[Service]\nType=simple\nExecStart=\nExecStart=/usr/bin/dockerd -D --default-runtime runc" | sudo tee "$file"
sudo sed -i 's!^\(ExecStart=[^$].*$\)!\1 --add-runtime kata-runtime=/usr/local/bin/kata-runtime!g' "$file"
sudo systemctl daemon-reload
sudo systemctl restart docker

Test

sudo docker run -ti --runtime kata-runtime busybox sh

Appendices

Checking Docker default runtime

sudo docker info|grep -i "default runtime"|cut -d: -f2-|grep -q runc  && echo "SUCCESS" || echo "ERROR: Wrong default runtime"
Clone this wiki locally