diff --git a/how-to/README.md b/how-to/README.md index 72e11b4e12..28fc4455d5 100644 --- a/how-to/README.md +++ b/how-to/README.md @@ -14,6 +14,7 @@ ## Hypervisors Integration - [Kata Containers with Firecracker](https://github.com/kata-containers/documentation/wiki/Initial-release-of-Kata-Containers-with-Firecracker-support) - [Kata Containers with NEMU](how-to-use-kata-containers-with-nemu.md) +- [Kata Containers with ACRN Hypervisor](how-to-use-kata-containers-with-acrn.md) ## Advanced Topics - [How to use Kata Containers with virtio-fs](how-to-use-virtio-fs-with-kata.md) diff --git a/how-to/how-to-use-kata-containers-with-acrn.md b/how-to/how-to-use-kata-containers-with-acrn.md new file mode 100644 index 0000000000..cfde69c771 --- /dev/null +++ b/how-to/how-to-use-kata-containers-with-acrn.md @@ -0,0 +1,108 @@ +# Kata Containers with ACRN + +This document provides an overview on how to run Kata containers with ACRN hypervisor and device model. + +- [Introduction](#introduction) +- [Pre-requisites](#pre-requisites) +- [Install and Configure Docker](#install-and-configure-docker) +- [Configure Kata Containers with ACRN](#configure-kata-containers-with-acrn) + +## Introduction + +ACRN is a flexible, lightweight Type-1 reference hypervisor built with real-time and safety-criticality in mind. ACRN uses an open source platform making it optimized to streamline embedded development. + +Some of the key features being: + +- Small footprint - Approx. 25K lines of code (LOC). +- Real Time - Low latency, faster boot time, improves overall responsiveness with hardware. +- Adaptability - Multi-OS support for guest operating systems like Linux, Android, RTOSes. +- Rich I/O mediators - Allows sharing of various I/O devices across VMs. +- Optimized for a variety of IoT (Internet of Things) and embedded device solutions. + +Please refer to ACRN [documentation](https://projectacrn.github.io/latest/index.html) for more details on ACRN hypervisor and device model. + +## Pre-requisites + +This document requires the presence of the ACRN hypervisor and Kata Containers on your system. Install using the instructions available through the following links: + +- ACRN supported [Hardware](https://projectacrn.github.io/latest/hardware.html#supported-hardware). +- ACRN [software](https://projectacrn.github.io/latest/getting-started/apl-nuc.html#use-the-script-to-set-up-acrn-automatically) setup. +- Kata Containers installation: Automated installation does not seem to be supported for Clear Linux, so please use [manual installation](https://github.com/kata-containers/documentation/blob/master/Developer-Guide.md) steps. + +> **Note:** Create rootfs image and not initrd image. + +In order to run Kata with ACRN, your container stack must provide block-based storage, such as device-mapper. + +> **Note:** Currently, you can only launch one VM from Kata Containers using ACRN hypervisor (SDC scenario) due to [this issue](https://github.com/kata-containers/runtime/issues/1785). + +## Install and Configure Docker + +Install Docker 18.06 (as Docker 18.09 does not support device-mapper). To configure Docker for device-mapper and Kata, + +1. Stop Docker daemon if it is already running. + +```bash +$ sudo systemctl stop docker +``` + +2. Set `/etc/docker/daemon.json` with the following contents. + +``` +{ + "storage-driver": "devicemapper" +} +``` + +3. Restart docker. + +```bash +$ sudo systemctl daemon-reload +$ sudo systemctl restart docker +``` + +4. Configure [Docker](https://github.com/kata-containers/documentation/blob/master/Developer-Guide.md#update-the-docker-systemd-unit-file) to use `kata-runtime`. + +## Configure Kata Containers with ACRN + +To configure Kata Containers with ACRN, copy the generated `configuration-acrn.toml` file when building the `kata-runtime` to either `/etc/kata-containers/configuration.toml` or `/usr/share/defaults/kata-containers/configuration.toml`. + +The following command shows full paths to the `configuration.toml` files that the runtime loads. It will use the first path that exists. (Please make sure the kernel and image paths are set correctly in the `configuration.toml` file) + +```bash +$ sudo kata-runtime --kata-show-default-config-paths +``` + +>**Warning:** Please offline CPUs using [this](offline_cpu.sh) script, else VM launches will fail. + +```bash +$ sudo ./offline_cpu.sh +``` + +Start an ACRN based Kata Container, + +```bash +$ sudo docker run -ti --runtime=kata-runtime busybox sh +``` + +You will see ACRN(`acrn-dm`) is now running on your system, as well as a `kata-shim`, `kata-proxy`. You should obtain an interactive shell prompt. Verify that all the Kata processes terminate once you exit the container. + +```bash +$ ps -ef | grep -E "kata|acrn" +``` + +Validate ACRN hypervisor by using `kata-runtime kata-env`, + +```sh +$ kata-runtime kata-env | awk -v RS= '/\[Hypervisor\]/' +[Hypervisor] + MachineType = "" + Version = "DM version is: 1.2-unstable-254577a6-dirty (daily tag:acrn-2019w27.4-140000p) + Path = "/usr/bin/acrn-dm" + BlockDeviceDriver = "virtio-blk" + EntropySource = "/dev/urandom" + Msize9p = 0 + MemorySlots = 10 + Debug = false + UseVSock = false + SharedFS = "" +``` diff --git a/how-to/offline_cpu.sh b/how-to/offline_cpu.sh new file mode 100644 index 0000000000..8ac2da31f0 --- /dev/null +++ b/how-to/offline_cpu.sh @@ -0,0 +1,24 @@ +#!/bin/bash +# Copyright (c) 2019 Intel Corporation +# +# SPDX-License-Identifier: Apache-2.0 +# +# Description: Offline SOS CPUs except BSP before launch UOS + +[ $(id -u) -eq 0 ] || { echo >&2 "ERROR: run as root"; exit 1; } + +for i in $(ls -d /sys/devices/system/cpu/cpu[1-9]*); do + online=`cat $i/online` + idx=`echo $i | tr -cd "[0-9]"` + echo "INFO:$0: cpu$idx online=$online" + if [ "$online" = "1" ]; then + echo 0 > $i/online + while [ "$online" = "1" ]; do + sleep 1 + echo 0 > $i/online + online=`cat $i/online` + done + echo $idx > /sys/class/vhm/acrn_vhm/offline_cpu + fi +done +