diff --git a/docs/user_docs/handle-an-exception/full-disk-lock.md b/docs/user_docs/handle-an-exception/full-disk-lock.md deleted file mode 100644 index 0397b09014e..00000000000 --- a/docs/user_docs/handle-an-exception/full-disk-lock.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Full disk lock -description: How to configure disk lock when it is about to be full -sidebar_position: 2 -sidebar_label: Full disk lock ---- - -# Full disk lock - -The full disk lock function of KubeBlocks ensures the stability and availability of a database. This function triggers a disk lock when the disk usage reaches a set threshold, thereby pausing write operations and only allowing read operations. Such a mechanism prevents a database from being affected by disk space exhaustion. - -## Mechanism of lock/unlock - -When the space water level of any configured volume exceeds the defined threshold, the instance is locked (read-only). Meanwhile, the system sends a related warning event, including the specific threshold and space usage information of each volume. - -When the space water level of all configured volumes falls below the defined threshold, the instance is unlocked (read and write). Meanwhile, the system sends a related warning event, including the specific threshold and space usage information of each volume. - -:::note - -1. The full disk lock function currently supports global (ClusterDefinition) enabling or disabling and does not support Cluster dimension control. Dynamically enabling or disabling this function may affect the existing Cluster instances that use this ClusterDefinition and cause them to restart. Please operate with caution. - -2. The full disk locking function relies on the read permission (get & list) of the two system resource nodes and nodes/stats. If you create an instance via kbcli, make sure to grant the controller administrative rights to the ClusterRoleBinding. - -3. Currently, full disk lock is available for ApeCloud MySQL, PostgreSQL and MongoDB. - -::: - -## 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 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. - -```bash -volumeProtectionSpec: - highWatermark: 90 - volumes: - - highWatermark: 85 - name: data -``` - -:::note - -The recommended value of `highWatermark` is 90. - -::: - -## Disable full disk lock - -Delete `volumeProtectionSpec` from the cluster definition file. diff --git a/docs/user_docs/installation/install-kbcli.md b/docs/user_docs/installation/install-kbcli.md index a2eddb6d3e6..0222e9e3634 100644 --- a/docs/user_docs/installation/install-kbcli.md +++ b/docs/user_docs/installation/install-kbcli.md @@ -42,9 +42,11 @@ You can install kbcli with `curl` or `brew`. ```bash curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s x.y.z ``` + You can view all versions of kbcli, including alpha and beta releases, on the [kbcli releases list](https://github.com/apecloud/kbcli/releases). To get stable releases, use this command: + ```bash curl -s "https://api.github.com/repos/apecloud/kbcli/releases?per_page=100&page=1" | jq -r '.[] | select(.prerelease == false) | .tag_name' | sort -V -r ``` @@ -148,6 +150,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 +167,10 @@ Install kbcli using the `curl` command. +## 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 index e6b7376fe02..a8c2cc1ba7f 100644 --- 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: - secretAccessKey: - ``` - - * `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. - - - - - - ```bash - kubectl create -f backuprepo.yaml - ``` - - Use the command below to check the BackupRepo after installation. - - ```bash - kubectl get backuprepo - ``` - - - - - - ```bash - kbcli kubeblocks install -f backuprepo.yaml - ``` - - Use the command below to check the BackupRepo after installation. - - ```bash - kbcli backuprepo list - ``` - - - - - ### Manual BackupRepo configuration If you do not configure the BackupRepo information when installing KubeBlocks, you can manually configure it by the following instructions. @@ -389,6 +320,40 @@ If you do not configure the BackupRepo information when installing KubeBlocks, y + + + ```bash + # Create a secret to save the access key for the S3 compatible storage + kubectl create secret generic s3-comp-credential-for-backuprepo \ + -n kb-system \ + --from-literal=accessKeyId= \ + --from-literal=secretAccessKey= + + # Create the BackupRepo resource + kubectl apply -f - <<-'EOF' + apiVersion: dataprotection.kubeblocks.io/v1alpha1 + kind: BackupRepo + metadata: + name: my-repo + annotations: + dataprotection.kubeblocks.io/is-default-repo: "true" + spec: + storageProviderRef: s3-compatible + accessMethod: Tool + pvReclaimPolicy: Retain + volumeCapacity: 100Gi + config: + bucket: test-kb-backup + endpoint: + forcePathStyle: true + credential: + name: s3-comp-credential-for-backuprepo + namespace: kb-system + EOF + ``` + + + 3. View the BackupRepo and its status. If the status is `Ready`, the BackupRepo is ready. @@ -430,10 +395,12 @@ If you do not configure the BackupRepo information when installing KubeBlocks, y --bucket test-kb-backup \ --access-key-id \ --secret-access-key \ - --access-method Tool \ # Mount is also acceptable + --access-method Tool \ --default ``` + You can also specify `--access-method` as `Mount`. + @@ -443,7 +410,20 @@ If you do not configure the BackupRepo information when installing KubeBlocks, y --provider oss \ --region cn-zhangjiakou \ --bucket test-kb-backup \ - # --endpoint https://oss-cn-zhangjiakou-internal.aliyuncs.com \ can show the specified oss endpoint + --access-key-id \ + --secret-access-key \ + --access-method Tool \ + --default + ``` + + You can also explicitly specify the OSS endpoint using the `--endpoint` flag. For example, + + ```bash + kbcli backuprepo create my-repo \ + --provider oss \ + --region cn-zhangjiakou \ + --bucket test-kb-backup \ + --endpoint https://oss-cn-zhangjiakou-internal.aliyuncs.com \ --access-key-id \ --secret-access-key \ --access-method Tool \ @@ -469,12 +449,12 @@ If you do not configure the BackupRepo information when installing KubeBlocks, y + For COS, the naming format of a bucket is ``，where APPID is automatically generated by Tencent Cloud. When setting `--bucket`, first create the bucket on the Tencent Cloud console and retrieve the bucket name. + ```bash kbcli backuprepo create my-repo \ --provider cos \ --region ap-guangzhou \ - # In COS, the naming format of a bucket is ，where APPID is automatically generated by Tencent Cloud - # When setting up, first create the bucket through Tencent Cloud's console and obtain the bucket name --bucket test-kb-backup \ --access-key-id \ --secret-access-key \ @@ -487,9 +467,8 @@ 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 \ @@ -498,6 +477,8 @@ If you do not configure the BackupRepo information when installing KubeBlocks, y --default ``` + GCS supported by KubeBlocks is the S3-compatible version provided by Google Cloud. + @@ -505,7 +486,7 @@ If you do not configure the BackupRepo information when installing KubeBlocks, y ```bash kbcli backuprepo create my-repo \ --provider minio \ - --endpoint \ # The access address for the deployed MinIO is: http://minio.kb-system.svc.cluster.local:9000 + --endpoint \ --bucket test-minio \ --access-key-id \ --secret-access-key \ @@ -513,16 +494,21 @@ If you do not configure the BackupRepo information when installing KubeBlocks, y --default ``` + The address for the deployed MinIO is http://minio.kb-system.svc.cluster.local:9000. + - + ```bash kbcli backuprepo create my-repo \ - --provider pvc \ - --storage-class-name "nfs-storage" \ - --access-mode "ReadWriteMany" \ - --volume-capacity "100Gi" \ + --provider s3-compatible \ + --endpoint \ + --bucket test-minio \ + --access-key-id \ + --secret-access-key \ + --access-method Tool \ + --force-path-style=true \ --default ``` @@ -534,7 +520,7 @@ If you do not configure the BackupRepo information when installing KubeBlocks, y * `my-repo` is the name of the created backup repository. If you do not specify a name, the system creates a random name, following the format `backuprepo-xxxxx`. * `--default` means that this repository is set as the default repository. Note that there can only be one default global repository. If there exist multiple default repositories, KubeBlocks cannot decide which one to use (similar to the default StorageClass of Kubernetes), which further results in backup failure. Using kbcli to create BackupRepo can avoid such problems because kbcli checks whether there is another default repository before creating a new one. - * `--provider` specifies the storage type, i.e. `storageProvider`, and is required for creating a BakcupRepo. The available values are `s3`, `cos`, `gcs-s3comp`, `obs`, `oss`, `minio`, `ftp`, and `nfs`. Parameters for different storage providers vary and you can run `kbcli backuprepo create --provider STORAGE-PROVIDER-NAME -h` to view the flags for different storage providers. Please note that `--provider` is mandatory in configuration. + * `--provider` specifies the storage type, i.e. `storageProvider`, and is required for creating a BakcupRepo. The available values are `s3`, `cos`, `gcs-s3comp`, `obs`, `oss`, `minio`, `s3-compatible`, `ftp`, and `nfs`. Parameters for different storage providers vary and you can run `kbcli backuprepo create --provider STORAGE-PROVIDER-NAME -h` to view the flags for different storage providers. Please note that `--provider` is mandatory in configuration. After `kbcli backuprepo create` is executed successfully, the system creates the K8s resource whose type is `BackupRepo`. You can modify the annotation of this resource to adjust the default repository. @@ -560,4 +546,86 @@ If you do not configure the BackupRepo information when installing KubeBlocks, y - \ No newline at end of file + + +:::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 `s3-compatible` 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: + secretAccessKey: + ``` + + * `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`, `s3-compatible`, `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. + + + + + + ```bash + kubectl create -f backuprepo.yaml + ``` + + Use the command below to check the BackupRepo after installation. + + ```bash + kubectl get backuprepo + ``` + + + + + + ```bash + kbcli kubeblocks install -f backuprepo.yaml + ``` + + Use the command below to check the BackupRepo after installation. + + ```bash + kbcli backuprepo list + ``` + + + + 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 deleted file mode 100644 index 1ecb062476c..00000000000 --- a/i18n/zh-cn/user-docs/handle-an-exception/full-disk-lock.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: 磁盘满锁 -description: 磁盘空间将满时，如何设置磁盘锁定 -sidebar_position: 2 -sidebar_label: 磁盘满锁 ---- - -# 磁盘满锁 - -KubeBlocks 的磁盘满锁功能确保了数据库的稳定性和可用性。该功能在磁盘使用量达到设定的阈值时触发磁盘锁定，从而暂停写操作，只允许读操作。这样的机制可以防止数据库受到磁盘空间耗尽的影响。 - -## 锁定/解锁机制 - -只要有某些卷的空间水位超过定义的阈值，实例就会被锁定（只读）。同时，系统会发送相关警报，包括每个卷的具体阈值和空间使用信息。 -当所有卷的空间水位都低于定义的阈值时，实例将被解锁（读写）。同时，系统也会发送相关警报，包括每个卷的具体阈值和空间使用信息。 - -:::note - -1. 磁盘满锁功能目前支持全局（ClusterDefinition）启用或禁用，暂不支持集群维度的控制。动态启用或禁用此功能可能会影响使用此 ClusterDefinition 的现有集群实例，并导致它们重新启动。请谨慎操作。 -2. 磁盘满锁功能依赖于两个系统资源节点和 nodes/stats 的读取权限（get 和 list）。如果你通过 kbcli 创建实例，请确保为控制器授予 ClusterRoleBinding 的管理权限。 -3. 支持的引擎：ApeCloud MySQL、PostgreSQL、MongoDB。 - -::: - -## 启用磁盘满锁 - -- 对于 MySQL 数据库，当磁盘使用量达到 `highwatermark` 值时，读写用户无法写入磁盘，而超级用户仍然可以写入。 -- 对于 PostgreSQL 和 MongoDB 数据库，当磁盘使用量达到 `highwatermark` 时，无论是读写用户还是超级用户都无法写入。 -- 组件级别的高水位的默认阈值为 `90`，当磁盘使用量达到 90% 时将锁定磁盘。而卷级别的设置为 `85`，会覆盖组件级别的阈值。 - -在集群定义中，添加以下内容以启用磁盘满锁功能。你可以根据需要进行设置。 - -```yaml -volumeProtectionSpec: - highWatermark: 90 - volumes: - - highWatermark: 85 - name: data -``` - -:::note - -推荐将 `highWatermark` 设置为 90。 - -::: - -## 禁用磁盘满锁 - -从 ClusterDefinition 文件中删除 `volumeProtectionSpec`。 diff --git a/i18n/zh-cn/user-docs/installation/install-kbcli.md b/i18n/zh-cn/user-docs/installation/install-kbcli.md index 1cb321a8187..43e19305a99 100644 --- 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 系统。 +## 升级 kbcli + +升级 kbcli 仅需[卸载当前版本](./uninstall-kubeblocks-and-kbcli.md#卸载-kbcli)，并安装新版本。 + ## (可选) 启用 kbcli 的自动补全功能 `kbcli` 支持命令行自动补全。 diff --git a/i18n/zh-cn/user-docs/maintenance/backup-and-restore/backup/backup-repo.md b/i18n/zh-cn/user-docs/maintenance/backup-and-restore/backup/backup-repo.md index 3eeddb30c07..db90fa32234 100644 --- a/i18n/zh-cn/user-docs/maintenance/backup-and-restore/backup/backup-repo.md +++ b/i18n/zh-cn/user-docs/maintenance/backup-and-restore/backup/backup-repo.md @@ -13,7 +13,7 @@ import TabItem from '@theme/TabItem'; ## 概述 -BackupRepo 是备份数据的存储仓库，支持配置 OSS（阿里云对象存储），S3（亚马逊对象存储），COS（腾讯云对象存储），GCS（谷歌云对象存储），OBS（华为云对象存储），MinIO 等兼容 S3 协议的对象存储作为备份仓库，同时支持 K8s 原生的 PVC 作为备份仓库。 +BackupRepo 是备份数据的存储仓库，支持配置 OSS（阿里云对象存储），S3（亚马逊对象存储），COS（腾讯云对象存储），GCS（谷歌云对象存储），OBS（华为云对象存储），MinIO 等兼容 S3 协议的对象存储作为备份仓库。 用户可以创建多个 BackupRepo 以适应不同的场景。例如，根据不同的业务需求，可以把业务 A 的数据存储在 A 仓库，把业务 B 的数据存储在 B 仓库，或者可以按地区配置多个仓库以实现异地容灾。在创建备份时，你需要指定备份仓库。你也可以创建一个默认的备份仓库，如果在创建备份时未指定具体的仓库，KubeBlocks 将使用此默认仓库来存储备份数据。 @@ -34,12 +34,18 @@ BackupRepo 是备份数据的存储仓库，支持配置 OSS（阿里云对象 1. 在 `kb-system` 命名空间中安装 MinIO。 + ```bash + 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" + ``` + + 如果上述仓库地址网络无法连接，可使用以下命令安装。 + ```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" ``` - 获取初始的用户名和密码： +2. 获取初始的用户名和密码. ```bash # 初始 username @@ -49,7 +55,7 @@ BackupRepo 是备份数据的存储仓库，支持配置 OSS（阿里云对象 echo $(kubectl get secret --namespace kb-system minio -o jsonpath="{.data.root-password}" | base64 -d) ``` -2. 生成连接凭证。 +3. 生成连接凭证。 执行 `kubectl port-forward --namespace kb-system svc/minio 9001:9001`，然后访问 `127.0.0.1:9001` 进入登录页面。 @@ -57,7 +63,7 @@ BackupRepo 是备份数据的存储仓库，支持配置 OSS（阿里云对象 ![backup-and-restore-backup-repo-1](./../../../../img/backup-and-restore-backup-repo-1.png) -3. 创建 bucket。 +4. 创建 bucket。 在 MinIO 仪表盘上创建一个名为 `test-minio` 的存储桶。 @@ -74,8 +80,8 @@ BackupRepo 是备份数据的存储仓库，支持配置 OSS（阿里云对象 准备好对象存储服务后，就可以配置 BackupRepo 了。KubeBlocks 提供两种配置方式： -* 安装 KubeBlocks 时自动配置 BackupRepo； * 按需手动配置 BackupRepo。 +* 安装 KubeBlocks 时自动配置 BackupRepo。 ### 访问 BackupRepo @@ -90,254 +96,26 @@ BackupRepo 是备份数据的存储仓库，支持配置 OSS（阿里云对象 不过，由于备份和恢复任务需要运行在数据库集群所在的 namespace 下，在 “Tool” 方式下，我们会自动将访问远端存储所需的密钥以 secret 资源的形式同步到这些 namespace 中，以供我们的数据传输工具使用。在多租户隔离的情况下，如果你认为这种同步 secret 的做法会带来安全隐患，可以选择使用 “Mount”。 -### 自动配置 BackupRepo - -安装 KubeBlocks 时，可以通过配置文件指定 BackupRepo 相关信息，KubeBlocks 会根据配置信息创建 BackupRepo 并自动安装必要的 CSI Driver。 - -1. 准备配置文件。 - - 以 AWS 的 S3 为例，配置文件 `backuprepo.yaml` 如下： - - ```yaml - backupRepo: - create: true - storageProvider: s3 - config: - region: cn-northwest-1 - bucket: test-kb-backup - secrets: - accessKeyId: - secretAccessKey: - ``` - - * `region` 表示 S3 所在区域。 - * `bucket` 表示 S3 的桶名称。 - * `accessKeyId` 表示 AWS 的 Access Key。 - * `secretAccessKey` 表示 AWS 的 Secret Key。 - * `storageProvider` 表示对象存储提供者，该示例中为 s3。 - -:::note - -* 在 KubeBlocks v0.8.0 中，`storageProvider` 目前可选 `s3`、`cos`、`gcs-s3comp`、`obs`、`oss`、`minio`、`pvc`、`ftp`、`nfs`。 -* 不同 `storageProvider` 所需的配置信息并不统一，上面展示的 `config` 和 `secrets` 适用于 S3。 -* 执行 `kubectl get storageproviders.dataprotection.kubeblocks.io` 命令可以查看支持的 `storageProvider`。 - -::: - -2. 安装 KubeBlocks 时指定配置文件。 - - - - - - ```bash - kbcli kubeblocks install -f backuprepo.yaml - ``` - - 安装完成后，可以执行命令查看 BackupRepo。 - - ```bash - kbcli backuprepo list - ``` - - - - - - ```bash - kubectl create -f backuprepo.yaml - ``` - - 安装完成后，可以执行命令查看 BackupRepo。 - - ```bash - kubectl get backuprepo - ``` - - - - - ### 手动配置 BackupRepo 如果在安装 KubeBlocks 时没有配置 BackupRepo 信息，你可以按照以下说明进行手动配置。 - + 1. 安装 S3 CSI driver （仅访问方式为 “Mount” 时需要安装）。 ```bash - # 启用 CSI-S3 引擎 - kbcli addon enable csi-s3 - - # 如需控制 addon 的安装，则添加其他参数 - # 默认 csi-s3 会在所有 node 安装 daemonSet pod，可以配置 tolerations，安装在指定 node - kbcli addon enable csi-s3 \ - --tolerations '[{"key":"taintkey","operator":"Equal","effect":"NoSchedule","value":"true"}]' \ - --tolerations 'daemonset:[{"key":"taintkey","operator":"Equal","effect":"NoSchedule","value":"true"}]' - - # 查看 CSI-S3 状态，确保其状态为 enabled - kbcli addon list csi-s3 + helm repo add kubeblocks https://jihulab.com/api/v4/projects/85949/packages/helm/stable + helm install csi-s3 kubeblocks/csi-s3 --version=0.7.0 -n kb-system ``` -2. 创建 BackupRepo。 - - - - - - ```bash - kbcli backuprepo create my-repo \ - --provider s3 \ - --region cn-northwest-1 \ - --bucket test-kb-backup \ - --access-key-id \ - --secret-access-key \ - --access-method Tool \ # 也可以填 Mount - --default - ``` - - - - - - ```bash - kbcli backuprepo create my-repo \ - --provider oss \ - --region cn-zhangjiakou \ - --bucket test-kb-backup \ - # --endpoint https://oss-cn-zhangjiakou-internal.aliyuncs.com \ 可以显示指定 oss endpoint - --access-key-id \ - --secret-access-key \ - --access-method Tool \ - --default - ``` - - - - - - ```bash - kbcli backuprepo create my-repo \ - --provider obs \ - --region cn-north-4 \ - --bucket test-kb-backup \ - --access-key-id \ - --secret-access-key \ - --access-method Tool \ - --default - ``` - - - - - - ```bash - kbcli backuprepo create my-repo \ - --provider cos \ - --region ap-guangzhou \ - # 腾讯云中存储桶的命名格式为 ，APPID 为腾讯云自动生成 - # 设置 bucket 时先通过腾讯云的控制台创建 bucket，获取存储桶名称 - --bucket test-kb-backup \ - --access-key-id \ - --secret-access-key \ - --access-method Tool \ - --default - ``` - - - - - - ```bash - # 目前的 gcs 为谷歌云的 s3 兼容版 - kbcli backuprepo create my-repo \ - --provider gcs \ - --region auto \ - --bucket test-kb-backup \ - --access-key-id \ - --secret-access-key \ - --access-method Tool \ - --default - ``` - - - - - - ```bash - kbcli backuprepo create my-repo \ - --provider minio \ - --endpoint \ # 以上部署的 MinIO 的访问地址为 http://minio.kb-system.svc.cluster.local:9000 - --bucket test-minio \ - --access-key-id \ - --secret-access-key \ - --access-method Tool \ - --default - ``` - - - - - - ```bash - kbcli backuprepo create my-repo \ - --provider pvc \ - --storage-class-name "nfs-storage" \ - --access-mode "ReadWriteMany" \ - --volume-capacity "100Gi" \ - --default - ``` - - - - - 以上命令创建了一个名为 `my-repo` 的默认备份仓库。 - - * `my-repo` 为仓库名，可以留空不填，此时 kbcli 会使用形如 `backuprepo-xxxxx` 的随机名字。 - * `--default` 表示该仓库是默认仓库。全局只能有一个默认仓库，如果系统中存在多个默认仓库，KubeBlocks 无法选出应该使用哪个仓库（这个行为跟 K8s 的 default StorageClass 类似），会导致备份失败。使用 kbcli 创建 BackupRepo 能避免出现这种情况，因为 kbcli 在创建时会确保当前没有第二个默认仓库。 - * `--provider` 参数对应后端存储类型，即 `storageProvider`，可选值为 `s3`、`cos`、`gcs-s3comp`、`obs`、`oss`、`minio`、`ftp`、`nfs`。不同存储所需的命令行参数不同，可以通过 `kbcli backuprepo create --provider STORAGE-PROVIDER-NAME -h` 命令查看参数信息（注意 `--provider` 参数是必需的）。 - - `kbcli backuprepo create` 命令执行成功后，就会在系统中创建一个类型为 BackupRepo 的 K8s 资源，可以通过修改该资源的 annotation 来调整默认仓库。 - - ```bash - # 取消默认仓库 - kubectl annotate backuprepo old-default-repo \ - --overwrite=true \ - dataprotection.kubeblocks.io/is-default-repo=false - ``` - - ```bash - # 设置新的默认仓库 - kubectl annotate backuprepo backuprepo-4qms6 \ - --overwrite=true \ - dataprotection.kubeblocks.io/is-default-repo=true - ``` - -3. 查看 BackupRepo 及其状态。 - - 如果 STATUS 为 `Ready`，说明 BackupRepo 已经准备就绪。 - - ```bash - kbcli backuprepo list - ``` - - - - - -1. 安装 S3 CSI driver （仅访问方式为 “Mount” 时需要安装）。 + 您也可以自定义安装 S3 CSI driver。例如，`csi-s3` 默认在所有节点上安装一个 daemonSet Pod，您可以通过配置容忍，实现仅在指定节点上安装。 ```bash helm repo add kubeblocks https://jihulab.com/api/v4/projects/85949/packages/helm/stable - helm install csi-s3 kubeblocks/csi-s3 --version=0.7.0 -n kb-system - - # You can add flags to customize the installation of this addon - # CSI-S3 installs a daemonSet Pod on all nodes by default and you can set tolerations to install it on the specified node - --set-json tolerations='[{"key":"taintkey","operator":"Equal","effect":"NoSchedule","value":"taintValue"}]' - --set-json daemonsetTolerations='[{"key":"taintkey","operator":"Equal","effect":"NoSchedule","value":"taintValue"}]' + helm install csi-s3 kubeblocks/csi-s3 --version=0.7.0 -n kb-system --set-json tolerations='[{"key":"taintkey","operator":"Equal","effect":"NoSchedule","value":"taintValue"}]' --set-json daemonsetTolerations='[{"key":"taintkey","operator":"Equal","effect":"NoSchedule","value":"taintValue"}]' ``` 2. 创建 BackupRepo。 @@ -553,6 +331,40 @@ BackupRepo 是备份数据的存储仓库，支持配置 OSS（阿里云对象 + + + ```bash + # 创建 secret，用于保存 S3-compatible 存储的访问密钥 + kubectl create secret generic s3-comp-credential-for-backuprepo \ + -n kb-system \ + --from-literal=accessKeyId= \ + --from-literal=secretAccessKey= + + # 创建 BackupRepo 资源 + kubectl apply -f - <<-'EOF' + apiVersion: dataprotection.kubeblocks.io/v1alpha1 + kind: BackupRepo + metadata: + name: my-repo + annotations: + dataprotection.kubeblocks.io/is-default-repo: "true" + spec: + storageProviderRef: s3-compatible + accessMethod: Tool + pvReclaimPolicy: Retain + volumeCapacity: 100Gi + config: + bucket: test-kb-backup + endpoint: + forcePathStyle: true + credential: + name: s3-comp-credential-for-backuprepo + namespace: kb-system + EOF + ``` + + + 3. 查看 BackupRepo 及其状态。 如果 STATUS 为 `Ready`，说明 BackupRepo 已经准备就绪。 @@ -563,4 +375,270 @@ BackupRepo 是备份数据的存储仓库，支持配置 OSS（阿里云对象 + + +1. 安装 S3 CSI driver（仅访问方式为 “Mount” 时需要安装）。 + + ```bash + # 启用 CSI-S3 引擎 + kbcli addon enable csi-s3 + + # 如需控制 addon 的安装，则添加其他参数 + # 默认 csi-s3 会在所有 node 安装 daemonSet pod，可以配置 tolerations，安装在指定 node + kbcli addon enable csi-s3 \ + --tolerations '[{"key":"taintkey","operator":"Equal","effect":"NoSchedule","value":"true"}]' \ + --tolerations 'daemonset:[{"key":"taintkey","operator":"Equal","effect":"NoSchedule","value":"true"}]' + + # 查看 CSI-S3 状态，确保其状态为 enabled + kbcli addon list csi-s3 + ``` + +2. 创建 BackupRepo。 + + + + + + ```bash + kbcli backuprepo create my-repo \ + --provider s3 \ + --region cn-northwest-1 \ + --bucket test-kb-backup \ + --access-key-id \ + --secret-access-key \ + --access-method Tool \ + --default + ``` + + 你也可将 `--access-method` 配置为 `Mount`。 + + + + + + ```bash + kbcli backuprepo create my-repo \ + --provider oss \ + --region cn-zhangjiakou \ + --bucket test-kb-backup \ + --access-key-id \ + --secret-access-key \ + --access-method Tool \ + --default + ``` + + 你还可以使用 `--endpoint` 显示指定 OSS endpoint，示例如下： + + ```bash + kbcli backuprepo create my-repo \ + --provider oss \ + --region cn-zhangjiakou \ + --bucket test-kb-backup \ + --endpoint https://oss-cn-zhangjiakou-internal.aliyuncs.com \ + --access-key-id \ + --secret-access-key \ + --access-method Tool \ + --default + ``` + + + + + + ```bash + kbcli backuprepo create my-repo \ + --provider obs \ + --region cn-north-4 \ + --bucket test-kb-backup \ + --access-key-id \ + --secret-access-key \ + --access-method Tool \ + --default + ``` + + + + + + 腾讯云中存储桶的命名格式为 ``，APPID 为腾讯云自动生成。设置 `--bucket` 时，请先通过腾讯云的控制台创建 bucket，获取存储桶名称。 + + ```bash + kbcli backuprepo create my-repo \ + --provider cos \ + --region ap-guangzhou \ + --bucket test-kb-backup \ + --access-key-id \ + --secret-access-key \ + --access-method Tool \ + --default + ``` + + + + + + ```bash + kbcli backuprepo create my-repo \ + --provider gcs-s3comp \ + --region auto \ + --bucket test-kb-backup \ + --access-key-id \ + --secret-access-key \ + --access-method Tool \ + --default + ``` + + KubeBlocks 目前支持的 GCS 为谷歌云的 S3 兼容版。 + + + + + + ```bash + kbcli backuprepo create my-repo \ + --provider minio \ + --endpoint \ + --bucket test-minio \ + --access-key-id \ + --secret-access-key \ + --access-method Tool \ + --default + ``` + + 以上部署的 MinIO 的访问地址为 http://minio.kb-system.svc.cluster.local:9000。 + + + + + + ```bash + kbcli backuprepo create my-repo \ + --provider s3-compatible \ + --endpoint \ + --bucket test-minio \ + --access-key-id \ + --secret-access-key \ + --access-method Tool \ + --force-path-style=true \ + --default + ``` + + + + + + 以上命令创建了一个名为 `my-repo` 的默认备份仓库。 + + * `my-repo` 为仓库名，可以留空不填，此时 kbcli 会使用形如 `backuprepo-xxxxx` 的随机名字。 + * `--default` 表示该仓库是默认仓库。全局只能有一个默认仓库，如果系统中存在多个默认仓库，KubeBlocks 无法选出应该使用哪个仓库（这个行为跟 K8s 的 default StorageClass 类似），会导致备份失败。使用 kbcli 创建 BackupRepo 能避免出现这种情况，因为 kbcli 在创建时会确保当前没有第二个默认仓库。 + * `--provider` 参数对应后端存储类型，即 `storageProvider`，可选值为 `s3`、`cos`、`gcs-s3comp`、`obs`、`oss`、`minio`、`s3-compatible`、`ftp`、`nfs`。不同存储所需的命令行参数不同，可以通过 `kbcli backuprepo create --provider STORAGE-PROVIDER-NAME -h` 命令查看参数信息（注意 `--provider` 参数是必需的）。 + + `kbcli backuprepo create` 命令执行成功后，就会在系统中创建一个类型为 BackupRepo 的 K8s 资源，可以通过修改该资源的 annotation 来调整默认仓库。 + + ```bash + # 取消默认仓库 + kubectl annotate backuprepo old-default-repo \ + --overwrite=true \ + dataprotection.kubeblocks.io/is-default-repo=false + ``` + + ```bash + # 设置新的默认仓库 + kubectl annotate backuprepo backuprepo-4qms6 \ + --overwrite=true \ + dataprotection.kubeblocks.io/is-default-repo=true + ``` + +3. 查看 BackupRepo 及其状态。 + + 如果 STATUS 为 `Ready`，说明 BackupRepo 已经准备就绪。 + + ```bash + kbcli backuprepo list + ``` + + + + +:::note + +如果 BackupRepo 状态显示 Failed，或者长时间处于 PreChecking 状态，可执行 `kubectl describe backuprepo my-repo` 或 `kbcli backuprepo describe my-repo` 命令，根据 `status.conditions` 中的信息，查找异常原因。 + +建议从以下方面进行排查： + +* 检查配置内容是否正确，如 `endpoint`，`accessKeyId` 和 `secretAccessKey` 等参数是否正确填写。 +* 对于其他自建的对象存储，如 Ceph Object Storage ，可尝试使用 `s3-compatible` StorageProvider。由于 `s3` StorageProvider 默认使用 virtual hosting 风格的 URL 访问服务端，自建对象存储很可能不支持这种访问方式。 +* 如提示 `InvalidLocationConstraint` 错误，请先检查 `region` 参数是否正确填写。如果仍有 `InvalidLocationConstraint` 报错，可尝试将 `region` 参数留空不填。 +* 如果长时间处于 `PreChecking` 状态，很可能是网络问题。请确保在 K8s 集群内能正常访问存储服务，例如可运行一个 Pod，在 Pod 里面通过对应的客户端尝试连接存储服务。 +* KubeBlocks 内部使用 [rclone](https://rclone.org/) 传输数据，请确保能通过 rclone 正常访问当前所使用的存储服务。 + +::: + +### 自动配置 BackupRepo + +安装 KubeBlocks 时，可以通过配置文件指定 BackupRepo 相关信息，KubeBlocks 会根据配置信息创建 BackupRepo。 + +1. 准备配置文件。 + + 以 AWS 的 S3 为例，配置文件 `backuprepo.yaml` 如下： + + ```yaml + backupRepo: + create: true + storageProvider: s3 + config: + region: cn-northwest-1 + bucket: test-kb-backup + secrets: + accessKeyId: + secretAccessKey: + ``` + + * `region` 表示 S3 所在区域。 + * `bucket` 表示 S3 的桶名称。 + * `accessKeyId` 表示 AWS 的 Access Key。 + * `secretAccessKey` 表示 AWS 的 Secret Key。 + * `storageProvider` 表示对象存储提供者，该示例中为 s3。 + +:::note + +* KubeBlocks 中，`storageProvider` 目前可选 `s3`、`cos`、`gcs-s3comp`、`obs`、`oss`、`minio`、`s3-compatible`、`ftp`、`nfs`。 +* 不同 `storageProvider` 所需的配置信息并不统一，上面展示的 `config` 和 `secrets` 适用于 S3。 +* 执行 `kubectl get storageproviders.dataprotection.kubeblocks.io` 命令可以查看支持的 `storageProvider`。 + +::: + +2. 安装 KubeBlocks 时指定配置文件。 + + + + + + ```bash + kbcli kubeblocks install -f backuprepo.yaml + ``` + + 安装完成后，可以执行命令查看 BackupRepo。 + + ```bash + kbcli backuprepo list + ``` + + + + + + ```bash + kubectl create -f backuprepo.yaml + ``` + + 安装完成后，可以执行命令查看 BackupRepo。 + + ```bash + kubectl get backuprepo + ``` + + + +