diff --git a/docs/how-to/how-to-set-sandbox-config-kata.md b/docs/how-to/how-to-set-sandbox-config-kata.md index ba347bca67..f58b90e6e4 100644 --- a/docs/how-to/how-to-set-sandbox-config-kata.md +++ b/docs/how-to/how-to-set-sandbox-config-kata.md @@ -3,6 +3,11 @@ Kata Containers gives users freedom to customize at per-pod level, by setting a wide range of Kata specific annotations in the pod specification. +Some annotations may be [restricted](#restricted-annotations) by the +configuration file for security reasons, notably annotations that could lead the +runtime to execute programs on the host. Such annotations are marked with _(R)_ in +the tables below. + # Kata Configuration Annotations There are several kinds of Kata configurations and they are listed below. @@ -40,6 +45,7 @@ There are several kinds of Kata configurations and they are listed below. | `io.katacontainers.config.hypervisor.block_device_cache_set` | `boolean` | cache-related options will be set to block devices or not | | `io.katacontainers.config.hypervisor.block_device_driver` | string | the driver to be used for block device, valid values are `virtio-blk`, `virtio-scsi`, `nvdimm`| | `io.katacontainers.config.hypervisor.cpu_features` | `string` | Comma-separated list of CPU features to pass to the CPU (QEMU) | +| `io.katacontainers.config.hypervisor.ctlpath` (R) | `string` | Path to the `acrnctl` binary for the ACRN hypervisor | | `io.katacontainers.config.hypervisor.default_max_vcpus` | uint32| the maximum number of vCPUs allocated for the VM by the hypervisor | | `io.katacontainers.config.hypervisor.default_memory` | uint32| the memory assigned for a VM by the hypervisor in `MiB` | | `io.katacontainers.config.hypervisor.default_vcpus` | uint32| the default vCPUs assigned for a VM by the hypervisor | @@ -55,7 +61,7 @@ There are several kinds of Kata configurations and they are listed below. | `io.katacontainers.config.hypervisor.enable_vhost_user_store` | `boolean` | enable vhost-user storage device (QEMU) | | `io.katacontainers.config.hypervisor.enable_virtio_mem` | `boolean` | enable virtio-mem (QEMU) | | `io.katacontainers.config.hypervisor.entropy_source` | string| the path to a host source of entropy (`/dev/random`, `/dev/urandom` or real hardware RNG device) | -| `io.katacontainers.config.hypervisor.file_mem_backend` | string | file based memory backend root directory | +| `io.katacontainers.config.hypervisor.file_mem_backend` (R) | string | file based memory backend root directory | | `io.katacontainers.config.hypervisor.firmware_hash` | string | container firmware SHA-512 hash value | | `io.katacontainers.config.hypervisor.firmware` | string | the guest firmware that will run the container VM | | `io.katacontainers.config.hypervisor.guest_hook_path` | string | the path within the VM that will be used for drop in hooks | @@ -66,7 +72,7 @@ There are several kinds of Kata configurations and they are listed below. | `io.katacontainers.config.hypervisor.initrd_hash` | string | container guest initrd SHA-512 hash value | | `io.katacontainers.config.hypervisor.initrd` | string | the guest initrd image that will run in the container VM | | `io.katacontainers.config.hypervisor.jailer_hash` | string | container jailer SHA-512 hash value | -| `io.katacontainers.config.hypervisor.jailer_path` | string | the jailer that will constrain the container VM | +| `io.katacontainers.config.hypervisor.jailer_path` (R) | string | the jailer that will constrain the container VM | | `io.katacontainers.config.hypervisor.kernel_hash` | string | container kernel image SHA-512 hash value | | `io.katacontainers.config.hypervisor.kernel_params` | string | additional guest kernel parameters | | `io.katacontainers.config.hypervisor.kernel` | string | the kernel used to boot the container VM | @@ -79,7 +85,7 @@ There are several kinds of Kata configurations and they are listed below. | `io.katacontainers.config.hypervisor.pcie_root_port` | specify the number of PCIe Root Port devices. The PCIe Root Port device is used to hot-plug a PCIe device (QEMU) | | `io.katacontainers.config.hypervisor.shared_fs` | string | the shared file system type, either `virtio-9p` or `virtio-fs` | | `io.katacontainers.config.hypervisor.use_vsock` | `boolean` | specify use of `vsock` for agent communication | -| `io.katacontainers.config.hypervisor.vhost_user_store_path` | `string` | specify the directory path where vhost-user devices related folders, sockets and device nodes should be (QEMU) | +| `io.katacontainers.config.hypervisor.vhost_user_store_path` (R) | `string` | specify the directory path where vhost-user devices related folders, sockets and device nodes should be (QEMU) | | `io.katacontainers.config.hypervisor.virtio_fs_cache_size` | uint32 | virtio-fs DAX cache size in `MiB` | | `io.katacontainers.config.hypervisor.virtio_fs_cache` | string | the cache mode for virtio-fs, valid values are `always`, `auto` and `none` | | `io.katacontainers.config.hypervisor.virtio_fs_daemon` | string | virtio-fs `vhost-user` daemon path | @@ -168,3 +174,31 @@ spec: stdin: true tty: true ``` + +# Restricted annotations + +Some annotations are _restricted_, meaning that the configuration file specifies +the acceptable values. Currently, only hypervisor annotations are restricted, +for security reason, with the intent to control which binaries the Kata +Containers runtime will launch on your behalf. + +The configuration file validates the annotation _name_ as well as the annotation +_value_. + +The acceptable annotation names are defined by the `enable_annotations` entry in +the configuration file. + +For restricted annotations, an additional configuration entry provides a list of +acceptable values. Since most restricted annotations are intended to control +which binaries the runtime can execute, the valid value is generally provided by +a shell pattern, as defined by `glob(3)`. The table below provides the name of +the configuration entry: + +| Key | Config file entry | Comments | +|-------| ----- | ----- | +| `ctlpath` | `valid_ctlpaths` | Valid paths for `acrnctl` binary | +| `file_mem_backend` | `valid_file_mem_backends` | Valid locations for the file-based memory backend root directory | +| `jailer_path` | `valid_jailer_paths`| Valid paths for the jailer constraining the container VM (Firecracker) | +| `path` | `valid_hypervisor_paths` | Valid hypervisors to run the container VM | +| `vhost_user_store_path` | `valid_vhost_user_store_paths` | Valid paths for vhost-user related files| +| `virtio_fs_daemon` | `valid_virtio_fs_daemon_paths` | Valid paths for the `virtiofsd` daemon |