Add RKE2 best practice

cnrancher · Dec 5, 2023 · 4fa6c4e · 4fa6c4e
1 parent 68a86b4
commit 4fa6c4e
Show file tree

Hide file tree

Showing 4 changed files with 378 additions and 20 deletions.
diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.7/20-bestpractice/02-k3s.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.7/20-bestpractice/02-k3s.md
@@ -13,7 +13,7 @@ title: "K3s 离线安装"
     ```sh
     #!/bin/bash
 
-    # 本例中，将 K3s 容器镜像存储至本地目录中
+    # 本例中，将 K3s 容器镜像 Layer 文件存储至本地目录
     mkdir -p registry
 
     docker run -d \
@@ -39,7 +39,7 @@ title: "K3s 离线安装"
 
 1. 在 [K3s GitHub Release](https://github.com/k3s-io/k3s/releases/) 页面下载 K3s 镜像列表。
 
-    > 本例使用版本 `v1.27.6+k3s1`
+    > 本例使用版本为 `v1.27.6+k3s1`。
 
     ```sh
     wget 'https://github.com/k3s-io/k3s/releases/download/v1.27.6%2Bk3s1/k3s-images.txt'
@@ -129,7 +129,7 @@ title: "K3s 离线安装"
 
     :::note
 
-    本例中，假设您的镜像仓库的 IP 地址绑定了域名 `private.io`。
+    本例中，假设您的镜像仓库的 IP 地址绑定了域名 `registry.example.com`。
 
     :::
 
@@ -141,33 +141,33 @@ title: "K3s 离线安装"
     mirrors:
         docker.io:
             endpoint:
-            - "http://private.io:5000"
-        "private.io:5000":
+            - "http://registry.example.com:5000"
+        "registry.example.com:5000":
             endpoint:
-            - "http://private.io:5000"
+            - "http://registry.example.com:5000"
     ```
 
 1. 参考 [K3s 离线安装](https://docs.k3s.io/installation/airgap#install-k3s) 文档，安装 K3s。
 
     ```sh
     export INSTALL_K3S_SKIP_DOWNLOAD=true
-    export INSTALL_K3S_EXEC="--system-default-registry=private.io:5000"
+    export INSTALL_K3S_EXEC="--system-default-registry=registry.example.com:5000"
 
     ./install.sh
     ```
 
     您可执行以下命令，从私有镜像仓库中拉取镜像，以确保 `registries.yaml` 配置正确：
 
     ```sh
-    k3s crictl pull private.io:5000/rancher/mirrored-pause:3.6
+    k3s crictl pull registry.example.com:5000/rancher/mirrored-pause:3.6
     ```
 
     使用以下命令查看已拉取的镜像：
 
     ```shell-session
     $ sudo k3s crictl images
     IMAGE                                              TAG                    IMAGE ID            SIZE
-    private.io:5000/rancher/klipper-helm               v0.8.2-build20230815   5f89cb8137ccb       90.9MB
-    private.io:5000/rancher/local-path-provisioner     v0.0.24                b29384aeb4b13       14.9MB
+    registry.example.com:5000/rancher/klipper-helm               v0.8.2-build20230815   5f89cb8137ccb       90.9MB
+    registry.example.com:5000/rancher/local-path-provisioner     v0.0.24                b29384aeb4b13       14.9MB
     ......
     ```
diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.7/20-bestpractice/03-rke2.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.7/20-bestpractice/03-rke2.md
@@ -2,4 +2,183 @@
 title: "RKE2 离线安装"
 ---
 
-> WIP
+本例将引导您使用 Hangar 快速搭建包含多架构容器镜像的 Registry 服务器，以用于 RKE2 Air-Gap（离线环境）安装。
+
+您可按照 [RKE2 私有镜像仓库方法](https://docs.rke2.io/zh/install/airgap#%E7%A7%81%E6%9C%89%E9%95%9C%E5%83%8F%E4%BB%93%E5%BA%93%E6%96%B9%E6%B3%95) 在离线环境安装 RKE2。
+
+## 最佳实践
+
+1. 部署一个 [registry](https://distribution.github.io/distribution/) 服务器，用于存储 RKE2 容器镜像。
+
+    ```sh
+    #!/bin/bash
+
+    # 本例中，将 RKE2 容器镜像 Layer 文件存储至本地目录
+    mkdir -p registry
+
+    docker run -d \
+        -p 5000:5000 \
+        -v $(pwd)/registry:/var/lib/registry \
+        --name registry \
+        registry:2
+    ```
+
+    登录至私有镜像仓库：
+
+    ```sh
+    hangar login 'localhost:5000' --tls-verify=false
+    ```
+
+    :::note
+
+    默认情况下，Registry 可以使用任意的用户名和密码登录。
+
+    您可以参考 [Distribution Registry Token Authentication](https://distribution.github.io/distribution/spec/auth/) 配置 Registry 的认证信息，并参考 [HTTPS certificate](https://distribution.github.io/distribution/about/deploying/#get-a-certificate) 配置 HTTPS。
+
+    :::
+
+1. 在 [RKE2 GitHub Release](https://github.com/rancher/rke2/releases) 页面下载 RKE2 镜像列表。
+
+    > 本例使用版本为 `v1.27.7+rke2r1`。
+
+    ```sh
+    # 下载 AMD64 架构镜像列表
+    wget 'https://github.com/rancher/rke2/releases/download/v1.27.7%2Brke2r1/rke2-images-all.linux-amd64.txt'
+
+    # 下载 ARM64 架构镜像列表
+    wget 'https://github.com/rancher/rke2/releases/download/v1.27.7%2Brke2r1/rke2-images-all.linux-arm64.txt'
+    ```
+
+    如果您需要在 `amd64` 架构和 `arm64` 架构的机器上运行 RKE2，可使用以下命令将 `amd64` 和 `arm64` 架构的镜像列表合并为一个镜像列表。
+
+    ```sh
+    sort rke2-images-all.linux-*.txt | uniq > rke2-images-all.linux.txt
+    ```
+
+1. 如果私有镜像仓库的主机可以访问公共网络，您可使用 Hangar [mirror](/docs/v1.7/mirror/mirror) 命令，将 `amd64` 和 `arm64` 架构的容器镜像从 Docker Hub Mirror 至私有镜像仓库。
+
+    ```sh
+    #!/bin/bash
+
+    hangar mirror \
+        -f 'rke2-images-all.linux.txt' \
+        -s 'docker.io' \
+        -d 'localhost:5000' \
+        --arch 'amd64,arm64' \
+        --os 'linux' \
+        --jobs 5 \
+        --tls-verify=false
+    ```
+
+    可使用 [mirror validate](/docs/v1.7/mirror/validate) 命令确保镜像均被正确拷贝至私有镜像仓库中。
+
+    ```sh
+    #!/bin/bash
+
+    hangar mirror validate \
+        -f 'rke2-images-all.linux.txt' \
+        -s 'docker.io' \
+        -d 'localhost:5000' \
+        --arch 'amd64,arm64' \
+        --os 'linux' \
+        --jobs 5 \
+        --tls-verify=false
+    ```
+
+1. 如果主机无法访问至公共网络，可先在有网络链接的主机上使用 [hangar save](/docs/v1.7/save/save) 命令保存镜像，之后使用 [hangar load](/docs/v1.7/load/load) 命令将保存的容器镜像拷贝至私有镜像仓库中。
+
+    ```sh
+    #!/bin/bash
+
+    # 将镜像保存在 rke-images.zip 压缩包中。
+    # 在有网络链接的设备执行以下命令。
+    hangar save \
+        -f 'rke2-images-all.linux.txt' \
+        -s 'docker.io' \
+        -d 'rke2-images.zip' \
+        --arch 'amd64,arm64' \
+        --os 'linux' \
+        --jobs 5
+
+    # 如有需要，验证已保存的镜像。
+    hangar save validate \
+        -f 'rke2-images-all.linux.txt' \
+        -s 'docker.io' \
+        -d 'rke2-images.zip' \
+        --arch 'amd64,arm64' \
+        --os 'linux' \
+        --jobs 5
+    ```
+
+    生成的 `rke2-images.zip` 压缩包含有 `amd64` 和 `arm64` 架构的容器镜像。
+
+    ```sh
+    #!/bin/bash
+
+    # 将 rke2-images.zip 保存的镜像上传至私有镜像仓库。
+    # 可在无网络链接的设备上执行此命令。
+    hangar load \
+        -s 'rke2-images.zip' \
+        -d 'localhost:5000' \
+        --arch 'amd64,arm64' \
+        --os 'linux' \
+        --jobs 5 \
+        --tls-verify=false
+
+    # 如有需要，验证已上传的镜像。
+    hangar load validate \
+        -s 'rke2-images.zip' \
+        -d 'localhost:5000' \
+        --arch 'amd64,arm64' \
+        --os 'linux' \
+        --jobs 5 \
+        --tls-verify=false
+    ```
+
+1. 参考 [RKE2 Containerd 镜像仓库配置](https://docs.rke2.io/zh/install/containerd_registry_configuration) 文档，创建 `/etc/rancher/rke2/registries.yaml` 配置文件。
+
+    :::note
+
+    本例中，假设您的镜像仓库的 IP 地址绑定了域名 `registry.example.com`。
+
+    :::
+
+    ```sh
+    mkdir -p /etc/rancher/rke2
+    ```
+
+    ```yaml title="/etc/rancher/rke2/registries.yaml"
+    mirrors:
+        docker.io:
+            endpoint:
+            - "http://registry.example.com:5000"
+        "registry.example.com:5000":
+            endpoint:
+            - "http://registry.example.com:5000"
+    ```
+
+1. 参考 [RKE2 离线安装](https://docs.rke2.io/zh/install/airgap#%E5%AE%89%E8%A3%85-rke2) 文档，安装 RKE2。
+
+    创建配置文件，设定 RKE2 的 `system-default-registry` 为 `registry.example.com`。
+
+    ```yaml title="/etc/rancher/rke2/config.yaml"
+    system-default-registry: "registry.example.com:5000"
+    ```
+
+    在安装并启动 RKE2 后，您可执行以下命令，从私有镜像仓库中拉取镜像，以确保 `registries.yaml` 配置正确：
+
+    ```sh
+    sudo /var/lib/rancher/rke2/bin/crictl \
+        --config "/var/lib/rancher/rke2/agent/etc/crictl.yaml" \
+        pull registry.example.com:5000/rancher/mirrored-pause:3.6
+    ```
+
+    使用以下命令查看已拉取的镜像：
+
+    ```shell-session
+    $ sudo /var/lib/rancher/rke2/bin/crictl --config "/var/lib/rancher/rke2/agent/etc/crictl.yaml" images
+    IMAGE                                                   TAG                            IMAGE ID            SIZE
+    registry.example.com:5000/rancher/hardened-calico       v3.26.1-build20230802          a0e7293895577       195MB
+    registry.example.com:5000/rancher/hardened-etcd         v3.5.9-k3s1-build20230802      c6b7a4f2f79b2       64.4MB
+    ......
+    ```
diff --git a/versioned_docs/version-v1.7/20-bestpractice/02-k3s.md b/versioned_docs/version-v1.7/20-bestpractice/02-k3s.md
@@ -129,7 +129,7 @@ You can use the [K3s Private Registry Method](https://docs.k3s.io/installation/a
 
     :::note
 
-    In this example, we assume that the private image registry IP address was bind to the URL `private.io`.
+    In this example, we assume that the private image registry IP address was bind to the URL `registry.example.com`.
 
     :::
 
@@ -141,33 +141,33 @@ You can use the [K3s Private Registry Method](https://docs.k3s.io/installation/a
     mirrors:
         docker.io:
             endpoint:
-            - "http://private.io:5000"
-        "private.io:5000":
+            - "http://registry.example.com:5000"
+        "registry.example.com:5000":
             endpoint:
-            - "http://private.io:5000"
+            - "http://registry.example.com:5000"
     ```
 
 1. Install K3s by refer to the guide of [Air Gap install K3s](https://docs.k3s.io/installation/airgap#install-k3s).
 
     ```sh
     export INSTALL_K3S_SKIP_DOWNLOAD=true
-    export INSTALL_K3S_EXEC="--system-default-registry=private.io:5000"
+    export INSTALL_K3S_EXEC="--system-default-registry=registry.example.com:5000"
 
     ./install.sh
     ```
 
     You can execute following command to pull images from the private image registry server to ensure that the `registries.yaml` config is working properly:
 
     ```sh
-    k3s crictl pull private.io:5000/rancher/mirrored-pause:3.6
+    k3s crictl pull registry.example.com:5000/rancher/mirrored-pause:3.6
     ```
 
     Use following command to view pulled images from the private image registry:
 
     ```shell-session
     $ sudo k3s crictl images
     IMAGE                                              TAG                    IMAGE ID            SIZE
-    private.io:5000/rancher/klipper-helm               v0.8.2-build20230815   5f89cb8137ccb       90.9MB
-    private.io:5000/rancher/local-path-provisioner     v0.0.24                b29384aeb4b13       14.9MB
+    registry.example.com:5000/rancher/klipper-helm               v0.8.2-build20230815   5f89cb8137ccb       90.9MB
+    registry.example.com:5000/rancher/local-path-provisioner     v0.0.24                b29384aeb4b13       14.9MB
     ......
     ```