mirror of
https://github.com/kata-containers/kata-containers.git
synced 2025-04-30 20:54:26 +00:00
docs: Improve top-level and runtime README
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
parent
1dcb413e68
commit
9818cf7196
73
README.md
73
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.
|
||||
|
||||
@ -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
|
||||
|
||||
[](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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user