From 679df0fb77112f9d6192e12f50a53c073e71791b Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Tue, 3 Nov 2020 11:29:22 +0000 Subject: [PATCH] docs: Update top-level README Rework the top-level README to reflect the current use of this repository. Fixes: #1064. Signed-off-by: James O. D. Hunt --- README.md | 222 +++++++++++++++++++++++++++++------------------------- 1 file changed, 119 insertions(+), 103 deletions(-) diff --git a/README.md b/README.md index 192a9b99a8..3638445c87 100644 --- a/README.md +++ b/README.md @@ -2,130 +2,146 @@ # Kata Containers -* [Raising issues](#raising-issues) -* [Kata Containers repositories](#kata-containers-repositories) - * [Code Repositories](#code-repositories) - * [Kata Containers-developed components](#kata-containers-developed-components) - * [Agent](#agent) - * [KSM throttler](#ksm-throttler) - * [Runtime](#runtime) - * [Trace forwarder](#trace-forwarder) - * [Additional](#additional) - * [Kernel](#kernel) - * [CI](#ci) - * [Community](#community) +* [Kata Containers](#kata-containers) + * [Introduction](#introduction) + * [Getting started](#getting-started) * [Documentation](#documentation) - * [Packaging](#packaging) - * [Test code](#test-code) - * [Utilities](#utilities) - * [OS builder](#os-builder) - * [Web content](#web-content) + * [Community](#community) + * [Getting help](#getting-help) + * [Raising issues](#raising-issues) + * [Kata Containers 1.x versions](#kata-containers-1x-versions) + * [Developers](#developers) + * [Components](#components) + * [Kata Containers 1.x components](#kata-containers-1x-components) + * [Common repositories](#common-repositories) + * [Packaging and releases](#packaging-and-releases) + * [Credits](#credits) --- Welcome to Kata Containers! -The purpose of this repository is to act as a "top level" site for the project. Specifically it is used: +This repository is the home of the Kata Containers code for the 2.0 and newer +releases. -- To provide a list of the various *other* [Kata Containers repositories](#kata-containers-repositories), - along with a brief explanation of their purpose. +If you want to learn about Kata Containers, visit the main +[Kata Containers website](https://katacontainers.io). -- To provide a general area for [Raising Issues](#raising-issues). +For further details on the older (first generation) Kata Containers 1.x +versions, see the +[Kata Containers 1.x components](#kata-containers-1x-components) +section. -## Raising issues +## Introduction -This repository is used for [raising -issues](https://github.com/kata-containers/kata-containers/issues/new): +Kata Containers is an open source project and community working to build a +standard implementation of lightweight Virtual Machines (VMs) that feel and +perform like containers, but provide the workload isolation and security +advantages of VMs. -- That might affect multiple code repositories. +## Getting started -- Where the raiser is unsure which repositories are affected. +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). + +## Community + +To learn more about the project, its community and governance, see the +[community repository](https://github.com/kata-containers/community). This is +the first place to go if you wish to contribute to the project. + +## Getting help + +See the [community](#community) section for ways to contact us. + +### Raising issues + +Please raise an issue +[in this repository](https://github.com/kata-containers/kata-containers/issues). + +#### Kata Containers 1.x versions + +For older Kata Containers 1.x releases, please raise an issue in the +[Kata Containers 1.x component repository](#kata-containers-1x-components) +that seems most appropriate. + +If in doubt, raise an issue +[in the Kata Containers 1.x runtime repository](https://github.com/kata-containers/runtime/issues). + +## Developers + +### Components + +| Component | Type | Description | +|-|-|-| +| [agent-ctl](tools/agent-ctl) | utility | Tool that provides low-level access for testing the agent. | +| [agent](src/agent) | core | Management process running inside the virtual machine / POD that sets up the container environment. | +| [documentation](docs) | documentation | Documentation common to all components (such as design and install documentation). | +| [osbuilder](tools/osbuilder) | infrastructure | Tool to create "mini O/S" rootfs and initrd images for the hypervisor. | +| [packaging](tools/packaging) | infrastructure | Scripts and metadata for producing packaged binaries
(components, hypervisors, kernel and rootfs). | +| [runtime](src/runtime) | core | Main component run by a container manager and providing a containerd shimv2 runtime implementation. | +| [trace-forwarder](src/trace-forwarder) | utility | Agent tracing helper. | + +#### Kata Containers 1.x components + +For the first generation of Kata Containers (1.x versions), each component was +kept in a separate repository. + +For information on the Kata Containers 1.x releases, see the +[Kata Containers 1.x releases page](https://github.com/kata-containers/runtime/releases). + +For further information on particular Kata Containers 1.x components, see the +individual component repositories: + +| Component | Type | Description | +|-|-|-| +| [agent](https://github.com/kata-containers/agent) | core | See [components](#components). | +| [documentation](https://github.com/kata-containers/documentation) | documentation | | +| [KSM throttler](https://github.com/kata-containers/ksm-throttler) | optional core | Daemon that monitors containers and deduplicates memory to maximize container density on the host. | +| [osbuilder](https://github.com/kata-containers/osbuilder) | infrastructure | See [components](#components). | +| [packaging](https://github.com/kata-containers/packaging) | infrastructure | See [components](#components). | +| [proxy](https://github.com/kata-containers/proxy) | core | Multiplexes communications between the shims, agent and runtime. | +| [runtime](https://github.com/kata-containers/runtime) | core | See [components](#components). | +| [shim](https://github.com/kata-containers/shim) | core | Handles standard I/O and signals on behalf of the container process. | > **Note:** -> -> - If an issue affects only a single component, it should be raised in that -> components repository. +> +> - There are more components for the original Kata Containers 1.x implementation. +> - The current implementation simplifies the design significantly: +> compare the [current](docs/design/architecture.md) and +> [previous generation](https://github.com/kata-containers/documentation/blob/master/design/architecture.md) +> designs. -## Kata Containers repositories +### Common repositories -### CI +The following repositories are used by both the current and first generation Kata Containers implementations: -The [CI](https://github.com/kata-containers/ci) repository stores the Continuous -Integration (CI) system configuration information. +| Component | Description | Current | First generation | Notes | +|-|-|-|-|-| +| CI | Continuous Integration configuration files and scripts. | [Kata 2.x](https://github.com/kata-containers/ci/tree/2.0-dev) | [Kata 1.x](https://github.com/kata-containers/ci/tree/master) | | +| kernel | The Linux kernel used by the hypervisor to boot the guest image. | [Kata 2.x][kernel] | [Kata 1.x][kernel] | Patches are stored in the packaging component. | +| tests | Test code. | [Kata 2.x](https://github.com/kata-containers/tests/tree/2.0-dev) | [Kata 1.x](https://github.com/kata-containers/tests/tree/master) | Excludes unit tests which live with the main code. | +| www.katacontainers.io | Contains the source for the [main web site](https://www.katacontainers.io). | [Kata 2.x][github-katacontainers.io] | [Kata 1.x][github-katacontainers.io] | | | -### Community +### Packaging and releases -The [Community](https://github.com/kata-containers/community) repository is -the first place to go if you want to use or contribute to the project. - -### Code Repositories - -#### Kata Containers-developed components - -##### Agent - -The [`kata-agent`](src/agent/README.md) runs inside the -virtual machine and sets up the container environment. - -##### KSM throttler - -The [`kata-ksm-throttler`](https://github.com/kata-containers/ksm-throttler) -is an optional utility that monitors containers and deduplicates memory to -maximize container density on a host. - -##### Runtime - -The [`kata-runtime`](src/runtime/README.md) is usually -invoked by a container manager and provides high-level verbs to manage -containers. - -##### Trace forwarder - -The [`kata-trace-forwarder`](src/trace-forwarder) is a component only used -when tracing the [agent](#agent) process. - -#### Additional - -##### Kernel - -The hypervisor uses a [Linux\* kernel](https://github.com/kata-containers/linux) to boot the guest image. - -### Documentation - -The [docs](docs/README.md) directory holds documentation common to all code components. - -### Packaging - -We use the [packaging](tools/packaging/README.md) to create packages for the [system -components](#kata-containers-developed-components) including -[rootfs](#os-builder) and [kernel](#kernel) images. - -### Test code - -The [tests](https://github.com/kata-containers/tests) repository hosts all -test code except the unit testing code (which is kept in the same repository -as the component it tests). - -### Utilities - -#### OS builder - -The [osbuilder](tools/osbuilder/README.md) tool can create -a rootfs and a "mini O/S" image. This image is used by the hypervisor to setup -the environment before switching to the workload. - -#### `kata-agent-ctl` - -[`kata-agent-ctl`](tools/agent-ctl) is a low-level test tool for -interacting with the agent. - -### Web content - -The -[www.katacontainers.io](https://github.com/kata-containers/www.katacontainers.io) -repository contains all sources for the https://www.katacontainers.io site. +Kata Containers is now +[available natively for most distributions](docs/install/README.md#packaged-installation-methods). +However, packaging scripts and metadata are still used to generate snap and GitHub releases. See +the [components](#components) section for further details. ## Credits Kata Containers uses [packagecloud](https://packagecloud.io) for package hosting. + +--- + +[kernel]: https://www.kernel.org +[github-katacontainers.io]: https://github.com/kata-containers/www.katacontainers.io