docs: fix bugs in kbcli, full disk lock and backuprepo docs in releas…

…e-0.9 (#8869)
apecloud · Jan 24, 2025 · 2e964e9 · 2e964e9
1 parent 8cf92c7
commit 2e964e9
Show file tree

Hide file tree

Showing 6 changed files with 454 additions and 335 deletions.
diff --git a/docs/user_docs/handle-an-exception/full-disk-lock.md b/docs/user_docs/handle-an-exception/full-disk-lock.md
@@ -27,26 +27,57 @@ When the space water level of all configured volumes falls below the defined thr
 
 ## Enable full disk lock
 
-- For MySQL database, the read/write user cannot write to the disk when the disk usage reaches the `highwatermark` value, while the superuser can still write.
+- For MySQL, the read/write user cannot write to the disk when the disk usage reaches the `highwatermark` value, while the superuser can still write.
 - For PostgreSQL and MongoDB, both the read/write user and the superuser cannot write when the disk usage reaches `highwatermark`.
 - `90` is the default value setting for the high watermark at the component level which means the disk is locked when the disk usage reaches 90%, while `85` is used for the volumes which overwrites the component's threshold value.
 
-In the cluster definition, add the following content to enable the full disk lock function. You can set the value according to your need.
+**Steps:**
 
-```bash
-volumeProtectionSpec:
-  highWatermark: 90
-  volumes:
-  - highWatermark: 85
-    name: data
-```
+1. Edit the ClusterDefinition Custom Resource (CR) of a database.
 
-:::note
+   This guide takes `mysql` as an example. You can replace `mysql` with `postgresql` or `mongodb`.
 
-The recommended value of `highWatermark` is 90.
+   ```bash
+   kubectl edit clusterdefinition mysql
+   ```
 
-:::
+2. Add the `volumeProtectionSpec` field under `spec.componentDefs[]` to enable the full disk lock function. You can set the values of `highWatermark` as needed.
+
+   ```yaml
+   ...
+   spec:
+     componentDefs:
+     ...
+     - name: mysql
+       volumeProtectionSpec:
+         highWatermark: 90
+         volumes:
+         - highWatermark: 85
+           name: data
+     ...
+   ```
+
+   :::note
+
+   The recommended value of `highWatermark` is 90.
+
+   :::
+
+3. Save the changes and exit.
 
 ## Disable full disk lock
 
-Delete `volumeProtectionSpec` from the cluster definition file.
+To disable the full disk lock function, just delete the `volumeProtectionSpec` field from the ClusterDefinition CR.
+
+**Steps:**
+
+1. Edit the ClusterDefinition CR of a database.
+
+   This guide takes `mysql` as an example. You can replace `mysql` with `postgresql` or `mongodb`.
+
+   ```bash
+   kubectl edit clusterdefinition mysql
+   ```
+
+2. Delete the `volumeProtectionSpec` field.
+3. Save the changes and exit.
diff --git a/docs/user_docs/installation/install-kbcli.md b/docs/user_docs/installation/install-kbcli.md
@@ -148,6 +148,12 @@ Install kbcli using the `curl` command.
    curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash
    ```
 
+   To install a specified version of kbcli, use `-s` after the command and describe the version you want to install.
+
+   ```bash
+   curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s x.y.z
+   ```
+
 2. Run `kbcli version` to check the version of kbcli and ensure that it is successfully installed.
 
 :::note
@@ -159,6 +165,10 @@ Install kbcli using the `curl` command.
 </TabItem>
 </Tabs>
 
+## Upgrade kbcli
+
+To upgrade kbcli, [uninstall the current kbcli](./uninstall-kubeblocks-and-kbcli.md#uninstall-kbcli) and install the latest version.
+
 ## (Optional) Enable auto-completion for kbcli
 
 `kbcli` supports command line auto-completion.

diff --git a/docs/user_docs/maintenance/backup-and-restore/backup/backup-repo.md b/docs/user_docs/maintenance/backup-and-restore/backup/backup-repo.md
@@ -11,7 +11,7 @@ import TabItem from '@theme/TabItem';
 
 # Introduction
 
-BackupRepo is the storage repository for backup data. Currently, KubeBlocks supports configuring various object storage services as backup repositories, including OSS (Alibaba Cloud Object Storage Service), S3 (Amazon Simple Storage Service), COS (Tencent Cloud Object Storage), GCS (Google Cloud Storage), OBS (Huawei Cloud Object Storage), MinIO, and other S3-compatible services. Additionally, it also supports using Kubernetes-native PVCs as backup repositories.
+BackupRepo is the storage repository for backup data. Currently, KubeBlocks supports configuring various object storage services as backup repositories, including OSS (Alibaba Cloud Object Storage Service), S3 (Amazon Simple Storage Service), COS (Tencent Cloud Object Storage), GCS (Google Cloud Storage), OBS (Huawei Cloud Object Storage), MinIO, and other S3-compatible services.
 
 You can create multiple BackupRepos to suit different scenarios. For example, based on different businesses, the data of business A is stored in repository A, and the data of business B is stored in repository B. Or you can configure multiple repositories by region to realize geo-disaster recovery. But it is required to specify backup repositories when you create a backup. You can also create a default backup repository and KubeBlocks uses this default repository to store backup data if no specific repository is specified.
 
@@ -33,8 +33,7 @@ If you don't have an object storage service from a cloud provider, you can deplo
 1. Install MinIO in the `kb-system` namespace.
 
    ```bash
-   helm repo add kubeblocks-apps https://jihulab.com/api/v4/projects/152630/packages/helm/stable
-   helm install minio kubeblocks-apps/minio --namespace kb-system --create-namespace --set "extraEnvVars[0].name=MINIO_BROWSER_LOGIN_ANIMATION" --set "extraEnvVars[0].value=off"
+   helm install minio oci://registry-1.docker.io/bitnamicharts/minio --namespace kb-system --create-namespace --set "extraEnvVars[0].name=MINIO_BROWSER_LOGIN_ANIMATION" --set "extraEnvVars[0].value=off"
    ```
 
    Get the initial username and password:
@@ -88,74 +87,6 @@ Generally, it is recommended to use the "Tool" method as it does not require ins
 
 However, as backup and restore tasks require running in the namespace of the database cluster, using the "Tool" approach automatically synchronizes the necessary credentials for accessing the remote storage as secret resources in those namespaces. These credentials are used by the data transfer tool. If you have concerns about security risks associated with synchronizing secrets in a multi-tenant environment, you can choose to use the "Mount" method.
 
-### Automatic BackupRepo configuration
-
-You can specify the BackupRepo information in a YAML configuration file when installing KubeBlocks, and KubeBlocks will create the BackupRepo and automatically install the necessary CSI Driver based on the provided configuration.
-
-1. Prepare the configuration file.
-
-   Taking AWS S3 as an example, the configuration file `backuprepo.yaml` is:
-
-    ```yaml
-    backupRepo:
-      create: true
-      storageProvider: s3
-      config:
-        region: cn-northwest-1
-        bucket: test-kb-backup
-      secrets:
-        accessKeyId: <ACCESS KEY>
-        secretAccessKey: <SECRET KEY>
-    ```
-
-    * `region`: specifies the region where S3 is located.
-    * `bucket`: specifies the bucket name of S3.
-    * `accessKeyId`: specifies the Access Key of AWS.
-    * `secretAccessKey`: specifies the Secret Key of AWS.
-    * `storageProvider`：specifies the object storage provider, which is S3 in this case.
-
-:::note
-
-* For KubeBlocks v0.8.0, the available `storageProvider` options are `s3`, `cos`, `gcs-s3comp`, `obs`, `oss`, `minio`, `pvc`, `ftp`, and `nfs`.
-* For different `storageProvider`, the configuration may differ. `config` and `secrets` in the above example are applied to S3.
-* Execute the command `kubectl get storageproviders.dataprotection.kubeblocks.io` to view the supported `storageProvider` options.
-
-:::
-
-2. Specify the configuration file when installing KubeBlocks.
-
-   <Tabs>
-
-   <TabItem value="kubectl" label="kubectl" default>
-
-   ```bash
-   kubectl create -f backuprepo.yaml
-   ```
-
-   Use the command below to check the BackupRepo after installation.
-
-   ```bash
-   kubectl get backuprepo
-   ```
-
-   </TabItem>
-
-   <TabItem value="kbcli" label="kbcli">
-
-   ```bash
-   kbcli kubeblocks install -f backuprepo.yaml
-   ```
-
-   Use the command below to check the BackupRepo after installation.
-
-   ```bash
-   kbcli backuprepo list
-   ```
-
-   </TabItem>
-
-   </Tabs>
-
 ### Manual BackupRepo configuration
 
 If you do not configure the BackupRepo information when installing KubeBlocks, you can manually configure it by the following instructions.
@@ -489,7 +420,7 @@ If you do not configure the BackupRepo information when installing KubeBlocks, y
    ```bash
    # The current GCS is the S3-compatible version provided by Google Cloud
    kbcli backuprepo create my-repo \
-     --provider gcs \
+     --provider gcs-s3comp \
      --region auto \
      --bucket  test-kb-backup \
      --access-key-id <ACCESS KEY> \
@@ -560,4 +491,86 @@ If you do not configure the BackupRepo information when installing KubeBlocks, y
 
 </TabItem>
 
-</Tabs>
+</Tabs>
+
+:::note
+
+If the BackupRepo status shows Failed or remains in PreChecking for a long time, run `kubectl describe backuprepo my-repo` or `kbcli backuprepo describe my-repo` to check the `status.conditions` for details.
+
+To troubleshoot:
+
+* Check whether configuration parameters, such as `endpoint`, `accessKeyId`, and `secretAccessKey`, are correctly specified.
+* For self-hosted object storage (e.g., Ceph Object Storage), try using `minio` as StorageProvider. The default `s3` StorageProvider uses a virtual hosting URL style, which some self-hosted storage may not support.
+* If an `InvalidLocationConstraint` error occurs, check whether its parameter is correctly configured. If this error persists, leave the `region` parameter empty and try again.
+* If the status remains in the `PreChecking` state, check your network connection. Ensure the storage service is accessible from within the Kubernetes cluster. You can test this by running a Pod and connecting to the storage service using the corresponding client.
+* KubeBlocks uses [rclone](https://rclone.org/) internally for data transfer. Check whether rclone can successfully access the storage service.
+
+:::
+
+### Automatic BackupRepo configuration
+
+You can specify the BackupRepo information in a YAML configuration file when installing KubeBlocks, and KubeBlocks will create the BackupRepo accordingly.
+
+1. Prepare the configuration file.
+
+   Taking AWS S3 as an example, the configuration file `backuprepo.yaml` is:
+
+    ```yaml
+    backupRepo:
+      create: true
+      storageProvider: s3
+      config:
+        region: cn-northwest-1
+        bucket: test-kb-backup
+      secrets:
+        accessKeyId: <ACCESS KEY>
+        secretAccessKey: <SECRET KEY>
+    ```
+
+    * `region`: specifies the region where S3 is located.
+    * `bucket`: specifies the bucket name of S3.
+    * `accessKeyId`: specifies the Access Key of AWS.
+    * `secretAccessKey`: specifies the Secret Key of AWS.
+    * `storageProvider`：specifies the object storage provider, which is S3 in this case.
+
+:::note
+
+* In KubeBlocks, the available `storageProvider` options are `s3`, `cos`, `gcs-s3comp`, `obs`, `oss`, `minio`, `ftp`, and `nfs`.
+* For different `storageProvider`, the configuration may differ. `config` and `secrets` in the above example are applied to S3.
+* Execute the command `kubectl get storageproviders.dataprotection.kubeblocks.io` to view the supported `storageProvider` options.
+
+:::
+
+2. Specify the configuration file when installing KubeBlocks.
+
+   <Tabs>
+
+   <TabItem value="kubectl" label="kubectl" default>
+
+   ```bash
+   kubectl create -f backuprepo.yaml
+   ```
+
+   Use the command below to check the BackupRepo after installation.
+
+   ```bash
+   kubectl get backuprepo
+   ```
+
+   </TabItem>
+
+   <TabItem value="kbcli" label="kbcli">
+
+   ```bash
+   kbcli kubeblocks install -f backuprepo.yaml
+   ```
+
+   Use the command below to check the BackupRepo after installation.
+
+   ```bash
+   kbcli backuprepo list
+   ```
+
+   </TabItem>
+
+   </Tabs>
diff --git a/i18n/zh-cn/user-docs/handle-an-exception/full-disk-lock.md b/i18n/zh-cn/user-docs/handle-an-exception/full-disk-lock.md
@@ -28,22 +28,49 @@ KubeBlocks 的磁盘满锁功能确保了数据库的稳定性和可用性。该
 - 对于 PostgreSQL 和 MongoDB 数据库，当磁盘使用量达到 `highwatermark` 时，无论是读写用户还是超级用户都无法写入。
 - 组件级别的高水位的默认阈值为 `90`，当磁盘使用量达到 90% 时将锁定磁盘。而卷级别的设置为 `85`，会覆盖组件级别的阈值。
 
-在集群定义中，添加以下内容以启用磁盘满锁功能。你可以根据需要进行设置。
+1. 编辑数据库引擎的 ClusterDefinition Custom Resource（CR）。
 
-```yaml
-volumeProtectionSpec:
-  highWatermark: 90
-  volumes:
-  - highWatermark: 85
-    name: data
-```
+   本文档以 `mysql` 为例，可按需将 `mysql` 替换为 `postgresql` 或 `mongodb`。
 
-:::note
+   ```bash
+   kubectl edit clusterdefinition mysql
+   ```
 
-推荐将 `highWatermark` 设置为 90。
+2. 将 `volumeProtectionSpec` 字段添加至 `spec.componentDefs[]`，启用磁盘满锁功能。可根据需要设置 `highWatermark` 的值。
 
-:::
+   ```yaml
+   ...
+   spec:
+     componentDefs:
+     ...
+     - name: mysql
+       volumeProtectionSpec:
+         highWatermark: 90
+         volumes:
+         - highWatermark: 85
+           name: data
+     ...
+   ```
+
+   :::note
+
+   推荐将 `highWatermark` 设置为 90。
+
+   :::
+
+3. 保存设置，并退出。
 
 ## 禁用磁盘满锁
 
-从 ClusterDefinition 文件中删除 `volumeProtectionSpec`。
+从 ClusterDefinition 文件中删除 `volumeProtectionSpec` 即可禁用磁盘满锁功能。
+
+1. 编辑数据库引擎的 ClusterDefinition CR。
+
+   本文档以 `mysql` 为例，可按需将 `mysql` 替换为 `postgresql` 或 `mongodb`。
+
+   ```bash
+   kubectl edit clusterdefinition mysql
+   ```
+
+2. 删除 `volumeProtectionSpec` 字段。
+3. 保存设置，并退出。
diff --git a/i18n/zh-cn/user-docs/installation/install-kbcli.md b/i18n/zh-cn/user-docs/installation/install-kbcli.md
@@ -150,6 +150,12 @@ kbcli 目前支持 macOS、Windows 和 Linux 系统。
     curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash
     ```
 
+    如果想安装 kbcli 的指定版本，在上述命令后面加上 `-s` 和你想安装的版本号。
+
+    ```bash
+    curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s x.y.z
+    ```
+
 2. 执行 `kbcli version` 命令，检查 `kbcli` 版本并确保已成功安装。
 
 :::note
@@ -161,6 +167,10 @@ kbcli 目前支持 macOS、Windows 和 Linux 系统。
 </TabItem>
 </Tabs>
 
+## 升级 kbcli
+
+升级 kbcli 仅需[卸载当前版本](./uninstall-kubeblocks-and-kbcli.md#卸载-kbcli)，并安装新版本。
+
 ## (可选) 启用 kbcli 的自动补全功能
 
 `kbcli` 支持命令行自动补全。