github/kata-containers
1
0
Fork 2
mirror of https://github.com/kata-containers/kata-containers.git synced 2025-09-15 05:49:05 +00:00
Code Issues Projects Releases Wiki Activity

docs: Improve top-level and runtime README

Browse Source 
Various improvements to the top-level README file:

- Moved the following sections from the runtime's README to the
  top-level README:
  - License
  - Platform support / Hardware requirements
- Added the following sections to the top-level README:
  - Configuration
  - Hypervisors
- Improved formatting of the Documentation section in the top-level
  README.
- Removed some unused named links from the top-level README.

Also improvements to the runtime README:

- Removed confusing mention of the old 1.x runtime name.
- Clarify the binary name for the 2.x runtime and the utility program.

> **Note:**
>
> We cannot currently link to the AMD website as that site's
> configuration causes the CI static checks to fail. See
> https://github.com/kata-containers/tests/issues/4401

Fixes: #3557.

Signed-off-by: James O. D. Hunt <james.o.hunt@intel.com>
This commit is contained in:
James O. D. Hunt
2022-01-26 10:44:04 +00:00
parent 1dcb413e68
commit 9818cf7196
2 changed files with 114 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files

117
src/runtime/README.md
View File

@@ -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