From 56cdfa831ff6a372fbf0228fa897a4f01cd9f75d Mon Sep 17 00:00:00 2001 From: LandonTClipp <11232769+LandonTClipp@users.noreply.github.com> Date: Tue, 24 Mar 2026 10:53:19 -0700 Subject: [PATCH] docs: Add annotation config to doc site Adding the pod annotation config to the doc site. A symlink is created at docs/pod-annotations.md that points to how-to/how-to-set-sandbox-config-kata.md so that the URL for this file will be created at `/pod-annotations`. Also adding brief contrbuting guidelines and how-to's for running the documentation site locally for local previews. Signed-off-by: LandonTClipp <11232769+LandonTClipp@users.noreply.github.com> --- docs/.nav.yml | 16 +++++--- docs/doc-contributing.md | 21 ++++++++++ docs/how-to/how-to-set-sandbox-config-kata.md | 39 ++++++++++++------- docs/pod-annotations.md | 1 + tests/spellcheck/kata-dictionary.txt | 4 ++ 5 files changed, 60 insertions(+), 21 deletions(-) create mode 100644 docs/doc-contributing.md create mode 120000 docs/pod-annotations.md diff --git a/docs/.nav.yml b/docs/.nav.yml index 324a9f0c12..15dab995cc 100644 --- a/docs/.nav.yml +++ b/docs/.nav.yml @@ -1,12 +1,14 @@ # https://lukasgeiter.github.io/mkdocs-awesome-nav/ nav: - - Home: index.md - - Getting Started: - - prerequisites.md - - installation.md + - Home: + - index.md + - Getting Started: + - prerequisites.md + - installation.md - Configuration: - - helm-configuration.md - - runtime-configuration.md + - Helm: helm-configuration.md + - Runtime: runtime-configuration.md + - Annotations: pod-annotations.md - Platform Support: - hypervisors.md - Guides: @@ -14,5 +16,7 @@ nav: - NVIDIA GPU Passthrough: use-cases/NVIDIA-GPU-passthrough-and-Kata-QEMU.md - NVIDIA vGPU: use-cases/NVIDIA-GPU-passthrough-and-Kata.md - Intel Discrete GPU: use-cases/Intel-Discrete-GPU-passthrough-and-Kata.md + - Contributing: + - Documentation: doc-contributing.md - Misc: - Architecture: design/architecture/ diff --git a/docs/doc-contributing.md b/docs/doc-contributing.md new file mode 100644 index 0000000000..4f351435cd --- /dev/null +++ b/docs/doc-contributing.md @@ -0,0 +1,21 @@ +# Documentation Contributions + +The documentation system is built using a static site generator called [mkdocs-materialx](https://jaywhj.github.io/mkdocs-materialx/), a fork of [mkdocs-material](https://squidfunk.github.io/mkdocs-material/). + +## Local Serving + +All documentation files are in the `docs/` subfolder. When modifying docs, you can run `make docs-serve` at the top-level of the project to build and serve them locally: + +``` +$ make docs-serve +INFO - [17:37:42] Serving on http://0.0.0.0:8000/kata-containers/ +``` + +## Adding New Files + +Markdown files should be organized in a flat topology as much as possible. The location of the markdown files will map directly its URL, so they should not be moved once they are created. The navigation structure of the static site is controlled via the `docs/.nav.yml` file. + +## Configuration + +The configuration of the build system is controlled through the `mkdocs.yaml` file. The reference for various parameters can be found at the [mkdocs-materialx](https://jaywhj.github.io/mkdocs-materialx/setup/index.html) website. + 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 f2f8b5bef3..535d233c6d 100644 --- a/docs/how-to/how-to-set-sandbox-config-kata.md +++ b/docs/how-to/how-to-set-sandbox-config-kata.md @@ -1,4 +1,4 @@ -# Per-Pod Kata Configurations +# Pod Annotations Kata Containers gives users freedom to customize at per-pod level, by setting a wide range of Kata specific annotations in the pod specification. @@ -8,17 +8,20 @@ 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 +## Kata Configuration Annotations + There are several kinds of Kata configurations and they are listed below. -## Global Options +### Global Options + | Key | Value Type | Comments | |-------| ----- | ----- | | `io.katacontainers.config_path` | string | Kata config file location that overrides the default config paths | | `io.katacontainers.pkg.oci.bundle_path` | string | OCI bundle path | | `io.katacontainers.pkg.oci.container_type`| string | OCI container type. Only accepts `pod_container` and `pod_sandbox` | -## Runtime Options +### Runtime Options + | Key | Value Type | Comments | |-------| ----- | ----- | | `io.katacontainers.config.runtime.experimental` | `boolean` | determines if experimental features enabled | @@ -30,7 +33,8 @@ There are several kinds of Kata configurations and they are listed below. | `io.katacontainers.config.runtime.create_container_timeout` | `uint64` | the timeout for create a container in `seconds`, default is `60` | | `io.katacontainers.config.runtime.experimental_force_guest_pull` | `boolean` | forces the runtime to pull the image in the guest VM, default is `false`. This is an experimental feature and might be removed in the future. | -## Agent Options +### Agent Options + | Key | Value Type | Comments | |-------| ----- | ----- | | `io.katacontainers.config.agent.enable_tracing` | `boolean` | enable tracing for the agent | @@ -38,7 +42,15 @@ There are several kinds of Kata configurations and they are listed below. | `io.katacontainers.config.agent.kernel_modules` | string | the list of kernel modules and their parameters that will be loaded in the guest kernel. Semicolon separated list of kernel modules and their parameters. These modules will be loaded in the guest kernel using `modprobe`(8). E.g., `e1000e InterruptThrottleRate=3000,3000,3000 EEE=1; i915 enable_ppgtt=0` | | `io.katacontainers.config.agent.cdh_api_timeout` | uint32 | timeout in second for Confidential Data Hub (CDH) API service, default is `50` | -## Hypervisor Options +### Hypervisor Options + +Hypervisor annotations must be explicitly whitelisted in the Kata runtime config. Example: + +```toml title="/path/to/configuration.toml" +# List of valid annotation names for the hypervisor +enable_annotations = ["enable_iommu", "virtio_fs_extra_args", "kernel_params"] +``` + | Key | Value Type | Comments | |-------| ----- | ----- | | `io.katacontainers.config.hypervisor.asset_hash_type` | string | the hash type used for assets verification, default is `sha512` | @@ -86,7 +98,7 @@ There are several kinds of Kata configurations and they are listed below. | `io.katacontainers.config.hypervisor.memory_offset` | uint64| the memory space used for `nvdimm` device by the hypervisor | | `io.katacontainers.config.hypervisor.memory_slots` | uint32| the memory slots assigned to the VM by the hypervisor | | `io.katacontainers.config.hypervisor.msize_9p` | uint32 | the `msize` for 9p shares | -| `io.katacontainers.config.hypervisor.path` | string | the hypervisor that will run the container VM | +| `io.katacontainers.config.hypervisor.path` | string | the hypervisor that will run the container VM. The path must be whitelisted in the runtime configuration's `valid_hypervisor_paths` parameter. | | `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 | @@ -102,17 +114,14 @@ There are several kinds of Kata configurations and they are listed below. | `io.katacontainers.config.hypervisor.block_device_num_queues` | `usize` | The number of queues to use for block devices (runtime-rs only) | | `io.katacontainers.config.hypervisor.block_device_queue_size` | uint32 | The size of the of the queue to use for block devices (runtime-rs only) | -## Container Options +### Container Options + | Key | Value Type | Comments | |-------| ----- | ----- | | `io.katacontainers.container.resource.swappiness"` | `uint64` | specify the `Resources.Memory.Swappiness` | | `io.katacontainers.container.resource.swap_in_bytes"` | `uint64` | specify the `Resources.Memory.Swap` | -# CRI-O Configuration - -In case of CRI-O, all annotations specified in the pod spec are passed down to Kata. - -# containerd Configuration +## containerd Configuration For containerd, annotations specified in the pod spec are passed down to Kata starting with version `1.3.0` of containerd. Additionally, extra configuration is @@ -138,7 +147,7 @@ $ cat /etc/containerd/config Additional documentation on the above configuration can be found in the [containerd docs](https://github.com/containerd/cri/blob/8d5a8355d07783ba2f8f451209f6bdcc7c412346/docs/config.md). -# Example - Using annotations +## Example As mentioned above, not all containers need the same modules, therefore using the configuration file for specifying the list of kernel modules per POD can @@ -194,7 +203,7 @@ spec: tty: true ``` -# Restricted annotations +## Restricted annotations Some annotations are _restricted_, meaning that the configuration file specifies the acceptable values. Currently, only hypervisor annotations are restricted, diff --git a/docs/pod-annotations.md b/docs/pod-annotations.md new file mode 120000 index 0000000000..a142727419 --- /dev/null +++ b/docs/pod-annotations.md @@ -0,0 +1 @@ +./how-to/how-to-set-sandbox-config-kata.md \ No newline at end of file diff --git a/tests/spellcheck/kata-dictionary.txt b/tests/spellcheck/kata-dictionary.txt index f108066645..0184e2897b 100644 --- a/tests/spellcheck/kata-dictionary.txt +++ b/tests/spellcheck/kata-dictionary.txt @@ -13,6 +13,10 @@ SPDK upcall virtcontainers +# Open source projects + +materialx + # Hardware & Architecture AMD APQN