Important

This is the latest documentation for the unstable development branch of Project ACRN (master).
Use the drop-down menu on the left to select documentation for a stable release such as v3.2 or v3.0.

Run Kata Containers on a Service VM

This tutorial describes how to install, configure, and run Kata Containers on the Ubuntu based Service VM with the ACRN hypervisor. In this configuration, Kata Containers leverage the ACRN hypervisor instead of QEMU, which is used by default. Refer to the Kata Containers with ACRN presentation for more details on Kata Containers and how the integration with ACRN has been done.

Prerequisites

  1. Refer to the ACRN supported hardware.

  2. For a default prebuilt ACRN binary in the end-to-end (E2E) package, you must have 4 CPU cores or enable “CPU Hyper-threading” in order to have 4 CPU threads for 2 CPU cores.

  3. Follow the Getting Started Guide to set up the ACRN Service VM based on Ubuntu.

  4. This tutorial is validated on the following configurations:

    • ACRN v2.0 (branch: release_2.0)

    • Ubuntu 20.04

  5. Kata Containers are supported for ACRN hypervisors configured for the Industry or SDC scenarios.

Install Docker

The following instructions install Docker* on the Ubuntu Service VM. Refer to the Get Docker Engine - Community for Ubuntu installation guide for detailed information.

  1. Install the following prerequisite packages:

    $ sudo apt-get install apt-transport-https ca-certificates curl
    
  2. Run the following commands to add Docker’s official GPG key, set up the repository, and install the Docker Engine - Community from the repository:

    $ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
    $ sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
    $ sudo apt-get update
    $ sudo apt-get install -y docker-ce docker-ce-cli containerd.io
    

Install Kata Containers

Kata Containers provide a variety of installation methods, this guide uses kata-deploy to automate the Kata Containers installation procedure.

  1. Install Kata Containers:

    $ sudo docker run -v /opt/kata:/opt/kata -v /var/run/dbus:/var/run/dbus -v /run/systemd:/run/systemd -v /etc/docker:/etc/docker -it katadocker/kata-deploy kata-deploy-docker install
    
  2. Install the acrnctl tool:

    $ cd /home/acrn/work/acrn-hypervisor
    $ sudo cp build/misc/tools/acrnctl /usr/bin/
    

    Note

    This assumes you have built ACRN on this machine following the instructions in the Getting Started Guide.

  3. Modify the /etc/docker/daemon.json file in order to:

    1. Add a kata-acrn runtime (runtimes section).

      Note

      In order to run Kata with ACRN, the container stack must provide block-based storage, such as device-mapper. Since Docker may be configured to use overlay2 storage driver, the above configuration also instructs Docker to use device-mapper storage driver.

    2. Use the device-mapper storage driver.

    3. Make Docker use Kata Containers by default.

    These changes are highlighted below.

    Code Block 1 /etc/docker/daemon.json
    {
      "storage-driver": "devicemapper",
      "default-runtime": "kata-acrn",
      "runtimes": {
        "kata-qemu": {
          "path": "/opt/kata/bin/kata-runtime",
          "runtimeArgs": [ "--kata-config", "/opt/kata/share/defaults/kata-containers/configuration-qemu.toml" ]
        },
        "kata-qemu-virtiofs": {
          "path": "/opt/kata/bin/kata-runtime",
          "runtimeArgs": [ "--kata-config", "/opt/kata/share/defaults/kata-containers/configuration-qemu-virtiofs.toml" ]
        },
        "kata-fc": {
          "path": "/opt/kata/bin/kata-runtime",
          "runtimeArgs": [ "--kata-config", "/opt/kata/share/defaults/kata-containers/configuration-fc.toml" ]
        },
        "kata-clh": {
          "path": "/opt/kata/bin/kata-runtime",
          "runtimeArgs": [ "--kata-config", "/opt/kata/share/defaults/kata-containers/configuration-clh.toml" ]
        },
        "kata-acrn": {
          "path": "/opt/kata/bin/kata-runtime",
          "runtimeArgs": [ "--kata-config", "/opt/kata/share/defaults/kata-containers/configuration-acrn.toml" ]
        }
      }
    }
    
  4. Configure Kata to use ACRN.

    Modify the [hypervisor.acrn] section in the /opt/kata/share/defaults/kata-containers/configuration-acrn.toml file.

    Code Block 2 /opt/kata/share/defaults/kata-containers/configuration-acrn.toml
    [hypervisor.acrn]
    path = "/usr/bin/acrn-dm"
    ctlpath = "/usr/bin/acrnctl"
    kernel = "/opt/kata/share/kata-containers/vmlinuz.container"
    image = "/opt/kata/share/kata-containers/kata-containers.img"
    
  5. Restart the Docker service.

    $ sudo systemctl restart docker
    

Verify that these configurations are effective by checking the following outputs:

$ sudo docker info | grep -i runtime
WARNING: the devicemapper storage-driver is deprecated, and will be removed in a future release.
WARNING: devicemapper: usage of loopback devices is strongly discouraged for production use.
         Use `--storage-opt dm.thinpooldev` to specify a custom block storage device.
 Runtimes: kata-clh kata-fc kata-qemu kata-qemu-virtiofs runc kata-acrn
 Default Runtime: kata-acrn
$ /opt/kata/bin/kata-runtime --kata-config /opt/kata/share/defaults/kata-containers/configuration-acrn.toml kata-env | awk -v RS= '/\[Hypervisor\]/'
[Hypervisor]
  MachineType = ""
  Version = "DM version is: 2.0-unstable-7c7bf767-dirty (daily tag:acrn-2020w23.5-180000p), build by acrn@2020-06-11 17:11:17"
  Path = "/usr/bin/acrn-dm"
  BlockDeviceDriver = "virtio-blk"
  EntropySource = "/dev/urandom"
  SharedFS = ""
  VirtioFSDaemon = ""
  Msize9p = 0
  MemorySlots = 10
  PCIeRootPort = 0
  HotplugVFIOOnRootBus = false
  Debug = false
  UseVSock = false

Run a Kata Container With ACRN

The system is now ready to run a Kata Container on ACRN. Note that a reboot is recommended after the installation.

Before running a Kata Container on ACRN, you must take at least one CPU offline:

$ curl -O https://raw.githubusercontent.com/kata-containers/documentation/master/how-to/offline_cpu.sh
$ chmod +x ./offline_cpu.sh
$ sudo ./offline_cpu.sh

Start a Kata Container on ACRN:

$ sudo docker run -ti busybox sh

If you run into problems, contact us on the ACRN mailing list and provide as much detail as possible about the issue. The output of sudo docker info and kata-runtime kata-env is useful.