From 6f9efb4043f38a384d4f07c5e545a3377c0759ff Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Wed, 15 Dec 2021 17:44:24 +0000 Subject: [PATCH] docs: Move arch doc to separate directory Move the architecture document into a new `docs/design/architecture/` directory in preparation for splitting it into more manageable pieces. Signed-off-by: James O. D. Hunt --- docs/README.md | 2 +- docs/Upgrading.md | 2 +- docs/design/README.md | 2 +- .../README.md} | 68 +++++++++---------- docs/design/virtualization.md | 2 +- snap/README.md | 2 +- src/agent/README.md | 4 +- src/runtime/README.md | 2 +- src/runtime/virtcontainers/README.md | 2 +- 9 files changed, 43 insertions(+), 43 deletions(-) rename docs/design/{architecture.md => architecture/README.md} (94%) diff --git a/docs/README.md b/docs/README.md index f5fd38eef760..7eb65a210c12 100644 --- a/docs/README.md +++ b/docs/README.md @@ -41,7 +41,7 @@ Documents that help to understand and contribute to Kata Containers. ### Design and Implementations -* [Kata Containers Architecture](design/architecture.md): Architectural overview of Kata Containers +* [Kata Containers Architecture](design/architecture): Architectural overview of Kata Containers * [Kata Containers E2E Flow](design/end-to-end-flow.md): The entire end-to-end flow of Kata Containers * [Kata Containers design](./design/README.md): More Kata Containers design documents * [Kata Containers threat model](./threat-model/threat-model.md): Kata Containers threat model diff --git a/docs/Upgrading.md b/docs/Upgrading.md index ef633fe68fc8..0403b91beab7 100644 --- a/docs/Upgrading.md +++ b/docs/Upgrading.md @@ -114,7 +114,7 @@ with containerd. > kernel or image. If you are using custom -[guest assets](design/architecture.md#guest-assets), +[guest assets](design/architecture/README.md#guest-assets), you must upgrade them to work with Kata Containers 2.x since Kata Containers 1.x assets will **not** work. diff --git a/docs/design/README.md b/docs/design/README.md index 1a334453edd9..775f4d4c9ff8 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -2,7 +2,7 @@ Kata Containers design documents: -- [Kata Containers architecture](architecture.md) +- [Kata Containers architecture](architecture) - [API Design of Kata Containers](kata-api-design.md) - [Design requirements for Kata Containers](kata-design-requirements.md) - [VSocks](VSocks.md) diff --git a/docs/design/architecture.md b/docs/design/architecture/README.md similarity index 94% rename from docs/design/architecture.md rename to docs/design/architecture/README.md index 1281a2e367d2..296276a7b150 100644 --- a/docs/design/architecture.md +++ b/docs/design/architecture/README.md @@ -9,8 +9,8 @@ stronger [workload](#workload) isolation using hardware [virtualization](#virtualization) technology as a second layer of defence. -Kata Containers runs on [multiple architectures](../../src/runtime/README.md#platform-support) -and supports [multiple hypervisors](../hypervisors.md). +Kata Containers runs on [multiple architectures](../../../src/runtime/README.md#platform-support) +and supports [multiple hypervisors](../../hypervisors.md). This document is a summary of the Kata Containers architecture. @@ -19,11 +19,11 @@ This document is a summary of the Kata Containers architecture. For details on how Kata Containers maps container concepts to VM technologies, and how this is realized in the multiple hypervisors and VMMs that Kata supports see the -[virtualization documentation](./virtualization.md). +[virtualization documentation](../virtualization.md). ## Compatibility -The [Kata Containers runtime](../../src/runtime) is compatible with +The [Kata Containers runtime](../../../src/runtime) is compatible with the [OCI](https://github.com/opencontainers) [runtime specification](https://github.com/opencontainers/runtime-spec) and therefore works seamlessly with the @@ -104,7 +104,7 @@ available. The diagram below shows how the original architecture was simplified with the advent of shimv2. -![Kubernetes integration with shimv2](arch-images/shimv2.svg) +![Kubernetes integration with shimv2](../arch-images/shimv2.svg) ## Root filesystem @@ -370,14 +370,14 @@ runtime cleans up the environment (which includes terminating the > **Note:** > -> When [agent tracing is enabled](../tracing.md#agent-shutdown-behaviour), +> When [agent tracing is enabled](../../tracing.md#agent-shutdown-behaviour), > the shutdown behaviour is different. #### Container manager requested shutdown If the container manager requests the container be deleted, the [runtime](#runtime) will signal the agent by sending it a -`DestroySandbox` [ttRPC API](../../src/agent/protocols/protos/agent.proto) request. +`DestroySandbox` [ttRPC API](../../../src/agent/protocols/protos/agent.proto) request. ## Guest assets @@ -388,7 +388,7 @@ small root filesystem image to boot the VM. ### Guest kernel -The [guest kernel](../../tools/packaging/kernel) +The [guest kernel](../../../tools/packaging/kernel) is passed to the hypervisor and used to boot the VM. The default kernel provided in Kata Containers is highly optimized for kernel boot time and minimal memory footprint, providing only those @@ -400,9 +400,9 @@ Linux LTS (Long Term Support) [kernel](https://www.kernel.org). The hypervisor uses an image file which provides a minimal root filesystem used by the guest kernel to boot the VM and host the Kata Container. Kata Containers supports both initrd and rootfs based -minimal guest images. The [default packages](../install/) provide both +minimal guest images. The [default packages](../../install/) provide both an image and an initrd, both of which are created using the -[`osbuilder`](../../tools/osbuilder) tool. +[`osbuilder`](../../../tools/osbuilder) tool. > **Notes:** > @@ -419,12 +419,12 @@ an image and an initrd, both of which are created using the > Fedora or any other distribution potentially. > > The `osbuilder` tool provides -> [configurations for various common Linux distributions](../../tools/osbuilder/rootfs-builder) +> [configurations for various common Linux distributions](../../../tools/osbuilder/rootfs-builder) > which can be built into either initrd or rootfs guest images. > > - If you are using a [packaged version of Kata -> Containers](../install), you can see image details by running the -> [`kata-collect-data.sh`](../../src/runtime/data/kata-collect-data.sh.in) +> Containers](../../install), you can see image details by running the +> [`kata-collect-data.sh`](../../../src/runtime/data/kata-collect-data.sh.in) > script as `root` and looking at the "Image details" section of the > output. @@ -468,7 +468,7 @@ See also the [process overview](#process-overview). > - The container workload is running inside a full container > environment which itself is running within a VM environment. > -> - See the [configuration files for the `osbuilder` tool](../../tools/osbuilder/rootfs-builder) +> - See the [configuration files for the `osbuilder` tool](../../../tools/osbuilder/rootfs-builder) > for details of the default distribution for platforms other than > Intel x86_64. @@ -520,18 +520,18 @@ See also the [process overview](#process-overview). See also: -- The [osbuilder](../../tools/osbuilder) tool +- The [osbuilder](../../../tools/osbuilder) tool This is used to build all default image types. -- The [versions database](../../versions.yaml) +- The [versions database](../../../versions.yaml) The `default-image-name` and `default-initrd-name` options specify the default distributions for each image type. ## Hypervisor -The [hypervisor](../hypervisors.md) specified in the +The [hypervisor](../../hypervisors.md) specified in the [configuration file](#configuration) creates a VM to host the [agent](#agent) and the [workload](#workload) inside the [container environment](#environments). @@ -548,7 +548,7 @@ The [hypervisor](../hypervisors.md) specified in the ## Agent -The Kata Containers agent ([`kata-agent`](../../src/agent)), written +The Kata Containers agent ([`kata-agent`](../../../src/agent)), written in the [Rust programming language](https://www.rust-lang.org), is a long running process that runs inside the VM. It acts as the supervisor for managing the containers and the [workload](#workload) @@ -560,7 +560,7 @@ for each VM created. The agent communicates with the other Kata components (primarily the [runtime](#runtime)) using a [`ttRPC`](https://github.com/containerd/ttrpc-rust) based -[protocol](../../src/agent/protocols/protos). +[protocol](../../../src/agent/protocols/protos). > **Note:** > @@ -572,7 +572,7 @@ The agent communicates with the other Kata components (primarily the ## Runtime -The Kata Containers runtime (the [`containerd-shim-kata-v2`](../../src/runtime/cmd/containerd-shim-kata-v2 +The Kata Containers runtime (the [`containerd-shim-kata-v2`](../../../src/runtime/cmd/containerd-shim-kata-v2 ) binary) is a [shimv2](#shim-v2-architecture) compatible runtime. > **Note:** @@ -583,7 +583,7 @@ The Kata Containers runtime (the [`containerd-shim-kata-v2`](../../src/runtime/c > shim v2 API. The runtime makes heavy use of the [`virtcontainers` -package](../../src/runtime/virtcontainers), which provides a generic, +package](../../../src/runtime/virtcontainers), which provides a generic, runtime-specification agnostic, hardware-virtualized containers library. @@ -616,13 +616,13 @@ The `exec` command allows an administrator or developer to enter the [VM root environment](#environments) which is not accessible by the container [workload](#workload). -See [the developer guide](../Developer-Guide.md#connect-to-debug-console) for further details. +See [the developer guide](../../Developer-Guide.md#connect-to-debug-console) for further details. ### Configuration -See the [configuration file details](../../src/runtime/README.md#configuration). +See the [configuration file details](../../../src/runtime/README.md#configuration). -The configuration file is also used to enable runtime [debug output](../Developer-Guide.md#enable-full-debug). +The configuration file is also used to enable runtime [debug output](../../Developer-Guide.md#enable-full-debug). ## Process overview @@ -656,7 +656,7 @@ To overcome incompatibility between typical container engines expectations and virtual machines, Kata Containers networking transparently connects `veth` interfaces with `TAP` ones using Traffic Control: -![Kata Containers networking](arch-images/network.png) +![Kata Containers networking](../arch-images/network.png) With a TC filter in place, a redirection is created between the container network and the virtual machine. As an example, the CNI may create a device, `eth0`, in the container's network @@ -681,7 +681,7 @@ remove a guest network endpoint and to manipulate the guest route table. The following diagram illustrates the Kata Containers network hotplug workflow. -![Network Hotplug](arch-images/kata-containers-network-hotplug.png) +![Network Hotplug](../arch-images/kata-containers-network-hotplug.png) ## Storage @@ -761,8 +761,8 @@ Kata Containers is an officially supported CRI-O and containerd runtime. Refer to the following guides on how to set up Kata Containers with Kubernetes: -- [How to use Kata Containers and containerd](../how-to/containerd-kata.md) -- [Run Kata Containers with Kubernetes](../how-to/run-kata-with-k8s.md) +- [How to use Kata Containers and containerd](../../how-to/containerd-kata.md) +- [Run Kata Containers with Kubernetes](../../how-to/run-kata-with-k8s.md) #### OCI annotations @@ -792,11 +792,11 @@ with a Kubernetes pod: With `RuntimeClass`, users can define Kata Containers as a `RuntimeClass` and then explicitly specify that a pod must be created as a Kata Containers pod. For details, please refer to [How to use -Kata Containers and containerd](../../docs/how-to/containerd-kata.md). +Kata Containers and containerd](../../../docs/how-to/containerd-kata.md). ## Tracing -The [tracing document](../tracing.md) provides details on the tracing +The [tracing document](../../tracing.md) provides details on the tracing architecture. # Appendices @@ -846,19 +846,19 @@ more traditional VM file and device mapping mechanisms: - Utilizing `mmap(2)`'s `MAP_SHARED` shared memory option on the host allows the host to efficiently share pages. -![DAX](arch-images/DAX.png) +![DAX](../arch-images/DAX.png) For further details of the use of NVDIMM with QEMU, see the [QEMU project documentation](https://www.qemu.org). ## Agent control tool -The [agent control tool](../../src/tools/agent-ctl) is a test and +The [agent control tool](../../../src/tools/agent-ctl) is a test and development tool that can be used to learn more about a Kata Containers system. ## Terminology -See the [project glossary](../../Glossary.md). +See the [project glossary](../../../Glossary.md). -[debug-console]: ../Developer-Guide.md#connect-to-debug-console +[debug-console]: ../../Developer-Guide.md#connect-to-debug-console diff --git a/docs/design/virtualization.md b/docs/design/virtualization.md index eab3d6602a3c..75ec62bf46b5 100644 --- a/docs/design/virtualization.md +++ b/docs/design/virtualization.md @@ -41,7 +41,7 @@ Kata Containers with QEMU has complete compatibility with Kubernetes. Depending on the host architecture, Kata Containers supports various machine types, for example `pc` and `q35` on x86 systems, `virt` on ARM systems and `pseries` on IBM Power systems. The default Kata Containers machine type is `pc`. The machine type and its [`Machine accelerators`](#machine-accelerators) can -be changed by editing the runtime [`configuration`](./architecture.md/#configuration) file. +be changed by editing the runtime [`configuration`](architecture/README.md#configuration) file. Devices and features used: - virtio VSOCK or virtio serial diff --git a/snap/README.md b/snap/README.md index 1114315befa4..3729542ecd78 100644 --- a/snap/README.md +++ b/snap/README.md @@ -76,7 +76,7 @@ then a new configuration file can be [created](#configure-kata-containers) and [configured][7]. [1]: https://docs.snapcraft.io/snaps/intro -[2]: ../docs/design/architecture.md#root-filesystem-image +[2]: ../docs/design/architecture/README.md#root-filesystem-image [3]: https://docs.snapcraft.io/reference/confinement#classic [4]: https://github.com/kata-containers/runtime#configuration [5]: https://docs.docker.com/engine/reference/commandline/dockerd diff --git a/src/agent/README.md b/src/agent/README.md index 98ec59bbdf7e..24161cebed68 100644 --- a/src/agent/README.md +++ b/src/agent/README.md @@ -6,14 +6,14 @@ The Kata agent is a long running process that runs inside the Virtual Machine (VM) (also known as the "pod" or "sandbox"). The agent is packaged inside the Kata Containers -[guest image](../../docs/design/architecture.md#guest-image) +[guest image](../../docs/design/architecture/README.md#guest-image) which is used to boot the VM. Once the runtime has launched the configured [hypervisor](../../docs/hypervisors.md) to create a new VM, the agent is started. From this point on, the agent is responsible for creating and managing the life cycle of the containers inside the VM. For further details, see the -[architecture document](../../docs/design/architecture.md). +[architecture document](../../docs/design/architecture). ## Audience diff --git a/src/runtime/README.md b/src/runtime/README.md index 2a893681f1c2..c7de965445b6 100644 --- a/src/runtime/README.md +++ b/src/runtime/README.md @@ -70,7 +70,7 @@ See the ## Architecture overview -See the [architecture overview](../../docs/design/architecture.md) +See the [architecture overview](../../docs/design/architecture) for details on the Kata Containers design. ## Configuration diff --git a/src/runtime/virtcontainers/README.md b/src/runtime/virtcontainers/README.md index 97f01cfb9193..bd090b65d6a2 100644 --- a/src/runtime/virtcontainers/README.md +++ b/src/runtime/virtcontainers/README.md @@ -135,7 +135,7 @@ There are three drawbacks about using CNM instead of CNI: # Storage -See [Kata Containers Architecture](../../../docs/design/architecture.md#storage). +See [Kata Containers Architecture](../../../docs/design/architecture/README.md#storage). # Devices