1.. _run-kata-containers:
2
3Run Kata Containers on a Service VM
4###################################
5
6This tutorial describes how to install, configure, and run `Kata Containers
7<https://katacontainers.io/>`_ on the Ubuntu based Service VM with the ACRN
8hypervisor. In this configuration,
9Kata Containers leverage the ACRN hypervisor instead of QEMU, which is used by
10default. Refer to the `Kata Containers with ACRN presentation
11<https://www.slideshare.net/ProjectACRN/acrn-kata-container-on-acrn>`_
12for more details on Kata Containers and how the integration with ACRN
13has been done.
14
15Prerequisites
16**************
17
18#. Refer to the :ref:`ACRN supported hardware <hardware>`.
19#. For a default prebuilt ACRN binary in the end-to-end (E2E) package, you must have 4
20   CPU cores or enable "CPU Hyper-threading" in order to have 4 CPU threads for 2 CPU cores.
21#. Follow the :ref:`gsg` to set up the ACRN Service VM
22   based on Ubuntu.
23#. This tutorial is validated on the following configurations:
24
25   - ACRN v2.0 (branch: ``release_2.0``)
26   - Ubuntu 20.04
27
28#. Kata Containers are supported for ACRN hypervisors configured for
29   the Industry or SDC scenarios.
30
31
32Install Docker
33**************
34
35The following instructions install Docker* on the Ubuntu Service VM.
36Refer to the `Get Docker Engine - Community for Ubuntu
37<https://docs.docker.com/engine/install/ubuntu/>`_
38installation guide for detailed information.
39
40#. Install the following prerequisite packages:
41
42   .. code-block:: none
43
44      $ sudo apt-get install apt-transport-https ca-certificates curl
45
46#. Run the following commands to add Docker's official GPG key,
47   set up the repository, and install the Docker Engine - Community
48   from the repository:
49
50   .. code-block:: none
51
52      $ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
53      $ sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
54      $ sudo apt-get update
55      $ sudo apt-get install -y docker-ce docker-ce-cli containerd.io
56
57Install Kata Containers
58***********************
59
60Kata Containers provide a variety of installation methods, this guide uses
61`kata-deploy <https://github.com/kata-containers/packaging/tree/master/kata-deploy>`_
62to automate the Kata Containers installation procedure.
63
64#. Install Kata Containers:
65
66   .. code-block:: none
67
68      $ 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
69
70#. Install the ``acrnctl`` tool:
71
72   .. code-block:: none
73
74      $ cd /home/acrn/work/acrn-hypervisor
75      $ sudo cp build/misc/tools/acrnctl /usr/bin/
76
77   .. note:: This assumes you have built ACRN on this machine following the
78      instructions in the :ref:`gsg`.
79
80#. Modify the :ref:`daemon.json` file in order to:
81
82   a. Add a ``kata-acrn`` runtime (``runtimes`` section).
83
84      .. note:: In order to run Kata with ACRN, the container stack must provide
85         block-based storage, such as :file:`device-mapper`. Since Docker may be
86         configured to use :file:`overlay2` storage driver, the above
87         configuration also instructs Docker to use :file:`device-mapper`
88         storage driver.
89
90   #. Use the ``device-mapper`` storage driver.
91
92   #. Make Docker use Kata Containers by default.
93
94   These changes are highlighted below.
95
96   .. code-block:: none
97      :emphasize-lines: 2,3,21-24
98      :name: daemon.json
99      :caption: /etc/docker/daemon.json
100
101      {
102        "storage-driver": "devicemapper",
103        "default-runtime": "kata-acrn",
104        "runtimes": {
105          "kata-qemu": {
106            "path": "/opt/kata/bin/kata-runtime",
107            "runtimeArgs": [ "--kata-config", "/opt/kata/share/defaults/kata-containers/configuration-qemu.toml" ]
108          },
109          "kata-qemu-virtiofs": {
110            "path": "/opt/kata/bin/kata-runtime",
111            "runtimeArgs": [ "--kata-config", "/opt/kata/share/defaults/kata-containers/configuration-qemu-virtiofs.toml" ]
112          },
113          "kata-fc": {
114            "path": "/opt/kata/bin/kata-runtime",
115            "runtimeArgs": [ "--kata-config", "/opt/kata/share/defaults/kata-containers/configuration-fc.toml" ]
116          },
117          "kata-clh": {
118            "path": "/opt/kata/bin/kata-runtime",
119            "runtimeArgs": [ "--kata-config", "/opt/kata/share/defaults/kata-containers/configuration-clh.toml" ]
120          },
121          "kata-acrn": {
122            "path": "/opt/kata/bin/kata-runtime",
123            "runtimeArgs": [ "--kata-config", "/opt/kata/share/defaults/kata-containers/configuration-acrn.toml" ]
124          }
125        }
126      }
127
128#. Configure Kata to use ACRN.
129
130   Modify the ``[hypervisor.acrn]`` section in the ``/opt/kata/share/defaults/kata-containers/configuration-acrn.toml``
131   file.
132
133   .. code-block:: none
134      :emphasize-lines: 2,3
135      :name: configuration-acrn.toml
136      :caption: /opt/kata/share/defaults/kata-containers/configuration-acrn.toml
137
138      [hypervisor.acrn]
139      path = "/usr/bin/acrn-dm"
140      ctlpath = "/usr/bin/acrnctl"
141      kernel = "/opt/kata/share/kata-containers/vmlinuz.container"
142      image = "/opt/kata/share/kata-containers/kata-containers.img"
143
144#. Restart the Docker service.
145
146   .. code-block:: none
147
148      $ sudo systemctl restart docker
149
150Verify that these configurations are effective by checking the following
151outputs:
152
153.. code-block:: console
154
155   $ sudo docker info | grep -i runtime
156   WARNING: the devicemapper storage-driver is deprecated, and will be removed in a future release.
157   WARNING: devicemapper: usage of loopback devices is strongly discouraged for production use.
158            Use `--storage-opt dm.thinpooldev` to specify a custom block storage device.
159    Runtimes: kata-clh kata-fc kata-qemu kata-qemu-virtiofs runc kata-acrn
160    Default Runtime: kata-acrn
161
162.. code-block:: console
163
164   $ /opt/kata/bin/kata-runtime --kata-config /opt/kata/share/defaults/kata-containers/configuration-acrn.toml kata-env | awk -v RS= '/\[Hypervisor\]/'
165   [Hypervisor]
166     MachineType = ""
167     Version = "DM version is: 2.0-unstable-7c7bf767-dirty (daily tag:acrn-2020w23.5-180000p), build by acrn@2020-06-11 17:11:17"
168     Path = "/usr/bin/acrn-dm"
169     BlockDeviceDriver = "virtio-blk"
170     EntropySource = "/dev/urandom"
171     SharedFS = ""
172     VirtioFSDaemon = ""
173     Msize9p = 0
174     MemorySlots = 10
175     PCIeRootPort = 0
176     HotplugVFIOOnRootBus = false
177     Debug = false
178     UseVSock = false
179
180Run a Kata Container With ACRN
181******************************
182
183The system is now ready to run a Kata Container on ACRN. Note that a reboot
184is recommended after the installation.
185
186Before running a Kata Container on ACRN, you must take at least one CPU offline:
187
188.. code-block:: none
189
190   $ curl -O https://raw.githubusercontent.com/kata-containers/documentation/master/how-to/offline_cpu.sh
191   $ chmod +x ./offline_cpu.sh
192   $ sudo ./offline_cpu.sh
193
194Start a Kata Container on ACRN:
195
196.. code-block:: none
197
198   $ sudo docker run -ti busybox sh
199
200If you run into problems, contact us on the `ACRN mailing list
201<https://lists.projectacrn.org/g/acrn-dev>`_ and provide as
202much detail as possible about the issue. The output of ``sudo docker info``
203and ``kata-runtime kata-env`` is useful.
204