docs: Document restricted annotations

Document restricted annotations, as implemented in
https://github.com/kata-containers/kata-containers/pull/902

Fixes: #1044
Forward-port-of: https://github.com/kata-containers/documentation/pull/755

Signed-off-by: Christophe de Dinechin <dinechin@redhat.com>

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 |