H2O 3 在 EC2 上配置 S3 访问凭证完整指南:core-site.xml、API 动态设置与多节点集群部署
H2O 3 在 EC2 上配置 S3 访问凭证完整指南:core-site.xml、API 动态设置与多节点集群部署
H2O 3 作为分布式机器学习平台,可以通过 s3:// 路径前缀直接导入 Amazon S3 中的数据帧,但这要求将 AWS 访问凭证传递给 H2O。本文基于 H2O 3 仓库中的官方文档与源码实现,系统讲解单机(Standalone)模式下三种凭证传递方式(core-site.xml 配置文件、R/Python 动态 API、会话令牌临时凭证)的完整用法,并逐步演示如何在 EC2 上搭建多节点 H2O 集群并安全分发凭证。读完本文,你将掌握从单节点到多节点在 AWS 上使用 S3 存储的完整实战方案,并理解其底层凭证解析原理。
说明:本文对应的原文档
h2o-docs/src/product/howto/H2O-DevS3Creds.md已标注"不再维护",官方最新内容位于 cloud-integration 目录。本文以原文档为主线,融合更新版文档与源码细节。
一、为什么需要把 S3 凭证传给 H2O
H2O 在导入数据帧时支持 s3://...、s3n://...、s3a://... 等多种 S3 风格路径前缀(见 PersistManager.java 中的 S3、S3N、S3A 常量定义)。要访问这些路径下的数据,H2O 必须持有有效的 AWS 凭证,即:
- AWS 凭证(Credentials 对):由 AWS Secret Key(Access Key ID)与 AWS Secret Access Key 组成的二元组;
- 临时凭证(Temporary Credentials):由 Access Key ID、Secret Access Key 与 Session Token 组成的三元组,适用于需要会话令牌的场景。
原文档基于 Redhat AMI、Amazon Linux AMI 和 Ubuntu AMI 做过验证。官方建议:将凭证存放在独立文件中,再通过脚本读取并传递给 H2O。这样做一方面避免凭证扩散到其他位置,另一方面后续更换密钥信息时只需改动一处,更加安全。
二、单机(Standalone)模式:三种凭证传递方式
使用简单的 Java 启动命令运行 H2O 单机模式时,可以通过以下三种方式传入 S3 凭证。
方式一:core-site.xml + -hdfs_config 启动参数
创建 core-site.xml 文件,将属性编辑为你的 Access Key ID 与 Access Key,然后使用 -hdfs_config 标志启动:
<property>
<name>fs.s3n.awsAccessKeyId</name>
<value>[AWS SECRET KEY]</value>
</property>
<property>
<name>fs.s3n.awsSecretAccessKey</name>
<value>[AWS SECRET ACCESS KEY]</value>
</property>
启动命令:
java -jar h2o.jar -hdfs_config core-site.xml
从源码看,-hdfs_config 是 H2O.java 中定义的命令行参数(hdfs_config,用于指定 HDFS 配置文件),解析逻辑在参数处理分支中将其追加到配置数组(H2O.java)。H2O 启动时会加载该 XML,把其中的 fs.s3* 属性交给 Hadoop 文件系统层解析,从而完成 S3 客户端初始化。
方式二:R API 动态设置凭证
在访问 bucket 之前动态设置凭证:
h2o.set_s3_credentials("AWS_ACCESS_KEY", "AWS_SECRET_KEY")
h2o.importFile(path = "s3://bucket/path/to/file.csv")
R 端的实现位于 import.R:h2o.set_s3_credentials(secretKeyId, secretAccessKey, sessionToken = NULL) 会先校验三个参数非空、且为字符类型,然后通过 POST PersistS3 REST 接口把参数发送给 H2O 后端,成功后打印 Credentials successfully set.。
方式三:Python API 动态设置凭证
from h2o.persist import set_s3_credentials
set_s3_credentials("AWS_ACCESS_KEY", "AWS_SECRET_KEY")
h2o.import_file(path = "s3://bucket/path/to/file.csv")
Python 端的实现位于 persist.py:set_s3_credentials(secret_key_id, secret_access_key, session_token=None) 会对 None 和空字符串参数抛出 H2OValueError,然后将参数封装后调用 h2o.api("POST /3/PersistS3", data=params)。值得注意:
- 该函数不校验凭证的正确性,错误的凭证会在第一次 S3 导入调用时才暴露(docstring 中明确说明);
- 支持可选的
session_token参数,用于 AWS 临时凭证; - 对应的
remove_s3_credentials()(persist.py)通过DELETE /3/PersistS3移除此前动态设置的凭证,且不影响实例变量或其他来源的凭证。
仓库中的测试用例 pyunit_set_s3_credentials.py 验证了"不设置凭证时从 S3 导入会失败、设置后导入成功"的完整行为链路;pyunit_validate_set_s3_credentials.py 则覆盖了对空串/None 参数的校验。
已废弃:在 URL 中内嵌凭证
h2o.importFile(path = "s3://<AWS_ACCESS_KEY>:<AWS_SECRET_KEY>@bucket/path/to/file.csv")
在 URL 中直接携带凭证被视为安全风险,该方式已废弃,请勿在生产环境使用。
三、动态凭证的底层实现原理
POST /3/PersistS3 接口对应的 REST schema 是 PersistS3CredentialsV3.java:三个字段 secret_key_id(必填)、secret_access_key(必填)、session_token(可选)。凭证会被包装为 IcedS3Credentials,以键 S3_CREDENTIALS_KEY 存入分布式键值存储 DKV,并区分两种鉴权形态:
isAWSCredentialsAuth():session_token为null,使用普通 AWS 凭证;isAWSSessionTokenAuth():三个字段均非空,使用带会话令牌的临时凭证。
真正消费凭证的是 PersistS3.java 中的 H2OAWSCredentialsProviderChain,其凭证提供者链按顺序为:
- H2ODynamicCredentialsProvider:从 DKV 读取
IcedS3Credentials,返回BasicAWSCredentials或BasicSessionCredentials(PersistS3.java); - H2OArgCredentialsProvider:读取命令行参数
--aws_credentials指定的 properties 文件(默认位置为AwsCredentials.properties),支持accessKey/secretKey键值对(PersistS3.java); - DefaultAWSCredentialsProviderChain:AWS SDK 标准默认链,最终可回落至 IAM 角色的临时凭证。
这也解释了原文档中的一句关键说明:如果使用 IAM 角色运行 H2O,则无需向集群各节点分发 AWS 凭证,H2O 能够直接访问与实例关联的临时访问密钥(IAM 凭证由 AWS 环境注入,默认链自动识别)。
四、使用临时凭证(Session Token)
H2O 同时支持普通 AWS 凭证与基于 Session Token 的临时鉴权。临时凭证同样有两种传入路径:
通过 core-site.xml 传入临时凭证
与普通凭证的差异在于:需要在 core-site.xml 中指定一个能解析临时凭证的凭证提供者,并补充 Session Token 属性:
<property>
<name>fs.s3a.aws.credentials.provider</name>
<value>org.apache.hadoop.fs.s3a.TemporaryAWSCredentialsProvider</value>
</property>
<property>
<name>fs.s3a.access.key</name>
<value>[AWS SECRET KEY]</value>
</property>
<property>
<name>fs.s3a.secret.key</name>
<value>[AWS SECRET ACCESS KEY]</value>
</property>
<property>
<name>fs.s3a.session.token</name>
<value>[AWS SESSION TOKEN]</value>
</property>
启动方式与普通凭证相同:
java -jar h2o.jar -hdfs_config core-site.xml
通过 R/Python API 传入临时凭证
h2o.set_s3_credentials("AWS_ACCESS_KEY", "AWS_SECRET_KEY", "AWS_SESSION_TOKEN")
h2o.importFile(path = "s3://bucket/path/to/file.csv")
from h2o.persist import set_s3_credentials
set_s3_credentials("AWS_ACCESS_KEY", "AWS_SECRET_KEY", "AWS_SESSION_TOKEN")
h2o.import_file(path = "s3://bucket/path/to/file.csv")
同样地,把凭证内嵌进 URL(如 s3://<key>:<secret>:<token>@bucket/...)属于安全风险且已废弃。
五、Core-site.xml 完整示例
官方更新版文档给出的完整 core-site.xml 示例如下(含可选的 fs.default.name 默认 bucket 设置与 Session Token 属性):
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="configuration.xsl"?>
<!-- Put site-specific property overrides in this file. -->
<configuration>
<!--
<property>
<name>fs.default.name</name>
<value>s3://<your s3 bucket></value>
</property>
-->
<property>
<name>fs.s3.awsAccessKeyId</name>
<value>insert access key here</value>
</property>
<property>
<name>fs.s3.awsSecretAccessKey</name>
<value>insert secret key here</value>
</property>
<property>
<name>fs.s3.awsSessionToken</name>
<value>insert session token here</value>
</property>
</configuration>
关于路径前缀与属性名的选择,可结合 PersistManager.java 中的 scheme 识别逻辑理解:
- H2O 同时识别
s3:、s3n:、s3a:三种前缀,分别路由到不同的后端实现; - 官方建议用
s3://导入数据、用s3n://导出数据(更新版文档明确推荐); - 一个 S3 客户端只能指定一个 endpoint,因此同一 H2O 实例要么读 AWS S3,要么读 Minio S3,不能同时读取两者。
此外,core-site.xml 并非唯一文件式凭证来源。如 start-h2o-bg.sh 所示,EC2 部署脚本还会生成 aws_credentials.properties(键 accessKey、secretKey),并通过 --aws_credentials= 参数启动 H2O,这条路径对应上文提到的 H2OArgCredentialsProvider。相关启动参数 -aws_credentials 与 -configure_s3_using_s3a(使用 S3A 文件系统配置 S3 客户端)都定义于 H2O.java。
六、多节点(Multi-Node)EC2 集群部署
多节点部署的完整脚本位于仓库 ec2 目录。启动多节点 H2O 集群前,需要确认宿主机已安装 Python 和 boto Python 库。
第 1 步:编辑并运行实例启动脚本
编辑 h2o-cluster-launch-instances.py,填入 SSH key 名称、安全组名称及其他环境相关变量。该脚本要求设置三个环境变量:AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_SSH_PRIVATE_KEY_FILE,并提供了以下可调参数:
| 参数 | 说明 | 示例默认值 |
|---|---|---|
keyName |
AWS SSH key pair 名称 | 需填写 |
securityGroupName |
AWS 安全组名称(注意 H2O 使用 TCP/UDP 端口 54321、54322;RStudio 使用 8787) | SecurityDisabled |
numInstancesToLaunch |
要启动的实例数 | 2 |
instanceType |
实例类型 | m3.2xlarge |
instanceNameRoot |
实例命名前缀 | h2o-instance |
spotBid |
竞价实例(Spot Instance)出价金额,设为字符串金额启用 | None |
iam_profile_name / iam_profile_resource_name |
为实例绑定 IAM 角色 | None |
regionName / amiID |
区域与 AMI | us-east-1 |
脚本启动后会在当前目录生成 nodes-public(公网 DNS 列表)与 nodes-private(私网 IP 列表)两个文件,供后续脚本读取。
然后选择分发 H2O 二进制的方式(二选一):
./h2o-cluster-launch-instances.py
./h2o-cluster-distribute-h2o.sh
或者:
./h2o-cluster-launch-instances.py
./h2o-cluster-download-h2o.sh
- h2o-cluster-distribute-h2o.sh 会从本机
h2o.jar或../h2o.jar等路径定位 jar 包,通过scp依次复制到nodes-public中的每台节点; - h2o-cluster-download-h2o.sh 则直接在节点上从 S3 发布桶下载指定分支、指定 build 号的 H2O 压缩包并解压;
- 第二种方式通常更快,因为下载流量直接取自 S3,不经由宿主机中转。
第 2 步:向集群分发 AWS 凭证
运行凭证分发脚本:
./h2o-cluster-distribute-aws-credentials.sh
该脚本(h2o-cluster-distribute-aws-credentials.sh)会基于环境变量 AWS_ACCESS_KEY_ID 与 AWS_SECRET_ACCESS_KEY 动态生成 core-site.xml 和 aws_credentials.properties,并通过 scp 将两者复制到每台节点的 ~/.ec2 目录,供后续后台启动脚本读取。
两点重要提示:
- IAM 角色场景:如果使用 IAM 角色运行 H2O,则无需执行此分发步骤,H2O 可直接访问实例关联的临时访问密钥;
- 安全警告:分发凭证会把
AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY(临时凭证场景下还会带上AWS_SESSION_TOKEN)复制到集群实例中以启用 S3/S3N 访问,把安全密钥加入云环境需格外谨慎。
第 3 步:逐节点启动 H2O
每台 EC2 实例上启动一个 H2O 节点:
./h2o-cluster-start-h2o.sh
每台节点执行后需等待约 60 秒,再在下一台节点上执行。h2o-cluster-start-h2o.sh 会遍历 nodes-public,通过 SSH 在每台节点上调用 start-h2o-bg.sh 后台启动 H2O。该后台脚本会自动完成:
- 读取
/proc/meminfo,将 H2O 的-Xmx设为物理内存的 90%; - 若存在
~/.ec2/core-site.xml,自动追加-hdfs_config .ec2/core-site.xml参数; - 若存在
~/.ec2/aws_credentials.properties,自动追加--aws_credentials=.ec2/aws_credentials.properties参数; - 使用
-flatfile flatfile.txt(由分发 flatfile 脚本生成)组建成集群。
第 4 步:访问集群 Web UI
在浏览器中,用任一节点的公网 DNS 地址替换 IP_ADDRESS:
http://IP_ADDRESS:54321
日常管理命令:
- 启动 H2O:
./h2o-cluster-start-h2o.sh - 停止 H2O:
./h2o-cluster-stop-h2o.sh(通过killall java终止各节点上的 H2O 进程) - 关闭整个集群:使用 Amazon AWS 控制台手动终止实例
注意:要成功导入数据,数据文件必须位于所有节点的相同位置(例如 S3 上的同一路径)。
七、启动 H2O 前的环境准备
端口与虚拟化类型
在 EC2 集群上启动 H2O 之前,请确认 TCP 端口 54321 和 54322 均可访问。
选择操作系统与预构建 AMI 的虚拟化类型时:Windows 用户必须使用硬件辅助虚拟机(HVM);Linux 用户可在半虚拟化(PV)与 HVM 之间选择。该选择决定了你能启动的实例类型。
配置实例
- 为实例选择 IAM 角色与策略。H2O 会自动检测实例关联的临时访问密钥,因此无需再把 AWS 凭证复制到实例上。
- 启动实例时,选择一个可访问的密钥对(Key Pair)。
Windows 用户:隧道接入实例
如果 Windows 终端无法直接使用 ssh,可安装 Cygwin 或自带 ssh 的 Git Bash,然后直接连接:
ssh -i amy_account.pem ec2-user@54.165.25.98
否则可下载 PuTTY,按以下步骤操作:
- 启动 PuTTY Key Generator;
- 加载下载好的 AWS pem 密钥文件(若看不到文件,把浏览器文件类型切换为 "All");
- 将私钥保存为
.ppk文件; - 启动 PuTTY 客户端;
- 在 Session 区域输入主机名或 IP 地址——Ubuntu 用户默认主机名为
ubuntu@<ip-address>,Linux 用户默认主机名为ec2-user@<ip-address>; - 在左侧选择 SSH → Auth,点击 Browse 按钮选择用于认证的私钥文件;
- 开始新会话,点击 Yes 确认缓存服务器的 rsa2 密钥指纹并继续连接。
下载 Java 与 H2O
- 若实例上尚未安装 Java,请先安装 JDK 1.8 或更高版本;
- 用
wget从 H2O 下载页面复制所选 build 对应的 zip 链接,然后依次执行:
wget http://h2o-release.s3.amazonaws.com/h2o/{{branch_name}}/{{build_number}}/index.html
unzip h2o-{{project_version}}.zip
cd h2o-{{project_version}}
java -Xmx4g -jar h2o.jar
- 打开浏览器访问
<Private_IP_Address>:54321或<Public_DNS>:54321,即可使用 H2O 的 Web 界面(Flow)。
附录:S3 客户端调优相关的系统属性速查
如果需要进一步调优 S3 访问行为(超时、重试、区域、自定义凭证提供者等),PersistS3.java 中定义了以下以 sys.ai.h2o.persist.s3. 为前缀的系统属性:
| 系统属性 | 作用 |
|---|---|
sys.ai.h2o.persist.s3.socketTimeout |
Socket 超时时间 |
sys.ai.h2o.persist.s3.connectionTimeout |
连接超时时间 |
sys.ai.h2o.persist.s3.maxErrorRetry |
最大错误重试次数 |
sys.ai.h2o.persist.s3.maxHttpConnections |
最大 HTTP 连接数 |
sys.ai.h2o.persist.s3.force.http |
强制使用 HTTP 协议 |
sys.ai.h2o.persist.s3.endPoint |
S3 endpoint(可用于指向 Minio 等服务端) |
sys.ai.h2o.persist.s3.region |
S3 区域,如 us-east-1 |
sys.ai.h2o.persist.s3.enable.path.style |
启用 path-style 访问(Minio 推荐) |
sys.ai.h2o.persist.s3.customCredentialsProviderClass |
自定义凭证提供者类名 |
sys.ai.h2o.persist.s3.clientFactoryClass |
自定义 S3 客户端工厂类名 |
例如,连接 Minio 云存储(S3 兼容服务)时,官方更新版文档给出了如下启动方式:
java -Dsys.ai.h2o.persist.s3.endPoint=https://play.min.io:9000 \
-Dsys.ai.h2o.persist.s3.enable.path.style=true \
-jar h2o.jar -hdfs_config core-site.xml
随后即可通过 h2o.importFile(path = "s3://bucket/path/to/file.csv")(R)、h2o.import_file(...)(Python)或 Flow 中的 importFiles [ "s3://bucket/path/to/file.csv" ] 导入 Minio 上的数据。
从整体看,H2O 的 S3 集成遵循"配置驱动 + 提供者链兜底"的设计:core-site.xml 与 properties 文件适合静态凭证的批量化部署,R/Python 动态 API 适合运行时灵活切换凭证,而 IAM 角色则在多节点场景下彻底免去密钥分发环节。结合本文的部署步骤与底层凭证链说明,你可以根据实际安全策略选择最合适的凭证管理方式。

