github/kata-containers
1
0
Fork 1
mirror of https://github.com/kata-containers/kata-containers.git synced 2025-04-29 20:24:31 +00:00
Code Issues Projects Releases Wiki Activity

docs: Move arch doc to separate directory

Browse Source 
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 <james.o.hunt@intel.com>
This commit is contained in:
James O. D. Hunt 2021-12-15 17:44:24 +00:00
parent 32d62c85c2
commit 6f9efb4043
9 changed files with 43 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/README.md
View File

@ -41,7 +41,7 @@ Documents that help to understand and contribute to Kata Containers.
### Design and Implementations ### 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 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 design](./design/README.md): More Kata Containers design documents
* [Kata Containers threat model](./threat-model/threat-model.md): Kata Containers threat model * [Kata Containers threat model](./threat-model/threat-model.md): Kata Containers threat model

2
docs/Upgrading.md
View File

@ -114,7 +114,7 @@ with containerd.
> kernel or image. > kernel or image.
If you are using custom 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 you must upgrade them to work with Kata Containers 2.x since Kata
Containers 1.x assets will **not** work. Containers 1.x assets will **not** work.

2
docs/design/README.md
View File

@ -2,7 +2,7 @@
Kata Containers design documents: Kata Containers design documents:
- [Kata Containers architecture](architecture.md) - [Kata Containers architecture](architecture)
- [API Design of Kata Containers](kata-api-design.md) - [API Design of Kata Containers](kata-api-design.md)
- [Design requirements for Kata Containers](kata-design-requirements.md) - [Design requirements for Kata Containers](kata-design-requirements.md)
- [VSocks](VSocks.md) - [VSocks](VSocks.md)

68
docs/design/architecture.md → docs/design/architecture/README.md
View File

@ -9,8 +9,8 @@ stronger [workload](#workload) isolation using hardware
[virtualization](#virtualization) technology as a second layer of [virtualization](#virtualization) technology as a second layer of
defence. defence.
Kata Containers runs on [multiple architectures](../../src/runtime/README.md#platform-support) Kata Containers runs on [multiple architectures](../../../src/runtime/README.md#platform-support)
and supports [multiple hypervisors](../hypervisors.md). and supports [multiple hypervisors](../../hypervisors.md).
This document is a summary of the Kata Containers architecture. 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 For details on how Kata Containers maps container concepts to VM
technologies, and how this is realized in the multiple hypervisors and technologies, and how this is realized in the multiple hypervisors and
VMMs that Kata supports see the VMMs that Kata supports see the
[virtualization documentation](./virtualization.md). [virtualization documentation](../virtualization.md).
## Compatibility ## 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) the [OCI](https://github.com/opencontainers)
[runtime specification](https://github.com/opencontainers/runtime-spec) [runtime specification](https://github.com/opencontainers/runtime-spec)
and therefore works seamlessly with the and therefore works seamlessly with the
@ -104,7 +104,7 @@ available.
The diagram below shows how the original architecture was simplified The diagram below shows how the original architecture was simplified
with the advent of shimv2. with the advent of shimv2.
![Kubernetes integration with shimv2](arch-images/shimv2.svg) ![Kubernetes integration with shimv2](../arch-images/shimv2.svg)
## Root filesystem ## Root filesystem
@ -370,14 +370,14 @@ runtime cleans up the environment (which includes terminating the
> **Note:** > **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. > the shutdown behaviour is different.
#### Container manager requested shutdown #### Container manager requested shutdown
If the container manager requests the container be deleted, the If the container manager requests the container be deleted, the
[runtime](#runtime) will signal the agent by sending it a [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 ## Guest assets
@ -388,7 +388,7 @@ small root filesystem image to boot the VM.
### Guest kernel ### 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. is passed to the hypervisor and used to boot the VM.
The default kernel provided in Kata Containers is highly optimized for The default kernel provided in Kata Containers is highly optimized for
kernel boot time and minimal memory footprint, providing only those 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 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 filesystem used by the guest kernel to boot the VM and host the Kata
Container. Kata Containers supports both initrd and rootfs based 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 an image and an initrd, both of which are created using the
[`osbuilder`](../../tools/osbuilder) tool. [`osbuilder`](../../../tools/osbuilder) tool.
> **Notes:** > **Notes:**
> >
@ -419,12 +419,12 @@ an image and an initrd, both of which are created using the
> Fedora or any other distribution potentially. > Fedora or any other distribution potentially.
> >
> The `osbuilder` tool provides > 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. > which can be built into either initrd or rootfs guest images.
> >
> - If you are using a [packaged version of Kata > - If you are using a [packaged version of Kata
> Containers](../install), you can see image details by running the > Containers](../../install), you can see image details by running the
> [`kata-collect-data.sh`](../../src/runtime/data/kata-collect-data.sh.in) > [`kata-collect-data.sh`](../../../src/runtime/data/kata-collect-data.sh.in)
> script as `root` and looking at the "Image details" section of the > script as `root` and looking at the "Image details" section of the
> output. > output.
@ -468,7 +468,7 @@ See also the [process overview](#process-overview).
> - The container workload is running inside a full container > - The container workload is running inside a full container
> environment which itself is running within a VM environment. > 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 > for details of the default distribution for platforms other than
> Intel x86_64. > Intel x86_64.
@ -520,18 +520,18 @@ See also the [process overview](#process-overview).
See also: See also:
- The [osbuilder](../../tools/osbuilder) tool - The [osbuilder](../../../tools/osbuilder) tool
This is used to build all default image types. 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-image-name` and `default-initrd-name` options specify
the default distributions for each image type. the default distributions for each image type.
## Hypervisor ## Hypervisor
The [hypervisor](../hypervisors.md) specified in the The [hypervisor](../../hypervisors.md) specified in the
[configuration file](#configuration) creates a VM to host the [configuration file](#configuration) creates a VM to host the
[agent](#agent) and the [workload](#workload) inside the [agent](#agent) and the [workload](#workload) inside the
[container environment](#environments). [container environment](#environments).
@ -548,7 +548,7 @@ The [hypervisor](../hypervisors.md) specified in the
## Agent ## 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 in the [Rust programming language](https://www.rust-lang.org), is a
long running process that runs inside the VM. It acts as the long running process that runs inside the VM. It acts as the
supervisor for managing the containers and the [workload](#workload) 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 The agent communicates with the other Kata components (primarily the
[runtime](#runtime)) using a [runtime](#runtime)) using a
[`ttRPC`](https://github.com/containerd/ttrpc-rust) based [`ttRPC`](https://github.com/containerd/ttrpc-rust) based
[protocol](../../src/agent/protocols/protos). [protocol](../../../src/agent/protocols/protos).
> **Note:** > **Note:**
> >
@ -572,7 +572,7 @@ The agent communicates with the other Kata components (primarily the
## Runtime ## 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. ) binary) is a [shimv2](#shim-v2-architecture) compatible runtime.
> **Note:** > **Note:**
@ -583,7 +583,7 @@ The Kata Containers runtime (the [`containerd-shim-kata-v2`](../../src/runtime/c
> shim v2 API. > shim v2 API.
The runtime makes heavy use of the [`virtcontainers` 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 runtime-specification agnostic, hardware-virtualized containers
library. 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 [VM root environment](#environments) which is not accessible by the container
[workload](#workload). [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 ### 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 ## Process overview
@ -656,7 +656,7 @@ To overcome incompatibility between typical container engines expectations
and virtual machines, Kata Containers networking transparently connects `veth` and virtual machines, Kata Containers networking transparently connects `veth`
interfaces with `TAP` ones using Traffic Control: 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 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 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. 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 ## 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 runtime. Refer to the following guides on how to set up Kata
Containers with Kubernetes: Containers with Kubernetes:
- [How to use Kata Containers and containerd](../how-to/containerd-kata.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) - [Run Kata Containers with Kubernetes](../../how-to/run-kata-with-k8s.md)
#### OCI annotations #### OCI annotations
@ -792,11 +792,11 @@ with a Kubernetes pod:
With `RuntimeClass`, users can define Kata Containers as a With `RuntimeClass`, users can define Kata Containers as a
`RuntimeClass` and then explicitly specify that a pod must be created `RuntimeClass` and then explicitly specify that a pod must be created
as a Kata Containers pod. For details, please refer to [How to use 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 ## Tracing
The [tracing document](../tracing.md) provides details on the tracing The [tracing document](../../tracing.md) provides details on the tracing
architecture. architecture.
# Appendices # 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 - Utilizing `mmap(2)`'s `MAP_SHARED` shared memory option on the host
allows the host to efficiently share pages. 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 For further details of the use of NVDIMM with QEMU, see the [QEMU
project documentation](https://www.qemu.org). project documentation](https://www.qemu.org).
## Agent control tool ## 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 development tool that can be used to learn more about a Kata
Containers system. Containers system.
## Terminology ## 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

2
docs/design/virtualization.md
View File

@ -41,7 +41,7 @@ Kata Containers with QEMU has complete compatibility with Kubernetes.
Depending on the host architecture, Kata Containers supports various machine types, 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 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 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: Devices and features used:
- virtio VSOCK or virtio serial - virtio VSOCK or virtio serial

2
snap/README.md
View File

@ -76,7 +76,7 @@ then a new configuration file can be [created](#configure-kata-containers)
and [configured][7]. and [configured][7].
[1]: https://docs.snapcraft.io/snaps/intro [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 [3]: https://docs.snapcraft.io/reference/confinement#classic
[4]: https://github.com/kata-containers/runtime#configuration [4]: https://github.com/kata-containers/runtime#configuration
[5]: https://docs.docker.com/engine/reference/commandline/dockerd [5]: https://docs.docker.com/engine/reference/commandline/dockerd

4
src/agent/README.md
View File

@ -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"). (VM) (also known as the "pod" or "sandbox").
The agent is packaged inside the Kata Containers 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 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 [hypervisor](../../docs/hypervisors.md) to create a new VM, the agent is
started. From this point on, the agent is responsible for creating and started. From this point on, the agent is responsible for creating and
managing the life cycle of the containers inside the VM. managing the life cycle of the containers inside the VM.
For further details, see the For further details, see the
[architecture document](../../docs/design/architecture.md). [architecture document](../../docs/design/architecture).
## Audience ## Audience

2
src/runtime/README.md
View File

@ -70,7 +70,7 @@ See the
## Architecture overview ## Architecture overview
See the [architecture overview](../../docs/design/architecture.md) See the [architecture overview](../../docs/design/architecture)
for details on the Kata Containers design. for details on the Kata Containers design.
## Configuration ## Configuration

2
src/runtime/virtcontainers/README.md
View File

@ -135,7 +135,7 @@ There are three drawbacks about using CNM instead of CNI:
# Storage # Storage
See [Kata Containers Architecture](../../../docs/design/architecture.md#storage). See [Kata Containers Architecture](../../../docs/design/architecture/README.md#storage).
# Devices # Devices