Iceberg Federation

Overview

Federation places an existing Iceberg REST catalog behind Gravitino without moving any metadata. You register the remote catalog as a Gravitino Iceberg catalog with catalog-backend set to rest, and Gravitino proxies namespace and table operations to it. The remote catalog remains the system of record for its own tables.

The remote catalog also remains the authority on access. Gravitino forwards the caller's identity, and the remote catalog decides what that caller may see, vends the credentials for reading the data, and records the access in its own audit trail. Gravitino contributes a single endpoint, a shared namespace across every catalog in the metalake, and the tags and policies it holds at the metadata layer.

Any implementation of the Iceberg REST specification can be federated, including another Gravitino server, Apache Polaris, or a vendor catalog service.

Quick Start

Federating a catalog is a single catalog creation call against a running Gravitino server. The example below federates a remote catalog named sales that lives on another Iceberg REST server.

1. Create the catalog. Point uri at the remote Iceberg REST endpoint, and set warehouse to the name of the catalog you want on that endpoint.

export GRAVITINO_URI=http://{gravitino_host}:8090
export METALAKE={metalake_name}

curl -X POST -H "Content-Type: application/json" \
  -d '{
        "name": "federated_sales",
        "type": "RELATIONAL",
        "provider": "lakehouse-iceberg",
        "properties": {
          "catalog-backend": "rest",
          "uri": "https://{remote_host}/iceberg/",
          "warehouse": "sales",
          "table-metadata-cache-impl": ""
        }
      }' \
  "${GRAVITINO_URI}/api/metalakes/${METALAKE}/catalogs"

2. Read it back through Gravitino. The federated catalog behaves like any other catalog in the metalake.

curl "${GRAVITINO_URI}/api/metalakes/${METALAKE}/catalogs/federated_sales/schemas"

3. Reach it from an engine. Any Iceberg REST client can read the same catalog through the Gravitino Iceberg REST service by using the catalog name as the prefix. See Iceberg REST Catalog Service for the service configuration.

Identifying the Remote Catalog

Two properties describe where the federated metadata lives, and they are easy to confuse.

Property	Meaning	Required
uri	The base URI of the remote Iceberg REST endpoint	Yes
warehouse	The catalog to select on that endpoint. In the Iceberg REST specification this value identifies the catalog	No

For every other backend, warehouse is a storage location such as s3://{bucket}/{prefix}. For a REST backend it is a catalog name, because that is what the Iceberg REST specification uses it for. A remote server that exposes several catalogs under one URI needs this value to know which one you mean, and a server that exposes only one does not.

Gravitino never writes data for a federated catalog and never needs a storage location of its own, so no warehouse path is configured on this side.

Passing the Caller's Identity

A REST backend always forwards the caller's authorization header to the remote catalog. Gravitino takes the header value from the authenticated principal and places it on every outgoing request, so the remote catalog sees the end user rather than a shared service account.

Forwarding is unconditional for this backend and cannot be turned off. Requests made by a principal that carries no token fail with an error stating that the principal has no authorization header value, so an anonymous or unauthenticated caller cannot reach a federated catalog at all.

What the Remote Catalog Must Accept

The header is forwarded exactly as it arrived. Gravitino does not exchange the token, re-sign it, or request a new one on the caller's behalf. Both servers therefore have to accept the same token, which means both trust the same identity provider and the remote catalog accepts the audience the token was issued for.

The usual failure is the audience. A token minted for Gravitino carries Gravitino's audience claim, and a remote catalog that validates audience strictly rejects it. Either register one application in the identity provider that both servers accept, or configure the remote catalog to accept the audience Gravitino uses.

Configure authentication on the Gravitino side as described in How to Authenticate.

Authorizing Federated Access

By default, a Gravitino Iceberg REST service that proxies to a REST backend does not run its own authorization checks. The downstream catalog performs them, and skipping the local check avoids evaluating the same request twice.

Set gravitino.iceberg-rest.disable-rest-authz to false to have Gravitino authorize the request against its own model before proxying. The two checks then both apply, and a caller needs the privilege in Gravitino as well as at the remote catalog.

Value	Behavior
true	Only the remote catalog authorizes the request. This is the default
false	Gravitino authorizes the request first, then proxies it to the remote catalog

The skip applies only when the catalog's backend is genuinely a REST catalog. Every other backend is authorized locally regardless of this setting. See Access Control for the Gravitino privilege model.

Requesting Vended Credentials

Federated tables are read with credentials the remote catalog issues, because it owns the storage configuration. Set data-access on the catalog to ask for them, and Gravitino sends the matching Iceberg access delegation header on each table load.

Value	Effect
vended-credentials	The remote catalog returns scoped storage credentials with the table
remote-signing	The remote catalog signs storage requests instead of handing out credentials

Any other value is rejected when the catalog is created. If the property is left unset, no delegation header is sent and the client falls back to whatever storage credentials it already has.

For how Gravitino vends credentials for the catalogs it owns, see Credential Vending.

Tuning the Connection

A federated catalog adds a network hop to every metadata operation, so the client timeouts matter more than they do for a local backend.

Property	Meaning	Default
rest-client-connection-timeout-ms	Time allowed to establish the HTTP connection	10000
rest-client-socket-timeout-ms	Time allowed between bytes on the connection	60000

Set table-metadata-cache-impl to an empty string on a federated catalog. The table metadata cache needs a backend that can report a table's metadata location, and a REST catalog cannot. Leaving the default in place is harmless but logs a warning at catalog load and disables the cache anyway.

Limitations

Gravitino proxies the Iceberg REST protocol and adds nothing to it, so a federated catalog carries the following constraints.

Storage configuration belongs to the remote catalog, and the credentials and file IO settings on the Gravitino catalog do not apply to federated tables. Audit coverage is split, with Gravitino recording the request it received and the remote catalog recording what it did with the request. Table maintenance and statistics run against catalogs Gravitino owns and do not reach federated tables. Tags and policies attached in Gravitino describe the federated metadata but are not visible to a client that talks to the remote catalog directly.

Using the API

Federated catalogs are created, altered, and dropped through the standard catalog endpoints.

Operation	Method	Path
Create catalog	POST	/api/metalakes/{metalake}/catalogs
Load catalog	GET	/api/metalakes/{metalake}/catalogs/{catalog}
Alter catalog	PUT	/api/metalakes/{metalake}/catalogs/{catalog}
Drop catalog	DELETE	/api/metalakes/{metalake}/catalogs/{catalog}

See Manage Catalogs and Schemas for the full request and response payloads, and Iceberg Catalog for the properties shared by all Iceberg catalog backends.