From 7c610a6ff1e4ebba9cfedac7f03bede41ccb5f88 Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Mon, 14 Jun 2021 09:59:57 +0100 Subject: [PATCH 1/4] docs: Fix shell code Correct the shell code in the packaging tools README to keep the CI happy. Signed-off-by: James O. D. Hunt --- tools/packaging/release/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/packaging/release/README.md b/tools/packaging/release/README.md index d2f1a4446f30..bc7518077f25 100644 --- a/tools/packaging/release/README.md +++ b/tools/packaging/release/README.md @@ -34,7 +34,7 @@ $ ./update-repository-version.sh -h To update project version for Kata Containers, use the following: ```bash -$ make bump-kata-version NEW_VERSION= +$ make bump-kata-version NEW_VERSION="${new_version}" ``` The makefile target `bump-kata-version` creates a GitHub pull request in the From f186c5e284a2153bb3c797dd81fb5053bfeecbba Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Wed, 16 Jun 2021 11:18:05 +0100 Subject: [PATCH 2/4] docs: Fix invalid URLs Correct broken / stale URLs as detected by the CI URL checker. Signed-off-by: James O. D. Hunt --- README.md | 4 ++-- docs/how-to/service-mesh.md | 5 +++-- docs/use-cases/Nvidia-GPU-passthrough-and-Kata.md | 2 +- src/runtime/README.md | 2 +- tools/packaging/release/README.md | 2 ++ 5 files changed, 9 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 598d394220d8..721aae8ae78d 100644 --- a/README.md +++ b/README.md @@ -127,9 +127,9 @@ The following repositories are used by both the current and first generation Kat | Component | Description | Current | First generation | Notes | |-|-|-|-|-| -| CI | Continuous Integration configuration files and scripts. | [Kata 2.x](https://github.com/kata-containers/ci/tree/main) | [Kata 1.x](https://github.com/kata-containers/ci/tree/master) | | +| CI | Continuous Integration configuration files and scripts. | [Kata 2.x](https://github.com/kata-containers/ci/tree/master) | [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/main) | [Kata 1.x](https://github.com/kata-containers/tests/tree/master) | Excludes unit tests which live with the main code. | +| tests | Test code. | [Kata 2.x](https://github.com/kata-containers/tests/tree/main) | [Kata 1.x](https://github.com/kata-containers/tests/tree/main) | 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] | | | ### Packaging and releases diff --git a/docs/how-to/service-mesh.md b/docs/how-to/service-mesh.md index dde04fd1195a..8dedbfed982a 100644 --- a/docs/how-to/service-mesh.md +++ b/docs/how-to/service-mesh.md @@ -76,15 +76,16 @@ is not able to perform a proper setup of the rules. ### Service Mesh Istio -As a reference, you can follow Istio [instructions](https://istio.io/docs/setup/kubernetes/quick-start/#download-and-prepare-for-the-installation). - The following is a summary of what you need to install Istio on your system: + ``` $ curl -L https://git.io/getLatestIstio | sh - $ cd istio-* $ export PATH=$PWD/bin:$PATH ``` +See the [Istio documentation](https://istio.io/docs) for further details. + Now deploy Istio in the control plane of your cluster with the following: ``` $ kubectl apply -f install/kubernetes/istio-demo.yaml diff --git a/docs/use-cases/Nvidia-GPU-passthrough-and-Kata.md b/docs/use-cases/Nvidia-GPU-passthrough-and-Kata.md index 2fed3ffe757b..e4e88c46ac52 100644 --- a/docs/use-cases/Nvidia-GPU-passthrough-and-Kata.md +++ b/docs/use-cases/Nvidia-GPU-passthrough-and-Kata.md @@ -303,4 +303,4 @@ Tue Mar 3 00:03:49 2020 - [Configuring a VM for GPU Pass-Through by Using the QEMU Command Line](https://docs.nvidia.com/grid/latest/grid-vgpu-user-guide/index.html#using-gpu-pass-through-red-hat-el-qemu-cli) - https://gitlab.com/nvidia/container-images/driver/-/tree/master -- https://github.com/NVIDIA/nvidia-docker/wiki/Driver-containers-(Beta) +- https://github.com/NVIDIA/nvidia-docker/wiki/Driver-containers diff --git a/src/runtime/README.md b/src/runtime/README.md index 1d58e12fbfaf..8830ab1e9273 100644 --- a/src/runtime/README.md +++ b/src/runtime/README.md @@ -150,7 +150,7 @@ $ kata-runtime env For detailed information and analysis on obtaining logs for other system components, see the documentation for the -[`kata-log-parser`](https://github.com/kata-containers/tests/tree/master/cmd/log-parser) +[`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. diff --git a/tools/packaging/release/README.md b/tools/packaging/release/README.md index bc7518077f25..46404c35fb63 100644 --- a/tools/packaging/release/README.md +++ b/tools/packaging/release/README.md @@ -34,6 +34,8 @@ $ ./update-repository-version.sh -h To update project version for Kata Containers, use the following: ```bash +# Set to the required version +$ new_version="a.b.c" $ make bump-kata-version NEW_VERSION="${new_version}" ``` From 4f0726bc49207e0dd08a1eeb17e9480940dd6ad0 Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Mon, 14 Jun 2021 09:39:10 +0100 Subject: [PATCH 3/4] docs: Remove table of contents Removed all TOCs now that GitHub auto-generates them. Also updated the documentation requirements doc removing the requirement to add a TOC. Fixes: #2022. Signed-off-by: James O. D. Hunt --- README.md | 17 ------ docs/Developer-Guide.md | 53 ------------------- docs/Documentation-Requirements.md | 21 ++------ docs/Licensing-strategy.md | 4 -- docs/Limitations.md | 32 ----------- docs/README.md | 11 ---- docs/Release-Process.md | 14 ----- docs/Upgrading.md | 13 ----- docs/design/VSocks.md | 7 --- docs/design/architecture.md | 21 -------- docs/design/end-to-end-flow.md | 1 - docs/design/host-cgroups.md | 15 ------ docs/design/kata-2-0-metrics.md | 15 ------ docs/design/kata-api-design.md | 1 + docs/design/vcpu-handling.md | 8 --- docs/design/virtualization.md | 11 ---- docs/how-to/README.md | 7 +-- docs/how-to/containerd-kata.md | 18 ------- docs/how-to/how-to-hotplug-memory-arm64.md | 4 -- .../how-to-import-kata-logs-with-fluentd.md | 15 ------ docs/how-to/how-to-set-prometheus-in-k8s.md | 8 --- ...to-use-k8s-with-cri-containerd-and-kata.md | 13 ----- .../how-to-use-kata-containers-with-acrn.md | 5 -- docs/how-to/how-to-use-sysctls-with-kata.md | 1 + docs/how-to/how-to-use-virtio-fs-with-kata.md | 3 -- .../how-to/how-to-use-virtio-mem-with-kata.md | 4 -- docs/how-to/privileged.md | 5 -- docs/how-to/run-kata-with-crictl.md | 11 ---- docs/how-to/run-kata-with-k8s.md | 13 ----- docs/how-to/service-mesh.md | 16 ------ .../what-is-vm-cache-and-how-do-I-use-it.md | 5 -- ...at-is-vm-templating-and-how-do-I-use-it.md | 5 ++ docs/hypervisors.md | 6 --- docs/install/README.md | 22 ++------ docs/install/aws-installation-guide.md | 5 -- docs/install/gce-installation-guide.md | 6 --- docs/install/minikube-installation-guide.md | 12 ----- docs/install/snap-installation-guide.md | 6 --- .../Intel-GPU-passthrough-and-Kata.md | 8 --- .../Nvidia-GPU-passthrough-and-Kata.md | 12 ----- docs/use-cases/using-Intel-QAT-and-kata.md | 30 +---------- docs/use-cases/using-Intel-SGX-and-kata.md | 5 -- .../using-SPDK-vhostuser-and-kata.md | 9 +--- docs/use-cases/using-SRIOV-and-kata.md | 8 --- docs/use-cases/zun_kata.md | 1 + snap/README.md | 8 --- src/runtime/README.md | 20 ------- src/runtime/pkg/katatestutils/README.md | 10 ---- src/runtime/virtcontainers/README.md | 22 -------- .../documentation/Developers.md | 9 ---- .../documentation/api/1.0/api.md | 4 -- src/trace-forwarder/README.md | 3 -- tools/agent-ctl/README.md | 9 ---- tools/osbuilder/README.md | 22 -------- tools/osbuilder/dockerfiles/QAT/README.md | 5 -- tools/osbuilder/image-builder/README.md | 3 -- tools/osbuilder/initrd-builder/README.md | 3 -- tools/osbuilder/rootfs-builder/README.md | 17 ------ tools/osbuilder/tests/README.md | 3 -- tools/packaging/README.md | 12 ----- tools/packaging/ccloudvm/README.md | 5 -- tools/packaging/cmd/kata-pkgsync/README.md | 4 -- tools/packaging/kata-deploy/README.md | 10 ---- tools/packaging/kernel/README.md | 9 ---- tools/packaging/kernel/configs/README.md | 5 -- tools/packaging/release/README.md | 7 --- 66 files changed, 21 insertions(+), 676 deletions(-) diff --git a/README.md b/README.md index 721aae8ae78d..7066eb9fa3e0 100644 --- a/README.md +++ b/README.md @@ -2,23 +2,6 @@ # Kata Containers -* [Kata Containers](#kata-containers) - * [Introduction](#introduction) - * [Getting started](#getting-started) - * [Documentation](#documentation) - * [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) - * [Glossary of Terms](#glossary-of-terms) - ---- - Welcome to Kata Containers! This repository is the home of the Kata Containers code for the 2.0 and newer diff --git a/docs/Developer-Guide.md b/docs/Developer-Guide.md index d7ea25c2c215..a6723cd074c5 100644 --- a/docs/Developer-Guide.md +++ b/docs/Developer-Guide.md @@ -1,56 +1,3 @@ -- [Warning](#warning) -- [Assumptions](#assumptions) -- [Initial setup](#initial-setup) -- [Requirements to build individual components](#requirements-to-build-individual-components) -- [Build and install the Kata Containers runtime](#build-and-install-the-kata-containers-runtime) -- [Check hardware requirements](#check-hardware-requirements) - - [Configure to use initrd or rootfs image](#configure-to-use-initrd-or-rootfs-image) - - [Enable full debug](#enable-full-debug) - - [debug logs and shimv2](#debug-logs-and-shimv2) - - [Enabling full `containerd` debug](#enabling-full-containerd-debug) - - [Enabling just `containerd shim` debug](#enabling-just-containerd-shim-debug) - - [Enabling `CRI-O` and `shimv2` debug](#enabling-cri-o-and-shimv2-debug) - - [journald rate limiting](#journald-rate-limiting) - - [`systemd-journald` suppressing messages](#systemd-journald-suppressing-messages) - - [Disabling `systemd-journald` rate limiting](#disabling-systemd-journald-rate-limiting) -- [Create and install rootfs and initrd image](#create-and-install-rootfs-and-initrd-image) - - [Build a custom Kata agent - OPTIONAL](#build-a-custom-kata-agent---optional) - - [Get the osbuilder](#get-the-osbuilder) - - [Create a rootfs image](#create-a-rootfs-image) - - [Create a local rootfs](#create-a-local-rootfs) - - [Add a custom agent to the image - OPTIONAL](#add-a-custom-agent-to-the-image---optional) - - [Build a rootfs image](#build-a-rootfs-image) - - [Install the rootfs image](#install-the-rootfs-image) - - [Create an initrd image - OPTIONAL](#create-an-initrd-image---optional) - - [Create a local rootfs for initrd image](#create-a-local-rootfs-for-initrd-image) - - [Build an initrd image](#build-an-initrd-image) - - [Install the initrd image](#install-the-initrd-image) -- [Install guest kernel images](#install-guest-kernel-images) -- [Install a hypervisor](#install-a-hypervisor) - - [Build a custom QEMU](#build-a-custom-qemu) - - [Build a custom QEMU for aarch64/arm64 - REQUIRED](#build-a-custom-qemu-for-aarch64arm64---required) -- [Run Kata Containers with Containerd](#run-kata-containers-with-containerd) -- [Run Kata Containers with Kubernetes](#run-kata-containers-with-kubernetes) -- [Troubleshoot Kata Containers](#troubleshoot-kata-containers) -- [Appendices](#appendices) - - [Checking Docker default runtime](#checking-docker-default-runtime) - - [Set up a debug console](#set-up-a-debug-console) - - [Simple debug console setup](#simple-debug-console-setup) - - [Enable agent debug console](#enable-agent-debug-console) - - [Start `kata-monitor` - ONLY NEEDED FOR 2.0.x](#start-kata-monitor---only-needed-for-20x) - - [Connect to debug console](#connect-to-debug-console) - - [Traditional debug console setup](#traditional-debug-console-setup) - - [Create a custom image containing a shell](#create-a-custom-image-containing-a-shell) - - [Build the debug image](#build-the-debug-image) - - [Configure runtime for custom debug image](#configure-runtime-for-custom-debug-image) - - [Create a container](#create-a-container) - - [Connect to the virtual machine using the debug console](#connect-to-the-virtual-machine-using-the-debug-console) - - [Enabling debug console for QEMU](#enabling-debug-console-for-qemu) - - [Enabling debug console for cloud-hypervisor / firecracker](#enabling-debug-console-for-cloud-hypervisor--firecracker) - - [Connecting to the debug console](#connecting-to-the-debug-console) - - [Obtain details of the image](#obtain-details-of-the-image) - - [Capturing kernel boot logs](#capturing-kernel-boot-logs) - # Warning This document is written **specifically for developers**: it is not intended for end users. diff --git a/docs/Documentation-Requirements.md b/docs/Documentation-Requirements.md index 1971f0ba1435..e131b3f38910 100644 --- a/docs/Documentation-Requirements.md +++ b/docs/Documentation-Requirements.md @@ -1,16 +1,3 @@ -* [Introduction](#introduction) -* [General requirements](#general-requirements) -* [Linking advice](#linking-advice) -* [Notes](#notes) -* [Warnings and other admonitions](#warnings-and-other-admonitions) -* [Files and command names](#files-and-command-names) -* [Code blocks](#code-blocks) -* [Images](#images) -* [Spelling](#spelling) -* [Names](#names) -* [Version numbers](#version-numbers) -* [The apostrophe](#the-apostrophe) - # Introduction This document outlines the requirements for all documentation in the [Kata @@ -23,10 +10,6 @@ All documents must: - Be written in simple English. - Be written in [GitHub Flavored Markdown](https://github.github.com/gfm) format. - Have a `.md` file extension. -- Include a TOC (table of contents) at the top of the document with links to - all heading sections. We recommend using the - [`kata-check-markdown`](https://github.com/kata-containers/tests/tree/main/cmd/check-markdown) - tool to generate the TOC. - Be linked to from another document in the same repository. Although GitHub allows navigation of the entire repository, it should be @@ -43,6 +26,10 @@ All documents must: which can then execute the commands specified to ensure the instructions are correct. This avoids documents becoming out of date over time. +> **Note:** +> +> Do not add a table of contents (TOC) since GitHub will auto-generate one. + # Linking advice Linking between documents is strongly encouraged to help users and developers diff --git a/docs/Licensing-strategy.md b/docs/Licensing-strategy.md index d113183e3c4e..618beb92b364 100644 --- a/docs/Licensing-strategy.md +++ b/docs/Licensing-strategy.md @@ -1,9 +1,5 @@ # Licensing strategy -* [Project License](#project-license) -* [License file](#license-file) -* [License for individual files](#license-for-individual-files) - ## Project License The license for the [Kata Containers](https://github.com/kata-containers) diff --git a/docs/Limitations.md b/docs/Limitations.md index 95cb58c8f332..3d6a07949d2d 100644 --- a/docs/Limitations.md +++ b/docs/Limitations.md @@ -1,35 +1,3 @@ -* [Overview](#overview) -* [Definition of a limitation](#definition-of-a-limitation) -* [Scope](#scope) -* [Contributing](#contributing) -* [Pending items](#pending-items) - * [Runtime commands](#runtime-commands) - * [checkpoint and restore](#checkpoint-and-restore) - * [events command](#events-command) - * [update command](#update-command) - * [Networking](#networking) - * [Docker swarm and compose support](#docker-swarm-and-compose-support) - * [Resource management](#resource-management) - * [docker run and shared memory](#docker-run-and-shared-memory) - * [docker run and sysctl](#docker-run-and-sysctl) - * [Docker daemon features](#docker-daemon-features) - * [SELinux support](#selinux-support) -* [Architectural limitations](#architectural-limitations) - * [Networking limitations](#networking-limitations) - * [Support for joining an existing VM network](#support-for-joining-an-existing-vm-network) - * [docker --net=host](#docker---nethost) - * [docker run --link](#docker-run---link) - * [Storage limitations](#storage-limitations) - * [Kubernetes `volumeMounts.subPaths`](#kubernetes-volumemountssubpaths) - * [Host resource sharing](#host-resource-sharing) - * [docker run --privileged](#docker-run---privileged) -* [Miscellaneous](#miscellaneous) - * [Docker --security-opt option partially supported](#docker---security-opt-option-partially-supported) -* [Appendices](#appendices) - * [The constraints challenge](#the-constraints-challenge) - -*** - # Overview A [Kata Container](https://github.com/kata-containers) utilizes a Virtual Machine (VM) to enhance security and diff --git a/docs/README.md b/docs/README.md index 691848aa0257..4773f86ac5c3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,16 +1,5 @@ # Documentation -* [Getting Started](#getting-started) -* [More User Guides](#more-user-guides) -* [Kata Use-Cases](#kata-use-cases) -* [Developer Guide](#developer-guide) - * [Design and Implementations](#design-and-implementations) - * [How to Contribute](#how-to-contribute) - * [Code Licensing](#code-licensing) - * [The Release Process](#the-release-process) -* [Help Improving the Documents](#help-improving-the-documents) -* [Website Changes](#website-changes) - The [Kata Containers](https://github.com/kata-containers) documentation repository hosts overall system documentation, with information common to multiple components. diff --git a/docs/Release-Process.md b/docs/Release-Process.md index 019aea822a63..903b8875f2fa 100644 --- a/docs/Release-Process.md +++ b/docs/Release-Process.md @@ -1,20 +1,6 @@ - # How to do a Kata Containers Release This document lists the tasks required to create a Kata Release. - -- [How to do a Kata Containers Release](#how-to-do-a-kata-containers-release) - - [Requirements](#requirements) - - [Release Process](#release-process) - - [Bump all Kata repositories](#bump-all-kata-repositories) - - [Merge all bump version Pull requests](#merge-all-bump-version-pull-requests) - - [Tag all Kata repositories](#tag-all-kata-repositories) - - [Check Git-hub Actions](#check-git-hub-actions) - - [Create release notes](#create-release-notes) - - [Announce the release](#announce-the-release) - - - ## Requirements - [hub](https://github.com/github/hub) diff --git a/docs/Upgrading.md b/docs/Upgrading.md index 062c85ebd6c5..ef633fe68fc8 100644 --- a/docs/Upgrading.md +++ b/docs/Upgrading.md @@ -1,16 +1,3 @@ -* [Introduction](#introduction) -* [Maintenance warning](#maintenance-warning) -* [Determine current version](#determine-current-version) -* [Determine latest version](#determine-latest-version) -* [Configuration changes](#configuration-changes) -* [Upgrade Kata Containers](#upgrade-kata-containers) - * [Upgrade native distribution packaged version](#upgrade-native-distribution-packaged-version) - * [Static installation](#static-installation) - * [Determine if you are using a static installation](#determine-if-you-are-using-a-static-installation) - * [Remove a static installation](#remove-a-static-installation) - * [Upgrade a static installation](#upgrade-a-static-installation) -* [Custom assets](#custom-assets) - # Introduction This document outlines the options for upgrading from a diff --git a/docs/design/VSocks.md b/docs/design/VSocks.md index f4179628d2e1..28ef4effb2bd 100644 --- a/docs/design/VSocks.md +++ b/docs/design/VSocks.md @@ -1,12 +1,5 @@ # Kata Containers and VSOCKs -- [Introduction](#introduction) - - [VSOCK communication diagram](#vsock-communication-diagram) -- [System requirements](#system-requirements) -- [Advantages of using VSOCKs](#advantages-of-using-vsocks) - - [High density](#high-density) - - [Reliability](#reliability) - ## Introduction There are two different ways processes in the virtual machine can communicate diff --git a/docs/design/architecture.md b/docs/design/architecture.md index 516827afa7c7..17a2ea8d5a93 100644 --- a/docs/design/architecture.md +++ b/docs/design/architecture.md @@ -1,26 +1,5 @@ # Kata Containers Architecture - -- [Kata Containers Architecture](#kata-containers-architecture) - - [Overview](#overview) - - [Virtualization](#virtualization) - - [Guest assets](#guest-assets) - - [Guest kernel](#guest-kernel) - - [Guest image](#guest-image) - - [Root filesystem image](#root-filesystem-image) - - [Initrd image](#initrd-image) - - [Agent](#agent) - - [Runtime](#runtime) - - [Configuration](#configuration) - - [Networking](#networking) - - [Network Hotplug](#network-hotplug) - - [Storage](#storage) - - [Kubernetes support](#kubernetes-support) - - [OCI annotations](#oci-annotations) - - [Mixing VM based and namespace based runtimes](#mixing-vm-based-and-namespace-based-runtimes) -- [Appendices](#appendices) - - [DAX](#dax) - ## Overview This is an architectural overview of Kata Containers, based on the 2.0 release. diff --git a/docs/design/end-to-end-flow.md b/docs/design/end-to-end-flow.md index edccb109414b..e09402089c3d 100644 --- a/docs/design/end-to-end-flow.md +++ b/docs/design/end-to-end-flow.md @@ -1,4 +1,3 @@ # Kata Containers E2E Flow - ![Kata containers e2e flow](arch-images/katacontainers-e2e-with-bg.jpg) diff --git a/docs/design/host-cgroups.md b/docs/design/host-cgroups.md index 6bb31cfb1746..5bec21f0bb57 100644 --- a/docs/design/host-cgroups.md +++ b/docs/design/host-cgroups.md @@ -1,18 +1,3 @@ -- [Host cgroup management](#host-cgroup-management) - - [Introduction](#introduction) - - [`SandboxCgroupOnly` enabled](#sandboxcgrouponly-enabled) - - [What does Kata do in this configuration?](#what-does-kata-do-in-this-configuration) - - [Why create a Kata-cgroup under the parent cgroup?](#why-create-a-kata-cgroup-under-the-parent-cgroup) - - [Improvements](#improvements) - - [`SandboxCgroupOnly` disabled (default, legacy)](#sandboxcgrouponly-disabled-default-legacy) - - [What does this method do?](#what-does-this-method-do) - - [Impact](#impact) -- [Supported cgroups](#supported-cgroups) - - [Cgroups V1](#cgroups-v1) - - [Cgroups V2](#cgroups-v2) - - [Distro Support](#distro-support) -- [Summary](#summary) - # Host cgroup management ## Introduction diff --git a/docs/design/kata-2-0-metrics.md b/docs/design/kata-2-0-metrics.md index 0d31f338606e..8adf3d9b5b10 100644 --- a/docs/design/kata-2-0-metrics.md +++ b/docs/design/kata-2-0-metrics.md @@ -1,20 +1,5 @@ # Kata 2.0 Metrics Design -* [Limitations of Kata 1.x and the target of Kata 2.0](#limitations-of-kata-1x-and-the-target-of-kata-20) -* [Metrics architecture](#metrics-architecture) - * [Kata monitor](#kata-monitor) - * [Kata runtime](#kata-runtime) - * [Kata agent](#kata-agent) - * [Performance and overhead](#performance-and-overhead) -* [Metrics list](#metrics-list) - * [Metric types](#metric-types) - * [Kata agent metrics](#kata-agent-metrics) - * [Firecracker metrics](#firecracker-metrics) - * [Kata guest OS metrics](#kata-guest-os-metrics) - * [Hypervisor metrics](#hypervisor-metrics) - * [Kata monitor metrics](#kata-monitor-metrics) - * [Kata containerd shim v2 metrics](#kata-containerd-shim-v2-metrics) - Kata implement CRI's API and support [`ContainerStats`](https://github.com/kubernetes/kubernetes/blob/release-1.18/staging/src/k8s.io/cri-api/pkg/apis/runtime/v1alpha2/api.proto#L101) and [`ListContainerStats`](https://github.com/kubernetes/kubernetes/blob/release-1.18/staging/src/k8s.io/cri-api/pkg/apis/runtime/v1alpha2/api.proto#L103) interfaces to expose containers metrics. User can use these interface to get basic metrics about container. But unlike `runc`, Kata is a VM-based runtime and has a different architecture. diff --git a/docs/design/kata-api-design.md b/docs/design/kata-api-design.md index 3398b219a59d..5976d9f0942f 100644 --- a/docs/design/kata-api-design.md +++ b/docs/design/kata-api-design.md @@ -1,4 +1,5 @@ # Kata API Design + To fulfill the [Kata design requirements](kata-design-requirements.md), and based on the discussion on [Virtcontainers API extensions](https://docs.google.com/presentation/d/1dbGrD1h9cpuqAPooiEgtiwWDGCYhVPdatq7owsKHDEQ), the Kata runtime library features the following APIs: - Sandbox based top API - Storage and network hotplug API diff --git a/docs/design/vcpu-handling.md b/docs/design/vcpu-handling.md index ab65357bbc9a..bb29efa1bc14 100644 --- a/docs/design/vcpu-handling.md +++ b/docs/design/vcpu-handling.md @@ -1,11 +1,3 @@ -- [Virtual machine vCPU sizing in Kata Containers](#virtual-machine-vcpu-sizing-in-kata-containers) - * [Default number of virtual CPUs](#default-number-of-virtual-cpus) - * [Virtual CPUs and Kubernetes pods](#virtual-cpus-and-kubernetes-pods) - * [Container lifecycle](#container-lifecycle) - * [Container without CPU constraint](#container-without-cpu-constraint) - * [Container with CPU constraint](#container-with-cpu-constraint) - * [Do not waste resources](#do-not-waste-resources) - # Virtual machine vCPU sizing in Kata Containers ## Default number of virtual CPUs diff --git a/docs/design/virtualization.md b/docs/design/virtualization.md index 3f79424ba448..eab3d6602a3c 100644 --- a/docs/design/virtualization.md +++ b/docs/design/virtualization.md @@ -1,16 +1,5 @@ # Virtualization in Kata Containers -- [Virtualization in Kata Containers](#virtualization-in-kata-containers) - - [Mapping container concepts to virtual machine technologies](#mapping-container-concepts-to-virtual-machine-technologies) - - [Kata Containers Hypervisor and VMM support](#kata-containers-hypervisor-and-vmm-support) - - [QEMU/KVM](#qemukvm) - - [Machine accelerators](#machine-accelerators) - - [Hotplug devices](#hotplug-devices) - - [Firecracker/KVM](#firecrackerkvm) - - [Cloud Hypervisor/KVM](#cloud-hypervisorkvm) - - [Summary](#summary) - - Kata Containers, a second layer of isolation is created on top of those provided by traditional namespace-containers. The hardware virtualization interface is the basis of this additional layer. Kata will launch a lightweight virtual machine, and use the guest’s Linux kernel to create a container workload, or workloads in the case of multi-container pods. In Kubernetes diff --git a/docs/how-to/README.md b/docs/how-to/README.md index 99deec79714a..a0088ada6b5e 100644 --- a/docs/how-to/README.md +++ b/docs/how-to/README.md @@ -1,11 +1,7 @@ # Howto Guides -* [Howto Guides](#howto-guides) - * [Kubernetes Integration](#kubernetes-integration) - * [Hypervisors Integration](#hypervisors-integration) - * [Advanced Topics](#advanced-topics) - ## Kubernetes Integration + - [Run Kata containers with `crictl`](run-kata-with-crictl.md) - [Run Kata Containers with Kubernetes](run-kata-with-k8s.md) - [How to use Kata Containers and Containerd](containerd-kata.md) @@ -28,6 +24,7 @@ - [Kata Containers with ACRN Hypervisor](how-to-use-kata-containers-with-acrn.md) ## Advanced Topics + - [How to use Kata Containers with virtio-fs](how-to-use-virtio-fs-with-kata.md) - [Setting Sysctls with Kata](how-to-use-sysctls-with-kata.md) - [What Is VMCache and How To Enable It](what-is-vm-cache-and-how-do-I-use-it.md) diff --git a/docs/how-to/containerd-kata.md b/docs/how-to/containerd-kata.md index b53942f7d96e..3a1bc5f0e043 100644 --- a/docs/how-to/containerd-kata.md +++ b/docs/how-to/containerd-kata.md @@ -1,23 +1,5 @@ # How to use Kata Containers and Containerd -- [Concepts](#concepts) - - [Kubernetes `RuntimeClass`](#kubernetes-runtimeclass) - - [Containerd Runtime V2 API: Shim V2 API](#containerd-runtime-v2-api-shim-v2-api) -- [Install](#install) - - [Install Kata Containers](#install-kata-containers) - - [Install containerd with CRI plugin](#install-containerd-with-cri-plugin) - - [Install CNI plugins](#install-cni-plugins) - - [Install `cri-tools`](#install-cri-tools) -- [Configuration](#configuration) - - [Configure containerd to use Kata Containers](#configure-containerd-to-use-kata-containers) - - [Kata Containers as a `RuntimeClass`](#kata-containers-as-a-runtimeclass) - - [Kata Containers as the runtime for untrusted workload](#kata-containers-as-the-runtime-for-untrusted-workload) - - [Kata Containers as the default runtime](#kata-containers-as-the-default-runtime) - - [Configuration for `cri-tools`](#configuration-for-cri-tools) -- [Run](#run) - - [Launch containers with `ctr` command line](#launch-containers-with-ctr-command-line) - - [Launch Pods with `crictl` command line](#launch-pods-with-crictl-command-line) - This document covers the installation and configuration of [containerd](https://containerd.io/) and [Kata Containers](https://katacontainers.io). The containerd provides not only the `ctr` command line tool, but also the [CRI](https://kubernetes.io/blog/2016/12/container-runtime-interface-cri-in-kubernetes/) diff --git a/docs/how-to/how-to-hotplug-memory-arm64.md b/docs/how-to/how-to-hotplug-memory-arm64.md index cad33c56a9c9..799367ad09d0 100644 --- a/docs/how-to/how-to-hotplug-memory-arm64.md +++ b/docs/how-to/how-to-hotplug-memory-arm64.md @@ -1,9 +1,5 @@ # How to use memory hotplug feature in Kata Containers on arm64 -- [Introduction](#introduction) -- [Install UEFI ROM](#install-uefi-rom) -- [Run for test](#run-for-test) - ## Introduction Memory hotplug is a key feature for containers to allocate memory dynamically in deployment. diff --git a/docs/how-to/how-to-import-kata-logs-with-fluentd.md b/docs/how-to/how-to-import-kata-logs-with-fluentd.md index 40d5b6c6d55d..c11893259226 100644 --- a/docs/how-to/how-to-import-kata-logs-with-fluentd.md +++ b/docs/how-to/how-to-import-kata-logs-with-fluentd.md @@ -1,20 +1,5 @@ # Importing Kata Containers logs with Fluentd -* [Introduction](#introduction) -* [Overview](#overview) - * [Test stack](#test-stack) - * [Importing the logs](#importing-the-logs) - * [Direct import `logfmt` from `systemd`](#direct-import-logfmt-from-systemd) - * [Configuring `minikube`](#configuring-minikube) - * [Pull from `systemd`](#pull-from-systemd) - * [Systemd Summary](#systemd-summary) - * [Directly importing JSON](#directly-importing-json) - * [JSON in files](#json-in-files) - * [Prefixing all keys](#prefixing-all-keys) -* [Kata `shimv2`](#kata-shimv2) -* [Caveats](#caveats) -* [Summary](#summary) - # Introduction This document describes how to import Kata Containers logs into [Fluentd](https://www.fluentd.org/), diff --git a/docs/how-to/how-to-set-prometheus-in-k8s.md b/docs/how-to/how-to-set-prometheus-in-k8s.md index 0cd7c2524955..2090c3bd51a3 100644 --- a/docs/how-to/how-to-set-prometheus-in-k8s.md +++ b/docs/how-to/how-to-set-prometheus-in-k8s.md @@ -2,14 +2,6 @@ This document describes how to run `kata-monitor` in a Kubernetes cluster using Prometheus's service discovery to scrape metrics from `kata-agent`. -- [Introduction](#introduction) -- [Pre-requisites](#pre-requisites) -- [Configure Prometheus](#configure-prometheus) -- [Configure `kata-monitor`](#configure-kata-monitor) -- [Setup Grafana](#setup-grafana) - * [Create `datasource`](#create-datasource) - * [Import dashboard](#import-dashboard) - > **Warning**: This how-to is only for evaluation purpose, you **SHOULD NOT** running it in production using this configurations. ## Introduction diff --git a/docs/how-to/how-to-use-k8s-with-cri-containerd-and-kata.md b/docs/how-to/how-to-use-k8s-with-cri-containerd-and-kata.md index 94eb91bb804c..68a840bcdf53 100644 --- a/docs/how-to/how-to-use-k8s-with-cri-containerd-and-kata.md +++ b/docs/how-to/how-to-use-k8s-with-cri-containerd-and-kata.md @@ -1,18 +1,5 @@ # How to use Kata Containers and CRI (containerd plugin) with Kubernetes -* [Requirements](#requirements) -* [Install and configure containerd](#install-and-configure-containerd) -* [Install and configure Kubernetes](#install-and-configure-kubernetes) - * [Install Kubernetes](#install-kubernetes) - * [Configure Kubelet to use containerd](#configure-kubelet-to-use-containerd) - * [Configure HTTP proxy - OPTIONAL](#configure-http-proxy---optional) -* [Start Kubernetes](#start-kubernetes) -* [Configure Pod Network](#configure-pod-network) -* [Allow pods to run in the master node](#allow-pods-to-run-in-the-master-node) -* [Create runtime class for Kata Containers](#create-runtime-class-for-kata-containers) -* [Run pod in Kata Containers](#run-pod-in-kata-containers) -* [Delete created pod](#delete-created-pod) - This document describes how to set up a single-machine Kubernetes (k8s) cluster. The Kubernetes cluster will use the diff --git a/docs/how-to/how-to-use-kata-containers-with-acrn.md b/docs/how-to/how-to-use-kata-containers-with-acrn.md index 24aa7c3ab0cb..39abf491875c 100644 --- a/docs/how-to/how-to-use-kata-containers-with-acrn.md +++ b/docs/how-to/how-to-use-kata-containers-with-acrn.md @@ -2,11 +2,6 @@ This document provides an overview on how to run Kata containers with ACRN hypervisor and device model. -- [Introduction](#introduction) -- [Pre-requisites](#pre-requisites) -- [Configure Docker](#configure-docker) -- [Configure Kata Containers with ACRN](#configure-kata-containers-with-acrn) - ## Introduction ACRN is a flexible, lightweight Type-1 reference hypervisor built with real-time and safety-criticality in mind. ACRN uses an open source platform making it optimized to streamline embedded development. diff --git a/docs/how-to/how-to-use-sysctls-with-kata.md b/docs/how-to/how-to-use-sysctls-with-kata.md index f740d7b2a9f7..117579a5c226 100644 --- a/docs/how-to/how-to-use-sysctls-with-kata.md +++ b/docs/how-to/how-to-use-sysctls-with-kata.md @@ -1,6 +1,7 @@ # Setting Sysctls with Kata ## Sysctls + In Linux, the sysctl interface allows an administrator to modify kernel parameters at runtime. Parameters are available via the `/proc/sys/` virtual process file system. diff --git a/docs/how-to/how-to-use-virtio-fs-with-kata.md b/docs/how-to/how-to-use-virtio-fs-with-kata.md index f7c098fda2fc..732b315c2a43 100644 --- a/docs/how-to/how-to-use-virtio-fs-with-kata.md +++ b/docs/how-to/how-to-use-virtio-fs-with-kata.md @@ -1,8 +1,5 @@ # Kata Containers with virtio-fs -- [Kata Containers with virtio-fs](#kata-containers-with-virtio-fs) - - [Introduction](#introduction) - ## Introduction Container deployments utilize explicit or implicit file sharing between host filesystem and containers. From a trust perspective, avoiding a shared file-system between the trusted host and untrusted container is recommended. This is not always feasible. In Kata Containers, block-based volumes are preferred as they allow usage of either device pass through or `virtio-blk` for access within the virtual machine. diff --git a/docs/how-to/how-to-use-virtio-mem-with-kata.md b/docs/how-to/how-to-use-virtio-mem-with-kata.md index 1725e74f1ab0..0c838927a972 100644 --- a/docs/how-to/how-to-use-virtio-mem-with-kata.md +++ b/docs/how-to/how-to-use-virtio-mem-with-kata.md @@ -1,9 +1,5 @@ # Kata Containers with `virtio-mem` -- [Introduction](#introduction) -- [Requisites](#requisites) -- [Run a Kata Container utilizing `virtio-mem`](#run-a-kata-container-utilizing-virtio-mem) - ## Introduction The basic idea of `virtio-mem` is to provide a flexible, cross-architecture memory hot plug and hot unplug solution that avoids many limitations imposed by existing technologies, architectures, and interfaces. diff --git a/docs/how-to/privileged.md b/docs/how-to/privileged.md index cecc3907d1c6..32ee486b7053 100644 --- a/docs/how-to/privileged.md +++ b/docs/how-to/privileged.md @@ -3,11 +3,6 @@ Kata Containers supports creation of containers that are "privileged" (i.e. have additional capabilities and access that is not normally granted). -* [Warnings](#warnings) - * [Host Devices](#host-devices) - * [Containerd and CRI](#containerd-and-cri) - * [CRI-O](#cri-o) - ## Warnings **Warning:** Whilst this functionality is supported, it can decrease the security of Kata Containers if not configured diff --git a/docs/how-to/run-kata-with-crictl.md b/docs/how-to/run-kata-with-crictl.md index b7c1b19886b5..35986b78f07c 100644 --- a/docs/how-to/run-kata-with-crictl.md +++ b/docs/how-to/run-kata-with-crictl.md @@ -1,16 +1,5 @@ # Working with `crictl` -* [What's `cri-tools`](#whats-cri-tools) -* [Use `crictl` run Pods in Kata containers](#use-crictl-run-pods-in-kata-containers) - * [Run `busybox` Pod](#run-busybox-pod) - * [Run pod sandbox with config file](#run-pod-sandbox-with-config-file) - * [Create container in the pod sandbox with config file](#create-container-in-the-pod-sandbox-with-config-file) - * [Start container](#start-container) - * [Run `redis` Pod](#run-redis-pod) - * [Create `redis-server` Pod](#create-redis-server-pod) - * [Create `redis-client` Pod](#create-redis-client-pod) - * [Check `redis` server is working](#check-redis-server-is-working) - ## What's `cri-tools` [`cri-tools`](https://github.com/kubernetes-sigs/cri-tools) provides debugging and validation tools for Kubelet Container Runtime Interface (CRI). diff --git a/docs/how-to/run-kata-with-k8s.md b/docs/how-to/run-kata-with-k8s.md index f5d28290d2c2..011d2b6bb422 100644 --- a/docs/how-to/run-kata-with-k8s.md +++ b/docs/how-to/run-kata-with-k8s.md @@ -1,18 +1,5 @@ # Run Kata Containers with Kubernetes -* [Run Kata Containers with Kubernetes](#run-kata-containers-with-kubernetes) - * [Prerequisites](#prerequisites) - * [Install a CRI implementation](#install-a-cri-implementation) - * [CRI-O](#cri-o) - * [Kubernetes Runtime Class (CRI-O v1.12 )](#kubernetes-runtime-class-cri-o-v112) - * [Untrusted annotation (until CRI-O v1.12)](#untrusted-annotation-until-cri-o-v112) - * [Network namespace management](#network-namespace-management) - * [containerd with CRI plugin](#containerd-with-cri-plugin) - * [Install Kubernetes](#install-kubernetes) - * [Configure for CRI-O](#configure-for-cri-o) - * [Configure for containerd](#configure-for-containerd) - * [Run a Kubernetes pod with Kata Containers](#run-a-kubernetes-pod-with-kata-containers) - ## Prerequisites This guide requires Kata Containers available on your system, install-able by following [this guide](../install/README.md). diff --git a/docs/how-to/service-mesh.md b/docs/how-to/service-mesh.md index 8dedbfed982a..ca69ad982848 100644 --- a/docs/how-to/service-mesh.md +++ b/docs/how-to/service-mesh.md @@ -1,21 +1,5 @@ # Kata Containers and service mesh for Kubernetes -* [Assumptions](#assumptions) -* [How they work](#how-they-work) -* [Prerequisites](#prerequisites) - * [Kata and Kubernetes](#kata-and-kubernetes) - * [Restrictions](#restrictions) -* [Install and deploy your service mesh](#install-and-deploy-your-service-mesh) - * [Service Mesh Istio](#service-mesh-istio) - * [Service Mesh Linkerd](#service-mesh-linkerd) -* [Inject your services with sidecars](#inject-your-services-with-sidecars) - * [Sidecar Istio](#sidecar-istio) - * [Sidecar Linkerd](#sidecar-linkerd) -* [Run your services with Kata](#run-your-services-with-kata) - * [Lower privileges](#lower-privileges) - * [Add annotations](#add-annotations) - * [Deploy](#deploy) - A service mesh is a way to monitor and control the traffic between micro-services running in your Kubernetes cluster. It is a powerful tool that you might want to use in combination with the security diff --git a/docs/how-to/what-is-vm-cache-and-how-do-I-use-it.md b/docs/how-to/what-is-vm-cache-and-how-do-I-use-it.md index 83adec9ac610..e3b2e080b587 100644 --- a/docs/how-to/what-is-vm-cache-and-how-do-I-use-it.md +++ b/docs/how-to/what-is-vm-cache-and-how-do-I-use-it.md @@ -1,10 +1,5 @@ # What Is VMCache and How To Enable It -* [What is VMCache](#what-is-vmcache) -* [How is this different to VM templating](#how-is-this-different-to-vm-templating) -* [How to enable VMCache](#how-to-enable-vmcache) -* [Limitations](#limitations) - ### What is VMCache VMCache is a new function that creates VMs as caches before using it. diff --git a/docs/how-to/what-is-vm-templating-and-how-do-I-use-it.md b/docs/how-to/what-is-vm-templating-and-how-do-I-use-it.md index 27587b093dfa..b031d09e8ca8 100644 --- a/docs/how-to/what-is-vm-templating-and-how-do-I-use-it.md +++ b/docs/how-to/what-is-vm-templating-and-how-do-I-use-it.md @@ -1,6 +1,7 @@ # What Is VM Templating and How To Enable It ### What is VM templating + VM templating is a Kata Containers feature that enables new VM creation using a cloning technique. When enabled, new VMs are created by cloning from a pre-created template VM, and they will share the @@ -8,11 +9,13 @@ same initramfs, kernel and agent memory in readonly mode. It is very much like a process fork done by the kernel but here we *fork* VMs. ### How is this different from VMCache + Both [VMCache](../how-to/what-is-vm-cache-and-how-do-I-use-it.md) and VM templating help speed up new container creation. When VMCache enabled, new VMs are created by the VMCache server. So it is not vulnerable to share memory CVE because each VM doesn't share the memory. VM templating saves a lot of memory if there are many Kata Containers running on the same host. ### What are the Pros + VM templating helps speed up new container creation and saves a lot of memory if there are many Kata Containers running on the same host. If you are running a density workload, or care a lot about container @@ -29,6 +32,7 @@ showed that VM templating speeds up Kata Containers creation by as much as 38.68%. See [full results here](https://gist.github.com/bergwolf/06974a3c5981494a40e2c408681c085d). ### What are the Cons + One drawback of VM templating is that it cannot avoid cross-VM side-channel attack such as [CVE-2015-2877](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-2877) that originally targeted at the Linux KSM feature. @@ -39,6 +43,7 @@ and can be classified as potentially misunderstood behaviors rather than vulnera **Warning**: If you care about such attack vector, do not use VM templating or KSM. ### How to enable VM templating + VM templating can be enabled by changing your Kata Containers config file (`/usr/share/defaults/kata-containers/configuration.toml`, overridden by `/etc/kata-containers/configuration.toml` if provided) such that: diff --git a/docs/hypervisors.md b/docs/hypervisors.md index 08ab8473858c..02dd49aa126b 100644 --- a/docs/hypervisors.md +++ b/docs/hypervisors.md @@ -1,11 +1,5 @@ # Hypervisors -* [Hypervisors](#hypervisors) - * [Introduction](#introduction) - * [Types](#types) - * [Determine currently configured hypervisor](#determine-currently-configured-hypervisor) - * [Choose a Hypervisor](#choose-a-hypervisor) - ## Introduction Kata Containers supports multiple hypervisors. This document provides a very diff --git a/docs/install/README.md b/docs/install/README.md index 41b7bafdbfa8..e1ddca218ef7 100644 --- a/docs/install/README.md +++ b/docs/install/README.md @@ -1,17 +1,5 @@ # Kata Containers installation user guides -* [Kata Containers installation user guides](#kata-containers-installation-user-guides) - * [Prerequisites](#prerequisites) - * [Legacy installation](#legacy-installation) - * [Packaged installation methods](#packaged-installation-methods) - * [Official packages](#official-packages) - * [Snap Installation](#snap-installation) - * [Automatic Installation](#automatic-installation) - * [Manual Installation](#manual-installation) - * [Build from source installation](#build-from-source-installation) - * [Installing on a Cloud Service Platform](#installing-on-a-cloud-service-platform) - * [Further information](#further-information) - The following is an overview of the different installation methods available. All of these methods equally result in a system configured to run Kata Containers. @@ -52,7 +40,7 @@ Kata packages are provided by official distribution repositories for: | [CentOS](centos-installation-guide.md) | 8 | | [Fedora](fedora-installation-guide.md) | 34 | -> **Note::** +> **Note:** > > All users are encouraged to uses the official distribution versions of Kata > Containers unless they understand the implications of alternative methods. @@ -75,11 +63,11 @@ Follow the [containerd installation guide](container-manager/containerd/containe ## Build from source installation -> **Notes:** +> **Note:** > -> - Power users who decide to build from sources should be aware of the -> implications of using an unpackaged system which will not be automatically -> updated as new [releases](../Stable-Branch-Strategy.md) are made available. +> Power users who decide to build from sources should be aware of the +> implications of using an unpackaged system which will not be automatically +> updated as new [releases](../Stable-Branch-Strategy.md) are made available. [Building from sources](../Developer-Guide.md#initial-setup) allows power users who are comfortable building software from source to use the latest component diff --git a/docs/install/aws-installation-guide.md b/docs/install/aws-installation-guide.md index 885449782e34..ee8494d60bc6 100644 --- a/docs/install/aws-installation-guide.md +++ b/docs/install/aws-installation-guide.md @@ -1,10 +1,5 @@ # Install Kata Containers on Amazon Web Services -* [Install and Configure AWS CLI](#install-and-configure-aws-cli) -* [Create or Import an EC2 SSH key pair](#create-or-import-an-ec2-ssh-key-pair) -* [Launch i3.metal instance](#launch-i3metal-instance) -* [Install Kata](#install-kata) - Kata Containers on Amazon Web Services (AWS) makes use of [i3.metal](https://aws.amazon.com/ec2/instance-types/i3/) instances. Most of the installation procedure is identical to that for Kata on your preferred distribution, except that you have to run it on bare metal instances since AWS doesn't support nested virtualization yet. This guide walks you through creating an i3.metal instance. ## Install and Configure AWS CLI diff --git a/docs/install/gce-installation-guide.md b/docs/install/gce-installation-guide.md index b53cef40c516..e126e3e27b0d 100644 --- a/docs/install/gce-installation-guide.md +++ b/docs/install/gce-installation-guide.md @@ -1,11 +1,5 @@ # Install Kata Containers on Google Compute Engine -* [Create an Image with Nested Virtualization Enabled](#create-an-image-with-nested-virtualization-enabled) - * [Create the Image](#create-the-image) - * [Verify VMX is Available](#verify-vmx-is-available) -* [Install Kata](#install-kata) -* [Create a Kata-enabled Image](#create-a-kata-enabled-image) - Kata Containers on Google Compute Engine (GCE) makes use of [nested virtualization](https://cloud.google.com/compute/docs/instances/enable-nested-virtualization-vm-instances). Most of the installation procedure is identical to that for Kata on your preferred distribution, but enabling nested virtualization currently requires extra steps on GCE. This guide walks you through creating an image and instance with nested virtualization enabled. Note that `kata-runtime check` checks for nested virtualization, but does not fail if support is not found. As a pre-requisite this guide assumes an installed and configured instance of the [Google Cloud SDK](https://cloud.google.com/sdk/downloads). For a zero-configuration option, all of the commands below were been tested under [Google Cloud Shell](https://cloud.google.com/shell/) (as of Jun 2018). Verify your `gcloud` installation and configuration: diff --git a/docs/install/minikube-installation-guide.md b/docs/install/minikube-installation-guide.md index e2f1cd1bacfa..9695cde60585 100644 --- a/docs/install/minikube-installation-guide.md +++ b/docs/install/minikube-installation-guide.md @@ -1,17 +1,5 @@ # Installing Kata Containers in Minikube -* [Installing Kata Containers in Minikube](#installing-kata-containers-in-minikube) - * [Introduction](#introduction) - * [Prerequisites](#prerequisites) - * [Setting up Minikube](#setting-up-minikube) - * [Checking for nested virtualization](#checking-for-nested-virtualization) - * [Check Minikube is running](#check-minikube-is-running) - * [Installing Kata Containers](#installing-kata-containers) - * [Enabling Kata Containers](#enabling-kata-containers) - * [Register the runtime](#register-the-runtime) - * [Testing Kata Containers](#testing-kata-containers) - * [Wrapping up](#wrapping-up) - ## Introduction [Minikube](https://kubernetes.io/docs/setup/minikube/) is an easy way to try out a Kubernetes (k8s) diff --git a/docs/install/snap-installation-guide.md b/docs/install/snap-installation-guide.md index dc85dc22c394..6e384289f94a 100644 --- a/docs/install/snap-installation-guide.md +++ b/docs/install/snap-installation-guide.md @@ -1,11 +1,5 @@ # Kata Containers snap package -* [Install Kata Containers](#install-kata-containers) -* [Configure Kata Containers](#configure-kata-containers) -* [Integration with shim v2 Container Engines](#integration-with-shim-v2-container-engines) -* [Remove Kata Containers snap package](#remove-kata-containers-snap-package) - - ## Install Kata Containers Kata Containers can be installed in any Linux distribution that supports diff --git a/docs/use-cases/Intel-GPU-passthrough-and-Kata.md b/docs/use-cases/Intel-GPU-passthrough-and-Kata.md index eb51fe763d6c..ce18ead804f5 100644 --- a/docs/use-cases/Intel-GPU-passthrough-and-Kata.md +++ b/docs/use-cases/Intel-GPU-passthrough-and-Kata.md @@ -1,13 +1,5 @@ # Using Intel GPU device with Kata Containers -- [Using Intel GPU device with Kata Containers](#using-intel-gpu-device-with-kata-containers) - - [Hardware Requirements](#hardware-requirements) - - [Host Kernel Requirements](#host-kernel-requirements) - - [Install and configure Kata Containers](#install-and-configure-kata-containers) - - [Build Kata Containers kernel with GPU support](#build-kata-containers-kernel-with-gpu-support) - - [GVT-d with Kata Containers](#gvt-d-with-kata-containers) - - [GVT-g with Kata Containers](#gvt-g-with-kata-containers) - An Intel Graphics device can be passed to a Kata Containers container using GPU passthrough (Intel GVT-d) as well as GPU mediated passthrough (Intel GVT-g). diff --git a/docs/use-cases/Nvidia-GPU-passthrough-and-Kata.md b/docs/use-cases/Nvidia-GPU-passthrough-and-Kata.md index e4e88c46ac52..1a3253fdc88e 100644 --- a/docs/use-cases/Nvidia-GPU-passthrough-and-Kata.md +++ b/docs/use-cases/Nvidia-GPU-passthrough-and-Kata.md @@ -1,17 +1,5 @@ # Using Nvidia GPU device with Kata Containers -- [Using Nvidia GPU device with Kata Containers](#using-nvidia-gpu-device-with-kata-containers) - - [Hardware Requirements](#hardware-requirements) - - [Host BIOS Requirements](#host-bios-requirements) - - [Host Kernel Requirements](#host-kernel-requirements) - - [Install and configure Kata Containers](#install-and-configure-kata-containers) - - [Build Kata Containers kernel with GPU support](#build-kata-containers-kernel-with-gpu-support) - - [Nvidia GPU pass-through mode with Kata Containers](#nvidia-gpu-pass-through-mode-with-kata-containers) - - [Nvidia vGPU mode with Kata Containers](#nvidia-vgpu-mode-with-kata-containers) - - [Install Nvidia Driver in Kata Containers](#install-nvidia-driver-in-kata-containers) - - [References](#references) - - An Nvidia GPU device can be passed to a Kata Containers container using GPU passthrough (Nvidia GPU pass-through mode) as well as GPU mediated passthrough (Nvidia vGPU mode).  diff --git a/docs/use-cases/using-Intel-QAT-and-kata.md b/docs/use-cases/using-Intel-QAT-and-kata.md index e8e8f274a72b..8482b67932a5 100644 --- a/docs/use-cases/using-Intel-QAT-and-kata.md +++ b/docs/use-cases/using-Intel-QAT-and-kata.md @@ -1,33 +1,5 @@ # Table of Contents -- [Table of Contents](#table-of-contents) -- [Introduction](#introduction) - - [Helpful Links before starting](#helpful-links-before-starting) - - [Steps to enable Intel® QAT in Kata Containers](#steps-to-enable-intel-qat-in-kata-containers) - - [Script variables](#script-variables) - - [Set environment variables (Every Reboot)](#set-environment-variables-every-reboot) - - [Prepare the Ubuntu Host](#prepare-the-ubuntu-host) - - [Identify which PCI Bus the Intel® QAT card is on](#identify-which-pci-bus-the-intel-qat-card-is-on) - - [Install necessary packages for Ubuntu](#install-necessary-packages-for-ubuntu) - - [Download Intel® QAT drivers](#download-intel-qat-drivers) - - [Copy Intel® QAT configuration files and enable virtual functions](#copy-intel-qat-configuration-files-and-enable-virtual-functions) - - [Expose and Bind Intel® QAT virtual functions to VFIO-PCI (Every reboot)](#expose-and-bind-intel-qat-virtual-functions-to-vfio-pci-every-reboot) - - [Check Intel® QAT virtual functions are enabled](#check-intel-qat-virtual-functions-are-enabled) - - [Prepare Kata Containers](#prepare-kata-containers) - - [Download Kata kernel Source](#download-kata-kernel-source) - - [Build Kata kernel](#build-kata-kernel) - - [Copy Kata kernel](#copy-kata-kernel) - - [Prepare Kata root filesystem](#prepare-kata-root-filesystem) - - [Compile Intel® QAT drivers for Kata Containers kernel and add to Kata Containers rootfs](#compile-intel-qat-drivers-for-kata-containers-kernel-and-add-to-kata-containers-rootfs) - - [Copy Kata rootfs](#copy-kata-rootfs) - - [Verify Intel® QAT works in a container](#verify-intel-qat-works-in-a-container) - - [Build OpenSSL Intel® QAT engine container](#build-openssl-intel-qat-engine-container) - - [Test Intel® QAT with the ctr tool](#test-intel-qat-with-the-ctr-tool) - - [Test Intel® QAT in Kubernetes](#test-intel-qat-in-kubernetes) - - [Troubleshooting](#troubleshooting) - - [Optional Scripts](#optional-scripts) - - [Verify Intel® QAT card counters are incremented](#verify-intel-qat-card-counters-are-incremented) - # Introduction Intel® QuickAssist Technology (QAT) provides hardware acceleration @@ -604,4 +576,4 @@ $ for i in 0434 0435 37c8 1f18 1f19; do lspci -d 8086:$i; done $ sudo watch cat /sys/kernel/debug/qat_c6xx_0000\:b1\:00.0/fw_counters $ sudo watch cat /sys/kernel/debug/qat_c6xx_0000\:b3\:00.0/fw_counters $ sudo watch cat /sys/kernel/debug/qat_c6xx_0000\:b5\:00.0/fw_counters -``` \ No newline at end of file +``` diff --git a/docs/use-cases/using-Intel-SGX-and-kata.md b/docs/use-cases/using-Intel-SGX-and-kata.md index 0e49e218585a..2a3af40186fc 100644 --- a/docs/use-cases/using-Intel-SGX-and-kata.md +++ b/docs/use-cases/using-Intel-SGX-and-kata.md @@ -1,10 +1,5 @@ # Kata Containers with SGX -- [Check if SGX is enabled](#check-if-sgx-is-enabled) -- [Install Host kernel with SGX support](#install-host-kernel-with-sgx-support) -- [Install Guest kernel with SGX support](#install-guest-kernel-with-sgx-support) -- [Run Kata Containers with SGX enabled](#run-kata-containers-with-sgx-enabled) - Intel® Software Guard Extensions (SGX) is a set of instructions that increases the security of applications code and data, giving them more protections from disclosure or modification. diff --git a/docs/use-cases/using-SPDK-vhostuser-and-kata.md b/docs/use-cases/using-SPDK-vhostuser-and-kata.md index 624b96b3bec9..4cef647ea24b 100644 --- a/docs/use-cases/using-SPDK-vhostuser-and-kata.md +++ b/docs/use-cases/using-SPDK-vhostuser-and-kata.md @@ -1,13 +1,6 @@ # Setup to run SPDK vhost-user devices with Kata Containers and Docker* -- [SPDK vhost-user target overview](#spdk-vhost-user-target-overview) -- [Install and setup SPDK vhost-user target](#install-and-setup-spdk-vhost-user-target) - - [Get source code and build SPDK](#get-source-code-and-build-spdk) - - [Run SPDK vhost-user target](#run-spdk-vhost-user-target) -- [Host setup for vhost-user devices](#host-setup-for-vhost-user-devices) -- [Launch a Kata container with SPDK vhost-user block device](#launch-a-kata-container-with-spdk-vhost-user-block-device) - -> **NOTE:** This guide only applies to QEMU, since the vhost-user storage +> **Note:** This guide only applies to QEMU, since the vhost-user storage > device is only available for QEMU now. The enablement work on other > hypervisors is still ongoing. diff --git a/docs/use-cases/using-SRIOV-and-kata.md b/docs/use-cases/using-SRIOV-and-kata.md index 85ed5f03e26f..2c4b2c836c07 100644 --- a/docs/use-cases/using-SRIOV-and-kata.md +++ b/docs/use-cases/using-SRIOV-and-kata.md @@ -1,13 +1,5 @@ # Setup to use SR-IOV with Kata Containers and Docker* -- [Install the SR-IOV Docker\* plugin](#install-the-sr-iov-docker-plugin) -- [Host setup for SR-IOV](#host-setup-for-sr-iov) - - [Checking your NIC for SR-IOV](#checking-your-nic-for-sr-iov) - - [IOMMU Groups and PCIe Access Control Services](#iommu-groups-and-pcie-access-control-services) - - [Update the host kernel](#update-the-host-kernel) -- [Set up the SR-IOV Device](#set-up-the-sr-iov-device) -- [Example: Launch a Kata Containers container using SR-IOV](#example-launch-a-kata-containers-container-using-sr-iov) - Single Root I/O Virtualization (SR-IOV) enables splitting a physical device into virtual functions (VFs). Virtual functions enable direct passthrough to virtual machines or containers. For Kata Containers, we enabled a Container Network diff --git a/docs/use-cases/zun_kata.md b/docs/use-cases/zun_kata.md index 20fa9c4f54a7..19560c99acaf 100644 --- a/docs/use-cases/zun_kata.md +++ b/docs/use-cases/zun_kata.md @@ -1,4 +1,5 @@ # OpenStack Zun DevStack working with Kata Containers + ## Introduction This guide describes how to get Kata Containers to work with OpenStack Zun diff --git a/snap/README.md b/snap/README.md index b2e69e5ee1c0..1114315befa4 100644 --- a/snap/README.md +++ b/snap/README.md @@ -1,13 +1,5 @@ # Kata Containers snap image -* [Initial setup](#initial-setup) -* [Install snap](#install-snap) -* [Build and install snap image](#build-and-install-snap-image) -* [Configure Kata Containers](#configure-kata-containers) -* [Integration with docker and Kubernetes](#integration-with-docker-and-kubernetes) -* [Remove snap](#remove-snap) -* [Limitations](#limitations) - This directory contains the resources needed to build the Kata Containers [snap][1] image. diff --git a/src/runtime/README.md b/src/runtime/README.md index 8830ab1e9273..a13636096caa 100644 --- a/src/runtime/README.md +++ b/src/runtime/README.md @@ -8,26 +8,6 @@ This repository contains the runtime for the For details of the other Kata Containers repositories, see the [repository summary](https://github.com/kata-containers/kata-containers). -* [Introduction](#introduction) -* [License](#license) -* [Platform support](#platform-support) - * [Hardware requirements](#hardware-requirements) -* [Download and install](#download-and-install) -* [Quick start for developers](#quick-start-for-developers) -* [Architecture overview](#architecture-overview) -* [Configuration](#configuration) - * [Hypervisor specific configuration](#hypervisor-specific-configuration) - * [Stateless systems](#stateless-systems) -* [Logging](#logging) - * [Kata OCI](#kata-oci) - * [Kata containerd shimv2](#kata-containerd-shimv2) -* [Debugging](#debugging) -* [Limitations](#limitations) -* [Community](#community) - * [Contact](#contact) -* [Further information](#further-information) -* [Additional packages](#additional-packages) - ## Introduction `kata-runtime`, referred to as "the runtime", is the Command-Line Interface diff --git a/src/runtime/pkg/katatestutils/README.md b/src/runtime/pkg/katatestutils/README.md index ef1c6f926c63..dd4cbe2a08ea 100644 --- a/src/runtime/pkg/katatestutils/README.md +++ b/src/runtime/pkg/katatestutils/README.md @@ -1,15 +1,5 @@ # Kata test utilities -* [Test Constraints](#test-constraints) - * [Usage](#usage) - * [Displaying the `TestConstraint`](#displaying-the-testconstraint) - * [Associating an issue with a constraint](#associating-an-issue-with-a-constraint) - * [Examples](#examples) - * [Skip tests based on user](#skip-tests-based-on-user) - * [Skip tests based on distro](#skip-tests-based-on-distro) - * [Skip tests based on kernel version](#skip-tests-based-on-kernel-version) - * [Full details](#full-details) - This package provides a small set of test utilities. See the [GoDoc](https://godoc.org/github.com/kata-containers/runtime/pkg/katatestutils) for full details. diff --git a/src/runtime/virtcontainers/README.md b/src/runtime/virtcontainers/README.md index c8072d4235d4..97f01cfb9193 100644 --- a/src/runtime/virtcontainers/README.md +++ b/src/runtime/virtcontainers/README.md @@ -1,25 +1,3 @@ -Table of Contents -================= - -* [What is it?](#what-is-it) -* [Background](#background) -* [Out of scope](#out-of-scope) - * [virtcontainers and Kubernetes CRI](#virtcontainers-and-kubernetes-cri) -* [Design](#design) - * [Sandboxes](#sandboxes) - * [Hypervisors](#hypervisors) - * [Agents](#agents) -* [API](#api) -* [Networking](#networking) - * [CNM](#cnm) -* [Storage](#storage) -* [Devices](#devices) - * [How to pass a device using VFIO-PCI passthrough](#how-to-pass-a-device-using-vfio-pci-passthrough) - * [How to pass a device using VFIO-AP passthrough](#how-to-pass-a-device-using-vfio-ap-passthrough) -* [Developers](#developers) -* [Persistent storage plugin support](#persistent-storage-plugin-support) -* [Experimental features](#experimental-features) - # What is it? `virtcontainers` is a Go library that can be used to build hardware-virtualized container diff --git a/src/runtime/virtcontainers/documentation/Developers.md b/src/runtime/virtcontainers/documentation/Developers.md index 6ec807658b2b..cbeeac3c4633 100644 --- a/src/runtime/virtcontainers/documentation/Developers.md +++ b/src/runtime/virtcontainers/documentation/Developers.md @@ -1,12 +1,3 @@ - -Table of Contents -================= - - * [Prerequisites](#prerequisites) - * [Building](#building) - * [Testing](#testing) - * [Submitting changes](#submitting-changes) - # Prerequisites `virtcontainers` has a few prerequisites for development: diff --git a/src/runtime/virtcontainers/documentation/api/1.0/api.md b/src/runtime/virtcontainers/documentation/api/1.0/api.md index 50097c6c5d9d..81872715f37e 100644 --- a/src/runtime/virtcontainers/documentation/api/1.0/api.md +++ b/src/runtime/virtcontainers/documentation/api/1.0/api.md @@ -3,10 +3,6 @@ The virtcontainers 1.0 API operates on two high level objects: [Sandboxes](#sandbox-api) and [containers](#container-api): -* [Sandbox API](#sandbox-api) -* [Container API](#container-api) -* [Examples](#examples) - ## Sandbox API The virtcontainers 1.0 sandbox API manages hardware virtualized diff --git a/src/trace-forwarder/README.md b/src/trace-forwarder/README.md index 562e0f4ff4b5..3cd36db44abe 100644 --- a/src/trace-forwarder/README.md +++ b/src/trace-forwarder/README.md @@ -1,8 +1,5 @@ # Trace Forwarder -* [Overview](#overview) -* [Full details](#full-details) - ## Overview The Kata Containers trace forwarder, `kata-trace-forwarder`, is a component diff --git a/tools/agent-ctl/README.md b/tools/agent-ctl/README.md index 8cd5954b5e21..9fc4771df7a6 100644 --- a/tools/agent-ctl/README.md +++ b/tools/agent-ctl/README.md @@ -1,14 +1,5 @@ # Agent Control tool -* [Overview](#overview) -* [Audience and environment](#audience-and-environment) -* [Full details](#full-details) -* [Code summary](#code-summary) -* [Running the tool](#running-the-tool) - * [Prerequisites](#prerequisites) - * [Connect to a real Kata Container](#connect-to-a-real-kata-container) - * [Run the tool and the agent in the same environment](#run-the-tool-and-the-agent-in-the-same-environment) - ## Overview The Kata Containers agent control tool (`kata-agent-ctl`) is a low-level test diff --git a/tools/osbuilder/README.md b/tools/osbuilder/README.md index 0cdb556b9f11..a602da25b5ba 100644 --- a/tools/osbuilder/README.md +++ b/tools/osbuilder/README.md @@ -1,27 +1,5 @@ # osbuilder -* [osbuilder](#osbuilder) - * [Introduction](#introduction) - * [Terms](#terms) - * [Building](#building) - * [Rootfs creation](#rootfs-creation) - * [Rootfs with systemd as init](#rootfs-with-systemd-as-init) - * [Rootfs with the agent as init](#rootfs-with-the-agent-as-init) - * [dracut based rootfs](#dracut-based-rootfs) - * [Image creation](#image-creation) - * [Image with systemd as init](#image-with-systemd-as-init) - * [Image with the agent as init](#image-with-the-agent-as-init) - * [dracut based image](#dracut-based-image) - * [Initrd creation](#initrd-creation) - * [Rootfs based initrd](#rootfs-based-initrd) - * [dracut based initrd](#dracut-based-initrd) - * [dracut options](#dracut-options) - * [Add kernel modules](#add-kernel-modules) - * [Custom images](#custom-images) - * [Intel® QuickAssist Technology (QAT) customized kernel and rootfs](#intel-quickassist-technology-qat-customized-kernel-and-rootfs) - * [Testing](#testing) - * [Platform-Distro Compatibility Matrix](#platform-distro-compatibility-matrix) - ## Introduction The Kata Containers runtime creates a virtual machine (VM) to isolate a set of diff --git a/tools/osbuilder/dockerfiles/QAT/README.md b/tools/osbuilder/dockerfiles/QAT/README.md index 99d23ac68c52..457446b8673c 100644 --- a/tools/osbuilder/dockerfiles/QAT/README.md +++ b/tools/osbuilder/dockerfiles/QAT/README.md @@ -1,8 +1,3 @@ - - * [Introduction](#introduction) - * [Building](#building) - * [Options](#options) - ## Introduction The files in this directory can be used to build a modified Kata Containers rootfs diff --git a/tools/osbuilder/image-builder/README.md b/tools/osbuilder/image-builder/README.md index 87ebe125ae73..dd6b26dfd1ac 100644 --- a/tools/osbuilder/image-builder/README.md +++ b/tools/osbuilder/image-builder/README.md @@ -1,6 +1,3 @@ -* [Creating a guest OS image](#creating-a-guest-os-image) -* [Further information](#further-information) - # Kata Containers image generation A Kata Containers disk image is generated using the `image_builder.sh` script. diff --git a/tools/osbuilder/initrd-builder/README.md b/tools/osbuilder/initrd-builder/README.md index 66eee37eb817..3dbddfe56ebf 100644 --- a/tools/osbuilder/initrd-builder/README.md +++ b/tools/osbuilder/initrd-builder/README.md @@ -1,6 +1,3 @@ -* [Creating a guest OS initrd image](#creating-a-guest-os-initrd-image) -* [Further information](#further-information) - # Kata Containers initrd image generation A Kata Containers initrd image is generated using the `initrd_builder.sh` script. diff --git a/tools/osbuilder/rootfs-builder/README.md b/tools/osbuilder/rootfs-builder/README.md index c49b58f860f3..fe3d1a8a22ab 100644 --- a/tools/osbuilder/rootfs-builder/README.md +++ b/tools/osbuilder/rootfs-builder/README.md @@ -1,20 +1,3 @@ -* [Building a Guest OS rootfs for Kata Containers](#building-a-guest-os-rootfs-for-kata-containers) - * [Supported base OSs](#supported-base-oss) - * [Extra features](#extra-features) - * [Supported distributions list](#supported-distributions-list) - * [Generate Kata specific files](#generate-kata-specific-files) - * [Rootfs requirements](#rootfs-requirements) - * [Creating a rootfs](#creating-a-rootfs) - * [Creating a rootfs with kernel modules](#creating-a-rootfs-with-kernel-modules) - * [Build a rootfs using Docker](#build-a-rootfs-using-docker) - * [Adding support for a new guest OS](#adding-support-for-a-new-guest-os) - * [Create template files](#create-template-files) - * [Modify template files](#modify-template-files) - * [Expected rootfs directory content](#expected-rootfs-directory-content) - * [Optional - Customize the rootfs](#optional---customize-the-rootfs) - * [Adding extra packages](#adding-extra-packages) - * [Arbitrary rootfs changes](#arbitrary-rootfs-changes) - # Building a Guest OS rootfs for Kata Containers The Kata Containers rootfs is created using the `rootfs.sh` script. diff --git a/tools/osbuilder/tests/README.md b/tools/osbuilder/tests/README.md index 7fb2e3b8aae1..10d337d25516 100644 --- a/tools/osbuilder/tests/README.md +++ b/tools/osbuilder/tests/README.md @@ -1,6 +1,3 @@ -* [Run the osbuilder tests](#run-the-osbuilder-tests) -* [Further information](#further-information) - ## Run the osbuilder tests osbuilder provides a test script that creates all rootfs disk images and diff --git a/tools/packaging/README.md b/tools/packaging/README.md index 0fbf4be31dda..a5f7cd681ada 100644 --- a/tools/packaging/README.md +++ b/tools/packaging/README.md @@ -1,17 +1,5 @@ # Kata Containers packaging -* [Introduction](#introduction) -* [Build in a container](#build-in-a-container) -* [Build a snap package](#build-a-snap-package) -* [Build static binaries](#build-static-binaries) -* [Build Kata Containers Kernel](#build-kata-containers-kernel) -* [Build QEMU](#build-qemu) -* [Test Kata using ccloudvm](#test-kata-using-ccloudvm) -* [Create a Kata Containers release](#create-a-kata-containers-release) -* [Jenkins files](#jenkins-files) -* [Packaging scripts](#packaging-scripts) -* [Credits](#credits) - ## Introduction Kata Containers currently supports packages for many distributions. Tooling to diff --git a/tools/packaging/ccloudvm/README.md b/tools/packaging/ccloudvm/README.md index cec0443cae4f..e438eea9a27f 100644 --- a/tools/packaging/ccloudvm/README.md +++ b/tools/packaging/ccloudvm/README.md @@ -1,10 +1,5 @@ # Test Kata using ccloudvm -* [How to use Kata workloads for `ccloudvm`](#how-to-use-kata-workloads-for-ccloudvm) - * [Create Docker\* and Kata Containers virtualized environment](#create-docker-and-kata-containers-virtualized-environment) - -*** - The [ccloudvm](https://github.com/intel/ccloudvm/) tool is a command to create development and demo environments. The tool sets up these development environments inside a virtual machine. diff --git a/tools/packaging/cmd/kata-pkgsync/README.md b/tools/packaging/cmd/kata-pkgsync/README.md index 0f98f7ebd82a..41d41826d789 100644 --- a/tools/packaging/cmd/kata-pkgsync/README.md +++ b/tools/packaging/cmd/kata-pkgsync/README.md @@ -1,9 +1,5 @@ # Kata OBS to Packagecloud sync tool -* [How it works](#how-it-works) -* [Detailed behaviour](#detailed-behaviour) -* [Install and Usage](#install-and-usage) - `kata-pkgsync` is a tool to synchronize Kata package from OBS to Packagecloud. ## How it works diff --git a/tools/packaging/kata-deploy/README.md b/tools/packaging/kata-deploy/README.md index 4e1068a0a94b..f0e5f9fb1197 100644 --- a/tools/packaging/kata-deploy/README.md +++ b/tools/packaging/kata-deploy/README.md @@ -1,15 +1,5 @@ # `kata-deploy` -* [Kubernetes quick start](#kubernetes-quick-start) - * [Install Kata on a running Kubernetes cluster](#install-kata-on-a-running-kubernetes-cluster) - * [Run a sample workload](#run-a-sample-workload) - * [Remove Kata from the Kubernetes cluster](#remove-kata-from-the-kubernetes-cluster) -* [`kata-deploy` details](#kata-deploy-details) - * [Dockerfile](#dockerfile) - * [DaemonSets and RBAC](#daemonsets-and-rbac) - * [Kata deploy](#kata-deploy) - * [Kata cleanup](#kata-cleanup) - [`kata-deploy`](.) provides a Dockerfile, which contains all of the binaries and artifacts required to run Kata Containers, as well as reference DaemonSets, which can be utilized to install Kata Containers on a running Kubernetes cluster. diff --git a/tools/packaging/kernel/README.md b/tools/packaging/kernel/README.md index 806165203466..e47c116eade5 100644 --- a/tools/packaging/kernel/README.md +++ b/tools/packaging/kernel/README.md @@ -1,14 +1,5 @@ # Build Kata Containers Kernel -* [Requirements](#requirements) -* [Usage](#usage) -* [Setup kernel source code](#setup-kernel-source-code) -* [Build the kernel](#build-the-kernel) -* [Install the Kernel in the default path for Kata](#install-the-kernel-in-the-default-path-for-kata) -* [Submit Kernel Changes](#submit-kernel-changes) -* [How is it tested](#how-is-it-tested) -* [Contribute](#contribute) - This document explains the steps to build a kernel recommended for use with Kata Containers. To do this use `build-kernel.sh`, this script automates the process to build a kernel for Kata Containers. diff --git a/tools/packaging/kernel/configs/README.md b/tools/packaging/kernel/configs/README.md index e664095b44ae..d3e550666997 100644 --- a/tools/packaging/kernel/configs/README.md +++ b/tools/packaging/kernel/configs/README.md @@ -1,8 +1,3 @@ -* [Kata Containers kernel config files](#kata-containers-kernel-config-files) - * [Types of config files](#types-of-config-files) - * [How to use config files](#how-to-use-config-files) - * [How to modify config files](#how-to-modify-config-files) - # Kata Containers kernel config files This directory contains Linux Kernel config files used to configure Kata diff --git a/tools/packaging/release/README.md b/tools/packaging/release/README.md index 46404c35fb63..3f17f238d629 100644 --- a/tools/packaging/release/README.md +++ b/tools/packaging/release/README.md @@ -1,12 +1,5 @@ # Release information -* [Introduction](#introduction) -* [Create a Kata Containers release](#create-a-kata-containers-release) -* [Release tools](#release-tools) - - [`update-repository-version.sh`](#update-repository-versionsh) - - [Update Kata projects to a new version](#update-kata-projects-to-a-new-version) - - [`tag_repos.sh`](#tag_repossh) - ## Introduction This directory contains information of the process and From 57b696a5ec080b4feab278b6b6ae5ec0f7e84e1f Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Thu, 1 Jul 2021 16:01:37 +0100 Subject: [PATCH 4/4] docs: Removed mention of 1.x All users should be running 2.x releases so remove the legacy details since it's arguably confusing to have two sets of details. Reworked the components listed in the main README so that rather than being sorted alphabetically, they are now sorted in semi-order of importance and split into two tables to make the point more clearly. Signed-off-by: James O. D. Hunt --- README.md | 70 +++++++++--------------------------------- docs/install/README.md | 5 --- 2 files changed, 15 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index 7066eb9fa3e0..7f5746260845 100644 --- a/README.md +++ b/README.md @@ -10,11 +10,6 @@ releases. If you want to learn about Kata Containers, visit the main [Kata Containers website](https://katacontainers.io). -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. - ## Introduction Kata Containers is an open source project and community working to build a @@ -51,69 +46,34 @@ Please raise an issue > **Note:** > If you are reporting a security issue, please follow the [vulnerability reporting process](https://github.com/kata-containers/community#vulnerability-handling) -#### 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 +### Main components + +The table below lists the core parts of the project: + | Component | Type | Description | |-|-|-| -| [agent-ctl](tools/agent-ctl) | utility | Tool that provides low-level access for testing the agent. | +| [runtime](src/runtime) | core | Main component run by a container manager and providing a containerd shimv2 runtime implementation. | | [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. +| [tests](https://github.com/kata-containers/tests) | tests | Excludes unit tests which live with the main code. | -For information on the Kata Containers 1.x releases, see the -[Kata Containers 1.x releases page](https://github.com/kata-containers/runtime/releases). +### Additional components -For further information on particular Kata Containers 1.x components, see the -individual component repositories: +The table below lists the remaining parts of the project: | 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:** -> -> - 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. - -### Common repositories - -The following repositories are used by both the current and first generation Kata Containers implementations: - -| Component | Description | Current | First generation | Notes | -|-|-|-|-|-| -| CI | Continuous Integration configuration files and scripts. | [Kata 2.x](https://github.com/kata-containers/ci/tree/master) | [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/main) | [Kata 1.x](https://github.com/kata-containers/tests/tree/main) | 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] | | | +| [packaging](tools/packaging) | infrastructure | Scripts and metadata for producing packaged binaries
(components, hypervisors, kernel and rootfs). | +| [kernel](https://www.kernel.org) | kernel | Linux kernel used by the hypervisor to boot the guest image. Patches are stored [here](tools/packaging/kernel). | +| [osbuilder](tools/osbuilder) | infrastructure | Tool to create "mini O/S" rootfs and initrd images and kernel for the hypervisor. | +| [`agent-ctl`](tools/agent-ctl) | utility | Tool that provides low-level access for testing the agent. | +| [`trace-forwarder`](src/trace-forwarder) | utility | Agent tracing helper. | +| [`ci`](https://github.com/kata-containers/ci) | CI | Continuous Integration configuration files and scripts. | +| [`katacontainers.io`](https://github.com/kata-containers/www.katacontainers.io) | Source for the [`katacontainers.io`](https://www.katacontainers.io) site. | ### Packaging and releases diff --git a/docs/install/README.md b/docs/install/README.md index e1ddca218ef7..40baec9169cd 100644 --- a/docs/install/README.md +++ b/docs/install/README.md @@ -10,11 +10,6 @@ See the [hardware requirements](/src/runtime/README.md#hardware-requirements) to see if your system is capable of running Kata Containers. -## Legacy installation - -If you wish to install a legacy 1.x version of Kata Containers, see -[the Kata Containers 1.x installation documentation](https://github.com/kata-containers/documentation/tree/master/install/). - ## Packaged installation methods > **Notes:**