From 88dfd8d447fa4e1e039ab9506e33d3b56ef1d914 Mon Sep 17 00:00:00 2001 From: Geoffroy Van Cutsem Date: Tue, 21 Jan 2020 17:03:02 +0100 Subject: [PATCH] doc: update Kata and ACRN tutorial Update the Kata and ACRN tutorial based on the latest SW components. Many previous steps are no longer required and have been removed. Signed-off-by: Geoffroy Van Cutsem --- doc/tutorials/run_kata_containers.rst | 113 ++++++++++++++++++++------ 1 file changed, 90 insertions(+), 23 deletions(-) diff --git a/doc/tutorials/run_kata_containers.rst b/doc/tutorials/run_kata_containers.rst index 567e77e64..64d5b51a7 100644 --- a/doc/tutorials/run_kata_containers.rst +++ b/doc/tutorials/run_kata_containers.rst @@ -14,39 +14,106 @@ details on Kata Containers and how the integration with ACRN has been done. Pre-Requisites ************** -.. _kata prerequisites: - https://github.com/kata-containers/documentation/blob/master/how-to/how-to-use-kata-containers-with-acrn.md#pre-requisites - #. Refer to the :ref:`ACRN supported hardware `. #. For a default prebuilt ACRN binary in the E2E package, you must have 4 CPU cores or enable "CPU Hyper-Threading” in order to have 4 CPU threads for 2 CPU cores. #. Follow :ref:`these instructions ` to set up the ACRN Service VM. -#. Build the ACRN kernel (required to support ``macvtap``, enabled by default since `247a3ba9243b `_). + + +Install Docker +************** + +.. code-block:: none + + $ sudo swupd bundle-add containers-basic + $ sudo systemctl enable docker + $ sudo systemctl start docker + +Install Kata Containers +*********************** + +The Kata Containers installation from Clear Linux's official repository does not +work with ACRN at the moment, we therefore install Kata Containers using the +`manual installation `_ +instructions (using a ``rootfs`` image). + +#. Install the build dependencies .. code-block:: none - $ git clone https://github.com/projectacrn/acrn-kernel.git - $ cd acrn-kernel - $ cp kernel_config_sos .config - $ make clean && make olddefconfig && make && make modules_install INSTALL_MOD_PATH=out/ + $ sudo swupd bundle-add go-basic devpkg-elfutils - Log in to the Service VM and use the new ACRN kernel: +#. Install Kata Containers - .. code-block:: none + At a high level, the `manual installation `_ + steps are: - $ sudo mount /dev/sda1 /mnt - $ sudo scp -r @:/acrn-kernel/arch/x86/boot/bzImage /mnt/ - $ sudo scp -r @:/acrn-kernel/out/lib/modules/* /lib/modules/ - $ conf_file=`sed -n '$ s/default //p' /mnt/loader/loader.conf`.conf - $ kernel_img=`sed -n 2p /mnt/loader/entries/$conf_file | cut -d'/' -f4` - $ sed -i "s/$kernel_img/bzImage/g" /mnt/loader/entries/$conf_file - $ sync && sudo umount /mnt && reboot - - .. note:: - Adjust the EFI System Partition (ESP) device node (``/dev/sda1`` in the example above) to match your system setup. + #. Build and install the Kata runtime + #. Create and install a ``rootfs`` + #. Build and install the Kata Containers kernel + #. Build and install the Kata proxy + #. Build and install the Kata shim Configure Kata on ACRN ********************** -Follow these `kata instructions -`_ -to configure and launch the Kata VMs with ACRN. +With the core components installed on the system, the next step is to configure +them to work seamlessly together. There are two parts to this. + +#. `Configure Docker `_ + to recognize the ``kata-runtime`` as an additional runtime available for use. + +#. Configure Kata to use ACRN. + + .. code-block:: none + + $ sudo mkdir -p /etc/kata-containers + $ sudo cp /usr/share/defaults/kata-containers/configuration-acrn.toml /etc/kata-containers/configuration.toml + +You can verify that these configurations are effective by checking the following outputs: + +.. code-block:: none + + $ sudo docker info | grep 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-runtime runc + +.. code-block:: none + + $ kata-runtime kata-env | awk -v RS= '/\[Hypervisor\]/' + [Hypervisor] + MachineType = "" + Version = "DM version is: 1.5-unstable-”2020w02.5.140000p_261” (daily tag:”2020w02.5.140000p”), build by mockbuild@2020-01-12 08:44:52" + Path = "/usr/bin/acrn-dm" + BlockDeviceDriver = "virtio-blk" + EntropySource = "/dev/urandom" + Msize9p = 0 + MemorySlots = 10 + Debug = false + UseVSock = false + SharedFS = "" + +Run a Kata Container with ACRN +****************************** + +The system is now ready to run a Kata Container on ACRN (a reboot is recommended +after the installation). + +Before running a Kata Container on ACRN, you must offline at least one CPU. + +.. code-block:: none + + $ curl -O https://raw.githubusercontent.com/kata-containers/documentation/master/how-to/offline_cpu.sh + $ chmod +x ./offline_cpu.sh + $ sudo ./offline_cpu.sh + +Now start a Kata Container on ACRN. + +.. code-block:: none + + $ sudo docker run -ti --runtime=kata-runtime busybox sh + +If you run into problems, contact us on the mailing list and provide as much +details as possible about the issue. The output of ``sudo docker info`` and +``kata-runtime kata-env`` is useful.