Skip to content

Commit

Permalink
docs: update kbcli and backup repo docs, delete full disk lock doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@michelle-0808
michelle-0808 committed Jan 24, 2025
1 parent 41146d3 commit 3de5241
Show file tree
Hide file tree
Showing 4 changed files with 181 additions and 137 deletions.
6 changes: 6 additions & 0 deletions docs/user_docs/installation/install-kbcli.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,12 @@ Install kbcli using the `curl` command.

1. Install kbcli.

```bash
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
```
Expand Down
152 changes: 83 additions & 69 deletions docs/user_docs/maintenance/backup-and-restore/backup/backup-repo.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -88,74 +88,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.
Expand Down Expand Up @@ -560,4 +492,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:
* Verify 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 you see an `InvalidLocationConstraint` error, 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 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>
10 changes: 10 additions & 0 deletions i18n/zh-cn/user-docs/installation/install-kbcli.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -161,6 +167,10 @@ kbcli 目前支持 macOS、Windows 和 Linux 系统。
</TabItem>
</Tabs>

## 升级 kbcli

升级 kbcli 仅需[卸载当前版本](./uninstall-kubeblocks-and-kbcli.md#卸载-kbcli)，并安装新版本。

## (可选) 启用 kbcli 的自动补全功能

`kbcli` 支持命令行自动补全。
Expand Down
150 changes: 82 additions & 68 deletions i18n/zh-cn/user-docs/maintenance/backup-and-restore/backup/backup-repo.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -90,74 +90,6 @@ 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: <ACCESS KEY>
secretAccessKey: <SECRET KEY>
```
* `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 时指定配置文件。

<Tabs>

<TabItem value="kbcli" label="kbcli" default>

```bash
kbcli kubeblocks install -f backuprepo.yaml
```

安装完成后，可以执行命令查看 BackupRepo。

```bash
kbcli backuprepo list
```

</TabItem>

<TabItem value="kubectl" label="kubectl">

```bash
kubectl create -f backuprepo.yaml
```

安装完成后，可以执行命令查看 BackupRepo。

```bash
kubectl get backuprepo
```

</TabItem>

</Tabs>

### 手动配置 BackupRepo

如果在安装 KubeBlocks 时没有配置 BackupRepo 信息，你可以按照以下说明进行手动配置。
Expand Down Expand Up @@ -564,3 +496,85 @@ BackupRepo 是备份数据的存储仓库，支持配置 OSS（阿里云对象
</TabItem>
</Tabs>
:::note
如果 BackupRepo 状态显示 Failed，或者长时间处于 PreChecking 状态，可执行 `kubectl describe backuprepo my-repo` 或 `kbcli backuprepo describe my-repo` 命令，根据 `status.conditions` 中的信息，查找异常原因。
建议从以下方面进行排查：
* 检查配置内容是否正确，如 `endpoint`，`accessKeyId` 和 `secretAccessKey` 等参数是否正确填写。
* 对于其他自建的对象存储，如 Ceph Object Storage ，可尝试使用 `minio` StorageProvider。由于 `s3` StorageProvider 默认使用 virtual hosting 风格的 URL 访问服务端，自建对象存储很可能不支持这种访问方式。
* 如提示 `InvalidLocationConstraint` 错误，`region` 参数可尝试留空不填。
* 如果长时间处于 `PreChecking` 状态，很可能是网络问题。请确保在 K8s 集群内能正常访问存储服务，例如可运行一个 Pod，在 Pod 里面通过对应的客户端尝试连接存储服务。
* KubeBlocks 内部使用 [rclone](https://rclone.org/) 传输数据，请确保能通过 rclone 正常访问当前所使用的存储服务。
:::
### 自动配置 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: <ACCESS KEY>
secretAccessKey: <SECRET KEY>
```
* `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 时指定配置文件。
<Tabs>
<TabItem value="kbcli" label="kbcli" default>
```bash
kbcli kubeblocks install -f backuprepo.yaml
```
安装完成后，可以执行命令查看 BackupRepo。
```bash
kbcli backuprepo list
```
</TabItem>
<TabItem value="kubectl" label="kubectl">
```bash
kubectl create -f backuprepo.yaml
```
安装完成后，可以执行命令查看 BackupRepo。
```bash
kubectl get backuprepo
```
</TabItem>
</Tabs>

0 comments on commit 3de5241

Please sign in to comment.