H2O 3 在 EC2 上配置 S3 访问凭证完整指南:core-site.xml、API 动态设置与多节点集群部署

原创2026-10-14 19:49:171,659 阅读
文章标签:人工智能机器学习AutoML大数据

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,其凭证提供者链按顺序为:

  1. H2ODynamicCredentialsProvider:从 DKV 读取 IcedS3Credentials,返回 BasicAWSCredentials 或 BasicSessionCredentials(PersistS3.java);
  2. H2OArgCredentialsProvider:读取命令行参数 --aws_credentials 指定的 properties 文件(默认位置为 AwsCredentials.properties),支持 accessKey / secretKey 键值对(PersistS3.java);
  3. 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 之间选择。该选择决定了你能启动的实例类型。

EC2 操作系统与虚拟化类型选择界面

配置实例

  1. 为实例选择 IAM 角色与策略。H2O 会自动检测实例关联的临时访问密钥,因此无需再把 AWS 凭证复制到实例上。
  2. 启动实例时,选择一个可访问的密钥对(Key Pair)。

EC2 实例配置界面(IAM 角色选择)

Windows 用户:隧道接入实例

如果 Windows 终端无法直接使用 ssh,可安装 Cygwin 或自带 ssh 的 Git Bash,然后直接连接:

ssh -i amy_account.pem ec2-user@54.165.25.98

否则可下载 PuTTY,按以下步骤操作:

  1. 启动 PuTTY Key Generator;
  2. 加载下载好的 AWS pem 密钥文件(若看不到文件,把浏览器文件类型切换为 "All");
  3. 将私钥保存为 .ppk 文件;
  4. 启动 PuTTY 客户端;
  5. 在 Session 区域输入主机名或 IP 地址——Ubuntu 用户默认主机名为 ubuntu@<ip-address>,Linux 用户默认主机名为 ec2-user@<ip-address>;
  6. 在左侧选择 SSH → Auth,点击 Browse 按钮选择用于认证的私钥文件;
  7. 开始新会话,点击 Yes 确认缓存服务器的 rsa2 密钥指纹并继续连接。

下载 Java 与 H2O

  1. 若实例上尚未安装 Java,请先安装 JDK 1.8 或更高版本;
  2. 用 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
  1. 打开浏览器访问 <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 角色则在多节点场景下彻底免去密钥分发环节。结合本文的部署步骤与底层凭证链说明,你可以根据实际安全策略选择最合适的凭证管理方式。

登录后查看全文
h2o-3