KubeEdge Image PrePull Feature Guide Document

docs/Image-PrePull-Feature-Enhancement-Instruction-Document/Instruction-Document.md

@@ -0,0 +1,157 @@
+# KubeEdge Image PrePull Feature Guide Document
+
+KubeEdge version 1.16 introduces a new feature called Image Pre-Pull, which allows users to load images ahead of time on edge nodes through the Kubernetes API of ImagePrePullJob. This feature supports pre-pull multiple images in batches across multiple edge nodes or node groups, helping to reduce the failure rates and inefficiencies associated with loading images during application deployment or updates, especially in large-scale scenarios.
+
+API example for pre-pull mirror image：
+
+```
+apiVersion: operations.kubeedge.io/v1alpha1
+kind: ImagePrePullJob
+metadata:
+ name: imageprepull-example
+ labels:
+ description:ImagePrePullLabel
+spec:
+ imagePrePullTemplate：
+ images:
+ - image1
+ - image2
+ nodes：
+ - edgenode1
+ - edgenode2
+ checkItems:
+ - "disk"
+ failureTolerate: "0.3"
+ concurrency: 2
+ timeoutSeconds: 180
+ retryTimes: 1
+ 
+```
+
+
+## 1. Preparation
+
+**Example：Nginx Demo**
+
+Nginx is a lightweight image that allows users to demonstrate it without any prerequisite environment. Nginx image will be uploaded to a private image repository in advance. Users can call the pre-pull function API from the cloud to pre-pull the Nginx image to edge nodes from the private image repository.
+
+**1）This example requires KubeEdge version to be v1.16.0 or above, and Kubernetes version to be v1.27.0 or above. The selected version is KubeEdge v1.16.0 and Kubernetes version is v1.27.3.**
+
+```
+[root@ke-cloud ~]# kubectl get node
+NAME STATUS ROLES AGE VERSION
+cloud.kubeedge Ready control-plane,master 3d v1.27.3
+edge.kubeedge Ready agent,edge 2d v1.27.7-kubeedge-v1.16.0
+
+Note: The following verification will use the edge node edge.kubeedge. If you refer to this article for related verification, the configuration of the edge node name in subsequent steps needs to be changed according to your actual situation.
+```
+
+**2）Ensure that the K8s apiserver has the following configuration enabled**
+
+
+```
+ taskManager:
+ enable: true // 由false修改为true
+```
+changes can be made by editing the file kubectl edit configmap cloudcore -n kubeedge with commands, and restarting the cloudcore component of the K8s apiserver.
+
+**3）Preparing Sample Code **
+
+yaml file example code
+```
+apiVersion: operations.kubeedge.io/v1alpha1
+kind: ImagePrePullJob
+metadata:
+ name: imageprepull-example
+spec:
+ imagePrePullTemplate:
+ concurrency: 1
+ failureTolerate: '0.1'
+ images:
+ - test:nginx
+ nodeNames:
+ - edge.kubeedge
+ imageSecrets: default/secret
+ retryTimes: 1
+ timeoutSeconds: 120
+
+```
+
+## 2. Prepare the image and Secret for the private image repository
+Here is a private image repository prepared for demonstration purposes using Alibaba Cloud's registry URL: registry.cn-hangzhou.aliyuncs.com. The demo space used is jilimoxing, and modifications may be necessary based on actual circumstances during the actual operation.
+
+**1）Pushing nginx into the private image repository**
+
+```
+[root@cloud ~]# docker tag nginx registry.cn-hangzhou.aliyuncs.com/jilimoxing/test:nginx
+[root@cloud crds~]# docker push registry.cn-hangzhou.aliyuncs.com/jilimoxing/test:nginx
+```
+
+**2）Create a Secret on the cloud**
+
+Using Kubectl create secret docker-registry to generate a secret for a private image repository, modify it according to your actual situation.
+
+```
+[root@cloud ~]# kubectl create secret docker-registry my-secret \
+ --docker-server=registry.cn-hangzhou.aliyuncs.com \
+ --docker-username=23021*****@qq.com \
+ --docker-password=Xy***** \
+ --docker-email=23021*****@qq.com
+
+[root@cloud ~]# kubectl get secret -A
+NAMESPACE NAME TYPE DATA AGE
+default my-secret kubernetes.io/dockerconfigjson 1 31s
+
+```
+
+## 3. Create Yaml File
+
+**1）Modify Code**
+
+To create a yaml file on a cloud node, you need to modify the corresponding images information and imageSecrets information to keep them consistent with the pre-pull image repository secret. The information should be as follows:
+```
+
+[root@ke-cloud ~]# vim imageprepull.yaml
+
+apiVersion: operations.kubeedge.io/v1alpha1
+kind: ImagePrePullJob
+metadata:
+ name: imageprepull-example
+spec:
+ imagePrePullTemplate:
+ concurrency: 1
+ failureTolerate: '0.1'
+ images:
+ - registry.cn-hangzhou.aliyuncs.com/jilimoxing/test:nginx
+ nodeNames:
+ - edge.kubeedge
+ imageSecrets: default/my-secret
+ retryTimes: 1
+ timeoutSeconds: 120
+
+```
+
+**2）executable file**
+
+
+```
+[root@ke-cloud ~]# kubectl apply -f imageprepull.yaml
+```
+
+
+## 4. Check if the edge node image has been pre-pull successfully
+
+Enter the edge terminal and use the command ctr -n k8s.io i ls to view.
+```
+[root@edge ~]# ctr -n k8s.io i ls
+```
+The corresponding image has been successfully pre-pull.
+```
+REF TYPE DIGEST SIZE PLATFORMS LABELS 
+registry.cn-hangzhou.aliyuncs.com/jilimoxing/test:nginx application/vnd.docker.distribution.manifest.v2+json sha256:73e957703f1266530db0aeac1fd6a3f87c1e59943f4c13eb340bb8521c6041d7 67.3 MiB linux/amd64 
+```
+
+## 5. Other
+
+**1）For more official KubeEdge examples, please refer to https://github.com/kubeedge/examples**
+

i18n/zh/docusaurus-plugin-content-docs/current/Image-PrePull-Feature-Enhancement-Instruction-Document/Instruction-Document.md

@@ -0,0 +1,156 @@
+# KubeEdge 镜像预加载功能指导文档
+
+KubeEdge 1.16版本引入了镜像预下载新特性，用户可以通过ImagePrePullJob的Kubernetes API提前在边缘节点上加载镜像，该特性支持在批量边缘节点或节点组中预下载多个镜像，帮助减少加载镜像在应用部署或更新过程，尤其是大规模场景中，带来的失败率高、效率低下等问题。
+
+镜像预下载API示例：
+
+```
+apiVersion: operations.kubeedge.io/v1alpha1
+kind: ImagePrePullJob
+metadata:
+ name: imageprepull-example
+ labels:
+ description:ImagePrePullLabel
+spec:
+ imagePrePullTemplate：
+ images:
+ - image1
+ - image2
+ nodes：
+ - edgenode1
+ - edgenode2
+ checkItems:
+ - "disk"
+ failureTolerate: "0.3"
+ concurrency: 2
+ timeoutSeconds: 180
+ retryTimes: 1
+ 
+```
+
+
+## 1. 准备工作
+
+**选用示例：Nginx Demo**
+
+nginx是一个轻量级镜像，用户无需任何环境即可进行此演示。nginx镜像将会提前上传到一个私有镜像仓库中。用户可以从云端调用预加载功能API，将私有镜像仓库中的nginx镜像，提前下发到边缘节点中。
+
+
+**1）本示例要求KubeEdge版本必须是v1.16.0+，kubernetes版本是v1.27.0+,此次选择的版本是KubeEdge v1.16.0,Kubernetes版本是v1.27.3**
+
+```
+[root@ke-cloud ~]# kubectl get node
+NAME STATUS ROLES AGE VERSION
+cloud.kubeedge Ready control-plane,master 3d v1.27.3
+edge.kubeedge Ready agent,edge 2d v1.27.7-kubeedge-v1.16.0
+
+说明：本文接下来的验证将使用边缘节点edge.kubeedge进行，如果你参考本文进行相关验证，后续边缘节点名称的配置需要根据你的实际情况进行更改。
+```
+
+**2）确保k8s apiserver开启了以下配置：**
+
+
+```
+ taskManager:
+ enable: true // 由false修改为true
+```
+可以通过命令修改kubectl edit configmap cloudcore -n kubeedge文件，并重启k8s-apiserver组件的cloudcore来进行更改。
+
+**3）准备示例代码：**
+
+yaml文件示例代码
+```
+apiVersion: operations.kubeedge.io/v1alpha1
+kind: ImagePrePullJob
+metadata:
+ name: imageprepull-example
+spec:
+ imagePrePullTemplate:
+ concurrency: 1
+ failureTolerate: '0.1'
+ images:
+ - test:nginx
+ nodeNames:
+ - edge.kubeedge
+ imageSecrets: default/secret
+ retryTimes: 1
+ timeoutSeconds: 120
+
+```
+
+## 2. 准备私有镜像仓的镜像和Secret
+在这里准备了一个阿里云的私有镜像仓用作演示:registry.cn-hangzhou.aliyuncs.com/,使用的演示空间为jilimoxing。实际操作过程中可以依据真实情况进行修改
+
+**1）推送nginx进入私有镜像仓**
+```
+[root@cloud ~]# docker tag nginx registry.cn-hangzhou.aliyuncs.com/jilimoxing/test:nginx
+[root@cloud crds~]# docker push registry.cn-hangzhou.aliyuncs.com/jilimoxing/test:nginx
+```
+
+**2）在云端创建Secret**
+
+使用Kubectl create secret docker-registry生成私有镜像仓库的secret，根据你的实际情况来进行修改
+
+```
+[root@cloud ~]# kubectl create secret docker-registry my-secret \
+ --docker-server=registry.cn-hangzhou.aliyuncs.com \
+ --docker-username=23021*****@qq.com \
+ --docker-password=Xy***** \
+ --docker-email=23021*****@qq.com
+
+[root@cloud ~]# kubectl get secret -A
+NAMESPACE NAME TYPE DATA AGE
+default my-secret kubernetes.io/dockerconfigjson 1 31s
+
+```
+
+## 3. 创建Yaml文件
+
+**1）修改代码**
+
+在云端节点上创建yaml文件，需要修改对应的images信息以及imageSecrets信息，保持和所需要预加载的镜像仓库secret一致，如下所示：
+```
+
+[root@ke-cloud ~]# vim imageprepull.yaml
+
+apiVersion: operations.kubeedge.io/v1alpha1
+kind: ImagePrePullJob
+metadata:
+ name: imageprepull-example
+spec:
+ imagePrePullTemplate:
+ concurrency: 1
+ failureTolerate: '0.1'
+ images:
+ - registry.cn-hangzhou.aliyuncs.com/jilimoxing/test:nginx
+ nodeNames:
+ - edge.kubeedge
+ imageSecrets: default/my-secret
+ retryTimes: 1
+ timeoutSeconds: 120
+
+```
+
+**2）执行文件**
+
+
+```
+[root@ke-cloud ~]# kubectl apply -f imageprepull.yaml
+```
+
+
+## 4. 检查边缘节点镜像是否预加载成功
+
+进入边缘端，使用命令ctr -n k8s.io i ls进行查看
+```
+[root@edge ~]# ctr -n k8s.io i ls
+```
+找到对应的镜像已被预加载成功
+```
+REF TYPE DIGEST SIZE PLATFORMS LABELS 
+registry.cn-hangzhou.aliyuncs.com/jilimoxing/test:nginx application/vnd.docker.distribution.manifest.v2+json sha256:73e957703f1266530db0aeac1fd6a3f87c1e59943f4c13eb340bb8521c6041d7 67.3 MiB linux/amd64 
+```
+
+## 5. 其他
+
+**1）更多的KubeEdge官方示例请参考 https://github.com/kubeedge/examples**