diff --git a/docs/design/arch-images/guest-image-management-architecture.png b/docs/design/arch-images/guest-image-management-architecture.png deleted file mode 100644 index 83ab0f022..000000000 Binary files a/docs/design/arch-images/guest-image-management-architecture.png and /dev/null differ diff --git a/docs/design/arch-images/guest-image-management-details.png b/docs/design/arch-images/guest-image-management-details.png deleted file mode 100644 index d58afe71a..000000000 Binary files a/docs/design/arch-images/guest-image-management-details.png and /dev/null differ diff --git a/docs/design/kata-guest-image-management-design.md b/docs/design/kata-guest-image-management-design.md index 160cf5321..a68a0db6e 100644 --- a/docs/design/kata-guest-image-management-design.md +++ b/docs/design/kata-guest-image-management-design.md @@ -49,13 +49,58 @@ Pull the container image directly from the guest VM using `nydus snapshotter` ba #### Architecture The following diagram provides an overview of the architecture for pulling image in the guest with key components. -![guest-image-management-architecture](arch-images/guest-image-management-architecture.png) +```mermaid +flowchart LR + Kubelet[kubelet]--> |1\. Pull image request & metadata|Containerd + Containerd-->|2\. Pull image metadata| E + Containerd-->Snapshotter[Nydus Snapshotter] + Snapshotter-->|3\. Pack image info| Containerd + Containerd-->Runtime[Kata Runtime] + Runtime-->Hypervisor + Hypervisor-->TEE + Runtime-->|4\. Pass image info to VM| Agent + CDH1-->|6\. Pull image with image info|E[Container Images Registry] + subgraph TEE [Virtual Machine] + Images[Container Images]-->|7\. Prepare container rootfs|H[Container] + + subgraph CDH [Confidential Data Hub] + CDH1[Image Mgmt] + end + + CDH-->Images + Agent[Kata Agent]-->|5\. Call image pull RPC|CDH + end +``` #### Sequence diagrams The following sequence diagram depicted below offers a detailed overview of the messages/calls exchanged to pull an unencrypted unsigned image from an unauthenticated container registry. This involves the kata-runtime, kata-agent, and the guest-components’ image-rs to use the guest pull mechanism. -![guest-image-management-details](arch-images/guest-image-management-details.png) +```mermaid +sequenceDiagram + par Hosts Side + Containerd/Kubelet->>runtime.kata_agent: createContainer(ctx,sandbox,c) + runtime.kata_agent->>runtime.fs_share_linux: ShareRootFilesystem(ctx,c) + runtime.fs_share_linux->>runtime.kata_agent: handleVirtualVolumeStorageObject(c,...,KataVolumeType) + runtime.kata_agent->>runtime.kata_agent: handleImageGuestPullBlockVolume(c,virtVolume,vol) + runtime.kata_agent->>runtime.fs_share_linux: ret:storage + runtime.fs_share_linux->>runtime.kata_agent: ret:sharedFile + and Guest Side + runtime.kata_agent->>agent.rpc: CreateContainerRequest(cid,...,storages,...,oci,...) + agent.rpc->>agent.storage: add_storage(storages...) + agent.storage->>agent.storage: StorageHandler.handler(driver) + agent.storage->>agent.storage.StorageHandler.ImagePullHandler: create_device(storage) + agent.storage.StorageHandler.ImagePullHandler->>agent.confidential_data_hub: pull_image(img,cid,img_metadata) + agent.confidential_data_hub->>Confidential Data Hub: pull_image(img,bundle_path) + Confidential Data Hub->>agent.confidential_data_hub: ret + agent.confidential_data_hub->>agent.storage.StorageHandler.ImagePullHandler: ret: bundle_path + agent.storage.StorageHandler.ImagePullHandler->>agent.storage: ret: device + agent.storage->>agent.rpc: ret: mount_list + and Return + agent.rpc->>runtime.kata_agent: ret: ok + runtime.kata_agent->>Containerd/Kubelet: ret: ok + end +``` First and foremost, the guest pull code path is only activated when `nydus snapshotter` requires the handling of a volume which type is `image_guest_pull`, as can be seen on the message below: ```json @@ -108,10 +153,10 @@ Below is an example of storage information packaged in the message sent to the k ``` Next, the kata-agent's RPC module will handle the create container request which, among other things, involves adding storages to the sandbox. The storage module contains implementations of `StorageHandler` interface for various storage types, being the `ImagePullHandler` in charge of handling the storage object for the container image (the storage manager instantiates the handler based on the value of the "driver"). -`ImagePullHandler` delegates the image pulling operation to the `ImageService.pull_image()` that is going to create the image's bundle directory on the guest filesystem and, in turn, class the image-rs to in fact fetch and uncompress the image's bundle. +`ImagePullHandler` delegates the image pulling operation to the `confidential_data_hub.pull_image()` that is going to create the image's bundle directory on the guest filesystem and, in turn, the `ImagePullService` of Confidential Data Hub to fetch, uncompress and mount the image's rootfs. > **Notes:** -> In this flow, `ImageService.pull_image()` parses the image metadata, looking for either the `io.kubernetes.cri.container-type: sandbox` or `io.kubernetes.cri-o.ContainerType: sandbox` (CRI-IO case) annotation, then it never calls the `image-rs.pull_image()` because the pause image is expected to already be inside the guest's filesystem, so instead `ImageService.unpack_pause_image()` is called. +> In this flow, `confidential_data_hub.pull_image()` parses the image metadata, looking for either the `io.kubernetes.cri.container-type: sandbox` or `io.kubernetes.cri-o.ContainerType: sandbox` (CRI-IO case) annotation, then it never calls the `pull_image()` RPC of Confidential Data Hub because the pause image is expected to already be inside the guest's filesystem, so instead `confidential_data_hub.unpack_pause_image()` is called. ## Using guest image pull with `nerdctl` @@ -121,6 +166,6 @@ nerdctl run --runtime io.containerd.kata.v2 --snapshotter nydus --label io.kuber ``` References: -[1] [[RFC] Image management proposal for hosting sharing and peer pods](https://github.com/confidential-containers/confidential-containers/issues/137) -[2] https://github.com/containerd/containerd/blob/main/docs/content-flow.md - +1. [[RFC] Image management proposal for hosting sharing and peer pods](https://github.com/confidential-containers/confidential-containers/issues/137) +2. https://github.com/containerd/containerd/blob/main/docs/content-flow.md +3. [Move guest pull ability to a configurable component](https://github.com/kata-containers/kata-containers/issues/9266)