Hive Metastore 联邦

Polaris 可以将目录操作联邦（federate）到现有的 Hive Metastore（HMS）。这样，外部 HMS 可以继续作为表元数据的事实来源（source of truth），而 Polaris 则负责代理访问、权限策略以及多引擎连接。

构建时启用

Hive 工厂（factory）作为可选扩展打包提供，未包含在默认的服务器构建中。在组装运行时或容器镜像时，需要将 NonRESTCatalogs Gradle 属性设置为包含 HIVE（以及你需要的任何其他非 REST 后端），以将其纳入构建：

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

runtime/server/build.gradle.kts 仅在存在该标志时才会接入此扩展，因此未启用该标志构建的二进制文件将拒绝 Hive 联邦请求。

功能配置

在构建了支持 Hive 的 Polaris 之后，请在 application.properties 文件（或等效的配置机制，例如环境变量或 Kubernetes ConfigMap）中启用所需的功能标志：

# Allows both REST and HIVE connection type
polaris.features."SUPPORTED_CATALOG_CONNECTION_TYPES"=["ICEBERG_REST","HIVE"]

# Allows IMPLICIT authentication, needed for Hive federation
polaris.features."SUPPORTED_EXTERNAL_CATALOG_AUTHENTICATION_TYPES"=["OAUTH","IMPLICIT"]

# Enables the federation feature itself
polaris.features."ENABLE_CATALOG_FEDERATION"=true

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

运行时要求

• 元数据存储连通性： 将 HMS Thrift 端点（thrift://host:port）暴露给 Polaris 部署。
• 配置发现： Iceberg 的 HiveCatalog 会从类路径加载 Hadoop/Hive 客户端设置。请通过 HADOOP_CONF_DIR/HIVE_CONF_DIR 或镜像层提供 hive-site.xml（如有需要还包括 core-site.xml）。
• 认证： Hive 联邦仅支持 IMPLICIT 认证，即 Polaris 使用运行进程的操作系统身份或 Kerberos 身份（不存储密钥）。请确保在启动 Polaris 之前，服务主体已登录或持有有效的 keytab/TGT。
• 对象存储角色： 配置 polaris.service-identity.<realm>.aws-iam.*（或默认 realm），以便服务器可以承担目录中引用的 AWS 角色。该 IAM 角色必须允许 Polaris 服务身份进行 STS 访问，并授予对表位置的相应权限。

Kerberos 配置示例

如果你的 Hive Metastore 强制要求 Kerberos，请将必要的配置与 Polaris 一同准备：

export KRB5_CONFIG=/etc/polaris/krb5.conf
export HADOOP_CONF_DIR=/etc/polaris/hadoop-conf   # contains hive-site.xml with HMS principal
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）。
• 由 java.security.auth.login.config 引用的 JAAS 条目应使用 useKeyTab=true，并指向上面所示的同一个 keytab，以便 Polaris JVM 能够自动刷新凭据。
• keytab 应仅对 Polaris 服务用户可读；隐式认证器会在启动时以及周期性续期时使用该 TGT。

仓库访问模式

当 Polaris 联邦到 HMS 时，服务端的 HiveCatalog 必须能够自行访问仓库存储，以便加载表元数据。这发生在 Polaris 返回任何客户端存储凭据之前。因此，实践中只有当 Polaris 服务端已具备可用的仓库访问路径时，Hive 联邦才能正常工作。

使用 -PNonRESTCatalogs=HIVE 构建 Polaris 后，当前的运行时行为可理解如下：

hive-site.xml 和 core-site.xml 可以通过 HADOOP_CONF_DIR / HIVE_CONF_DIR 挂载；它们本身并不要求重新构建 Polaris。相比之下，添加缺失的文件系统客户端库（例如 hadoop-aws）则需要对 Polaris 运行时或容器镜像进行自定义打包。

创建联邦目录

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

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 中包含这些可选字段。Polaris 会持久化这些字段，并在元数据提交期间代入 roleArn 所引用的角色时提供它们。

限制与操作注意事项

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

在满足这些限制条件后，Polaris 可以部署在 HMS 前端，使此处管理的 Iceberg 表通过 Pololaris REST API 获得受 OAuth 保护的多引擎访问能力。