mirror of
https://github.com/kata-containers/kata-containers.git
synced 2025-07-05 11:36:56 +00:00
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:
parent
105cb47991
commit
44a6d1a6f7
Binary file not shown.
Before Width: | Height: | Size: 61 KiB |
Binary file not shown.
Before Width: | Height: | Size: 122 KiB |
@ -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.
|
||||

|
||||
```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.
|
||||
|
||||

|
||||
```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)
|
||||
|
Loading…
Reference in New Issue
Block a user