Extension Bridge¶

Larger capabilities, such as conversational BI, dbt pipelines, ingestion with dlt and the OpenMetadata data catalog, live in extensions. Each one has its own Compose project (and, except OpenMetadata, a Helm chart), dependencies, images, version, changelog and CI, and talks to the core only through the Extension Bridge. The core and an extension are released independently and work together as long as both support the same contract version.

flowchart LR
    subgraph Core[iceberg-platform]
        Bridge[Extension Bridge /bridge/v1]
        Keycloak
        Polaris[Apache Polaris]
        RustFS
        Users[User portal]
    end
    subgraph Extension[Extension, e.g. iceberg-conversationalbi]
        App[Gateway: UI, API and MCP]
        Worker[Query worker]
    end
    Person[User or AI agent] -->|Keycloak sign-in: ext-id clients| App
    App -->|User context, automation principals, tokens| Bridge
    Worker -->|Short-lived Iceberg REST token| Polaris
    Worker -->|Vended credentials| RustFS
    Users -.->|Link| App

The contract¶

The Extension Bridge contract ships with every core release. It gives an extension the signed-in user's teams and databases, and automation principals: service accounts that act for one team in one environment, enabled only by that team's Administrators, with short-lived catalog tokens whose lifetime the platform sets (POLARIS_TOKEN_LIFETIME, one hour by default; each token reports it in expiresIn). Team shares the team received reach their read role. A listing extension reads the data shares that team administrators list in a data catalog (capability listings): GET /bridge/v1/listings for a cheap summary to poll, and GET /bridge/v1/listings/{shareId} for the metadata of the listed objects, with an ETag. It gets no token and no data. Extensions sign in through their own Keycloak clients, whose tokens Polaris refuses. Any producer may describe a table with the table-property conventions, which the catalog shows as Produced by. See the resource model for how automation principals are stored, and COMPATIBILITY.md for versioning. Changes are listed in the contract changelog.

Register an extension¶

uv run python -m scripts.setup --extension conversationalbi --origin http://localhost:3007 --handshake extensions/conversationalbi/.env.bridge
docker compose up -d --wait
docker compose -f compose.users.yaml up -d --wait users

Add --listing for an extension that publishes listings, such as OpenMetadata; it is added to PLATFORM_LISTING_EXTENSIONS, and the user portal then offers Listed in the data catalog on data shares. Recreating the platform services creates the extension's Keycloak clients and adds a link in the user portal. On the administration portal's Teams page, platform administrators see every automation principal and can revoke it. --remove-extension <id> unregisters an extension; its clients are disabled on the next start.

On Kubernetes, the platform chart's extensions value registers an extension: --set extensions.<id>.host=<host> writes its handshake to the Secret iceberg-bridge-<id>, which the extension's chart reads in the same namespace. Its isolated jobs run in a namespace of its own with the label io.iceberg-platform.isolated (see the network contract).

Extensions in this repository¶