github/kata-containers
1
0
Fork 2
mirror of https://github.com/kata-containers/kata-containers.git synced 2025-10-31 09:26:52 +00:00
Code Issues Projects Releases Wiki Activity

docs: Developer-Guide updated

Browse Source 
Developer-Guide.md is updated to work using current golang versions.
Related Readmes are also updated.

Signed-off-by: Joana Pecholt <joana.pecholt@aisec.fraunhofer.de>
This commit is contained in:
Joana Pecholt
2022-08-12 15:54:32 +02:00
parent 105eda5b9a
commit 0e69405e16
3 changed files with 147 additions and 132 deletions
Download Patch File Download Diff File Expand all files Collapse all files

262
docs/Developer-Guide.md
View File

@@ -33,51 +33,41 @@ You need to install the following to build Kata Containers components:
- `make`. - `make`.
- `gcc` (required for building the shim and runtime). - `gcc` (required for building the shim and runtime).
# Build and install the Kata Containers runtime # Build and install Kata Containers
## Build and install the Kata Containers runtime
``` ```bash
$ go get -d -u github.com/kata-containers/kata-containers $ git clone https://github.com/kata-containers/kata-containers.git
$ cd $GOPATH/src/github.com/kata-containers/kata-containers/src/runtime $ pushd kata-containers/src/runtime
$ make && sudo -E PATH=$PATH make install $ make && sudo -E "PATH=$PATH" make install
$ sudo mkdir -p /etc/kata-containers/
$ sudo install -o root -g root -m 0640 /usr/share/defaults/kata-containers/configuration.toml /etc/kata-containers
$ popd
``` ```
The build will create the following: The build will create the following:
- runtime binary: `/usr/local/bin/kata-runtime` and `/usr/local/bin/containerd-shim-kata-v2` - runtime binary: `/usr/local/bin/kata-runtime` and `/usr/local/bin/containerd-shim-kata-v2`
- configuration file: `/usr/share/defaults/kata-containers/configuration.toml` - configuration file: `/usr/share/defaults/kata-containers/configuration.toml` and `/etc/kata-containers/configuration.toml`
# Check hardware requirements
You can check if your system is capable of creating a Kata Container by running the following:
```
$ sudo kata-runtime check
```
If your system is *not* able to run Kata Containers, the previous command will error out and explain why.
## Configure to use initrd or rootfs image ## Configure to use initrd or rootfs image
Kata containers can run with either an initrd image or a rootfs image. Kata containers can run with either an initrd image or a rootfs image.
If you want to test with `initrd`, make sure you have `initrd = /usr/share/kata-containers/kata-containers-initrd.img` If you want to test with `initrd`, make sure you have uncommented `initrd = /usr/share/kata-containers/kata-containers-initrd.img`
in your configuration file, commenting out the `image` line: in your configuration file, commenting out the `image` line in
`/etc/kata-containers/configuration.toml`. For example:
`/usr/share/defaults/kata-containers/configuration.toml` and comment out the `image` line with the following. For example: ```bash
```
$ sudo mkdir -p /etc/kata-containers/
$ sudo install -o root -g root -m 0640 /usr/share/defaults/kata-containers/configuration.toml /etc/kata-containers
$ sudo sed -i 's/^\(image =.*\)/# \1/g' /etc/kata-containers/configuration.toml $ sudo sed -i 's/^\(image =.*\)/# \1/g' /etc/kata-containers/configuration.toml
$ sudo sed -i 's/^# \(initrd =.*\)/\1/g' /etc/kata-containers/configuration.toml
``` ```
You can create the initrd image as shown in the [create an initrd image](#create-an-initrd-image---optional) section. You can create the initrd image as shown in the [create an initrd image](#create-an-initrd-image---optional) section.
If you want to test with a rootfs `image`, make sure you have `image = /usr/share/kata-containers/kata-containers.img` If you want to test with a rootfs `image`, make sure you have uncommented `image = /usr/share/kata-containers/kata-containers.img`
in your configuration file, commenting out the `initrd` line. For example: in your configuration file, commenting out the `initrd` line. For example:
``` ```bash
$ sudo mkdir -p /etc/kata-containers/
$ sudo install -o root -g root -m 0640 /usr/share/defaults/kata-containers/configuration.toml /etc/kata-containers
$ sudo sed -i 's/^\(initrd =.*\)/# \1/g' /etc/kata-containers/configuration.toml $ sudo sed -i 's/^\(initrd =.*\)/# \1/g' /etc/kata-containers/configuration.toml
``` ```
The rootfs image is created as shown in the [create a rootfs image](#create-a-rootfs-image) section. The rootfs image is created as shown in the [create a rootfs image](#create-a-rootfs-image) section.
@@ -90,7 +80,7 @@ rootfs `image`(100MB+).
Enable seccomp as follows: Enable seccomp as follows:
``` ```bash
$ sudo sed -i '/^disable_guest_seccomp/ s/true/false/' /etc/kata-containers/configuration.toml $ sudo sed -i '/^disable_guest_seccomp/ s/true/false/' /etc/kata-containers/configuration.toml
``` ```
@@ -100,9 +90,7 @@ This will pass container seccomp profiles to the kata agent.
Enable full debug as follows: Enable full debug as follows:
``` ```bash
$ sudo mkdir -p /etc/kata-containers/
$ sudo install -o root -g root -m 0640 /usr/share/defaults/kata-containers/configuration.toml /etc/kata-containers
$ sudo sed -i -e 's/^# *\(enable_debug\).*=.*$/\1 = true/g' /etc/kata-containers/configuration.toml $ sudo sed -i -e 's/^# *\(enable_debug\).*=.*$/\1 = true/g' /etc/kata-containers/configuration.toml
$ sudo sed -i -e 's/^kernel_params = "\(.*\)"/kernel_params = "\1 agent.log=debug initcall_debug"/g' /etc/kata-containers/configuration.toml $ sudo sed -i -e 's/^kernel_params = "\(.*\)"/kernel_params = "\1 agent.log=debug initcall_debug"/g' /etc/kata-containers/configuration.toml
``` ```
@@ -175,7 +163,7 @@ and offers possible workarounds and fixes.
it stores. When messages are suppressed, it is noted in the logs. This can be checked it stores. When messages are suppressed, it is noted in the logs. This can be checked
for by looking for those notifications, such as: for by looking for those notifications, such as:
```sh ```bash
$ sudo journalctl --since today | fgrep Suppressed $ sudo journalctl --since today | fgrep Suppressed
Jun 29 14:51:17 mymachine systemd-journald[346]: Suppressed 4150 messages from /system.slice/docker.service Jun 29 14:51:17 mymachine systemd-journald[346]: Suppressed 4150 messages from /system.slice/docker.service
``` ```
@@ -200,7 +188,7 @@ RateLimitBurst=0
Restart `systemd-journald` for the changes to take effect: Restart `systemd-journald` for the changes to take effect:
```sh ```bash
$ sudo systemctl restart systemd-journald $ sudo systemctl restart systemd-journald
``` ```
@@ -214,25 +202,24 @@ $ sudo systemctl restart systemd-journald
The agent is built with a statically linked `musl.` The default `libc` used is `musl`, but on `ppc64le` and `s390x`, `gnu` should be used. To configure this: The agent is built with a statically linked `musl.` The default `libc` used is `musl`, but on `ppc64le` and `s390x`, `gnu` should be used. To configure this:
``` ```bash
$ export ARCH=$(uname -m) $ export ARCH="$(uname -m)"
$ if [ "$ARCH" = "ppc64le" -o "$ARCH" = "s390x" ]; then export LIBC=gnu; else export LIBC=musl; fi $ if [ "$ARCH" = "ppc64le" -o "$ARCH" = "s390x" ]; then export LIBC=gnu; else export LIBC=musl; fi
$ [ ${ARCH} == "ppc64le" ] && export ARCH=powerpc64le $ [ "${ARCH}" == "ppc64le" ] && export ARCH=powerpc64le
$ rustup target add ${ARCH}-unknown-linux-${LIBC} $ rustup target add "${ARCH}-unknown-linux-${LIBC}"
``` ```
To build the agent: To build the agent:
``` ```bash
$ go get -d -u github.com/kata-containers/kata-containers $ make -C kata-containers/src/agent
$ cd $GOPATH/src/github.com/kata-containers/kata-containers/src/agent && make
``` ```
The agent is built with seccomp capability by default. The agent is built with seccomp capability by default.
If you want to build the agent without the seccomp capability, you need to run `make` with `SECCOMP=no` as follows. If you want to build the agent without the seccomp capability, you need to run `make` with `SECCOMP=no` as follows.
``` ```bash
$ make -C $GOPATH/src/github.com/kata-containers/kata-containers/src/agent SECCOMP=no $ make -C kata-containers/src/agent SECCOMP=no
``` ```
> **Note:** > **Note:**
@@ -240,13 +227,6 @@ $ make -C $GOPATH/src/github.com/kata-containers/kata-containers/src/agent SECCO
> - If you enable seccomp in the main configuration file but build the agent without seccomp capability, > - If you enable seccomp in the main configuration file but build the agent without seccomp capability,
> the runtime exits conservatively with an error message. > the runtime exits conservatively with an error message.
## Get the osbuilder
```
$ go get -d -u github.com/kata-containers/kata-containers
$ cd $GOPATH/src/github.com/kata-containers/kata-containers/tools/osbuilder
```
## Create a rootfs image ## Create a rootfs image
### Create a local rootfs ### Create a local rootfs
@@ -254,24 +234,26 @@ As a prerequisite, you need to install Docker. Otherwise, you will not be
able to run the `rootfs.sh` script with `USE_DOCKER=true` as expected in able to run the `rootfs.sh` script with `USE_DOCKER=true` as expected in
the following example. the following example.
``` ```bash
$ export ROOTFS_DIR=${GOPATH}/src/github.com/kata-containers/kata-containers/tools/osbuilder/rootfs-builder/rootfs $ export distro="ubuntu" # example
$ sudo rm -rf ${ROOTFS_DIR} $ export ROOTFS_DIR="$(realpath kata-containers/tools/osbuilder/rootfs-builder/rootfs)"
$ cd $GOPATH/src/github.com/kata-containers/kata-containers/tools/osbuilder/rootfs-builder $ sudo rm -rf "${ROOTFS_DIR}"
$ script -fec 'sudo -E GOPATH=$GOPATH USE_DOCKER=true ./rootfs.sh ${distro}' $ pushd kata-containers/tools/osbuilder/rootfs-builder
$ script -fec 'sudo -E USE_DOCKER=true ./rootfs.sh "${distro}"'
$ popd
``` ```
You MUST choose a distribution (e.g., `ubuntu`) for `${distro}`. You MUST choose a distribution (e.g., `ubuntu`) for `${distro}`.
You can get a supported distributions list in the Kata Containers by running the following. You can get a supported distributions list in the Kata Containers by running the following.
``` ```bash
$ ./rootfs.sh -l $ ./kata-containers/tools/osbuilder/rootfs-builder/rootfs.sh -l
``` ```
If you want to build the agent without seccomp capability, you need to run the `rootfs.sh` script with `SECCOMP=no` as follows. If you want to build the agent without seccomp capability, you need to run the `rootfs.sh` script with `SECCOMP=no` as follows.
``` ```bash
$ script -fec 'sudo -E GOPATH=$GOPATH AGENT_INIT=yes USE_DOCKER=true SECCOMP=no ./rootfs.sh ${distro}' $ script -fec 'sudo -E AGENT_INIT=yes USE_DOCKER=true SECCOMP=no ./rootfs.sh "${distro}"'
``` ```
> **Note:** > **Note:**
@@ -287,17 +269,18 @@ $ script -fec 'sudo -E GOPATH=$GOPATH AGENT_INIT=yes USE_DOCKER=true SECCOMP=no
> >
> - You should only do this step if you are testing with the latest version of the agent. > - You should only do this step if you are testing with the latest version of the agent.
``` ```bash
$ sudo install -o root -g root -m 0550 -t ${ROOTFS_DIR}/usr/bin ../../../src/agent/target/x86_64-unknown-linux-musl/release/kata-agent $ sudo install -o root -g root -m 0550 -t "${ROOTFS_DIR}/usr/bin" "${ROOTFS_DIR}/../../../../src/agent/target/x86_64-unknown-linux-musl/release/kata-agent"
$ sudo install -o root -g root -m 0440 ../../../src/agent/kata-agent.service ${ROOTFS_DIR}/usr/lib/systemd/system/ $ sudo install -o root -g root -m 0440 "${ROOTFS_DIR}/../../../../src/agent/kata-agent.service" "${ROOTFS_DIR}/usr/lib/systemd/system/"
$ sudo install -o root -g root -m 0440 ../../../src/agent/kata-containers.target ${ROOTFS_DIR}/usr/lib/systemd/system/ $ sudo install -o root -g root -m 0440 "${ROOTFS_DIR}/../../../../src/agent/kata-containers.target" "${ROOTFS_DIR}/usr/lib/systemd/system/"
``` ```
### Build a rootfs image ### Build a rootfs image
``` ```bash
$ cd $GOPATH/src/github.com/kata-containers/kata-containers/tools/osbuilder/image-builder $ pushd kata-containers/tools/osbuilder/image-builder
$ script -fec 'sudo -E USE_DOCKER=true ./image_builder.sh ${ROOTFS_DIR}' $ script -fec 'sudo -E USE_DOCKER=true ./image_builder.sh "${ROOTFS_DIR}"'
$ popd
``` ```
> **Notes:** > **Notes:**
@@ -313,21 +296,26 @@ $ script -fec 'sudo -E USE_DOCKER=true ./image_builder.sh ${ROOTFS_DIR}'
### Install the rootfs image ### Install the rootfs image
``` ```bash
$ commit=$(git log --format=%h -1 HEAD) $ pushd kata-containers/tools/osbuilder/image-builder
$ date=$(date +%Y-%m-%d-%T.%N%z) $ commit="$(git log --format=%h -1 HEAD)"
$ date="$(date +%Y-%m-%d-%T.%N%z)"
$ image="kata-containers-${date}-${commit}" $ image="kata-containers-${date}-${commit}"
$ sudo install -o root -g root -m 0640 -D kata-containers.img "/usr/share/kata-containers/${image}" $ 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) $ (cd /usr/share/kata-containers && sudo ln -sf "$image" kata-containers.img)
$ popd
``` ```
## Create an initrd image - OPTIONAL ## Create an initrd image - OPTIONAL
### Create a local rootfs for initrd image ### Create a local rootfs for initrd image
```
$ export ROOTFS_DIR="${GOPATH}/src/github.com/kata-containers/kata-containers/tools/osbuilder/rootfs-builder/rootfs" ```bash
$ sudo rm -rf ${ROOTFS_DIR} $ export distro="ubuntu" # example
$ cd $GOPATH/src/github.com/kata-containers/kata-containers/tools/osbuilder/rootfs-builder $ export ROOTFS_DIR="$(realpath kata-containers/tools/osbuilder/rootfs-builder/rootfs)"
$ script -fec 'sudo -E GOPATH=$GOPATH AGENT_INIT=yes USE_DOCKER=true ./rootfs.sh ${distro}' $ sudo rm -rf "${ROOTFS_DIR}"
$ pushd kata-containers/tools/osbuilder/rootfs-builder/
$ script -fec 'sudo -E AGENT_INIT=yes USE_DOCKER=true ./rootfs.sh "${distro}"'
$ popd
``` ```
`AGENT_INIT` controls if the guest image uses the Kata agent as the guest `init` process. When you create an initrd image, `AGENT_INIT` controls if the guest image uses the Kata agent as the guest `init` process. When you create an initrd image,
always set `AGENT_INIT` to `yes`. always set `AGENT_INIT` to `yes`.
@@ -335,14 +323,14 @@ always set `AGENT_INIT` to `yes`.
You MUST choose a distribution (e.g., `ubuntu`) for `${distro}`. You MUST choose a distribution (e.g., `ubuntu`) for `${distro}`.
You can get a supported distributions list in the Kata Containers by running the following. You can get a supported distributions list in the Kata Containers by running the following.
``` ```bash
$ ./rootfs.sh -l $ ./kata-containers/tools/osbuilder/rootfs-builder/rootfs.sh -l
``` ```
If you want to build the agent without seccomp capability, you need to run the `rootfs.sh` script with `SECCOMP=no` as follows. If you want to build the agent without seccomp capability, you need to run the `rootfs.sh` script with `SECCOMP=no` as follows.
``` ```bash
$ script -fec 'sudo -E GOPATH=$GOPATH AGENT_INIT=yes USE_DOCKER=true SECCOMP=no ./rootfs.sh ${distro}' $ script -fec 'sudo -E AGENT_INIT=yes USE_DOCKER=true SECCOMP=no ./rootfs.sh "${distro}"'
``` ```
> **Note:** > **Note:**
@@ -351,28 +339,31 @@ $ script -fec 'sudo -E GOPATH=$GOPATH AGENT_INIT=yes USE_DOCKER=true SECCOMP=no
Optionally, add your custom agent binary to the rootfs with the following commands. The default `$LIBC` used Optionally, add your custom agent binary to the rootfs with the following commands. The default `$LIBC` used
is `musl`, but on ppc64le and s390x, `gnu` should be used. Also, Rust refers to ppc64le as `powerpc64le`: is `musl`, but on ppc64le and s390x, `gnu` should be used. Also, Rust refers to ppc64le as `powerpc64le`:
``` ```bash
$ export ARCH=$(uname -m) $ export ARCH="$(uname -m)"
$ [ ${ARCH} == "ppc64le" ] || [ ${ARCH} == "s390x" ] && export LIBC=gnu || export LIBC=musl $ [ "${ARCH}" == "ppc64le" ] || [ "${ARCH}" == "s390x" ] && export LIBC=gnu || export LIBC=musl
$ [ ${ARCH} == "ppc64le" ] && export ARCH=powerpc64le $ [ "${ARCH}" == "ppc64le" ] && export ARCH=powerpc64le
$ sudo install -o root -g root -m 0550 -T ../../../src/agent/target/${ARCH}-unknown-linux-${LIBC}/release/kata-agent ${ROOTFS_DIR}/sbin/init $ sudo install -o root -g root -m 0550 -T "${ROOTFS_DIR}/../../../../src/agent/target/${ARCH}-unknown-linux-${LIBC}/release/kata-agent" "${ROOTFS_DIR}/sbin/init"
``` ```
### Build an initrd image ### Build an initrd image
``` ```bash
$ cd $GOPATH/src/github.com/kata-containers/kata-containers/tools/osbuilder/initrd-builder $ pushd kata-containers/tools/osbuilder/initrd-builder
$ script -fec 'sudo -E AGENT_INIT=yes USE_DOCKER=true ./initrd_builder.sh ${ROOTFS_DIR}' $ script -fec 'sudo -E AGENT_INIT=yes USE_DOCKER=true ./initrd_builder.sh "${ROOTFS_DIR}"'
$ popd
``` ```
### Install the initrd image ### Install the initrd image
``` ```bash
$ commit=$(git log --format=%h -1 HEAD) $ pushd kata-containers/tools/osbuilder/initrd-builder
$ date=$(date +%Y-%m-%d-%T.%N%z) $ commit="$(git log --format=%h -1 HEAD)"
$ date="$(date +%Y-%m-%d-%T.%N%z)"
$ image="kata-containers-initrd-${date}-${commit}" $ image="kata-containers-initrd-${date}-${commit}"
$ sudo install -o root -g root -m 0640 -D kata-containers-initrd.img "/usr/share/kata-containers/${image}" $ sudo install -o root -g root -m 0640 -D kata-containers-initrd.img "/usr/share/kata-containers/${image}"
$ (cd /usr/share/kata-containers && sudo ln -sf "$image" kata-containers-initrd.img) $ (cd /usr/share/kata-containers && sudo ln -sf "$image" kata-containers-initrd.img)
$ popd
``` ```
# Install guest kernel images # Install guest kernel images
@@ -391,44 +382,44 @@ Kata Containers makes use of upstream QEMU branch. The exact version
and repository utilized can be found by looking at the [versions file](../versions.yaml). and repository utilized can be found by looking at the [versions file](../versions.yaml).
Find the correct version of QEMU from the versions file: Find the correct version of QEMU from the versions file:
``` ```bash
$ source ${GOPATH}/src/github.com/kata-containers/kata-containers/tools/packaging/scripts/lib.sh $ source kata-containers/tools/packaging/scripts/lib.sh
$ qemu_version=$(get_from_kata_deps "assets.hypervisor.qemu.version") $ qemu_version="$(get_from_kata_deps "assets.hypervisor.qemu.version")"
$ echo ${qemu_version} $ echo "${qemu_version}"
``` ```
Get source from the matching branch of QEMU: Get source from the matching branch of QEMU:
``` ```bash
$ go get -d github.com/qemu/qemu $ git clone -b "${qemu_version}" https://github.com/qemu/qemu.git
$ cd ${GOPATH}/src/github.com/qemu/qemu $ your_qemu_directory="$(realpath qemu)"
$ git checkout ${qemu_version}
$ your_qemu_directory=${GOPATH}/src/github.com/qemu/qemu
``` ```
There are scripts to manage the build and packaging of QEMU. For the examples below, set your There are scripts to manage the build and packaging of QEMU. For the examples below, set your
environment as: environment as:
``` ```bash
$ go get -d github.com/kata-containers/kata-containers $ packaging_dir="$(realpath kata-containers/tools/packaging)"
$ packaging_dir="${GOPATH}/src/github.com/kata-containers/kata-containers/tools/packaging"
``` ```
Kata often utilizes patches for not-yet-upstream and/or backported fixes for components, Kata often utilizes patches for not-yet-upstream and/or backported fixes for components,
including QEMU. These can be found in the [packaging/QEMU directory](../tools/packaging/qemu/patches), including QEMU. These can be found in the [packaging/QEMU directory](../tools/packaging/qemu/patches),
and it's *recommended* that you apply them. For example, suppose that you are going to build QEMU and it's *recommended* that you apply them. For example, suppose that you are going to build QEMU
version 5.2.0, do: version 5.2.0, do:
``` ```bash
$ cd $your_qemu_directory $ "$packaging_dir/scripts/apply_patches.sh" "$packaging_dir/qemu/patches/5.2.x/"
$ $packaging_dir/scripts/apply_patches.sh $packaging_dir/qemu/patches/5.2.x/
``` ```
To build utilizing the same options as Kata, you should make use of the `configure-hypervisor.sh` script. For example: To build utilizing the same options as Kata, you should make use of the `configure-hypervisor.sh` script. For example:
``` ```bash
$ cd $your_qemu_directory $ pushd "$your_qemu_directory"
$ $packaging_dir/scripts/configure-hypervisor.sh kata-qemu > kata.cfg $ "$packaging_dir/scripts/configure-hypervisor.sh" kata-qemu > kata.cfg
$ eval ./configure "$(cat kata.cfg)" $ eval ./configure "$(cat kata.cfg)"
$ make -j $(nproc --ignore=1) $ make -j $(nproc --ignore=1)
# Optional
$ sudo -E make install $ sudo -E make install
$ popd
``` ```
If you do not want to install the respective QEMU version, the configuration file can be modified to point to the correct binary. In `/etc/kata-containers/configuration.toml`, change `path = "/path/to/qemu/build/qemu-system-x86_64"` to point to the correct QEMU binary.
See the [static-build script for QEMU](../tools/packaging/static-build/qemu/build-static-qemu.sh) for a reference on how to get, setup, configure and build QEMU for Kata. See the [static-build script for QEMU](../tools/packaging/static-build/qemu/build-static-qemu.sh) for a reference on how to get, setup, configure and build QEMU for Kata.
### Build a custom QEMU for aarch64/arm64 - REQUIRED ### Build a custom QEMU for aarch64/arm64 - REQUIRED
@@ -439,11 +430,33 @@ See the [static-build script for QEMU](../tools/packaging/static-build/qemu/buil
> under upstream review for supporting NVDIMM on aarch64. > under upstream review for supporting NVDIMM on aarch64.
> >
You could build the custom `qemu-system-aarch64` as required with the following command: You could build the custom `qemu-system-aarch64` as required with the following command:
```bash
$ git clone https://github.com/kata-containers/tests.git
$ script -fec 'sudo -E tests/.ci/install_qemu.sh'
``` ```
$ go get -d github.com/kata-containers/tests
$ script -fec 'sudo -E ${GOPATH}/src/github.com/kata-containers/tests/.ci/install_qemu.sh' ## Build `virtiofsd`
When using the file system type virtio-fs (default), `virtiofsd` is required
```bash
$ pushd kata-containers/tools/packaging/static-build/virtiofsd
$ ./build-static-virtiofsd.sh
$ popd
``` ```
Modify `/etc/kata-containers/configuration.toml` and update value `virtio_fs_daemon = "/path/to/kata-containers/tools/packaging/static-build/virtiofsd/virtiofsd/virtiofsd"` to point to the binary.
# Check hardware requirements
You can check if your system is capable of creating a Kata Container by running the following:
```bash
$ sudo kata-runtime check
```
If your system is *not* able to run Kata Containers, the previous command will error out and explain why.
# Run Kata Containers with Containerd # Run Kata Containers with Containerd
Refer to the [How to use Kata Containers and Containerd](how-to/containerd-kata.md) how-to guide. Refer to the [How to use Kata Containers and Containerd](how-to/containerd-kata.md) how-to guide.
@@ -474,7 +487,7 @@ See [Set up a debug console](#set-up-a-debug-console).
## Checking Docker default runtime ## Checking Docker default runtime
``` ```bash
$ sudo docker info 2>/dev/null | grep -i "default runtime" | cut -d: -f2- | grep -q runc && echo "SUCCESS" || echo "ERROR: Incorrect default Docker runtime" $ sudo docker info 2>/dev/null | grep -i "default runtime" | cut -d: -f2- | grep -q runc && echo "SUCCESS" || echo "ERROR: Incorrect default Docker runtime"
``` ```
## Set up a debug console ## Set up a debug console
@@ -491,7 +504,7 @@ contain either `/bin/sh` or `/bin/bash`.
Enable debug_console_enabled in the `configuration.toml` configuration file: Enable debug_console_enabled in the `configuration.toml` configuration file:
``` ```toml
[agent.kata] [agent.kata]
debug_console_enabled = true debug_console_enabled = true
``` ```
@@ -502,7 +515,7 @@ This will pass `agent.debug_console agent.debug_console_vport=1026` to agent as
For Kata Containers `2.0.x` releases, the `kata-runtime exec` command depends on the`kata-monitor` running, in order to get the sandbox's `vsock` address to connect to. Thus, first start the `kata-monitor` process. For Kata Containers `2.0.x` releases, the `kata-runtime exec` command depends on the`kata-monitor` running, in order to get the sandbox's `vsock` address to connect to. Thus, first start the `kata-monitor` process.
``` ```bash
$ sudo kata-monitor $ sudo kata-monitor
``` ```
@@ -564,10 +577,10 @@ an additional `coreutils` package.
For example using CentOS: For example using CentOS:
``` ```bash
$ cd $GOPATH/src/github.com/kata-containers/kata-containers/tools/osbuilder/rootfs-builder $ pushd kata-containers/tools/osbuilder/rootfs-builder
$ export ROOTFS_DIR=${GOPATH}/src/github.com/kata-containers/kata-containers/tools/osbuilder/rootfs-builder/rootfs $ export ROOTFS_DIR="$(realpath ./rootfs)"
$ script -fec 'sudo -E GOPATH=$GOPATH USE_DOCKER=true EXTRA_PKGS="bash coreutils" ./rootfs.sh centos' $ script -fec 'sudo -E USE_DOCKER=true EXTRA_PKGS="bash coreutils" ./rootfs.sh centos'
``` ```
#### Build the debug image #### Build the debug image
@@ -582,9 +595,10 @@ Install the image:
>**Note**: When using an initrd image, replace the below rootfs image name `kata-containers.img` >**Note**: When using an initrd image, replace the below rootfs image name `kata-containers.img`
>with the initrd image name `kata-containers-initrd.img`. >with the initrd image name `kata-containers-initrd.img`.
``` ```bash
$ name="kata-containers-centos-with-debug-console.img" $ name="kata-containers-centos-with-debug-console.img"
$ sudo install -o root -g root -m 0640 kata-containers.img "/usr/share/kata-containers/${name}" $ sudo install -o root -g root -m 0640 kata-containers.img "/usr/share/kata-containers/${name}"
$ popd
``` ```
Next, modify the `image=` values in the `[hypervisor.qemu]` section of the Next, modify the `image=` values in the `[hypervisor.qemu]` section of the
@@ -593,7 +607,7 @@ to specify the full path to the image name specified in the previous code
section. Alternatively, recreate the symbolic link so it points to section. Alternatively, recreate the symbolic link so it points to
the new debug image: the new debug image:
``` ```bash
$ (cd /usr/share/kata-containers && sudo ln -sf "$name" kata-containers.img) $ (cd /usr/share/kata-containers && sudo ln -sf "$name" kata-containers.img)
``` ```
@@ -604,7 +618,7 @@ to avoid all subsequently created containers from using the debug image.
Create a container as normal. For example using `crictl`: Create a container as normal. For example using `crictl`:
``` ```bash
$ sudo crictl run -r kata container.yaml pod.yaml $ sudo crictl run -r kata container.yaml pod.yaml
``` ```
@@ -617,7 +631,7 @@ those for firecracker / cloud-hypervisor.
Add `agent.debug_console` to the guest kernel command line to allow the agent process to start a debug console. Add `agent.debug_console` to the guest kernel command line to allow the agent process to start a debug console.
``` ```bash
$ sudo sed -i -e 's/^kernel_params = "\(.*\)"/kernel_params = "\1 agent.debug_console"/g' "${kata_configuration_file}" $ sudo sed -i -e 's/^kernel_params = "\(.*\)"/kernel_params = "\1 agent.debug_console"/g' "${kata_configuration_file}"
``` ```
@@ -638,7 +652,7 @@ between the host and the guest. The kernel command line option `agent.debug_cons
Add the parameter `agent.debug_console_vport=1026` to the kernel command line Add the parameter `agent.debug_console_vport=1026` to the kernel command line
as shown below: as shown below:
``` ```bash
sudo sed -i -e 's/^kernel_params = "\(.*\)"/kernel_params = "\1 agent.debug_console_vport=1026"/g' "${kata_configuration_file}" sudo sed -i -e 's/^kernel_params = "\(.*\)"/kernel_params = "\1 agent.debug_console_vport=1026"/g' "${kata_configuration_file}"
``` ```
@@ -651,7 +665,7 @@ Next, connect to the debug console. The VSOCKS paths vary slightly between each
VMM solution. VMM solution.
In case of cloud-hypervisor, connect to the `vsock` as shown: In case of cloud-hypervisor, connect to the `vsock` as shown:
``` ```bash
$ sudo su -c 'cd /var/run/vc/vm/${sandbox_id}/root/ && socat stdin unix-connect:clh.sock' $ sudo su -c 'cd /var/run/vc/vm/${sandbox_id}/root/ && socat stdin unix-connect:clh.sock'
CONNECT 1026 CONNECT 1026
``` ```
@@ -659,7 +673,7 @@ CONNECT 1026
**Note**: You need to type `CONNECT 1026` and press `RETURN` key after entering the `socat` command. **Note**: You need to type `CONNECT 1026` and press `RETURN` key after entering the `socat` command.
For firecracker, connect to the `hvsock` as shown: For firecracker, connect to the `hvsock` as shown:
``` ```bash
$ sudo su -c 'cd /var/run/vc/firecracker/${sandbox_id}/root/ && socat stdin unix-connect:kata.hvsock' $ sudo su -c 'cd /var/run/vc/firecracker/${sandbox_id}/root/ && socat stdin unix-connect:kata.hvsock'
CONNECT 1026 CONNECT 1026
``` ```
@@ -668,7 +682,7 @@ CONNECT 1026
For QEMU, connect to the `vsock` as shown: For QEMU, connect to the `vsock` as shown:
``` ```bash
$ sudo su -c 'cd /var/run/vc/vm/${sandbox_id} && socat "stdin,raw,echo=0,escape=0x11" "unix-connect:console.sock"' $ sudo su -c 'cd /var/run/vc/vm/${sandbox_id} && socat "stdin,raw,echo=0,escape=0x11" "unix-connect:console.sock"'
``` ```
@@ -681,7 +695,7 @@ If the image is created using
[osbuilder](../tools/osbuilder), the following YAML [osbuilder](../tools/osbuilder), the following YAML
file exists and contains details of the image and how it was created: file exists and contains details of the image and how it was created:
``` ```bash
$ cat /var/lib/osbuilder/osbuilder.yaml $ cat /var/lib/osbuilder/osbuilder.yaml
``` ```

8
docs/how-to/containerd-kata.md
View File

@@ -77,8 +77,8 @@ $ command -v containerd
You can manually install CNI plugins as follows: You can manually install CNI plugins as follows:
```bash ```bash
$ go get github.com/containernetworking/plugins $ git clone https://github.com/containernetworking/plugins.git
$ pushd $GOPATH/src/github.com/containernetworking/plugins $ pushd plugins
$ ./build_linux.sh $ ./build_linux.sh
$ sudo mkdir /opt/cni $ sudo mkdir /opt/cni
$ sudo cp -r bin /opt/cni/ $ sudo cp -r bin /opt/cni/
@@ -93,8 +93,8 @@ $ popd
You can install the `cri-tools` from source code: You can install the `cri-tools` from source code:
```bash ```bash
$ go get github.com/kubernetes-sigs/cri-tools $ git clone https://github.com/kubernetes-sigs/cri-tools.git
$ pushd $GOPATH/src/github.com/kubernetes-sigs/cri-tools $ pushd cri-tools
$ make $ make
$ sudo -E make install $ sudo -E make install
$ popd $ popd

9
tools/packaging/kernel/README.md
View File

@@ -9,7 +9,8 @@ automates the process to build a kernel for Kata Containers.
The `build-kernel.sh` script requires an installed Golang version matching the The `build-kernel.sh` script requires an installed Golang version matching the
[component build requirements](../../../docs/Developer-Guide.md#requirements-to-build-individual-components). [component build requirements](../../../docs/Developer-Guide.md#requirements-to-build-individual-components).
It also requires [yq](https://github.com/mikefarah/yq) version 3.4.1 It also requires [yq](https://github.com/mikefarah/yq) version 3.4.1
> **Hint**: `snap install yq --channel=v3/stable` > **Hint**: `snap install yq --channel=v3/stable` \
> **or** `go install github.com/mikefarah/yq/v3@latest`
The Linux kernel scripts further require a few packages (flex, bison, and libelf-dev) The Linux kernel scripts further require a few packages (flex, bison, and libelf-dev)
@@ -53,7 +54,7 @@ Options:
``` ```
Example: Example:
``` ```bash
$ ./build-kernel.sh -v 5.10.25 -g nvidia -f -d setup $ ./build-kernel.sh -v 5.10.25 -g nvidia -f -d setup
``` ```
> **Note** > **Note**
@@ -68,8 +69,8 @@ $ ./build-kernel.sh -v 5.10.25 -g nvidia -f -d setup
## Setup kernel source code ## Setup kernel source code
```bash ```bash
$ go get -d -u github.com/kata-containers/kata-containers $ git clone github.com/kata-containers/kata-containers
$ cd $GOPATH/src/github.com/kata-containers/kata-containers/tools/packaging/kernel $ cd kata-containers/tools/packaging/kernel
$ ./build-kernel.sh setup $ ./build-kernel.sh setup
``` ```