Update docs of 1.7

1. Add advanced option usage examples of mirror, save, load commands. 2. Update docker-image CI example scripts. 3. Update best practice instructions.
cnrancher · Dec 7, 2023 · 13a470c · 13a470c
1 parent 83eef85
commit 13a470c
Show file tree

Hide file tree

Showing 13 changed files with 308 additions and 34 deletions.
diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.7/10-mirror/01-mirror.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.7/10-mirror/01-mirror.md
@@ -84,3 +84,27 @@ Global Flags:
 
 Use "hangar mirror [command] --help" for more information about a command.
 ```
+
+## Mirror 镜像时自定义 Project
+
+Hangar 的 `mirror` 命令提供一些高级参数，可以用于自定义 *源镜像* 和 *目标镜像* 的 Project（Namespace）。
+
+您可使用 `--source-project` 参数，自定义所有 *源镜像* 的 Project，并使用 `--destination-project` 参数，自定义所有 *目标镜像* 的 Project。
+
+以下是一个例子：
+
+- 本例中使用 `Default` 格式的镜像列表，包含了一些 Docker Hub 镜像，这些镜像的 Project 不一致（`library` 和 `cnrancher`）。
+
+    ```txt title="example.txt"
+    docker.io/library/nginx:latest
+    docker.io/cnrancher/hangar:latest
+    ```
+
+- 使用 `--destination-project` 参数，将这些镜像拷贝至另一个 Docker Hub 用户。
+
+    ```shell-session
+    $ hangar mirror -f "example.txt" --destination-project="USERNAME"
+    [17:00:00] [INFO] [IMG:1] Copying [docker.io/library/nginx:latest] => [docker.io/USERNAME/nginx:latest]
+    [17:00:00] [INFO] [IMG:2] Copying [docker.io/cnrancher/hangar:latest] => [docker.io/USERNAME/hangar:latest]
+    ......
+    ```
diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.7/11-save/01-save.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.7/11-save/01-save.md
@@ -32,6 +32,10 @@ title: "Save 命令"
 
     最终镜像文件将被保存在 `saved_example.zip` 压缩包中。
 
+3. 如果某些镜像无法下载，下载失败的镜像列表将保存在 `save-failed.txt`。
+
+    您可使用 `--failed` 参数指定输出的保存失败的镜像列表文件名。之后使用 Hangar 的 [Sync](/v1.7/sync/sync) 命令，将保存失败的镜像重新下载增添在已有的压缩包文件中。
+
 ## 压缩文件格式
 
 从 `v1.7.0` 起，Hangar 使用 `zip` 格式。

diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.7/12-load/01-load.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.7/12-load/01-load.md
@@ -7,19 +7,35 @@ title: "Load 命令"
 
 ## 快速上手
 
-使用以下命令将压缩包中存储的镜像批量上传至**目标镜像仓库**中：
+1. 使用以下命令将压缩包中存储的镜像批量上传至**目标镜像仓库**中：
 
-```bash
-#!/bin/bash
+    ```bash
+    #!/bin/bash
+
+    hangar load \
+        --file="example_image_list.txt" \
+        --source="save_example.zip" \
+        --destination=DESTINATION_REGISTRY_URL \
+        --arch=amd64,arm64 \
+        --os=linux \
+        --jobs=4
+    ```
 
-hangar load \
-    --file="example_image_list.txt" \
-    --source="save_example.zip" \
-    --destination=DESTINATION_REGISTRY_URL \
-    --arch=amd64,arm64 \
-    --os=linux \
-    --jobs=4
-```
+1. 如果某些镜像在上传时出错失败，这些失败的镜像列表将保存在 `load-failed.txt`。
+
+    您可使用 `--failed` 参数指定输出的上传失败的镜像列表文件名。之后使用 `--file` 参数，指定上传镜像时的列表文件，重新上传失败的镜像至镜像仓库中。
+
+    ```bash
+    #!/bin/bash
+
+    hangar load \
+        --file="load-failed.txt" \
+        --source="save_example.zip" \
+        --destination=DESTINATION_REGISTRY_URL \
+        --arch=amd64,arm64 \
+        --os=linux \
+        --jobs=4
+    ```
 
 ## Harbor 2.X
 
@@ -159,3 +175,68 @@ Hangar 的此特性允许依次从包含不同架构的容器镜像压缩包中
       ]
     }
     ```
+
+## 在上传镜像时自定义镜像的 Project 以及镜像列表的 Registry URL
+
+Hangar 的 `load` 命令提供了一些高级参数，用于自定义 *目标镜像* 的 Project 以及源镜像列表的 Registry URL。
+
+您可以在上传镜像时，使用 `--project` 参数自定义所有目标镜像的 Project。
+
+以下是一个例子：
+
+- 本例中，`save_example.zip` 压缩包文件中存储的镜像含有不同的 Project（`library` 和 `cnrancher`）。
+
+    ```shell-session
+    $ hangar archive ls -f save_example.zip
+    [15:58:34] [INFO] Created time: 2023-11-31 00:00:00 +0800 CST
+    [15:58:34] [INFO] Index version: v1.2.0
+    [15:58:34] [INFO] Images:
+       1 | docker.io/library/nginx:latest | arm64,amd64 | linux
+       2 | docker.io/cnrancher/hangar:latest | amd64,arm64 | linux
+    ```
+
+- 将压缩包中的所有镜像上传至 Docker Hub 的 `example` 用户。
+
+    ```shell-session
+    $ hangar load -s "save_example.zip" -d "docker.io" --project="example"
+    [16:00:00] [INFO] Arch List: [amd64,arm64]
+    [16:00:26] [INFO] OS List: [linux]
+    [16:00:32] [INFO] [IMG:2] Loading [docker.io/cnrancher/hangar:latest] => [docker.io/example/hangar:latest]
+    [16:00:32] [INFO] [IMG:1] Loading [docker.io/library/nginx:latest] => [docker.io/example/nginx:latest]
+    ......
+    ```
+
+----
+
+您可使用 `--source-registry` 参数，自定义上传镜像时镜像列表中的 Registry URL。
+
+以下是一个例子：
+
+- 本例中，`save_example.zip` 压缩包中镜像的 Registry URL 是 `127.0.0.1:5000`。
+
+    ```shell-session
+    $ hangar archive ls -f save_example.zip
+    [15:58:34] [INFO] Created time: 2023-11-31 00:00:00 +0800 CST
+    [15:58:34] [INFO] Index version: v1.2.0
+    [15:58:34] [INFO] Images:
+       1 | 127.0.0.1:5000/library/nginx:latest | arm64,amd64 | linux
+       2 | 127.0.0.1:5000/cnrancher/hangar:latest | amd64,arm64 | linux
+    ```
+
+- 镜像列表文件中，镜像的 Registry URL 为 `docker.io`。
+
+    ```txt title="example.txt"
+    docker.io/library/nginx:latest
+    docker.io/library/hangar:latest
+    ```
+
+- 当执行 `load` 命令并指定了上述镜像列表时，您需要添加 `--source-registry='127.0.0.1:5000'` 参数。
+
+    ```shell-session
+    $ hangar load -f "example.txt" -s "save_example.zip" --source-registry="127.0.0.1:5000" -d "REGISTRY_URL"
+    [16:00:00] [INFO] Arch List: [amd64,arm64]
+    [16:00:00] [INFO] OS List: [linux]
+    [16:00:00] [INFO] [IMG:2] Loading [127.0.0.1:5000/cnrancher/hangar:latest] => [REGISTRY_URL/cnrancher/hangar:latest]
+    [16:00:00] [INFO] [IMG:1] Loading [127.0.0.1:5000/library/nginx:latest] => [REGISTRY_URL/library/nginx:latest]
+    ......
+    ```
diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.7/20-bestpractice/01-k3s.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.7/20-bestpractice/01-k3s.md
@@ -147,7 +147,7 @@ title: "K3s 离线安装"
             - "http://registry.example.com:5000"
     ```
 
-1. 参考 [K3s 离线安装](https://docs.k3s.io/installation/airgap#install-k3s) 文档，安装 K3s。
+1. 参考 [K3s 离线安装](https://docs.k3s.io/installation/airgap#install-k3s) 文档，下载离线环境安装 K3s 所需的 `install.sh` 和 K3s 可执行文件。
 
     ```sh
     export INSTALL_K3S_SKIP_DOWNLOAD=true
@@ -156,7 +156,17 @@ title: "K3s 离线安装"
     ./install.sh
     ```
 
-    您可执行以下命令，从私有镜像仓库中拉取镜像，以确保 `registries.yaml` 配置正确：
+    使用以下命令检查 K3s 服务的运行状态。
+
+    ```sh
+    # 检查 K3s systemd 服务状态
+    systemctl status k3s
+
+    # 查看 K3s 集群的所有 Pod
+    k3s kubectl get pods -A
+    ```
+
+1. 您可执行以下命令，从私有镜像仓库中拉取镜像，以确保 `registries.yaml` 配置正确：
 
     ```sh
     k3s crictl pull registry.example.com:5000/rancher/mirrored-pause:3.6

diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.7/20-bestpractice/02-rke2.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.7/20-bestpractice/02-rke2.md
@@ -165,7 +165,19 @@ title: "RKE2 离线安装"
     system-default-registry: "registry.example.com:5000"
     ```
 
-    在安装并启动 RKE2 后，您可执行以下命令，从私有镜像仓库中拉取镜像，以确保 `registries.yaml` 配置正确：
+    使用以下命令检查 RKE2 服务的运行状态。
+
+    ```sh
+    # 检查 RKE2 systemd 服务状态
+    systemctl status rke2-server
+
+    # 查看 RKE2 集群的所有 Pod
+    # 默认的 kubeconfig 文件为 /etc/rancher/rke2/rke2.yaml
+    export KUBECONFIG="/etc/rancher/rke2/rke2.yaml"
+    kubectl get pods -A
+    ```
+
+1. 在安装并启动 RKE2 后，您可执行以下命令，从私有镜像仓库中拉取镜像，以确保 `registries.yaml` 配置正确：
 
     ```sh
     sudo /var/lib/rancher/rke2/bin/crictl \

diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.7/20-bestpractice/03-rancher.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.7/20-bestpractice/03-rancher.md
@@ -183,7 +183,9 @@ title: "Rancher 离线安装"
     ./install.sh
     ```
 
-    在安装 K3s 后，您可执行以下命令，从私有镜像仓库中拉取镜像，以确保 `registries.yaml` 配置正确：
+    在安装 Rancher 之前，您还需要安装 [kubectl](https://kubernetes.io/docs/reference/kubectl/) 和 [helm](https://helm.sh/docs/intro/install/) 工具。
+
+1. 在安装 K3s 后，您可执行以下命令，从私有镜像仓库中拉取镜像，以确保 `registries.yaml` 配置正确：
 
     ```sh
     k3s crictl pull registry.example.com:5000/rancher/mirrored-pause:3.6

diff --git a/versioned_docs/version-v1.7/10-mirror/01-mirror.md b/versioned_docs/version-v1.7/10-mirror/01-mirror.md
@@ -84,3 +84,27 @@ Global Flags:
 
 Use "hangar mirror [command] --help" for more information about a command.
 ```
+
+## Override project name when mirror images
+
+Hangar `mirror` command provides some advanced options to customize the project name (namespace) of the *SOURCE IMAGE* and *DESTINATION IMAGE*.
+
+You can use the `--source-project` option to override all source image projects and `--destination-project` option to override all destination image projects in the image list file.
+
+Here is an example:
+
+- The example `Default` format image list file contains images on Docker Hub with different projects (`library` and `cnrancher`).
+
+    ```txt title="example.txt"
+    docker.io/library/nginx:latest
+    docker.io/cnrancher/hangar:latest
+    ```
+
+- Use the `--destination-project` option to mirror these images to another user on Docker Hub.
+
+    ```shell-session
+    $ hangar mirror -f "example.txt" --destination-project="USERNAME"
+    [17:00:00] [INFO] [IMG:1] Copying [docker.io/library/nginx:latest] => [docker.io/USERNAME/nginx:latest]
+    [17:00:00] [INFO] [IMG:2] Copying [docker.io/cnrancher/hangar:latest] => [docker.io/USERNAME/hangar:latest]
+    ......
+    ```
diff --git a/versioned_docs/version-v1.7/11-save/01-save.md b/versioned_docs/version-v1.7/11-save/01-save.md
@@ -32,6 +32,10 @@ Use following command to save multiple container images from registry server int
 
     The images will saved into `saved_example.zip`.
 
+3. If error occured when saving some images, the save failed images will output to `save-failed.txt` by default.
+
+    You can use the `--failed` option to specify the output file of the save failed images, and then use hangar [sync](/v1.7/sync/sync) command to re-download the save failed images in `save-failed.txt` to the archive file without re-creating the whole archive file again.
+
 ## Archive File
 
 Hangar uses the `zip` format archive file since version `v1.7.0`.

diff --git a/versioned_docs/version-v1.7/12-load/01-load.md b/versioned_docs/version-v1.7/12-load/01-load.md
@@ -7,19 +7,35 @@ and the `load` command can be used in Air-Gapped (offline) installation scenario
 
 ## Quick Start
 
-Use following command to load multiple container images from archive file created by [save](/docs/v1.7/save/save#quick-start) command to the *destination registry server* parallelly.
+1. Use following command to load multiple container images from archive file created by [save](/docs/v1.7/save/save#quick-start) command to the *destination registry server* parallelly.
 
-```bash
-#!/bin/bash
+    ```bash
+    #!/bin/bash
+
+    hangar load \
+        --file="example_image_list.txt" \
+        --source="save_example.zip" \
+        --destination=DESTINATION_REGISTRY_URL \
+        --arch=amd64,arm64 \
+        --os=linux \
+        --jobs=4
+    ```
 
-hangar load \
-    --file="example_image_list.txt" \
-    --source="save_example.zip" \
-    --destination=DESTINATION_REGISTRY_URL \
-    --arch=amd64,arm64 \
-    --os=linux \
-    --jobs=4
-```
+1. If error occured when loading some images from the archive file, the load failed images will output to `load-failed.txt` by default.
+
+    You can use the `--failed` option to specify the output file of the load failed images, and then use the `--file` option of `hangar load` command to upload only these failed images from the archive file.
+
+    ```bash
+    #!/bin/bash
+
+    hangar load \
+        --file="load-failed.txt" \
+        --source="save_example.zip" \
+        --destination=DESTINATION_REGISTRY_URL \
+        --arch=amd64,arm64 \
+        --os=linux \
+        --jobs=4
+    ```
 
 ## Harbor 2.X
 
@@ -159,3 +175,68 @@ Here is an example:
       ]
     }
     ```
+
+## Override the project name or source registry URL when loading images
+
+Hangar `load` command provides some advanced options to customize the project name or source registry URL of the image list file when loading images.
+
+You can use the `--project` option to override all destination image projects when loading images.
+
+Here is an example:
+
+- The images in example `save_example.zip` archive file contains different projects (`library` and `cnrancher`).
+
+    ```shell-session
+    $ hangar archive ls -f save_example.zip
+    [15:58:34] [INFO] Created time: 2023-11-31 00:00:00 +0800 CST
+    [15:58:34] [INFO] Index version: v1.2.0
+    [15:58:34] [INFO] Images:
+       1 | docker.io/library/nginx:latest | arm64,amd64 | linux
+       2 | docker.io/cnrancher/hangar:latest | amd64,arm64 | linux
+    ```
+
+- Load all images in the archive file to the Docker Hub `example` user.
+
+    ```shell-session
+    $ hangar load -s "save_example.zip" -d "docker.io" --project="example"
+    [16:00:00] [INFO] Arch List: [amd64,arm64]
+    [16:00:26] [INFO] OS List: [linux]
+    [16:00:32] [INFO] [IMG:2] Loading [docker.io/cnrancher/hangar:latest] => [docker.io/example/hangar:latest]
+    [16:00:32] [INFO] [IMG:1] Loading [docker.io/library/nginx:latest] => [docker.io/example/nginx:latest]
+    ......
+    ```
+
+----
+
+You can use the `--source-registry` option to override the registry URL of the image list file when loading images from archive file with an image list file specified.
+
+Here is an example:
+
+- The registry URL of images in the example `save_example.zip` file is `127.0.0.1:5000`.
+
+    ```shell-session
+    $ hangar archive ls -f save_example.zip
+    [15:58:34] [INFO] Created time: 2023-11-31 00:00:00 +0800 CST
+    [15:58:34] [INFO] Index version: v1.2.0
+    [15:58:34] [INFO] Images:
+       1 | 127.0.0.1:5000/library/nginx:latest | arm64,amd64 | linux
+       2 | 127.0.0.1:5000/cnrancher/hangar:latest | amd64,arm64 | linux
+    ```
+
+- The registry URL of images in the example image list file is `docker.io`.
+
+    ```txt title="example.txt"
+    docker.io/library/nginx:latest
+    docker.io/library/hangar:latest
+    ```
+
+- You need to add `--source-registry='127.0.0.1:5000'` option when loading images from the archive file with the `example.txt` image list file specified.
+
+    ```shell-session
+    $ hangar load -f "example.txt" -s "save_example.zip" --source-registry="127.0.0.1:5000" -d "REGISTRY_URL"
+    [16:00:00] [INFO] Arch List: [amd64,arm64]
+    [16:00:00] [INFO] OS List: [linux]
+    [16:00:00] [INFO] [IMG:2] Loading [127.0.0.1:5000/cnrancher/hangar:latest] => [REGISTRY_URL/cnrancher/hangar:latest]
+    [16:00:00] [INFO] [IMG:1] Loading [127.0.0.1:5000/library/nginx:latest] => [REGISTRY_URL/library/nginx:latest]
+    ......
+    ```
diff --git a/versioned_docs/version-v1.7/20-bestpractice/01-k3s.md b/versioned_docs/version-v1.7/20-bestpractice/01-k3s.md
@@ -147,7 +147,7 @@ You can use the [K3s Private Registry Method](https://docs.k3s.io/installation/a
             - "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).
+1. Download the K3s installation script `install.sh` and K3s binary file by refer to [Air Gap install K3s](https://docs.k3s.io/installation/airgap#install-k3s), then install K3s server.
 
     ```sh
     export INSTALL_K3S_SKIP_DOWNLOAD=true
@@ -156,7 +156,17 @@ You can use the [K3s Private Registry Method](https://docs.k3s.io/installation/a
     ./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:
+    You can use following commands to view the status of K3s server.
+
+    ```sh
+    # Check the K3s systemd service status
+    systemctl status k3s
+
+    # View all pods of the K3s cluster
+    k3s kubectl get pods -A
+    ```
+
+1. 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 registry.example.com:5000/rancher/mirrored-pause:3.6