From 4fa6c4ed5777abd0e482d83176b68ee3ad8e5a75 Mon Sep 17 00:00:00 2001 From: Starry Wang Date: Tue, 5 Dec 2023 17:45:18 +0800 Subject: [PATCH] Add RKE2 best practice --- .../version-v1.7/20-bestpractice/02-k3s.md | 20 +- .../version-v1.7/20-bestpractice/03-rke2.md | 181 +++++++++++++++++- .../version-v1.7/20-bestpractice/02-k3s.md | 16 +- .../version-v1.7/20-bestpractice/03-rke2.md | 181 +++++++++++++++++- 4 files changed, 378 insertions(+), 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 index eff1dccc..21443cd0 100644 --- 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,17 +141,17 @@ 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 ``` @@ -159,7 +159,7 @@ title: "K3s 离线安装" 您可执行以下命令，从私有镜像仓库中拉取镜像，以确保 `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 ``` 使用以下命令查看已拉取的镜像： @@ -167,7 +167,7 @@ title: "K3s 离线安装" ```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 index c3ea1115..b2380817 100644 --- 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 index 96073396..3437e07d 100644 --- 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,17 +141,17 @@ 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 ``` @@ -159,7 +159,7 @@ You can use the [K3s Private Registry Method](https://docs.k3s.io/installation/a 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: @@ -167,7 +167,7 @@ You can use the [K3s Private Registry Method](https://docs.k3s.io/installation/a ```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/versioned_docs/version-v1.7/20-bestpractice/03-rke2.md b/versioned_docs/version-v1.7/20-bestpractice/03-rke2.md index cbd1c072..d6774d7d 100644 --- a/versioned_docs/version-v1.7/20-bestpractice/03-rke2.md +++ b/versioned_docs/version-v1.7/20-bestpractice/03-rke2.md @@ -2,4 +2,183 @@ title: "RKE2 Air-Gap Installation" --- -> WIP +This example will guide you to setup a multi-arch private image registry server for RKE2 Air-Gapped installation. + +You can use the [RKE2 Private Registry Method](https://docs.rke2.io/install/airgap#private-registry-method) to prepare the private image registry server used by RKE2. + +## Best Practice + +1. Setup a private [registry](https://distribution.github.io/distribution/) server to host the container images used by RKE2. + + ```sh + #!/bin/bash + + # In this example, we create a directory to store the container image layers. + mkdir -p registry + + docker run -d \ + -p 5000:5000 \ + -v $(pwd)/registry:/var/lib/registry \ + --name registry \ + registry:2 + ``` + + Login to the private image registry. + + ```sh + hangar login 'localhost:5000' --tls-verify=false + ``` + + :::note + + By default, the registry server can be login with any username and password. + + You can configure the authentication config of the registry server by refer to [Distribution Registry Token Authentication](https://distribution.github.io/distribution/spec/auth/) and setup the [HTTPS certificate](https://distribution.github.io/distribution/about/deploying/#get-a-certificate) to use in production. + + ::: + +1. Download the RKE2 image list file from [RKE2 GitHub Release](https://github.com/rancher/rke2/releases) page. + + > We use version `v1.27.7+rke2r1` in this example. + + ```sh + # Download the AMD64 image list file + wget 'https://github.com/rancher/rke2/releases/download/v1.27.7%2Brke2r1/rke2-images-all.linux-amd64.txt' + + # Download the ARM64 image list file + wget 'https://github.com/rancher/rke2/releases/download/v1.27.7%2Brke2r1/rke2-images-all.linux-arm64.txt' + ``` + + You can use following command to merge `amd64` and `arm64` image list into one file if you need to run RKE2 on both `amd64` and `arm64` architectures. + + ```sh + sort rke2-images-all.linux-*.txt | uniq > rke2-images-all.linux.txt + ``` + +1. If the server has the ability to access Docker Hub registry server (with internet connection), use Hangar [mirror](/docs/v1.7/mirror/mirror) command to mirror both `amd64` and `arm64` container images from Docker Hub to your private image registry. + + ```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 + ``` + + Use the Hangar [mirror validate](/docs/v1.7/mirror/validate) command to verify the copied container images if necessary. + + ```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. If the server can't access Docker Hub (without internet connection), use [hangar save](/docs/v1.7/save/save) and [hangar load](/docs/v1.7/load/load) command to copy container image to the private registry server. + + ```sh + #!/bin/bash + + # Save images into rke2-images.zip. + # Run these commands on a internet accessible machine. + hangar save \ + -f 'rke2-images-all.linux.txt' \ + -s 'docker.io' \ + -d 'rke2-images.zip' \ + --arch 'amd64,arm64' \ + --os 'linux' \ + --jobs 5 + + # Validate the saved images if necessary. + hangar save validate \ + -f 'rke2-images-all.linux.txt' \ + -s 'docker.io' \ + -d 'rke2-images.zip' \ + --arch 'amd64,arm64' \ + --os 'linux' \ + --jobs 5 + ``` + + The saved `rke2-images.zip` archive file contains both `amd64` and `arm64` container images. + + ```sh + #!/bin/bash + + # Load images from rke2-images.zip to the private image registry server. + # Run these commands on air-gapped machine. + hangar load \ + -s 'rke2-images.zip' \ + -d 'localhost:5000' \ + --arch 'amd64,arm64' \ + --os 'linux' \ + --jobs 5 \ + --tls-verify=false + + # Validate the loaded images if necessary. + hangar load validate \ + -s 'rke2-images.zip' \ + -d 'localhost:5000' \ + --arch 'amd64,arm64' \ + --os 'linux' \ + --jobs 5 \ + --tls-verify=false + ``` + +1. Create the `/etc/rancher/rke2/registries.yaml` configuration file by refer to [RKE2 Containerd Registry Configuration](https://docs.rke2.io/install/containerd_registry_configuration). + + :::note + + In this example, we assume that the private image registry IP address was bind to the URL `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. Install RKE2 by refer to the guide of [RKE2 Air-Gap Install](https://docs.rke2.io/install/airgap#install-rke2). + + Configure the RKE2 system default registry to `registry.example.com`. + + ```yaml title="/etc/rancher/rke2/config.yaml" + system-default-registry: "registry.example.com:5000" + ``` + + After install and launch RKE2 server, 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 + 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 + ``` + + Use following command to view pulled images from the private image registry: + + ```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 + ...... + ```