KnowForge/Apache Ozone 简体中文
客户端接口

s3a

师成师成· 更新于 2026-09-28· 阅读 14 分钟· 0 次阅读
登录后可跨设备保存划线和私人笔记登录

Ozone 通过 S3 Gateway 提供 S3 兼容的 REST 接口。Hadoop 的 S3A 文件系统（s3a://）是一种云连接器，它将 AWS S3 API 转换为 Hadoop 兼容的文件系统接口。Hive、Impala 和 Spark 等 Hadoop 风格的数据分析工具可以使用 Hadoop S3A 连接器访问 Ozone 的 S3 接口，因此无需修改应用即可在现有的 Hadoop 生态工具中使用 Ozone 桶。

本页介绍如何配置 Hadoop S3A 客户端以使用 Ozone 的 S3 Gateway（s3g），并提供使用 s3a 访问 Ozone s3g 的示例命令。有关 Ozone S3 Gateway 本身的详细信息（支持的 REST API、URL 方案、安全性），请参阅 S3 协议页面。有关 S3A 的更多信息，请参阅 Hadoop S3A 官方文档。

前提条件

  • 一个已启用 S3 Gateway 的运行中的 Ozone 集群。你可以按照 S3 协议文档中的说明启动一个基于 Docker 的集群（包含 S3 Gateway）。

  • Ozone S3 端点（例如 http://localhost:9878 或负载均衡器的 DNS 名称）。

  • 提供了 hadoop-aws 模块的 Hadoop 发行版。请参阅 Hadoop S3A 官方文档：

为 Ozone 配置 S3A

启用 S3A 客户端

确保 hadoop-aws 模块位于客户端类路径中。在典型的 Hadoop 安装中：

  • 在 hadoop-env.sh 中设置 HADOOP_OPTIONAL_TOOLS 以包含 hadoop-aws，或者
  • 添加对 org.apache.hadoop:hadoop-aws 的依赖，其版本与 hadoop-common 相同。

详情请参阅 Hadoop S3A 入门部分。

core-site.xml：将 S3A 指向 Ozone

在 Hadoop 配置（例如 core-site.xml）中添加以下属性，使 s3a:// URI 使用 Ozone S3 Gateway 而非 AWS S3：

<property>
  <name>fs.s3a.endpoint</name>
  <value>http://ozone-s3g-host:9878</value>
  <description>
    Ozone S3 Gateway endpoint. Replace with your s3g hostname or load balancer.
  </description>
</property>

<property>
  <name>fs.s3a.endpoint.region</name>
  <value>us-east-1</value>
  <description>
    Logical region name required by the S3A client. Ozone does not enforce regions,
    but this must be a valid-looking value.
  </description>
</property>

<property>
  <name>fs.s3a.path.style.access</name>
  <value>true</value>
  <description>
    Ozone S3 Gateway defaults to path-style URLs (http://host:9878/bucket),
    so S3A should use path-style access.
  </description>
</property>

这些属性遵循官方 S3A 连接设置，参见连接到 S3 存储。

Ozone 的推荐设置

Ozone S3 网关为 S3 分片上传（MPU）增加了 ETag 支持。对象版本控制以及其他一些 S3 行为可能仍与 AWS S3 存在差异。为避免与旧版客户端的兼容性问题，或在不使用 MPU 的情况下，可以在将 S3A 与 Ozone 配合使用时设置以下选项：

<property>
  <name>fs.s3a.bucket.probe</name>
  <value>0</value>
  <description>
    Disable the bucket existence probe at startup. This is the default in recent Hadoop
    versions and is recommended for third-party S3-compatible stores such as Ozone.
  </description>
</property>

<property>
  <name>fs.s3a.change.detection.mode</name>
  <value>none</value>
  <description>Disable change detection; not applicable to Ozone S3.</description>
</property>

凭据

Ozone 的 S3 网关使用与 AWS 相同的访问密钥和私有密钥模型。

  • 如果未启用安全功能，可以使用任意 AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY 组合。
  • 如果已启用安全功能，需通过 ozone s3 getsecret 获取密钥和私有密钥（需要 Kerberos 认证）。详情参见 S3 协议 — 安全性 和 S3 安全配置 章节。

在 core-site.xml 中配置 S3A 凭据：

<property>
  <name>fs.s3a.access.key</name>
  <value>your-access-key</value>
</property>

<property>
  <name>fs.s3a.secret.key</name>
  <value>your-secret-key</value>
</property>

或者，也可以使用环境变量，其文档见 通过 AWS 环境变量进行认证：

export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"

note

要生成和吊销 Ozone S3 密钥，请参阅 S3 协议页面的 Security（安全）部分。

caution

如果 Ozone S3 Gateway 通过 HTTPS 对外提供服务，JVM 必须信任该网关的 TLS 证书。Hadoop AWS 客户端（hadoop-aws）使用默认的 Java truststore；如果网关使用的是自定义或内部 CA，请将该 CA 添加到 JAVA_HOME/lib/security/jssecacerts，或相应地配置 JVM 的 truststore。否则，通过 S3A 连接 HTTPS 端点时可能会因证书错误而失败。

示例：通过 S3A 使用 hadoop fs 访问 Ozone

以下示例假定：

  • Ostone S3 Gateway 可通过 http://localhost:9878 访问
  • core-site.xml 已按上文进行配置
  • 已存在一个 S3 存储桶（例如 bucket1）（可以使用 aws s3api --endpoint http://localhost:9878 create-bucket --bucket bucket1 创建它）

S3A URL 的格式为 s3a://<bucket>/<path>。存储桶对应于 /s3v 卷下的 Ozone 桶，或一个桶链接（bucket link）。

列出 Ozone S3 桶中的对象

hadoop fs -ls s3a://bucket1/

使用 S3A 将本地文件上传到 Ozone

hadoop fs -put /data/local-file.txt s3a://bucket1/path/local-file.txt

从 Ozone 下载到本地或 HDFS

# To local filesystem
hadoop fs -copyToLocal s3a://bucket1/path/file.txt /tmp/from-ozone.txt

# Copy to HDFS
hadoop fs -cp s3a://bucket1/path/file.txt hdfs:///user/test/from-ozone.txt

使用内联配置快速测试

如果你无法修改集群级别的 core-site.xml，可以在命令行中传入 S3A 选项。请将端点、存储桶和凭据替换为你自己的值：

hadoop fs \
  -D fs.s3a.endpoint=http://localhost:9878 \
  -D fs.s3a.endpoint.region=us-east-1 \
  -D fs.s3a.path.style.access=true \
  -D fs.s3a.bucket.probe=0 \
  -D fs.s3a.change.detection.mode=none \
  -D fs.s3a.access.key=your-access-key \
  -D fs.s3a.secret.key=your-secret-key \
  -ls s3a://bucket1/

示例：在 HDFS 和 Ozone 之间使用 distcp

你可以将 S3A 作为 distcp 的源或目标，在 HDFS 和 Ozone 之间迁移数据。使用与上文相同的 S3A 配置。

从 HDFS 复制到 Ozone：

hadoop distcp hdfs:///data/source/dir s3a://bucket1/backup/dir

从 Ozone 复制到 HDFS：

hadoop distcp s3a://bucket1/backup/dir hdfs:///data/restore/dir

与 Ozone S3 文档的关系

本页从 Hadoop FileSystem 的角度（S3A 客户端）介绍如何使用 Ozone。有关 REST API 详情、支持的 S3 操作、存储桶链接以及 S3 安全性，请参阅 S3 协议 和 S3 安全 页面。

如需了解高级 S3A 选项（性能调优、加密、重试），请参阅官方的 Hadoop S3A 文档 及其子页面，例如 性能 和 加密。

评论

登录后参与评论

正在加载评论…