# 腾讯 COS

本指南介绍如何将[腾讯云对象存储](https://cloud.tencent.com/product/cos)配置为Alluxio的底层存储系统。\
腾讯云对象存储（COS）是腾讯云为海量数据提供的分布式存储服务，可通过 HTTP/HTTPS 协议访问。\
它可以存储海量数据，并具有无感带宽和容量扩展特性，是大数据计算和分析的理想数据池。

## 先决条件

Alluxio 以集群模式在多台计算机上运行，因此需要在这些计算机上部署其二进制软件包。

在将 COS 与 Alluxio 结合使用之前，要么创建一个新的存储桶，要么使用现有的存储桶。\
此外，无论是创建新目录还是选择现有目录，都要确定要在该数据桶中使用的目录。\
在本指南中，COS 存储桶的名称是 `COS_BUCKET`，存储桶内的目录是 `COS_DATA`，存储桶区域是 `COS_REGION`。

## 基本设置

使用 [挂载表操作](https://documentation.alluxio.io/ee-ai-cn/ai-3.6/overview/namespace#挂载表操作)\
来增加一个新的挂载点, 指定Alluxio路径在其上创建挂载，指定COS的路径作为UFS URI。\
密钥和配置选项也可以通过指定 `--option` 标志作为挂载命令的一部分来指定，如[配置挂载点](https://documentation.alluxio.io/ee-ai-cn/ai-3.6/overview/namespace#对不同挂载点使用不同的配置)所述。

以下是通过 Operator 创建挂载点的 `ufs.yaml` 文件示例：

```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: UnderFileSystem
metadata:
  name: alluxio-cos
  namespace: alx-ns
spec:
  alluxioCluster: alluxio-cluster
  path: cos://<COS_BUCKET>/<COS_DIRECTORY>
  mountPath: /cos
  mountOptions:
    fs.cos.access.key: <COS_ACCESS_KEY>
    fs.cos.secret.key: <COS_ACCESS_KEY_SECRET>
    fs.cos.region: <COS_REGION>
    fs.cos.app.id: <COS_APP_ID>
```

不使用 Operator 的情况下, 将 `cos://<COS_BUCKET>/<COS_DIRECTORY>` 挂载到 `/cos` 的示例命令如下：

```shell
bin/alluxio mount add --path /cos/ --ufs-uri cos://<COS_BUCKET>/<COS_DIRECTORY> \
  --option fs.cos.access.key=<COS_SECRET_ID> --option fs.cos.secret.key=<COS_SECRET_KEY> \
  --option fs.cos.region=<COS_REGION> --option fs.cos.app.id=<COS_APP_ID>
```

注意：COS 存储桶的完整名称为`<COS_BUCKET>-<COS_APP_ID>`。`path`的值应仅包含`<COS_BUCKET>`部分，省略 `<COS_APP_ID>`部分，最终格式为 `cos://<COS_BUCKET>/<COS_DIRECTORY>`。此外，请确保将 `fs.cos.app.id`设置为 `<COS_APP_ID>`。

请注意，如果您想挂载COS bucket的根，请在bucket名称后面添加一个斜杠（例如`cos://COS_BUCKET/`).

## 高级设置

请注意，配置选项可以指定为mount选项，也可以作为`conf/alluxio-site.properties`中的配置属性。\
以下部分将介绍如何将配置设置为属性，但也可以通过 `--option <key>=<value>` 将它们设置为挂载选项。

### COS 多段上传

默认的上传方法是一次性从头到尾上传一个文件。\
我们使用多段上传方法将一个文件分成多个段上传，每个段都将在一个线程中上传。\
上传时不会生成任何临时文件。

要启用 COS 多段上传，需要修改 `conf/alluxio-site.properties`，加入以下内容：

```properties
alluxio.underfs.cos.multipart.upload.enabled=true
```

您还可以在 `conf/alluxio-site.properties` 中指定其他参数，以使程序更快更好地运行。

```properties
# 使用分片上传时，上传分片的超时时间。
alluxio.underfs.object.store.multipart.upload.timeout
```

```properties
# COS 分片上传的线程池大小。
alluxio.underfs.cos.multipart.upload.threads
```

```properties
# COS 分片上传的分区大小。默认分区大小为 16MB。
alluxio.underfs.cos.multipart.upload.part.size
```

### 设置请求重试策略

有时可能会因为服务器暂时无法响应，而在访问UFS时出现错误。您可以为UFS请求配置一个重试政策。

每一个发往UnderFS的I/O请求，例如下载对象、上传对象、多段上传, Alluxio 都会检查响应结果。\
如果响应是一个错误，并且错误代码表明可以重试，则将根据配置中的重试策略重新提交请求。Alluxio 将会持续重试直到请求成功或者达到了重试的最大次数。\
连续的成功重试间的等待间隔时间将会逐步从配置的基础休眠时间增长到最大休眠时间。

以下错误码被归类为可重试错误码：`500 HTTP_INTERNAL_ERROR`，`502 HTTP_BAD_GATEWAY`，`503 HTTP_UNAVAILABLE`，`503 Slow Down`，和 `504 HTTP_GATEWAY_TIMEOUT`。

**注意：**

* 4xx 错误码 通常代表客户端错误，比如：NOT\_FOUND，PERMISSION\_DENIED，UNAUTHENTICATED等等。此类错误不应重试，因为问题出在客户端。
* 5xx 错误码 通常代表服务端错误，但是不是所有的 5xx 错误都需要被重试。比如 `501 HTTP_NOT_IMPLEMENTED` 不应该被重试。

如果你想设置 UFS 访问请求的重试策略，您需要修改 `conf/alluxio-site.properties` 文件，添加以下内容：

```properties
# 一个 UnderFS 访问请求的最大重试次数。
alluxio.underfs.business.retry.max.num=10

# 第一次失败后两次尝试之间的初始睡眠时间
alluxio.underfs.business.retry.base.sleep=30ms

# 两次尝试之间的最大睡眠时间
alluxio.underfs.business.retry.max.sleep=30s
```