Skip to main content

Iceberg federation

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.

Gravitino connects to the remote catalog in one of two ways, and the choice decides who authorizes access:

  • Forward the user's token. Gravitino passes each caller's own token to the remote catalog, which decides what that caller may see, vends the credentials for reading the data, and records the access in its own audit trail.
  • Connect as a service account. Gravitino presents one configured credential to the remote catalog, authorizes every caller against its own grants, and issues its own storage credentials scoped to the table. Use this for a remote catalog that cannot authorize your users itself, such as a managed catalog that accepts only its own API token.

Either way, 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 or a vendor catalog service.

An engine loads a table from the Iceberg REST service; for the federated catalog, Gravitino forwards the caller's own token to the remote Iceberg REST catalog, which authorizes the caller and returns the metadata and credentials; the engine then reads the remote catalog's data in object storage directly

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.

    Create a federated catalog
    curl -sS -X POST "https://{gravitino_host}/api/metalakes/{metalake}/catalogs" \
    -H "Accept: application/vnd.gravitino.v1+json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $TOKEN" \
    -d '{
    "name": "federated_sales",
    "type": "RELATIONAL",
    "provider": "lakehouse-iceberg",
    "properties": {
    "catalog-backend": "rest",
    "uri": "https://{remote_host}/iceberg",
    "warehouse": "sales",
    "table-metadata-cache-impl": ""
    }
    }'
  2. Read it back through Gravitino. The federated catalog behaves like any other catalog in the metalake.

    List schemas in the federated catalog
    curl -sS "https://{gravitino_host}/api/metalakes/{metalake}/catalogs/federated_sales/schemas" \
    -H "Accept: application/vnd.gravitino.v1+json" \
    -H "Authorization: Bearer $TOKEN"

    With the default connection the token must also be accepted by the remote catalog, because Gravitino forwards it; see Forward the user's token. To connect as a service account instead, see Connect as a service account.

  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.

Identify the remote catalog​

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

PropertyMeaningRequired
uriThe base URI of the remote Iceberg REST endpointYes
warehouseThe catalog to select on that endpoint. In the Iceberg REST specification this value identifies the catalogNo

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.

Forward the user's token​

By default a REST backend 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.

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 connected this way.

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. A caller who signs in with Basic credentials therefore has its user name and password sent to the remote catalog, so use OAuth tokens with federated catalogs. 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.

Connect as a service account​

A service account connection suits a remote catalog that cannot authorize Gravitino's users, for example a managed catalog whose only credential is its own API token. Gravitino presents one configured credential on every request to the remote catalog and authorizes each caller against Gravitino's own grants before anything is proxied.

In the UI, open Connect → Catalogs, click + Catalog, and choose Apache Iceberg with the REST backend. Set Remote authentication to Service account and paste the remote catalog's token into Service account token. The token is held by Gravitino only and is never returned in catalog responses.

The same connection through the API uses these catalog properties:

PropertyMeaningRequired
rest-backend-auth-typeuser-token forwards each caller's token (the default). service-account connects with the credential belowNo
rest-backend-tokenStatic bearer token the service account presents to the remote catalogOne of token or credential with service-account
rest-backend-credentialOAuth client credential (client_id:client_secret) the service account exchanges for a tokenOne of token or credential with service-account
rest-backend-oauth2-server-uriOAuth token endpoint for the client credential. Defaults to the remote catalog's own token endpointNo
rest-backend-scopeOAuth scope requested with the client credentialNo

A static token is used as is and never refreshed; to rotate it, update the catalog property. With a client credential, Gravitino fetches and refreshes the token itself.

A catalog connected as a service account behaves differently from a forwarding catalog in two ways:

  • Gravitino always authorizes it, whatever disable-rest-authz is set to, and the Iceberg REST service refuses to serve it when authorization is disabled. Grant access through roles as for any other catalog; see Privileges.
  • Gravitino always issues the storage credentials for its tables, because credentials the remote catalog vends would carry the service account's access rather than the caller's. Configure them as described in Storage credentials.

Authorize federated access​

By default, a Gravitino Iceberg REST service that proxies to a REST backend forwarding the user's token does not run its own authorization checks. The downstream catalog performs them, and skipping the local check avoids evaluating the same request twice. A catalog connected as a service account is always authorized by Gravitino.

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. Set it under gravitino.additionalConfigItems in my-values.yaml; see Set other server properties.

ValueBehavior
trueOnly the remote catalog authorizes the request. The default
falseGravitino 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 Privileges for the Gravitino privilege model.

When Gravitino authorizes a federated catalog, it keeps grants on the catalog's tables by table name. A table that is dropped and recreated directly in the remote catalog keeps the grants on that name.

Storage credentials​

Engines read a federated table's data directly from object storage, with credentials that either the remote catalog or Gravitino issues.

Credentials from the remote catalog​

By default 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.

ValueEffect
vended-credentialsThe remote catalog returns scoped storage credentials with the table
remote-signingThe 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.

Credentials from Gravitino​

Some remote catalogs vend broad, long-lived credentials, for example the catalog token's own storage keys for the whole bucket. Gravitino can issue the credentials instead, exactly as it does for a catalog it owns: scoped to the table's location, short-lived, and read-only unless the caller holds a write privilege on the table. Gravitino then never asks the remote catalog for credentials, and drops any the remote catalog returns unasked.

In the UI, set Storage credentials to Issued by Gravitino when you create the catalog; a service account catalog always uses Gravitino. Then open the catalog's Storage credentials tab and click + Cloud to add the provider that matches the remote catalog's storage, for example r2-token for Cloudflare R2 or s3-token for Amazon S3. Through the API, set rest-backend-storage-credential-source to local (the default, remote, uses the remote catalog's credentials) and configure credential-providers and the provider's properties on the catalog.

For the providers and their properties, see Credential vending. For Cloudflare R2, see S3-compatible storage.

Tune 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.

PropertyMeaningDefault
rest-client-connection-timeout-msTime allowed to establish the HTTP connection10000
rest-client-socket-timeout-msTime allowed between bytes on the connection60000

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.

Unless Gravitino issues the storage credentials, 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.

Use the API​

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

OperationMethodPath
Create catalogPOST/api/metalakes/{metalake}/catalogs
Load catalogGET/api/metalakes/{metalake}/catalogs/{catalog}
Alter catalogPUT/api/metalakes/{metalake}/catalogs/{catalog}
Drop catalogDELETE/api/metalakes/{metalake}/catalogs/{catalog}

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