# Amazon S3

本指南介绍了将 [Amazon AWS S3](https://aws.amazon.com/s3/) 配置为 Alluxio 的底层存储系统的说明。Amazon AWS S3，即亚马逊简单存储服务，是一种对象存储服务，提供行业领先的可扩展性、数据可用性、安全性和性能。有关 Amazon AWS S3 的更多信息，请阅读其[文档](https://docs.aws.amazon.com/s3/index.html)。

还支持与 S3 兼容的存储。有关具体示例，请参阅[与 S3 兼容的存储](/ee-ai-cn/ufs/s3-compatible.md)。

## 先决条件

在开始之前，请确保您已具备下列所需信息：

在使用 Amazon AWS S3 和 Alluxio 之前：

| `<S3_BUCKET>`        | [创建一个新的 S3 存储桶](https://docs.ceph.com/en/quincy/radosgw/s3/bucketops/) 或使用现有的存储桶                                                     |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `<S3_DIRECTORY>`     | 您希望在该容器中使用的目录，可以通过创建新目录或使用现有目录来实现。                                                                                                   |
| `<S3_ACCESS_KEY_ID>` | 用于对向 AWS 发出的编程请求进行签名。请参阅[如何获取访问密钥 ID 和秘密访问密钥](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-appendix-sign-up.html) |
| `<S3_SECRET_KEY>`    | 用于对向 AWS 发出的编程请求进行签名。请参阅[如何获取访问密钥 ID 和秘密访问密钥](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-appendix-sign-up.html) |

## 基本设置

使用[挂载表示例](/ee-ai-cn/ufs.md)添加新的挂载点，指定创建挂载的 Alluxio 路径和作为 UFS URI 的 S3 路径。凭据和配置选项也可以作为挂载操作的一部分指定，如[配置挂载点](/ee-ai-cn/ufs.md)中所述。

{% tabs %}
{% tab title="Kubernetes (Operator)" %}
使用 operator 创建挂载点的 `ufs.yaml` 示例：

```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: UnderFileSystem
metadata:
  name: alluxio-s3
  namespace: alx-ns
spec:
  alluxioCluster: alluxio-cluster
  path: s3://<S3_BUCKET>/<S3_DIRECTORY>
  mountPath: /s3
  mountOptions:
    s3a.accessKeyId: <S3_ACCESS_KEY_ID>
    s3a.secretKey: <S3_SECRET_KEY>
    alluxio.underfs.s3.region: <S3_REGION>
```

{% endtab %}

{% tab title="Docker / 裸机" %}
如果不使用 operator，将 `s3://<S3_BUCKET>/<S3_DIRECTORY>` 挂载到 `/s3` 的示例命令：

```shell
bin/alluxio mount add --path /s3/ --ufs-uri s3://<S3_BUCKET>/<S3_DIRECTORY> \
  --option s3a.accessKeyId=<S3_ACCESS_KEY_ID> --option s3a.secretKey=<S3_SECRET_KEY>
```

请注意，如果要挂载 S3 存储桶的根目录，请在存储桶名称后添加一个尾随斜杠（例如 `s3://S3_BUCKET/`）。
{% endtab %}
{% endtabs %}

有关设置 AWS 凭据的其他方法，请参阅[高级设置](#gao-ji-ping-ju-she-zhi)中的凭据部分。

### 挂载多个 S3 存储桶

您可以挂载任意数量的 S3 存储桶。每个挂载在 Alluxio 命名空间中创建一个独立的虚拟路径，可以使用不同的凭据和区域。

{% tabs %}
{% tab title="Kubernetes (Operator)" %}
每个存储桶创建一个 `UnderFileSystem` CR：

```yaml
# bucket-a.yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: UnderFileSystem
metadata:
  name: s3-bucket-a
  namespace: alx-ns
spec:
  alluxioCluster: alluxio-cluster
  path: s3://bucket-a-prod/
  mountPath: /bucket-a
  mountOptions:
    s3a.accessKeyId: "<KEY_A>"
    s3a.secretKey: "<SECRET_A>"
    alluxio.underfs.s3.region: "us-east-1"
```

```yaml
# bucket-b.yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: UnderFileSystem
metadata:
  name: s3-bucket-b
  namespace: alx-ns
spec:
  alluxioCluster: alluxio-cluster
  path: s3://bucket-b-analytics/
  mountPath: /bucket-b
  mountOptions:
    s3a.accessKeyId: "<KEY_B>"
    s3a.secretKey: "<SECRET_B>"
    alluxio.underfs.s3.region: "us-west-2"
```

```shell
kubectl apply -f bucket-a.yaml -f bucket-b.yaml
```

{% endtab %}

{% tab title="Docker / 裸机" %}
每个存储桶执行一次 `alluxio mount add`：

```shell
# 挂载第一个存储桶
bin/alluxio mount add \
  --path /bucket-a \
  --ufs-uri s3://bucket-a-prod/ \
  --option s3a.accessKeyId=<KEY_A> \
  --option s3a.secretKey=<SECRET_A> \
  --option alluxio.underfs.s3.region=us-east-1

# 挂载第二个存储桶（不同区域）
bin/alluxio mount add \
  --path /bucket-b \
  --ufs-uri s3://bucket-b-analytics/ \
  --option s3a.accessKeyId=<KEY_B> \
  --option s3a.secretKey=<SECRET_B> \
  --option alluxio.underfs.s3.region=us-west-2
```

{% endtab %}
{% endtabs %}

每个挂载路径必须唯一。挂载数量没有硬性限制。每个挂载的凭据优先级高于 `AlluxioCluster` `spec.properties` 中配置的全局凭据。

## 高级设置

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

### 配置 AWS SDK v1

配置访问 S3 存储桶时使用的 AWS SDK 版本。默认使用的版本是 v2。如果要将版本设置为 v1，请在 `conf/alluxio-site.properties` 中添加以下配置

```properties
alluxio.underfs.s3.sdk.version=1
```

请注意，AWS SDK v2 具有更好的内存管理和更高的吞吐量性能。

### 配置 S3 区域

配置访问 S3 存储桶时的 S3 区域将提高性能。否则，将启用全局 S3 存储桶访问，这会引入额外的请求。S3 区域可以通过属性 `alluxio.underfs.s3.region` 进行设置。

```properties
alluxio.underfs.s3.region=us-west-1
```

请注意，如果设置了 [S3 端点](#zhi-ding-duan-dian)，则此属性将被忽略，而使用特定于端点的区域属性。

### 高级凭据设置

如果您使用 AWS S3 作为 UFS，则需要为其配置凭据。有多种方法可以提供凭据：

* **直接密钥**：指定 `s3a.accessKeyId` 和 `s3a.secretKey`。Alluxio 将直接使用此密钥对访问 S3 UFS。
* **带密钥的 AssumeRole**：如果您指定 `aws.accessKeyId` 和 `aws.secretKey` 并启用 AssumeRole 功能，Alluxio 将使用此密钥对通过 AssumeRole 获取临时凭据以访问 S3 UFS。更多详细信息请参阅[使用 AWS AssumeRole](#shi-yong-aws-assumerole)。
* **凭证提供程序类**：如果您指定 `alluxio.underfs.s3.credential.provider.class`，Alluxio 将根据您指定的提供程序获取凭据。这对于更复杂的身份验证场景非常有用。支持的提供程序包括：
  * `WEBIDENTITY_TOKEN`：使用 Web Identity Token 文件获取凭据。这通常用于容器化环境，如 Kubernetes，其中服务帐户可以代入 IAM 角色。
  * `PROFILE`：使用您 `~/.aws/credentials` 文件中的命名配置文件。此方法非常适合开发环境或需要管理多个 IAM 用户角色并轻松切换的场景。
  * `INSTANCE_PROFILE`：使用 IAM 实例配置文件获取凭据。这通常用于 AWS 计算服务（如 EC2 实例）或 EKS 环境中，允许应用程序安全地访问 AWS 服务，而无需在应用程序内管理显式凭据。

您可以按从高到低的优先级以不同方式指定凭据：

1. 作为挂载选项指定的 `s3a.accessKeyId` 和 `s3a.secretKey`
2. 作为 Java 系统属性指定的 `s3a.accessKeyId` 和 `s3a.secretKey`
3. `alluxio-site.properties` 中指定的 `s3a.accessKeyId` 和 `s3a.secretKey`
4. 配置中指定的 `alluxio.underfs.s3.credential.provider.class`
5. Alluxio 服务器上的环境变量 `AWS_ACCESS_KEY_ID` 或 `AWS_ACCESS_KEY`（两者均可接受）和 `AWS_SECRET_ACCESS_KEY` 或 `AWS_SECRET_KEY`（两者均可接受）
6. `~/.aws/credentials` 中包含凭据的配置文件
7. 如果您使用的是 EC2 实例，则为 AWS 实例配置文件凭据

#### 在 Kubernetes 中设置凭据

下方的方式 A 和方式 B 是适用于所有 UFS 类型的通用 Kubernetes 模式 — 通用形式请参阅 UFS 概览中的 [Kubernetes：凭据管理](https://documentation.alluxio.io/ee-ai-cn/ufs/pages/QHxxAwAliFxrTQ5jOZw7#kubernetes凭据管理)。方式 C 为 AWS/EKS 专用。

在 Kubernetes 上通过 Operator 运行 Alluxio 时，有三种额外方式可以避免在每个挂载命令中重复指定凭据。

**方式 A：在 AlluxioCluster CR 的 `spec.properties` 中设置（推荐，简单直接）**

在 `AlluxioCluster` CR 中将凭据设置为全局属性。所有未单独指定凭据的 S3 挂载都会继承这些凭据：

```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
  properties:
    s3a.accessKeyId: "<YOUR_ACCESS_KEY>"
    s3a.secretKey: "<YOUR_SECRET_KEY>"
    alluxio.underfs.s3.region: "us-east-1"
```

配置后，`UnderFileSystem` CR 的 `mountOptions` 无需再指定凭据。如需跨账户访问，仍可在单个挂载的 `mountOptions` 中覆盖。

**方式 B：在 coordinator 和 worker Pod 上设置环境变量**

将凭据存储在 Kubernetes Secret 中，避免明文提交到版本控制：

```shell
kubectl create secret generic s3-credentials \
  --from-literal=access-key-id=<YOUR_ACCESS_KEY> \
  --from-literal=secret-access-key=<YOUR_SECRET_KEY> \
  -n alx-ns
```

然后在 `AlluxioCluster` CR 中引用该 Secret：

```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
  coordinator:
    env:
      - name: AWS_ACCESS_KEY_ID
        valueFrom:
          secretKeyRef:
            name: s3-credentials
            key: access-key-id
      - name: AWS_SECRET_ACCESS_KEY
        valueFrom:
          secretKeyRef:
            name: s3-credentials
            key: secret-access-key
  worker:
    env:
      - name: AWS_ACCESS_KEY_ID
        valueFrom:
          secretKeyRef:
            name: s3-credentials
            key: access-key-id
      - name: AWS_SECRET_ACCESS_KEY
        valueFrom:
          secretKeyRef:
            name: s3-credentials
            key: secret-access-key
```

**方式 C：IAM 节点角色（推荐用于 AWS EKS）**

将具有 S3 访问权限的 IAM 策略附加到 EKS 节点组角色。配置正确后，任何配置中均无需指定凭据。详见 [AWS 文档](https://docs.aws.amazon.com/eks/latest/userguide/create-node-role.html)。

当使用 AWS 实例配置文件作为凭据提供程序时：

* 创建一个具有访问已挂载存储桶权限的 [IAM 角色](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html)
* 创建一个[实例配置文件](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html#ec2-instance-profile)作为已定义 IAM 角色的容器
* 使用创建的配置文件启动 EC2 实例

请注意，IAM 角色需要访问存储桶中的文件以及存储桶本身，才能确定存储桶的所有者。可以通过设置属性 `alluxio.underfs.s3.inherit.acl=false` 来避免自动为存储桶分配所有者。

有关更多详细信息，请参阅 [Amazon 的文档](http://docs.aws.amazon.com/java-sdk/latest/developer-guide/credentials.html#id6)。

### HTTPS/HTTP 访问

默认情况下，Alluxio 使用 HTTPS 协议与 S3 进行安全通信。如果需要禁用 SSL 证书验证和 SSL 主机名验证，请配置以下属性：

```properties
alluxio.underfs.s3.secure.http.trust.all.certs=true
```

如果要使用 HTTP 协议与 S3 通信，请配置以下属性：

```properties
alluxio.underfs.s3.secure.http.enabled=false
```

### 启用服务器端加密

您可以加密存储在 S3 中的数据。加密仅对 S3 中静态数据有效，在客户端读取时将以解密形式传输。请注意，启用此功能还将启用 HTTPS 以符合读/写对象的要求。

通过配置 `conf/alluxio-site.properties` 启用此功能：

```properties
alluxio.underfs.s3.server.side.encryption.enabled=true
```

### DNS-Buckets

默认情况下，针对名为“mybucket”的存储桶的请求将发送到主机名“mybucket.s3.amazonaws.com”。您可以通过设置以下配置来启用 DNS-Buckets 以使用路径样式数据访问，例如：“<http://s3.amazonaws.com/mybucket”：>

```properties
alluxio.underfs.s3.disable.dns.buckets=true
```

### 通过代理访问 S3

要通过代理与 S3 通信，请修改 `conf/alluxio-site.properties` 以包含：

```properties
alluxio.underfs.s3.proxy.host=<PROXY_HOST>
alluxio.underfs.s3.proxy.port=<PROXY_PORT>
```

`<PROXY_HOST>` 和 `<PROXY_PORT>` 应替换为代理的主机和端口。默认情况下，使用 HTTPS 协议访问代理；如果代理仅支持 HTTP，请确保设置 `alluxio.underfs.s3.secure.http.enabled=false`。

### 指定端点

如果要访问特定端点（例如 AWS VPC 端点），请修改 `conf/alluxio-site.properties` 以包含：

```properties
alluxio.underfs.s3.endpoint=<S3_ENDPOINT>
alluxio.underfs.s3.endpoint.region=<S3_ENDPOINT_REGION>
```

端点和区域值都需要设置。请注意，设置端点后，`alluxio.underfs.s3.region=<S3_REGION>` 将不再生效。

对于非 Amazon 服务提供商，请将 S3 服务的主机名和端口设置为 `<S3_ENDPOINT>`。

### 使用 v2 S3 签名

一些 S3 服务提供商仅支持 v2 签名。对于这些 S3 提供商，您可以通过将 `alluxio.underfs.s3.signer.algorithm` 设置为 `S3SignerType` 来强制使用 v2 签名。

### \[实验性] S3 流式上传

S3 是一个对象存储，由于此功能，整个文件从客户端发送到 worker，存储在本地磁盘临时目录中，并默认在 `close()` 方法中上传。

要启用 S3 流式上传，您需要修改 `conf/alluxio-site.properties` 以包含：

```properties
alluxio.underfs.s3.streaming.upload.enabled=true
```

默认上传过程更安全，但存在以下问题：

* 上传时间慢。文件必须先发送到 Alluxio worker，然后 Alluxio worker 负责将文件上传到 S3。这两个过程是顺序的。
* 临时目录必须有足够的容量来存储整个文件。
* `close()` 速度慢。`close()` 方法的执行时间与文件大小成正比，与带宽成反比。即 O(FILE\_SIZE/BANDWIDTH)。

S3 流式上传功能解决了上述问题，并基于 [S3 低级分段上传](https://docs.aws.amazon.com/AmazonS3/latest/dev/mpListPartsJavaAPI.html)。

S3 流式上传具有以下优点：

* 上传时间更短。Alluxio worker 在接收新数据的同时上传缓冲数据。总上传时间至少与默认方法一样快。
* 容量要求更小。我们的数据根据分区（默认为 64MB 的 `alluxio.underfs.s3.streaming.upload.partition.size`）进行缓冲和上传。当一个分区成功上传后，该分区将被删除。
* `close()` 速度更快。我们在缓冲数据达到分区大小时开始上传数据，而不是在 `close()` 中上传整个文件。

如果 S3 流式上传中断，可能会有中间分区上传到 S3，S3 将对存储的数据收费。为了减少费用，用户可以修改 `conf/alluxio-site.properties` 以包含：

```properties
alluxio.underfs.cleanup.enabled=true
```

当达到清理间隔（由 `alluxio.underfs.cleanup.interval` 配置）时，所有非只读 S3 挂载点中超过清理年龄（由 `alluxio.underfs.s3.intermediate.upload.clean.age` 配置）的中间分段上传将被清理。

### S3 分段上传

我们使用分段上传方法通过多个部分上传一个文件，每个部分将在一个线程中上传。上传时不会生成任何临时文件。*它会消耗更多内存，但比流式上传模式更快*。

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

```properties
# Timeout for uploading part when using multipart upload.
alluxio.underfs.object.store.multipart.upload.timeout
```

<pre class="language-properties"><code class="lang-properties"><strong># Multipart upload partition size for S3. The default partition size is `16MB`
</strong>alluxio.underfs.s3.multipart.upload.partition.size
</code></pre>

禁用 S3 分段上传，上传方法会一次性从头到尾完整上传一个文件。您需要修改 `conf/alluxio-site.properties` 以包含：

```properties
alluxio.underfs.s3.multipart.upload.enabled=false
```

### 设置请求重试策略

适用于所有对象存储 UFS 类型的重试配置，请参阅 UFS 概览中的[请求重试策略](https://documentation.alluxio.io/ee-ai-cn/ufs/pages/QHxxAwAliFxrTQ5jOZw7#请求重试策略)。

### 设置更长的超时时间

如果 S3 连接速度慢，设置更长的超时时间会很有用：

```properties
alluxio.underfs.s3.socket.timeout=500sec
alluxio.underfs.s3.request.timeout=5min
```

### 针对高并发进行调整

当通过 Alluxio 以大量客户端访问 S3 时，每个 Alluxio 服务器，增加 S3 连接池大小以避免性能问题非常重要。如果连接池大小太小，可能会导致 S3 请求失败，并出现诸如“无法执行 HTTP 请求：等待池中连接超时”之类的错误，这是由于对可用连接的高度竞争造成的。增加池大小可通过设置以下内容确保更顺畅的通信和最佳性能：

```properties
alluxio.underfs.s3.connections.max=2048
```

### 使用面包屑优化元数据列表

与传统文件系统不同，许多对象存储没有目录的本机概念。常见的文件系统操作（例如检查目录是否存在、检索目录元数据或遍历目录）必须转换为基于前缀的对象列表操作。

当目录包含大量对象并且缺少目录占位符对象（以目录名称为前缀的零大小对象，称为“面包屑”）时，这些操作的成本可能会显着增加。为了减轻这种开销，通常会引入占位符对象来显式表示目录，从而提高与目录相关的元数据操作的性能。

Alluxio 提供了一个选项，通过使用“面包屑”对象来减轻这种开销，这些对象充当表示目录的轻量级占位符。默认情况下，Alluxio 会主动在 UFS 中创建面包屑对象来表示目录。要禁用此功能，请设置以下配置：

```properties
alluxio.underfs.object.store.breadcrumbs.enabled=false
```

面包屑具有以下优点：

* 提高性能：一旦创建了面包屑，就可以有效地访问目录元数据，避免重复的完整列表扫描。
* 缓存协同作用：与元数据缓存和预加载策略配合良好，以优化冷启动行为。

面包屑有以下几点需要考虑：

* 需要写权限：启用此功能需要对对象存储的写访问权限。
* 潜在的数据影响：关心数据纯度或对象存储外部修改的用户可能希望禁用它。
* 冷加载开销：创建面包屑对象时，初始目录加载可能会产生一次性写入成本。

建议：

* 如果 UFS 允许写入并且您正在优化性能（尤其是在列表性能较差的对象存储中），请启用。
* 如果 UFS 是只读的，或者出于合规性或审计原因不允许修改 UFS，请禁用。

## S3 对象的身份和访问控制

[S3 身份和访问管理](https://docs.aws.amazon.com/AmazonS3/latest/dev/s3-access-control.html) 与传统的 POSIX 权限模型有很大不同。例如，S3 ACL 不支持组或目录级设置。Alluxio 尽最大努力从 S3 ACL 信息中继承权限信息，包括文件所有者、组和权限模式。

### 为什么返回 403 访问被拒绝错误

Alluxio 配置中设置的 S3 凭据对应于一个 AWS 用户。如果此用户没有访问 S3 存储桶或对象所需的权限，将返回 403 权限被拒绝错误。

如果您在访问 S3 服务时在 Alluxio 服务器日志中看到 403 错误，您应该仔细检查

1. 您使用的是正确的 AWS 凭据。请参阅[凭据设置](#gao-ji-ping-ju-she-zhi)。
2. 您的 AWS 用户有权访问挂载到 Alluxio 的存储桶和对象。

阅读更多[AWS 故障排除指南](https://aws.amazon.com/premiumsupport/knowledge-center/s3-troubleshoot-403/)以了解 403 错误。

### 文件所有者和组

Alluxio 文件系统根据在 Alluxio 中配置的用于连接到 S3 的 AWS 帐户设置文件所有者。由于 S3 ACL 中没有组，因此所有者被重用为组。

默认情况下，Alluxio 提取此 AWS 帐户的显示名称作为文件所有者。如果此显示名称不可用，将使用此 AWS 用户的[规范用户 ID](https://docs.aws.amazon.com/general/latest/gr/acct-identifiers.html)。此规范用户 ID 通常是一个长字符串（例如 `79a59df900b949e55d96a1e698fbacedfd6e09d98eacf8f8d5218e7cd47ef2be`），因此在实践中通常不方便阅读和使用。或者，可以使用属性 `alluxio.underfs.s3.owner.id.to.username.mapping` 来指定从规范用户 ID 到 Alluxio 用户名的预设映射，格式为“id1=user1;id2=user2”。例如，编辑 `alluxio-site.properties` 以包含

```properties
alluxio.underfs.s3.owner.id.to.username.mapping=\
79a59df900b949e55d96a1e698fbacedfd6e09d98eacf8f8d5218e7cd47ef2be=john
```

此配置可帮助 Alluxio 将此 AWS 帐户拥有的所有对象识别为 Alluxio 命名空间中用户 `john` 拥有的对象。要查找您帐户的 AWS S3 规范 ID，请检查控制台 `https://console.aws.amazon.com/iam/home?#/security_credentials`，展开“帐户标识符”选项卡并参考“规范用户 ID”。

### 更改权限

Alluxio 目录和文件的 `chown`、`chgrp` 和 `chmod` **不会**传播到底层 S3 存储桶或对象。

### 使用 AWS AssumeRole

Alluxio 支持通过 [AWS AssumeRole API](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) 进行身份验证以连接到 AWS S3。启用 AssumeRole 后，AWS 访问密钥和秘密密钥将仅用于获取临时安全凭据。所有后续访问都将使用这些通过 AssumeRole 生成的临时凭据。

此外，还可以通过将 `alluxio.underfs.s3.credential.provider.class` 配置为 `WEBIDENTITY_TOKEN` 或 `INSTANCE_PROFILE` 等值来实现 AssumeRole 访问，具体详见[高级凭据设置](#advanced-credentials-setup)部分。

要在 Alluxio 中启用 AssumeRole，worker 和Coordinator上需要以下属性：

```properties
alluxio.underfs.s3.assumerole.enabled=true
alluxio.underfs.s3.assumerole.rolearn=arn:aws:iam::123456:role/example-role
```

注意：确保指定的角色存在，并且与提供的访问密钥和秘密密钥关联的用户有权代入目标角色 ARN 定义的角色。

除了强制性属性外，您还可以配置以下可选设置，以更好地控制会话行为和网络配置：

```properties
# Specifies a name for the session.
# Temporary credentials will be associated with this session.
# A random string is suffixed to ensure uniqueness.
alluxio.underfs.s3.assumerole.session.prefix="alluxio-assume-role"

# Specifies the session duration in seconds. Typically, this is between 900 and 3600 seconds.
# The session will be automatically refreshed by the AWS client,
# so no manual intervention is needed to refresh the temporary credentials.
alluxio.underfs.s3.assumerole.session.duration.second=900

# Enables the HTTPS protocol for AssumeRole requests. The default value is true.
alluxio.underfs.s3.assumerole.https.enabled=true

# Enables the HTTPS protocol for the AssumeRole proxy. The default value is false.
alluxio.underfs.s3.assumerole.proxy.https.enabled=false

# Specifies the proxy host for AssumeRole requests. Both proxy host and proxy port must be set
# in the Alluxio configuration; otherwise, the proxy settings will default to your system's
# environment configuration.
alluxio.underfs.s3.assumerole.proxy.host=<HOSTNAME>

# Specifies the proxy port for AssumeRole requests. Both proxy host and proxy port must be set
# in the Alluxio configuration; otherwise, the proxy settings will default to your system's
# environment configuration.
alluxio.underfs.s3.assumerole.proxy.port=<PORT_NUMBER>
```

注意：如果 Alluxio 配置中未设置代理主机和端口，JVM/系统环境变量 `HTTP(S)_PROXY`、`http(s)_proxy`、`http(s).proxyHost` 和 `http(s).proxyPort` 将被 AWS SDK 自动拾取。

以下是在 Alluxio 中设置 AssumeRole 的示例配置：

```properties
aws.accessKeyId=FOO
aws.secretKey=BAR
alluxio.underfs.s3.assumerole.enabled=true
alluxio.underfs.s3.assumerole.session.duration.second=1000
alluxio.underfs.s3.assumerole.session.prefix="alluxio"
alluxio.underfs.s3.assumerole.rolearn=arn:aws:iam::123456:role/example-role
```

总结：

* **临时凭据**：AWS 访问密钥仅用于请求临时凭据；所有未来的操作都依赖于这些凭据。
* **自动会话刷新**：会话由 AWS SDK 自动刷新，无需手动干预。
* **可自定义的配置**：您可以修改会话持续时间、代理设置和会话前缀以满足您的安全和环境需求。

通过设置这些属性，Alluxio 可以有效地使用通过 AssumeRole 获取的临时凭据对 AWS S3 进行身份验证和管理访问。

## 故障排除

### 启用 AWS-SDK 调试级别

如果在使用 SDK v2 针对 S3 后端运行时遇到问题，请启用其他日志记录以跟踪 HTTP 流量。在 `conf/alluxio-env.sh` 文件中设置 `ALLUXIO_WORKER_JAVA_OPTS`：

```properties
ALLUXIO_WORKER_JAVA_OPTS+=" -Daws.crt.log.level=Info  -Daws.crt.log.destination=File  -Daws.crt.log.filename=/opt/alluxio/logs/worker.log"
```

有关更多详细信息，请参阅 [Amazon 的文档](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/logging-slf4j.html)。

如果正在使用 AWS SDK V1，请修改 `conf/log4j.properties` 文件，添加以下属性：

```properties
log4j.logger.com.amazonaws=WARN
log4j.logger.com.amazonaws.request=DEBUG
log4j.logger.org.apache.http.wire=DEBUG
```

有关更多详细信息，请参阅 [Amazon 的文档](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/java-dg-logging.html)。

### 防止创建零字节文件

Alluxio 可能会在 S3 中创建零字节文件，作为列出底层存储内容时的性能优化。如果存储桶以只读访问权限挂载，则将禁止通过 S3 PUT 操作创建零字节文件。要禁用此优化，请设置以下配置。

```properties
alluxio.underfs.object.store.breadcrumbs.enabled=false
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.alluxio.io/ee-ai-cn/ufs/s3.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.