diff --git a/README.md b/README.md index e93c5f7400..0d8c5d2b82 100644 --- a/README.md +++ b/README.md @@ -17,16 +17,73 @@ standard implementation of lightweight Virtual Machines (VMs) that feel and perform like containers, but provide the workload isolation and security advantages of VMs. +## License + +The code is licensed under the Apache 2.0 license. +See [the license file](LICENSE) for further details. + +## Platform support + +Kata Containers currently runs on 64-bit systems supporting the following +technologies: + +| Architecture | Virtualization technology | +|-|-| +| `x86_64`, `amd64` | [Intel](https://www.intel.com) VT-x, AMD SVM | +| `aarch64` ("`arm64`")| [ARM](https://www.arm.com) Hyp | +| `ppc64le` | [IBM](https://www.ibm.com) Power | +| `s390x` | [IBM](https://www.ibm.com) Z & LinuxONE SIE | + +### Hardware requirements + +The [Kata Containers runtime](src/runtime) provides a command to +determine if your host system is capable of running and creating a +Kata Container: + +```bash +$ kata-runtime check +``` + +> **Notes:** +> +> - This command runs a number of checks including connecting to the +> network to determine if a newer release of Kata Containers is +> available on GitHub. If you do not wish this to check to run, add +> the `--no-network-checks` option. +> +> - By default, only a brief success / failure message is printed. +> If more details are needed, the `--verbose` flag can be used to display the +> list of all the checks performed. +> +> - If the command is run as the `root` user additional checks are +> run (including checking if another incompatible hypervisor is running). +> When running as `root`, network checks are automatically disabled. + ## Getting started See the [installation documentation](docs/install). ## Documentation -See the [official documentation](docs) -(including [installation guides](docs/install), -[the developer guide](docs/Developer-Guide.md), -[design documents](docs/design) and more). +See the [official documentation](docs) including: + +- [Installation guides](docs/install) +- [Developer guide](docs/Developer-Guide.md) +- [Design documents](docs/design) + - [Architecture overview](docs/design/architecture) + +## Configuration + +Kata Containers uses a single +[configuration file](src/runtime/README.md#configuration) +which contains a number of sections for various parts of the Kata +Containers system including the [runtime](src/runtime), the +[agent](src/agent) and the [hypervisor](#hypervisors). + +## Hypervisors + +See the [hypervisors document](docs/hypervisors.md) and the +[Hypervisor specific configuration details](src/runtime/README.md#hypervisor-specific-configuration). ## Community @@ -48,6 +105,8 @@ Please raise an issue ## Developers +See the [developer guide](docs/Developer-Guide.md). + ### Components ### Main components @@ -84,8 +143,4 @@ the [components](#components) section for further details. ## Glossary of Terms -See the [glossary of terms](Glossary.md) related to Kata Containers. ---- - -[kernel]: https://www.kernel.org -[github-katacontainers.io]: https://github.com/kata-containers/www.katacontainers.io +See the [glossary of terms](https://github.com/kata-containers/kata-containers/wiki/Glossary) related to Kata Containers. diff --git a/src/runtime/README.md b/src/runtime/README.md index 217cd2d443..fcffc238ad 100644 --- a/src/runtime/README.md +++ b/src/runtime/README.md @@ -2,19 +2,25 @@ # Runtime -This repository contains the runtime for the -[Kata Containers](https://github.com/kata-containers) project. +## Binary names + +This repository contains the following components: + +| Binary name | Description | +|-|-| +| `containerd-shim-kata-v2` | The [shimv2 runtime](../../docs/design/architecture/README.md#runtime) | +| `kata-runtime` | [utility program](../../docs/design/architecture/README.md#utility-program) | For details of the other Kata Containers repositories, see the [repository summary](https://github.com/kata-containers/kata-containers). ## Introduction -`kata-runtime`, referred to as "the runtime", is the Command-Line Interface -(CLI) part of the Kata Containers runtime component. It leverages the +The `containerd-shim-kata-v2` [binary](#binary-names) is the Kata +Containers [shimv2](../../docs/design/architecture/README.md#shim-v2-architecture) runtime. It leverages the [virtcontainers](virtcontainers) package to provide a high-performance standards-compliant runtime that creates -hardware-virtualized [Linux](https://www.kernel.org/) containers running on Linux hosts. +hardware-virtualized [Linux](https://www.kernel.org) containers running on Linux hosts. The runtime is [OCI](https://github.com/opencontainers/runtime-spec)-compatible, @@ -23,39 +29,6 @@ The runtime is allowing it to work seamlessly with both Docker and Kubernetes respectively. -## License - -The code is licensed under an Apache 2.0 license. -See [the license file](../../LICENSE) for further details. - -## Platform support - -Kata Containers currently works on systems supporting the following -technologies: - -- [Intel](https://www.intel.com) VT-x technology. -- [ARM](https://www.arm.com) Hyp mode (virtualization extension). -- [IBM](https://www.ibm.com) Power Systems. -- [IBM](https://www.ibm.com) Z mainframes. -### Hardware requirements - -The runtime has a built-in command to determine if your host system is capable -of running and creating a Kata Container: - -```bash -$ kata-runtime check -``` - -> **Note:** -> -> - By default, only a brief success / failure message is printed. -> If more details are needed, the `--verbose` flag can be used to display the -> list of all the checks performed. -> -> - `root` permission is needed to check if the system is capable of running -> Kata containers. In this case, additional checks are performed (e.g., if another -> incompatible hypervisor is running). - ## Download and install [![Get it from the Snap Store](https://snapcraft.io/static/images/badges/en/snap-store-black.svg)](https://snapcraft.io/kata-containers) @@ -63,11 +36,6 @@ $ kata-runtime check See the [installation guides](../../docs/install/README.md) available for various operating systems. -## Quick start for developers - -See the -[developer guide](../../docs/Developer-Guide.md). - ## Architecture overview See the [architecture overview](../../docs/design/architecture) @@ -76,7 +44,11 @@ for details on the Kata Containers design. ## Configuration The runtime uses a TOML format configuration file called `configuration.toml`. -The file contains comments explaining all options. +The file is divided into sections for settings related to various +parts of the system including the runtime itself, the [agent](../agent) and +the [hypervisor](#hypervisor-specific-configuration). + +Each option has a comment explaining its use. > **Note:** > @@ -84,6 +56,36 @@ The file contains comments explaining all options. > You may need to modify this file to optimise or tailor your system, or if you have > specific requirements. +### Configuration file location + +#### Runtime configuration file location + +The shimv2 runtime looks for its configuration in the following places (in order): + +- The `io.data containers.config.config_path` annotation specified + in the OCI configuration file (`config.json` file) used to create the pod sandbox. + +- The containerd + [shimv2](/docs/design/architecture/README.md#shim-v2-architecture) + options passed to the runtime. + +- The value of the `KATA_CONF_FILE` environment variable. + +- The [default configuration paths](#stateless-systems). + +#### Utility program configuration file location + +The `kata-runtime` utility program looks for its configuration in the +following locations (in order): + +- The path specified by the `--config` command-line option. + +- The value of the `KATA_CONF_FILE` environment variable. + +- The [default configuration paths](#stateless-systems). + +> **Note:** For both binaries, the first path that exists will be used. + ### Hypervisor specific configuration Kata Containers supports multiple hypervisors so your `configuration.toml` @@ -108,13 +110,6 @@ runtime attempts to load. The first path that exists will be used: $ kata-runtime --show-default-config-paths ``` -Aside from the built-in locations, it is possible to specify the path to a -custom configuration file using the `--config` option: - -```bash -$ kata-runtime --config=/some/where/configuration.toml ... -``` - The runtime will log the full path to the configuration file it is using. See the [logging](#logging) section for further details. @@ -132,27 +127,15 @@ components, see the documentation for the [`kata-log-parser`](https://github.com/kata-containers/tests/tree/main/cmd/log-parser) tool. -For runtime logs, see the following sections for the CRI-O and containerd shimv2 based runtimes. - -### Kata OCI - -The Kata OCI runtime (including when used with CRI-O), provides `--log=` and `--log-format=` options. -However, the runtime also always logs to the system log (`syslog` or `journald`). - -To view runtime log output: - -```bash -$ sudo journalctl -t kata-runtime -``` - ### Kata containerd shimv2 The Kata containerd shimv2 runtime logs through `containerd`, and its logs will be sent to wherever the `containerd` logs are directed. However, the -shimv2 runtime also always logs to the system log (`syslog` or `journald`) under the -identifier name of `kata`. +shimv2 runtime also always logs to the system log (`syslog` or `journald`) using the `kata` identifier. -To view the `shimv2` runtime log output: +> **Note:** Kata logging [requires containerd debug to be enabled](../../docs/Developer-Guide.md#enabling-full-containerd-debug). + +To view the `shimv2` runtime logs: ```bash $ sudo journalctl -t kata