Iceberg REST 联邦

Polaris 可以联邦外部的 Iceberg REST 目录（例如另一个 Polaris 部署、AWS Glue 或自定义的 Iceberg REST 实现），从而使 Polaris 服务能够访问由远端 Iceberg REST 目录管理的表和视图实体。

运行时要求

• REST 端点： 远端服务必须暴露 Iceberg REST 规范。请配置防火墙，确保 Polaris 能够访问你在连接配置中提供的基础 URI。
• 身份认证： Polaris 会使用 ConnectionConfigInfo.AuthenticationParameters 中定义的凭据转发请求。支持 OAuth2 客户端凭据、Bearer 令牌以及 AWS SigV4；请选择远端服务所期望的认证方式。

功能配置

目录联邦功能默认处于禁用状态。请在你的 application.properties 文件中（或等效的配置机制，例如环境变量或 Kubernetes ConfigMap）启用相应的功能标志：

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

创建联合 REST 目录

下面的代码片段注册了一个外部目录，该目录通过 OAuth2 客户端凭据将请求转发到远程 Polaris 服务器。iceberg-remote-catalog-name 为可选项；当远程服务器在同一 URI 下复用多个逻辑目录时，需提供该参数。

polaris catalogs create \
    --type EXTERNAL \
    --storage-type s3 \
    --role-arn "arn:aws:iam::123456789012:role/polaris-warehouse-access" \
    --default-base-location "s3://analytics-bucket/warehouse/" \
    --catalog-connection-type iceberg-rest \
    --iceberg-remote-catalog-name analytics \
    --catalog-uri "https://remote-polaris.example.com/catalog/v1" \
    --catalog-authentication-type OAUTH \
    --catalog-token-uri "https://remote-polaris.example.com/catalog/v1/oauth/tokens" \
    --catalog-client-id "<remote-client-id>" \
    --catalog-client-secret "<remote-client-secret>" \
    --catalog-client-scope "PRINCIPAL_ROLE:ALL" \
    analytics_rest

请参阅 CLI 文档，了解 BEARER 或 SIGV4 等其他认证类型的详细信息。

像为内部目录授予权限那样，将目录角色授予主体角色，使计算引擎能够获取具有联邦命名空间访问权限的令牌。

出站 HTTP 设置

Iceberg REST 联邦使用 Iceberg 的 HTTP 客户端。你可以在创建或更新外部目录时（通过 --property 或 --set-property）添加目录属性，从而透传非敏感的 HTTP 设置。

⚠️ 警告

目录属性会作为 Iceberg REST /config 响应的一部分返回给已认证的目录客户端。请仅在目录属性中放置非敏感的客户端配置。不要将密码、令牌、访问密钥或其他机密信息放入目录属性中。

常见设置包括：

• rest.client.proxy.hostname
• rest.client.proxy.port
• rest.client.connection-timeout-ms
• rest.client.socket-timeout-ms

示例：

polaris catalogs update analytics_rest \
    --set-property rest.client.proxy.hostname=proxy.example.com \
    --set-property rest.client.proxy.port=3128 \
    --set-property rest.client.connection-timeout-ms=30000 \
    --set-property rest.client.socket-timeout-ms=120000

连接配置属性（URI 和身份验证）在键相同时优先。

运维说明

• 连通性检查： Polaris 不会惰性探测远程服务；如果 REST 端点不可达或身份验证被拒绝，目录创建将会失败。
• 功能对等： Federation 会暴露远程服务所实现的全部表/命名空间操作。不受支持的功能会将远程错误直接返回给调用方。
• 注册表覆盖： 带有 overwrite=true 的 POST /v1/{catalog}/namespaces/{namespace}/register 目前仅适用于内部 Polaris 目录。对于联邦的外部目录，Polaris 会拒绝覆盖注册请求。
• 通用表： REST 联邦路径目前仅暴露 Iceberg 表；通用表联邦尚未实现。