从 Hive 到 Polaris：Apache Polaris Catalog 联邦查询功能实战指南

【免费下载链接】polaris-catalog Polaris Catalog is an open source catalog for Apache Iceberg 项目地址: https://gitcode.com/gh_mirrors/po/polaris-catalog

Apache Polaris Catalog 是 Apache Iceberg 的开源目录服务，它能够将现有的 Hive Metastore (HMS) 联邦到统一的查询入口，让外部 HMS 保持表元数据的权威性，同时通过 Polaris 实现访问控制、策略管理和多引擎连接。本文将详细介绍如何从 Hive 无缝迁移到 Polaris，实现高效的联邦查询功能。

Polaris 联邦查询架构解析

Polaris 的外部目录架构通过同步代理（Sync Agents）连接多种数据源，实现统一的元数据管理和查询访问。以下是 Polaris 联邦查询的核心架构图：

从架构图可以看出，Polaris 通过 External Catalogs 层整合了多种数据源，包括 Hive Metastore，同时提供统一的 Iceberg REST Catalog API 供数据消费者（如 Trino、Spark SQL、Snowflake 等）访问。这种架构使得 Hive 用户可以平滑过渡到 Polaris，无需大规模修改现有数据 pipeline。

构建支持 Hive 联邦的 Polaris 服务

要启用 Hive 联邦功能，需要在构建 Polaris 时包含 Hive 扩展。Hive 工厂作为可选扩展，默认不包含在服务器构建中，因此需要通过 Gradle 属性显式指定。

构建命令

在项目根目录执行以下命令，构建包含 Hive 支持的 Polaris 服务器：

./gradlew :polaris-server:assemble :polaris-server:quarkusAppPartsBuild --rerun \
  -DNonRESTCatalogs=HIVE -Dquarkus.container-image.build=true

此命令会将 Hive 扩展编译到 Polaris 服务器中，runtime/server/build.gradle.kts 文件会根据 NonRESTCatalogs 标志决定是否包含 Hive 支持。如果未设置此标志，构建的二进制文件将拒绝 Hive 联邦请求。

配置 Polaris 支持 Hive 联邦

构建完成后，需要在配置文件中启用相关功能标志，以支持 Hive 联邦。

配置文件设置

在 application.properties 文件中添加以下配置：

# 允许 REST 和 HIVE 连接类型
polaris.features."SUPPORTED_CATALOG_CONNECTION_TYPES"=["ICEBERG_REST","HIVE"]

# 允许 IMPLICIT 身份验证，Hive 联邦需要
polaris.features."SUPPORTED_EXTERNAL_CATALOG_AUTHENTICATION_TYPES"=["OAUTH","IMPLICIT"]

# 启用目录联邦功能
polaris.features."ENABLE_CATALOG_FEDERATION"=true

对于 Kubernetes 部署，这些属性应添加到挂载到 Polaris 容器的 ConfigMap 中（通常位于 /deployment/config/application.properties）。

运行时环境要求

要成功运行支持 Hive 联邦的 Polaris，需要满足以下运行时要求：

元数据存储连接

• Metastore 连接性：确保 Polaris 部署可以访问 HMS Thrift 端点（thrift://host:port）。
• 配置发现：Iceberg 的 HiveCatalog 从类路径加载 Hadoop/Hive 客户端设置。通过 HADOOP_CONF_DIR/HIVE_CONF_DIR 提供 hive-site.xml（必要时提供 core-site.xml）。

身份验证设置

Hive 联邦仅支持 IMPLICIT 身份验证，这意味着 Polaris 使用运行进程的操作系统或 Kerberos 身份（不存储密钥）。确保服务主体在启动 Polaris 之前已登录或持有有效的 keytab/TGT。

Kerberos 配置示例

如果 Hive Metastore 启用了 Kerberos，需要配置以下环境变量：

export KRB5_CONFIG=/etc/polaris/krb5.conf
export HADOOP_CONF_DIR=/etc/polaris/hadoop-conf   # 包含带有 HMS 主体的 hive-site.xml
export HADOOP_OPTS="-Djava.security.auth.login.config=/etc/polaris/jaas.conf"
kinit -kt /etc/polaris/keytabs/polaris.keytab polaris/service@EXAMPLE.COM

• hive-site.xml 必须定义 hive.metastore.sasl.enabled=true、metastore 主体和客户端主体模式（例如 hive.metastore.client.kerberos.principal=polaris/_HOST@REALM）。
• JAAS 条目（由 java.security.auth.login.config 引用）应使用 useKeyTab=true 并指向上述 keytab，以便 Polaris JVM 可以自动刷新凭据。

对象存储角色配置

配置 polaris.service-identity.<realm>.aws-iam.*（或默认 realm），使服务器能够承担目录引用的 AWS 角色。IAM 角色必须允许 Polaris 服务身份的 STS 访问，并授予表位置的权限。

创建联邦目录

使用管理 API（或 Python CLI）创建连接类型为 HIVE 的外部目录。以下示例注册一个代理到 thrift://hms.example.internal:9083 上运行的 HMS 的目录：

API 请求示例

curl -X POST https://<polaris-host>/management/v1/catalogs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "type": "EXTERNAL",
        "name": "analytics_hms",
        "storageConfigInfo": {
          "storageType": "S3",
          "roleArn": "arn:aws:iam::123456789012:role/polaris-warehouse-access",
          "region": "us-east-1"
        },
        "properties": { "default-base-location": "s3://analytics-bucket/warehouse/" },
        "connectionConfigInfo": {
          "connectionType": "HIVE",
          "uri": "thrift://hms.example.internal:9083",
          "warehouse": "s3://analytics-bucket/warehouse/",
          "authenticationParameters": { "authenticationType": "IMPLICIT" }
        }
      }'

default-base-location 是必需的，它告诉 Polaris 和 Iceberg 在哪里放置新的元数据文件。allowedLocations 是可选的，仅在希望将写入者限制到特定前缀集时提供。如果 IAM 信任策略需要 externalId 或显式 userArn，可在 storageConfigInfo 中包含这些可选字段。

限制和操作注意事项

在使用 Hive 联邦功能时，需要注意以下限制和操作建议：

• 单一身份：由于只允许 IMPLICIT 身份验证，Polaris 无法在单个部署中混合多个 Hive 身份（HiveFederatedCatalogFactory 拒绝其他身份验证类型）。规划将 Polaris 进程身份与目标 HMS 对齐的部署拓扑。
• 通用表：Hive 扩展公开在 HMS 中注册的 Iceberg 表。通用表联邦尚未实现（HiveFederatedCatalogFactory#createGenericCatalog 抛出 UnsupportedOperationException）。
• 配置缓存：尚未处理 Atlas 风格的目录故障转移和多 HMS 路由；Polaris 为每个连接初始化一个 HiveCatalog，并依赖底层 Iceberg 客户端进行重试。

满足这些约束后，Polaris 可以位于 HMS 前面，使得在那里管理的 Iceberg 表通过 Polaris REST API 获得 OAuth 保护的多引擎访问。

通过以上步骤，您可以成功将 Hive Metastore 联邦到 Apache Polaris Catalog，实现统一的元数据管理和多引擎查询访问，为您的数据分析工作流带来更大的灵活性和效率。如果您想了解更多关于 Polaris 的信息，可以参考官方文档 docs/federation/hive-metastore-federation.md。

【免费下载链接】polaris-catalog Polaris Catalog is an open source catalog for Apache Iceberg 项目地址: https://gitcode.com/gh_mirrors/po/polaris-catalog