Iceberg REST Federation

Polaris can federate an external Iceberg REST catalog (e.g., another Polaris deployment, AWS Glue, or a custom Iceberg REST implementation), enabling a Polaris service to access table and view entities managed by remote Iceberg REST Catalogs.

Runtime requirements

  • REST endpoint: The remote service must expose the Iceberg REST specification. Configure firewalls so Polaris can reach the base URI you provide in the connection config.
  • Authentication: Polaris forwards requests using the credentials defined in ConnectionConfigInfo.AuthenticationParameters. OAuth2 client credentials, bearer tokens, and AWS SigV4 are supported; choose the scheme the remote service expects.

Creating a federated REST catalog

The snippet below registers an external catalog that forwards to a remote Polaris server using OAuth2 client credentials. iceberg-remote-catalog-name is optional; supply it when the remote server multiplexes multiple logical catalogs under one 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-scopes "PRINCIPAL_ROLE:ALL" \
    analytics_rest

Refer to the CLI documentation for details on alternative authentication types such as BEARER or SIGV4.

Grant catalog roles to principal roles the same way you do for internal catalogs so compute engines receive tokens with access to the federated namespace.

Operational notes

  • Connectivity checks: Polaris does not lazily probe the remote service; catalog creation fails if the REST endpoint is unreachable or authentication is rejected.
  • Feature parity: Federation exposes whatever table/namespace operations the remote service implements. Unsupported features return the remote error directly to callers.
  • Generic tables: The REST federation path currently surfaces Iceberg tables only; generic table federation is not implemented.