配置Flink SQL+Iceberg+Hive Metastore时遇S3AFileSystem缺失错误

问题场景 #

在全新安装的Flink 1.18.1环境中配置Flink SQL结合Apache Iceberg目录与Hive Metastore，执行CREATE DATABASE时触发错误：

MetaException(message:java.lang.RuntimeException: java.lang.ClassNotFoundException: Class org.apache.hadoop.fs.s3a.S3AFileSystem not found)

核心原因 #

错误根源在于Hive Metastore（HMS）自身缺少S3A文件系统的依赖：当Iceberg通过HMS创建数据库时，HMS需要访问MinIO的S3存储路径，但当前使用的HMS镜像未包含hadoop-aws等必要依赖，导致无法识别s3a://协议的FileSystem实现。

同时存在两个次要问题：

• Iceberg Flink Runtime版本与Flink版本不匹配
• Flink侧部分依赖未放入正确的类路径目录

解决步骤 #

1. 替换Iceberg Flink Runtime为对应Flink版本的包 #

Iceberg的Runtime包必须与Flink版本严格对应，Flink 1.18需要使用iceberg-flink-runtime-1.18系列：

# 删除旧的不匹配包
rm ./lib/iceberg/iceberg-flink-runtime-1.17-1.4.3.jar
# 下载对应Flink 1.18的版本
curl https://repo1.maven.org/maven2/org/apache/iceberg/iceberg-flink-runtime-1.18/1.4.3/iceberg-flink-runtime-1.18-1.4.3.jar -o ./lib/iceberg/iceberg-flink-runtime-1.18-1.4.3.jar

2. 调整Flink侧依赖位置 #

将hadoop-aws包移动到Flink的lib根目录，确保能被类路径扫描到：

cp ./lib/aws/hadoop-aws-3.3.6.jar ./lib/

3. 给Hive Metastore添加S3支持 #

3.1 准备依赖包

下载HMS需要的S3相关依赖：

• hadoop-aws-3.3.6.jar
• aws-java-sdk-bundle-1.12.592.jar（hadoop-aws的依赖包）
• hadoop-common-3.3.6.jar

3.2 创建Hive配置文件

创建hive-site.xml，配置S3连接参数（注意HMS容器内要能访问MinIO，这里用容器名minio作为地址）：

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <property>
        <name>fs.s3a.access.key</name>
        <value>admin</value>
    </property>
    <property>
        <name>fs.s3a.secret.key</name>
        <value>password</value>
    </property>
    <property>
        <name>fs.s3a.endpoint</name>
        <value>http://minio:9000</value>
    </property>
    <property>
        <name>fs.s3a.path.style.access</name>
        <value>true</value>
    </property>
    <property>
        <name>fs.s3a.impl</name>
        <value>org.apache.hadoop.fs.s3a.S3AFileSystem</value>
    </property>
</configuration>

3.3 重新启动HMS容器

挂载配置文件和依赖包到HMS容器，确保容器能访问MinIO（使用host网络或自定义网络）：

# 先停止旧的HMS容器
docker stop hms-standalone

# 启动新的HMS容器，替换<本地路径>为你存放文件的实际路径
docker run --rm --detach --name hms-standalone \
           --publish 9083:9083 \
           --network host \
           -v <本地路径>/hive-site.xml:/etc/hive/conf/hive-site.xml \
           -v <本地路径>/hadoop-aws-3.3.6.jar:/usr/lib/hive/lib/hadoop-aws-3.3.6.jar \
           -v <本地路径>/aws-java-sdk-bundle-1.12.592.jar:/usr/lib/hive/lib/aws-java-sdk-bundle-1.12.592.jar \
           -v <本地路径>/hadoop-common-3.3.6.jar:/usr/lib/hive/lib/hadoop-common-3.3.6.jar \
           ghcr.io/recap-build/hive-metastore-standalone:latest

4. 修正Iceberg Catalog配置 #

修改Catalog创建语句中的S3地址，确保HMS能访问（如果用host网络可以保留localhost，否则用MinIO容器名）：

CREATE CATALOG c_iceberg_hive WITH (
   'type' = 'iceberg',
   'warehouse' = 's3a://warehouse',
   's3.endpoint' = 'http://localhost:9000',
   's3.path-style-access' = 'true',
   'catalog-type'='hive',
   'uri'='thrift://localhost:9083');

验证 #

重新启动Flink SQL Client，执行以下命令验证：

USE CATALOG c_iceberg_hive;
CREATE DATABASE db_rmoff;
-- 执行成功则问题解决

内容的提问来源于stack exchange，提问作者Robin Moffatt