github/kata-containers
1
0
Fork 1
mirror of https://github.com/kata-containers/kata-containers.git synced 2025-05-01 05:04:26 +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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
README.md
View File

@ -17,16 +17,73 @@ standard implementation of lightweight Virtual Machines (VMs) that feel and
perform like containers, but provide the workload isolation and security perform like containers, but provide the workload isolation and security
advantages of VMs. 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 ## Getting started
See the [installation documentation](docs/install). See the [installation documentation](docs/install).
## Documentation ## Documentation
See the [official documentation](docs) See the [official documentation](docs) including:
(including [installation guides](docs/install),
[the developer guide](docs/Developer-Guide.md), - [Installation guides](docs/install)
[design documents](docs/design) and more). - [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 ## Community
@ -48,6 +105,8 @@ Please raise an issue
## Developers ## Developers
See the [developer guide](docs/Developer-Guide.md).
### Components ### Components
### Main components ### Main components
@ -84,8 +143,4 @@ the [components](#components) section for further details.
## Glossary of Terms ## Glossary of Terms
See the [glossary of terms](Glossary.md) related to Kata Containers. See the [glossary of terms](https://github.com/kata-containers/kata-containers/wiki/Glossary) related to Kata Containers.
---
[kernel]: https://www.kernel.org
[github-katacontainers.io]: https://github.com/kata-containers/www.katacontainers.io

117
src/runtime/README.md
View File

@ -2,19 +2,25 @@
# Runtime # Runtime
This repository contains the runtime for the ## Binary names
[Kata Containers](https://github.com/kata-containers) project.
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 For details of the other Kata Containers repositories, see the
[repository summary](https://github.com/kata-containers/kata-containers). [repository summary](https://github.com/kata-containers/kata-containers).
## Introduction ## Introduction
`kata-runtime`, referred to as "the runtime", is the Command-Line Interface The `containerd-shim-kata-v2` [binary](#binary-names) is the Kata
(CLI) part of the Kata Containers runtime component. It leverages the Containers [shimv2](../../docs/design/architecture/README.md#shim-v2-architecture) runtime. It leverages the
[virtcontainers](virtcontainers) [virtcontainers](virtcontainers)
package to provide a high-performance standards-compliant runtime that creates 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 The runtime is
[OCI](https://github.com/opencontainers/runtime-spec)-compatible, [OCI](https://github.com/opencontainers/runtime-spec)-compatible,
@ -23,39 +29,6 @@ The runtime is
allowing it allowing it
to work seamlessly with both Docker and Kubernetes respectively. 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 ## 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) [![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) See the [installation guides](../../docs/install/README.md)
available for various operating systems. available for various operating systems.
## Quick start for developers
See the
[developer guide](../../docs/Developer-Guide.md).
## Architecture overview ## Architecture overview
See the [architecture overview](../../docs/design/architecture) See the [architecture overview](../../docs/design/architecture)
@ -76,7 +44,11 @@ for details on the Kata Containers design.
## Configuration ## Configuration
The runtime uses a TOML format configuration file called `configuration.toml`. 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:** > **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 > You may need to modify this file to optimise or tailor your system, or if you have
> specific requirements. > 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 ### Hypervisor specific configuration
Kata Containers supports multiple hypervisors so your `configuration.toml` 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 $ 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 runtime will log the full path to the configuration file it is using. See
the [logging](#logging) section for further details. 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) [`kata-log-parser`](https://github.com/kata-containers/tests/tree/main/cmd/log-parser)
tool. 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 ### Kata containerd shimv2
The Kata containerd shimv2 runtime logs through `containerd`, and its logs will be sent The Kata containerd shimv2 runtime logs through `containerd`, and its logs will be sent
to wherever the `containerd` logs are directed. However, the to wherever the `containerd` logs are directed. However, the
shimv2 runtime also always logs to the system log (`syslog` or `journald`) under the shimv2 runtime also always logs to the system log (`syslog` or `journald`) using the `kata` identifier.
identifier name of `kata`.
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 ```bash
$ sudo journalctl -t kata $ sudo journalctl -t kata