docs: update guest pull document

After moving guest pull abilities to CDH, the document of guest pull
should be updated due to new workflow.

Also, replace the diagram of PNG into a mermaid one for better
maintaince.

Signed-off-by: Xynnn007 <xynnn@linux.alibaba.com>
This commit is contained in:
Xynnn007 2025-04-27 13:48:07 +08:00
parent 105cb47991
commit 44a6d1a6f7
3 changed files with 52 additions and 7 deletions

Binary file not shown.

Before

Width:  |  Height:  |  Size: 61 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 122 KiB

View File

@ -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)