Source-Aligned Acquisition
A source-aligned (Bronze, SDP) data product copies data out of a source system and lands it as it is. The acquisition build pattern lets you declare that copy in the contract, rather than writing the ingestion code or an Airflow DAG: you say what to read, which engine reads it, and where the result goes.
Acquisition arrived with schema 0.7.3. The examples on this page use 0.7.5, the current stable schema.
Where this fits
This page is the reference for the acquisition block: engines, where data lands, what each key does, and what the CLI enforces today. Pair it with Product Types (the SDP/ADP/CDP vocabulary) and the Postgres → DuckDB walkthrough (a worked example).
Example: a CSV file to Parquet
Save this as contract.fluid.yaml next to a data/orders.csv, and install the local engine with pip install "data-product-forge[local]".
fluidVersion: "0.7.5"
kind: DataProduct
id: bronze.orders
name: Orders Bronze
domain: sales
metadata:
layer: Bronze
owner:
team: ingestion
email: ingestion@example.com
builds:
- id: ingest_orders
pattern: acquisition
engine: duckdb # a build-level key, not under properties
properties:
source:
kind: filesystem
connection:
uri: data/orders.csv
mode: full_refresh
streams: [orders]
sink:
format: parquet
quality:
gates:
- rule: not_null
columns: [order_id]
severity: error
onError: route_to_dlq
outputs:
- orders_raw
exposes:
- exposeId: orders_raw
kind: table
binding:
platform: local
format: parquet
location:
path: out/orders.parquet
contract:
schema: []
A source requires kind and mode. The build names the expose it fills in outputs, and that expose's binding decides where the data lands (see Where the build lands data).
fluid validate contract.fluid.yaml
fluid apply contract.fluid.yaml --mode amend-and-build --build-id ingest_orders --yes
✅ Valid FLUID contract (schema v0.7.5)
...
duckdb.run stream=orders sql_chars=294
...
✅ Executed: 1
❌ Failed: 0
--mode amend-and-build is what runs the build. A plain fluid apply on a local contract takes the local provider's materialisation path and does not run the acquisition engine.
The run writes the Parquet file and one run record, next to a .fluid/run-id.txt that holds the run's id:
.fluid/run-id.txt
.fluid/runs/bronze.orders/ingest_orders/runs/<run-id>.json
out/orders.parquet
fluid runs status bronze.orders and the other fluid runs commands read those records.
Ingestion engines
The engine is the build's engine key. The values the schema accepts for an acquisition build are duckdb, dlt, meltano, airbyte, kafka-connect and debezium. All of them implement the public Runner protocol in fluid_build.api.runner (see API stability).
| Engine | Reads | Needs |
|---|---|---|
duckdb | source.kind of filesystem (CSV, Parquet, JSON), postgres, mysql or mariadb, sqlite, http | pip install "data-product-forge[local]" (DuckDB 1.5.0 or newer) |
dlt | A dlt verified source, or your own @dlt.source module named in properties.dlt.source_module | The dlt package, for example pip install "dlt[sql_database]" for SQL sources |
meltano | A Singer tap | The tap installed in the same environment, or an existing Meltano project named in properties.meltano.project_dir |
airbyte | An Airbyte connector, through an Airbyte server or PyAirbyte | A reachable Airbyte server for bring-your-own and managed; the airbyte package for embedded |
kafka-connect | A Kafka Connect source connector, driven over the Connect REST API | A Kafka Connect cluster |
debezium | Change data capture from a database, through Kafka Connect or Debezium Server | A Kafka Connect cluster, or the debezium-server binary for embedded |
There are no dlt, meltano, airbyte, kafka-connect or debezium extras on the data-product-forge package: pip install "data-product-forge[dlt]" installs nothing extra. Install the engine's own dependency as shown.
Each runner declares which capabilities and deployment modes it supports. These are the values in the 0.18.1 runner classes:
| Engine | Capabilities | Deployment modes |
|---|---|---|
duckdb | full_refresh, incremental_append, schema_discovery, at_least_once | embedded |
dlt | full_refresh, incremental_append, incremental_merge, schema_evolution, schema_discovery, at_least_once | embedded |
meltano | full_refresh, incremental_append, incremental_dedup, schema_discovery, at_least_once | embedded, bring-your-own |
airbyte | full_refresh, incremental_append, incremental_dedup, cdc, schema_discovery, at_least_once | embedded, bring-your-own, managed |
kafka-connect | streaming, cdc, schema_discovery, at_least_once, exactly_once | bring-your-own, managed |
debezium | streaming, cdc, schema_discovery, at_least_once | embedded, bring-your-own, managed |
Asking for a capability
A build lists the capabilities it needs in builds[].capabilities. At apply time, the CLI compares that list with the engine's declared set and refuses a mismatch before running anything. fluid validate does not make this check.
engine: duckdb
capabilities: [exactly_once]
✗ runner `duckdb` does not support capability ['exactly_once']
why build asks for capabilities=['exactly_once']; runner declares ['at_least_once',
'full_refresh', 'incremental_append', 'schema_discovery'].
fix Switch engine to one declaring ['exactly_once'], or remove from build.capabilities.
This is the typed CapabilityMismatchError. Its doc link prints Capability warnings, which is about LLM model capabilities for fluid forge, not about runners. The runner check is the one above.
Three deployment modes
Airbyte, Meltano, Kafka Connect and Debezium take a deployment block under their own properties key (properties.airbyte.deployment, properties.meltano.deployment, and so on). duckdb and dlt run inside the fluid process and have no deployment key.
deployment.mode | Runs where |
|---|---|
embedded (schema default) | Inside the fluid process, or for Debezium as a local Debezium Server. |
bring-your-own | On a server you already run. Set server_url, and auth.secretRef for the credential. |
managed | On infrastructure the contract describes in a managed block. |
airbyte:
connector_image: airbyte/source-postgres
deployment:
mode: managed
managed:
target: kubernetes # docker | kubernetes | terraform | opentofu
profile: small # small | medium | large
managed.target is required when the mode is managed. The block also accepts chart, values_overlay, secrets and network.egressAllowList.
When deployment.mode is not set, the Airbyte runner uses bring-your-own, not the schema's embedded default.
Where the build lands data
The expose binding that the build lists in outputs decides where a DuckDB build writes. sink only decides the file format. There is no location key under sink, and a contract that sets one fails validation.
The destination is chosen in this order:
| Binding | The build writes |
|---|---|
| A BigQuery table | A staging file, which a load job then loads into the table. |
platform of aws, gcp or azure, with location.bucket | <s3, gs or azure>://<bucket>/<path>/<table>.<ext>. path is relative to the bucket and is always treated as a prefix. <table> is location.table, or the stream name when the binding has none. |
location.path and no bucket | A local file at that path, relative to the contract's directory. |
| Neither | out/<stream>.<ext> in the contract's directory. |
A path that is already a full URI (s3://...) is used as written. When the build reads more than one stream, location.path is not used and each stream lands at out/<stream>.<ext>.
exposes:
- exposeId: orders_raw
kind: table
binding:
platform: aws
format: parquet
location:
bucket: acme-lake
path: bronze/orders
database: bronze
table: orders
region: eu-west-1
With this binding the build writes s3://acme-lake/bronze/orders/orders.parquet. The Glue table that fluid generate iac emits for the same binding points at s3://acme-lake/bronze/orders, so the catalog and the data share one prefix. The destination's DuckDB extensions and credentials come from the destination, not from the source. The AWS-side view of the same landing is in Where a build lands data.
A binding that names no bucket stays on local disk. The build does not invent the {account}-fluid-data bucket that the IaC path falls back to, because moving data off the machine on the strength of a default would be a decision the CLI should not make for you.
sink.format takes iceberg, delta, parquet, csv, json, snowflake_table, bigquery_table, redshift_table or duckdb_table, with optional catalog and partitionBy. The DuckDB runner writes parquet, csv and json files. A streaming build's sink.catalog must name the same Iceberg catalog as the expose it writes (forge-cli #707, since 0.20.0); see Iceberg catalogs.
What the DuckDB sandbox allows
For the DuckDB engine, each connection runs in DuckDB's own sandbox (DuckDB sandbox). For an acquisition build that means:
A local source and each landing path must sit in the contract's directory, its FLUID workspace, or a directory in
FLUID_DUCKDB_ALLOWED_DIRS. Anything else is refused before the build runs:✗ The contract declares '/data/landing/orders.csv' (...), outside the directories it may read and write (...). The operator can allow a directory with FLUID_DUCKDB_ALLOWED_DIRS. fix Move the file under the contract's directory or its workspace, or, as the operator, list its directory in FLUID_DUCKDB_ALLOWED_DIRS (separated by ':').Name a file or a glob as the source
uri. As of 0.18.1, aurithat names a directory outside the contract's directory is refused even whenFLUID_DUCKDB_ALLOWED_DIRSlists it;<dir>/orders.csvor<dir>/*.csvworks.A
source.kind: httpsource is read from the URL you declare, and a declareds3://location is reachable. These are acquisition builds; SQL written inside a contract cannot read anhttp(s)URL.
Iceberg catalogs (location.catalog)
Since 0.20.0
This section describes forge-cli PR #707 and the follow-up fixes in forge-cli #709 and forge-cli #710, the Lakekeeper, Polaris and Unity checks of forge-cli #711, and sink.catalogAuth from forge-cli #712. All five shipped in 0.20.0. forge-cli 0.19.0 and earlier behave as described in On 0.19.0 and earlier, at the end of this section.
An Iceberg expose names the catalog that owns its table in binding.location.catalog. The streaming sinks (Kafka Connect and Debezium Server), dbt's catalogs.yml, the AWS and Confluent modules, fluid policy compile, fluid diff, fluid test and fluid validate read the value through one table in forge-cli (fluid_build/providers/_iceberg_catalog.py), so they agree on which catalog holds the table. The Snowflake module reads it for the Iceberg prerequisites only: the EXTERNAL VOLUME and the Glue catalog integration follow the table. It still emits a snowflake_database, snowflake_schema and snowflake_table for the expose's location.database, location.schema and location.table, whatever the catalog.
Example: stream into Lakekeeper
A Kafka Connect build streams Postgres changes into an Iceberg table that Lakekeeper catalogs, stored in S3:
fluidVersion: 0.7.5
kind: DataProduct
id: bronze.orders_stream
name: Orders stream
domain: sales
metadata:
layer: Bronze
owner:
team: data-platform
exposes:
- exposeId: orders
kind: table
binding:
platform: aws
format: iceberg
location:
catalog: lakekeeper
uri: http://lakekeeper:8181/catalog # Lakekeeper's Iceberg REST endpoint
warehouse: analytics # a Lakekeeper warehouse NAME, not s3://
database: streaming # the Iceberg namespace
table: orders
bucket: acme-lake # the S3 bucket behind the warehouse
region: eu-west-1
contract:
schema:
- name: order_id
type: integer
required: true
- name: amount_cents
type: integer
builds:
- id: stream_orders
pattern: acquisition
engine: kafka-connect
outputs: [orders]
properties:
source:
kind: postgres
mode: incremental_append
streams: [public.orders]
sink:
format: iceberg
kafka-connect:
streamingSink:
autoCreate: true
commitIntervalMs: 5000
The contract validates as written. (forge-cli #711, since 0.20.0) With an s3:// warehouse it would not, and a uri that does not end in /catalog draws a warning; see What a Lakekeeper, Polaris or Unity sink needs. fluid validate requires uri and warehouse for a REST catalog such as Lakekeeper; without uri it fails:
❌ Invalid FLUID contract (1 error(s)) (schema v0.7.5)
Validation completed in 0.001s
Validation Errors:
==================
1. iceberg sink (build 'stream_orders'): lakekeeper catalog requires binding.location.uri
These are the table and catalog keys of the sink config the Kafka Connect runner derives from it:
{
"iceberg.tables": "streaming.orders",
"iceberg.catalog.type": "rest",
"iceberg.catalog.warehouse": "analytics",
"iceberg.catalog.client.region": "eu-west-1",
"iceberg.catalog.uri": "http://lakekeeper:8181/catalog"
}
There is no iceberg.catalog.io-impl, no storage credential, and no catalog credential. (forge-cli #712, since 0.20.0) For a Lakekeeper that requires a token, see Authenticate a sink to a REST catalog. forge-cli picks a FileIO only for a warehouse with an object-store scheme (s3://, gs://, abfss://); a catalog addressed by warehouse name returns the table's storage settings with its metadata. With autoCreate: true, the Apache Iceberg sink creates the table and its namespace itself, as it has since Iceberg 1.6.0 (apache/iceberg#10186). It ignores a refusal to create the namespace, so if the catalog principal the sink uses may not create namespaces, create the streaming namespace for it first.
On AWS, the module holds the bucket and nothing in Glue, because the table lives in Lakekeeper:
fluid generate iac contract.fluid.yaml --out infra
Wrote OpenTofu module: infra/main.tf.json (provider: aws, 1 resources)
The one resource is aws_s3_bucket.bronze_orders_stream_acme_lake. Without bucket the module would hold nothing, and fluid generate iac fails with generate_iac_empty_module (pass --allow-empty if that is what you want).
How a value is read
Spelling. Case, surrounding whitespace, and
-against_are folded, soLakekeeperislakekeeperandSNOWFLAKE_MANAGEDissnowflake-managed. Two spellings are aliases:iceberg-rest(oriceberg_rest) isrest, andsnowflakeissnowflake-managed.No value. An Iceberg expose with no
location.cataloggets its platform's default:glueonplatform: awsandplatform: confluent,snowflake-managedonplatform: snowflake, andreston any other platform. (forge-cli #710, since 0.20.0)platform: confluentreads asgluebecause the Tableflow module publishes such a table to AWS Glue, sofluid policy compileand dbt read the catalog the table is in. With #707 and #709 alone it read asrest, andfluid policy compiledropped the expose's grants with a warning that the table was cataloged inrest; see Other commands. Onplatform: gcpthe default means two things: a streaming sink writes through a REST catalog, while dbt-bigquery and the GCP module create a BigLake table. (forge-cli #709, since 0.20.0) So aplatform: gcpIceberg expose that a streaming sink writes must name its catalog. Without one,fluid validatefails, and so does the Kafka Connect or embedded Debezium Server run before it creates anything. Setcatalog: bigquery, or the REST kind your catalog is. #707 alone accepted it. An expose that no streaming sink writes may still leave the catalog out. The error, for a Kafka Connect buildstream_eventswriting a GCP expose with no catalog:1. iceberg sink (build 'stream_events'): the GCP Iceberg expose sets no binding.location.catalog, so it is read two ways: the sink would write through a REST catalog (the 'gcp' platform default) while dbt-bigquery and the GCP IaC, which read only binding.location.catalog, create a BigLake metastore table. Set binding.location.catalog: bigquery, or the REST kind your catalog is (e.g. rest, lakekeeper)Without
uriandwarehouse, the same build also draws theresterrors for them. Whensink.catalog,iceberg_catalog_overridesor a hand-written sink config sets the catalog, the parentheses name it instead of the platform default. The check reads the catalog that reaches the worker, whether atypeor acatalog-implclass selects it, and refuses every catalog but BigLake (type=bigquery, orcatalog-impl=org.apache.iceberg.gcp.bigquery.BigQueryMetastoreCatalog). A Glue catalog is refused too, fromsink.catalog: glueor from a hand-writteniceberg.catalog.catalog-impl: org.apache.iceberg.aws.glue.GlueCatalog. Forsink.catalog: glue:1. iceberg sink (build 'stream_events'): the GCP Iceberg expose sets no binding.location.catalog, so it is read two ways: the sink would write through a glue catalog (sink.catalog 'glue') while dbt-bigquery and the GCP IaC, which read only binding.location.catalog, create a BigLake metastore table. Set binding.location.catalog: bigquery, or the REST kind your catalog is (e.g. rest, lakekeeper)Once the expose names its catalog, a hand-written sink config must select that same catalog (below).
sink.catalog. A streaming build may setproperties.sink.catalog, but it must name the expose's catalog, because dbt and the modules read only the expose. Spellings are compared after folding. Leave it unset and the sink uses the expose's catalog. (forge-cli #711, since 0.20.0) The schema takessink.catalogfrom a list, in exactly these spellings:rest,glue,nessie,unity,snowflake-managedandhiveon 0.7.5, and those pluslakekeeperandpolarison 0.7.6. With #707 to #710 alone, 0.7.6 had the 0.7.5 list. A 0.7.5 contract whose expose is in Lakekeeper or Polaris leavessink.catalogunset; setting it fails:1. builds[0].properties.sink.catalog: 'lakekeeper' is not one of ['rest', 'glue', 'nessie', 'unity', 'snowflake-managed', 'hive']Any other value is refused by
fluid validateon every Iceberg expose, with the accepted spellings. Aplatform: confluentexpose has its own rule, below.fluid applyon AWS refuses the value too, asunknown-iceberg-catalog, because whether a Glue table exists depends on it. (forge-cli #709, since 0.20.0) So does the native AWS planner thatfluid diffruns; on #707 alone it planned the S3 buckets and no Glue table. A typo on an expose that also declaresgovernance.lakeFormationdraws only the two errors below, not a Lake Formation refusal that names the typo as a catalog.
❌ Invalid FLUID contract (2 error(s)) (schema v0.7.5)
Validation completed in 0.001s
Validation Errors:
==================
1. iceberg sink (build 'stream_orders'): unknown Iceberg catalog 'lakekeper' in binding.location.catalog; use one of: bigquery, dynamodb, glue, hadoop, hive, jdbc, lakekeeper, nessie, polaris, rest, snowflake-managed, unity, iceberg-rest, snowflake
2. expose 'orders': binding.location.catalog 'lakekeper' is not a catalog kind FLUID knows. Use one of: bigquery, dynamodb, glue, hadoop, hive, jdbc, lakekeeper, nessie, polaris, rest, snowflake-managed, unity, iceberg-rest, snowflake. Each emitter guesses differently for an unknown value (the streaming sink writes over Iceberg REST, dbt and the Snowflake IaC treat it as Snowflake-managed), so the table would be written to two different catalogs.
A sink.catalog that names another catalog than the expose:
1. iceberg sink (build 'stream_orders'): sink.catalog 'glue' disagrees with the expose's catalog 'lakekeeper' (binding.location.catalog); the sink would write through glue while dbt and the IaC read lakekeeper. Set binding.location.catalog: glue and drop sink.catalog
(forge-cli #709, since 0.20.0) A hand-written sink config or an override must select the expose's catalog too. A sink_connector_config or iceberg_catalog_overrides on a Kafka Connect build, or a server.sink.config on an embedded Debezium Server build, whose type or catalog-impl selects another catalog than the expose's is an error on every platform: the sink would write one catalog while dbt and the modules read the other. They are compared as the catalog the worker builds, so type=rest matches rest, lakekeeper, polaris, unity and snowflake-managed, and glue matches type=glue or catalog-impl=org.apache.iceberg.aws.glue.GlueCatalog. #707 alone accepted such a config. A hand-written iceberg.catalog.type: rest for an AWS expose with no location.catalog, whose catalog is Glue:
1. iceberg sink (build 'stream_orders'): sink_connector_config sets iceberg.catalog.type='rest', so the sink would write through a REST catalog while dbt and the IaC read the expose's catalog 'glue' (the 'aws' platform default). Declare the catalog the sink writes to in binding.location.catalog; a REST endpoint that fronts Glue (Glue's Iceberg REST endpoint) is catalog: rest
Declare the catalog the sink writes to in binding.location.catalog. A REST endpoint that fronts Glue, such as Glue's Iceberg REST endpoint, is catalog: rest, with its uri and warehouse. On platform: aws the expose is then a table in another catalog: the module creates its bucket and nothing in Glue, and Lake Formation governance on it is refused.
What each kind produces
location.catalog | Sink catalog selector | dbt catalogs.yml on Snowflake | Snowflake module | AWS module | A streaming sink needs |
|---|---|---|---|---|---|
glue | catalog-impl=org.apache.iceberg.aws.glue.GlueCatalog | iceberg_rest | Glue CATALOG INTEGRATION | the bucket, a Glue database and a Glue table | nothing (warns without region) |
rest | type=rest | iceberg_rest | nothing; validate warns | the bucket only | uri, warehouse |
lakekeeper | type=rest | iceberg_rest | nothing; validate warns | the bucket only | uri, warehouse as a name (warns when uri does not end in /catalog) |
polaris | type=rest | iceberg_rest | nothing; validate warns | the bucket only | uri, warehouse as a name |
unity | type=rest | iceberg_rest | nothing; validate warns | the bucket only | uri, warehouse as a name |
nessie | type=nessie | iceberg_rest | nothing; validate warns | the bucket only | uri, warehouse |
bigquery | type=bigquery | iceberg_rest | nothing; validate warns | the bucket only | project (warns with no gs:// warehouse to derive, and on a Kafka Connect build) |
hive | type=hive | left out, with a warning | nothing; validate errors | the bucket only | nothing |
jdbc | type=jdbc | left out, with a warning | nothing; validate errors | the bucket only | uri, and warehouse or a bucket to derive it from |
hadoop | type=hadoop | left out, with a warning | nothing; validate errors | the bucket only | warehouse |
dynamodb | catalog-impl=org.apache.iceberg.aws.dynamodb.DynamoDbCatalog | left out, with a warning | nothing; validate errors | the bucket only | warehouse, or a bucket to derive it from |
snowflake-managed | type=rest | built_in | EXTERNAL VOLUME | the bucket only | uri, warehouse |
How to read the columns:
Sink catalog selector. Kafka Connect takes the key with the
iceberg.catalog.prefix (iceberg.catalog.type,iceberg.catalog.catalog-impl), and Debezium Server withdebezium.sink.iceberg.. Thetypevalues are catalog types Apache Iceberg defines. Iceberg has nolakekeeper,polarisorunitytype, so those catalogs are reached over Iceberg REST, and nodynamodbtype, so DynamoDB is selected by class.type=bigqueryneeds an Iceberg runtime of 1.10 or later. Fornessiethe sink uses Iceberg's Nessie client, which the stock Apache Iceberg Kafka Connect runtime does not bundle, sofluid validatewarns on akafka-connectbuild. (forge-cli #709, since 0.20.0) Akafka-connectbuild that sendstype=bigquerydraws a warning too, because the published Apache Iceberg Kafka Connect sink predates it:1. iceberg sink (build 'stream_events'): the sink config sets iceberg.catalog.type=bigquery, which the published Apache Iceberg Kafka Connect sink (1.9.2 on Confluent Hub) cannot load: Iceberg's CatalogUtil gains the bigquery type in 1.10, so on that sink the connector fails at start. Run a sink built from Iceberg >= 1.10Both warnings follow the catalog that reaches the worker, selected by
typeor by acatalog-implclass (org.apache.iceberg.nessie.NessieCatalog,org.apache.iceberg.gcp.bigquery.BigQueryMetastoreCatalog), aftericeberg_catalog_overridesand a hand-writtensink_connector_configare merged in. A hand-written config that setsiceberg.catalog.type: restfor abigqueryornessieexpose draws neither, and is an error instead, because it selects another catalog than the expose's (How a value is read).dbt
catalogs.ymlon Snowflake and Snowflake module apply toplatform: snowflake. The Snowflake module column lists the Iceberg prerequisite the module creates; for every kind it also emits the database, schema andsnowflake_tablethe binding'slocationnames. Apart fromglue, Snowflake reaches theiceberg_restkinds through a catalog integration that authenticates with a secret. The module is credential-free, so it creates none, andfluid validatewarns (an error under--strict). Snowflake has no catalog integration forhive,jdbc,hadoopordynamodb, so an expose naming one failsfluid validate. The prerequisites each emitted object needs are in Iceberg tables via dbt.AWS module applies to
platform: aws: the bucket is the one the binding names. See On AWS.A streaming sink needs the listed
binding.locationkeys when a Kafka Connect build, or a Debezium Server build inembeddedmode, writes the expose. (forge-cli #710, since 0.20.0) Adynamodborjdbcwarehouse may instead derive from abucketor come from an override, and abigqueryproject from an override; see What a DynamoDB, JDBC or BigQuery sink needs. (forge-cli #711, since 0.20.0) Alakekeeper,polarisorunitywarehouse is the catalog's warehouse name, never an object-store URI; see What a Lakekeeper, Polaris or Unity sink needs. (forge-cli #712, since 0.20.0) A REST catalog that requires a token also needssink.catalogAuth, whichfluid validatedoes not ask for; see Authenticate a sink to a REST catalog. Debezium inbring-your-ownormanagedmode creates only the source connector, so these checks do not apply to it. The Kafka Connect runner and the embedded Debezium Server runner run the same checks before they create anything, so a contractfluid validaterefuses also fails its run, for these builds:- (forge-cli #709, since 0.20.0) a build that declares
sink.format: iceberg, whether the runner derives the sink config or pushes a hand-written one:sink_connector_configon Kafka Connect,server.sink.configon an embedded Debezium Server build whoseserver.sink.typeisiceberg(the default). On #707 alone the runners checked only a config they derived, so a hand-written config thatfluid validaterefuses was still deployed; - an embedded Debezium Server build that derives its sink:
server.sink.type: iceberg(the default) with no hand-writtenserver.sink.config, or withserver.sink.iceberg_sink_enabled: true.
(forge-cli #709, since 0.20.0) In a contract with several builds, each of these two runners reads its properties from the build it runs, the build the checks read. They used to read the first build's.
- (forge-cli #709, since 0.20.0) a build that declares
What a Lakekeeper, Polaris or Unity sink needs
(forge-cli #711, since 0.20.0) Lakekeeper, Polaris and Unity address a warehouse by name. location.warehouse is the name the catalog knows it by, such as analytics, or <project-id>/analytics on Lakekeeper, and the catalog owns the storage location behind it. When a Kafka Connect build, or a Debezium Server build in embedded mode, writes such an expose, fluid validate refuses an object-store URI in location.warehouse (s3://, s3a://, s3n://, gs://, gcs://, abfs:// or abfss://, in any case), and so does the run, before it creates anything. The Lakekeeper example with warehouse: s3://acme-lake/warehouse:
❌ Invalid FLUID contract (1 error(s)) (schema v0.7.5)
Validation completed in 0.000s
Validation Errors:
==================
1. iceberg sink (build 'stream_orders'): lakekeeper addresses a warehouse by NAME (e.g. "analytics" or "<project-id>/<name>"), not an object-store URI; binding.location.warehouse is 's3://acme-lake/warehouse'
The check reads the warehouse that reaches the sink. An iceberg.catalog.warehouse in iceberg_catalog_overrides or sink_connector_config on Kafka Connect, or warehouse in server.sink.config on embedded Debezium Server, is refused the same way, and the error names where it came from:
1. iceberg sink (build 'stream_orders'): lakekeeper addresses a warehouse by NAME (e.g. "analytics" or "<project-id>/<name>"), not an object-store URI; iceberg_catalog_overrides iceberg.catalog.warehouse is 's3://acme-lake/warehouse'
Leading or trailing spaces do not hide a URI. Put the warehouse's name there instead; on platform: aws, location.bucket still names the bucket the module creates. On platform: gcp a gs:// warehouse is refused too, although the GCP Iceberg checks accept one on an expose no streaming sink writes. polaris and unity draw the same error with their own kind in it, suggesting a plain name such as "analytics"; only Lakekeeper is offered the <project-id>/<name> form. With #707 to #710 alone fluid validate accepted an object-store warehouse for all three. A missing warehouse draws the error it drew before, which says what the value is:
1. iceberg sink (build 'stream_orders'): lakekeeper catalog requires binding.location.warehouse (the catalog name)
Lakekeeper's /catalog path. Lakekeeper serves the Iceberg REST API under <host>/catalog, so its uri is http://lakekeeper:8181/catalog, not the bare host. A lakekeeper uri that does not end in /catalog is a warning rather than an error, because a reverse proxy may rewrite the path. With uri: http://lakekeeper:8181:
✅ Valid FLUID contract (schema v0.7.5)
⚠️ 1 warning(s)
Validation completed in 0.000s
Validation Warnings:
====================
1. iceberg sink (build 'stream_orders'): binding.location.uri 'http://lakekeeper:8181' does not end in '/catalog'; lakekeeper serves the Iceberg REST API under <host>/catalog
A trailing / is ignored, so http://lakekeeper:8181/catalog/ passes; a path after /catalog, such as /catalog/v1, draws the warning. Under --strict, fluid validate exits 1 on it. The run preflight logs it and goes on. polaris and unity have no path check.
What the checks do not cover:
- An expose no streaming sink writes. The checks run per Kafka Connect or embedded Debezium Server build, so a
lakekeeperexpose with ans3://warehouse that no such build writes validates. catalog: rest. A generic REST catalog, such as Apache Iceberg's REST fixture, takes an object-store warehouse, sorestgets neither check. Name the catalog's own kind to get them.
Authenticate a sink to a REST catalog
(forge-cli #712, since 0.20.0) A catalog that requires a token, such as a Lakekeeper behind Keycloak, needs the sink to authenticate. builds[].properties.sink.catalogAuth names the environment variable that holds the secret. forge-cli writes env:<NAME> into the sink config it derives, and Apache Iceberg's REST client reads the value from the environment of the process that runs the sink. The secret's value is in no config forge-cli writes or pushes.
catalogAuth applies to the sink config forge-cli derives for a Kafka Connect build with sink.format: iceberg or an embedded Debezium Server build, when the expose's catalog is reached over Iceberg REST: rest, lakekeeper, polaris, unity or snowflake-managed. It needs schema 0.7.6 or later (0.7.6 is stable since 0.26.0; see schema versions).
(forge-cli #818, since 0.27.0) The contract names the variable and the hosts that receive its value, so the operator has to allow both. Every host the credential reaches, the catalog and an OAuth2 token endpoint, must be https:// (a loopback host included), and the operator pairs the variable with each host in FLUID_ACQUISITION_SECRET_REF_ALLOWLIST; see Operator allowlists. The examples below use https:// for that reason.
Example: Lakekeeper behind Keycloak
The Lakekeeper example, for a Lakekeeper that accepts only tokens Keycloak issues for it. fluidVersion becomes "0.7.6", the build's sink gains catalogAuth, and the expose's location.uri becomes https://lakekeeper:8181/catalog, because the sink sends a token to it; the rest of the exposes are unchanged:
fluidVersion: "0.7.6"
# kind, id, name, domain, metadata and exposes as in the Lakekeeper example
builds:
- id: stream_orders
pattern: acquisition
engine: kafka-connect
outputs: [orders]
properties:
source:
kind: postgres
mode: incremental_append
streams: [public.orders]
sink:
format: iceberg
catalogAuth:
type: oauth2
credentialEnv: LAKEKEEPER_CREDENTIAL # a variable NAME; its value is <client-id>:<client-secret>
oauth2ServerUri: https://keycloak:8443/realms/iceberg/protocol/openid-connect/token
scope: lakekeeper
kafka-connect:
streamingSink:
autoCreate: true
commitIntervalMs: 5000
fluid validate contract.fluid.yaml
✅ Valid FLUID contract (schema v0.7.6)
⚠️ 1 warning(s)
Validation completed in 0.013s
Validation Warnings:
====================
1. iceberg sink (build 'stream_orders'): sink.catalogAuth.credentialEnv names LAKEKEEPER_CREDENTIAL. Iceberg resolves it from the Kafka Connect worker's environment and sends it to hosts this contract names, and the run refuses until the operator allows each: the Iceberg catalog host 'lakekeeper' is a name not in FLUID_ACQUISITION_DEPLOYMENT_HOST_ALLOWLIST; LAKEKEEPER_CREDENTIAL is not paired with the Iceberg catalog host 'lakekeeper' in FLUID_ACQUISITION_SECRET_REF_ALLOWLIST; the OAuth2 token endpoint host 'keycloak' is a name not in FLUID_ACQUISITION_DEPLOYMENT_HOST_ALLOWLIST; LAKEKEEPER_CREDENTIAL is not paired with the OAuth2 token endpoint host 'keycloak' in FLUID_ACQUISITION_SECRET_REF_ALLOWLIST. A contract names both the variable and the hosts, so without the operator's lists any variable there could go to a host the contract chose; a hostname needs an entry because the sink resolves it itself, later, where no lookup made here applies. If this is intended, add the entries in the OPERATOR environment (a shell or CI variable, not a project .env, which is ignored for these settings); this keeps the ones set here: export FLUID_ACQUISITION_SECRET_REF_ALLOWLIST="LAKEKEEPER_CREDENTIAL@lakekeeper,LAKEKEEPER_CREDENTIAL@keycloak" FLUID_ACQUISITION_DEPLOYMENT_HOST_ALLOWLIST="lakekeeper,keycloak". Leave the port off: a host written with a port never matches. A loopback host needs no entry, and a private IP address needs only the pairing
fluid validate reads the variable's name, not its value, so it passes whether or not LAKEKEEPER_CREDENTIAL is set where it runs. It warns, and does not fail, when the operator's lists do not yet allow the hosts, because validate may run where those lists are not set. The warning carries the export line the run needs. The Kafka Connect or Debezium Server run refuses the same case with the same text as an error, before it calls anything. With both entries exported, as in Operator allowlists, the contract validates with no warning:
✅ Valid FLUID contract (schema v0.7.6)
Validation completed in 0.013s
Set the variable on the Kafka Connect workers (Where to set the variable). The Keycloak client and the Lakekeeper settings that go with this contract are in Lakekeeper and Keycloak.
The same contract declaring fluidVersion: "0.7.5" fails, because the 0.7.5 schema has no catalogAuth:
1. builds[0].properties.sink: Additional properties are not allowed ('catalogAuth' was unexpected)
catalogAuth fields
| Field | type | Required | Becomes the catalog property |
|---|---|---|---|
type | both | yes | rest.auth.type=oauth2, for both types |
credentialEnv | oauth2 | yes | credential=env:<credentialEnv> |
oauth2ServerUri | oauth2 | yes | oauth2-server-uri |
scope | oauth2 | yes | scope |
audience | oauth2 | no | audience |
resource | oauth2 | no | resource |
tokenEnv | bearer | yes | token=env:<tokenEnv> |
type: oauth2is the OAuth2 client-credentials grant. The variablecredentialEnvnames holds<client-id>:<client-secret>; Iceberg splits it on the first:.oauth2ServerUriis the identity provider's token endpoint, andscopeis the scope the sink requests. Both are required: withoutoauth2ServerUri, Iceberg would send the credential to the catalog's ownv1/oauth/tokens, and withoutscopeit would requestcatalog, which most identity providers do not know.audienceandresourceare sent as parameters of the token request when set.type: bearerpresents a static token. The variabletokenEnvnames holds the token. It takes no other field.rest.auth.type=oauth2for both types. Iceberg sends a statictokenthrough its OAuth2 auth manager too. forge-cli always emits the property rather than leave Iceberg to infer the auth type from the other properties.A variable name is letters, digits and
_, not starting with a digit, with nothing after it, not even a trailing newline. A name that holds a run of 20 or more letters and digits, with a digit among them, bounded by underscores or the ends of the name, is refused as the shape of a personal access token, such as a Databricks or Unitydapitoken. The rule is a heuristic: a shorter token, or one with no digit, still passes as a name. A real variable name with such a run passes once you split the run with_.oauth2ServerUristarts with a lowercasehttp://orhttps://and has nouser:password@part. (since 0.27.0, forge-cli #818)fluid validateand the run then refusehttp://; see Operator allowlists. Iceberg treats any other spelling as a path on the catalog host and sends the credentials there. The query string is not checked, so keep secrets out of it too.oauth2ServerUri,scope,audienceandresourceare written as they are. None may hold a${...}expression, which Debezium Server would expand inapplication.propertieswhile Kafka Connect would pass it to Iceberg as text, a control character such as a line break or a tab, or a value starting withenv:, which Iceberg would resolve from the environment. Only the secret comes from the environment.Override text. (since 0.28.0, forge-cli #830) With
catalogAuth, a catalog URL that holds${, starts withenv:or holds a control character is refused wherever it is set, inbinding.location.urior in an override map, atfluid validateand in the run's preflight. The check reads the text before the sink expands it: Debezium Server expands a${...}expression when it starts, Kafka Connect resolves a${provider:path:key}reference with the worker's config providers, and Iceberg replaces a value that starts withenv:by that variable. The same text is refused in every other override value Iceberg reads: Kafka Connecticeberg_catalog_overrides, theiceberg.*keys ofsink_connector_configexcepticeberg.kafka.*, and every key of an embedded Debeziumserver.sink.config. A storage credential comes from the worker's or the server's own credential chain, not from the contract. Kafka-side keys such asconsumer.override.*andiceberg.kafka.*keep their config providers. A build withoutcatalogAuthis unchanged.
A message about a catalogAuth field that fails a check never shows the field's value, because it may be a secret pasted in place of a name. A variable name appears in a message only after it has passed the name checks.
What the derived config holds
The catalog keys of the sink config the Kafka Connect runner derives from the example:
{
"iceberg.catalog.type": "rest",
"iceberg.catalog.warehouse": "analytics",
"iceberg.catalog.client.region": "eu-west-1",
"iceberg.catalog.uri": "https://lakekeeper:8181/catalog",
"iceberg.catalog.rest.auth.type": "oauth2",
"iceberg.catalog.credential": "env:LAKEKEEPER_CREDENTIAL",
"iceberg.catalog.oauth2-server-uri": "https://keycloak:8443/realms/iceberg/protocol/openid-connect/token",
"iceberg.catalog.scope": "lakekeeper"
}
The runner pushes the config to the Kafka Connect REST API as it is. When forge-cli's live test against Lakekeeper and Keycloak last ran, on http (its streaming tests are skipped in 0.27.0, which refuses http for catalogAuth), the connector config Kafka Connect served and stored in its internal config topic held the env: reference, and neither it nor the worker's log held the secret.
The same build as an embedded Debezium Server build, cdc_orders (engine: debezium and properties.debezium.deployment.mode: embedded in place of the kafka-connect block), writes these sink lines to application.properties:
debezium.sink.type=iceberg
debezium.sink.iceberg.warehouse=analytics
debezium.sink.iceberg.table-namespace=streaming
debezium.sink.iceberg.type=rest
debezium.sink.iceberg.uri=https://lakekeeper:8181/catalog
debezium.sink.iceberg.client.region=eu-west-1
debezium.sink.iceberg.rest.auth.type=oauth2
debezium.sink.iceberg.credential=env:LAKEKEEPER_CREDENTIAL
debezium.sink.iceberg.oauth2-server-uri=https://keycloak:8443/realms/iceberg/protocol/openid-connect/token
debezium.sink.iceberg.scope=lakekeeper
The source password, and any other property whose value is a credential, is not written to the file. Its line holds an expression, and forge-cli passes the value to Debezium Server in that environment variable: the secretRef from the source connection becomes debezium.source.database.password=${FLUID_DBZ_SOURCE_DATABASE_PASSWORD}. Quarkus resolves the expression when the server starts. A server_binary wrapper that replaces the environment must pass the FLUID_DBZ_* variables through. The file is created readable by your user only (mode 0600). A sink value that starts with env: is Iceberg's own reference and is written as it is, as above.
type: bearer with tokenEnv: UC_TOKEN gives iceberg.catalog.rest.auth.type=oauth2 and iceberg.catalog.token=env:UC_TOKEN on Kafka Connect, and debezium.sink.iceberg.rest.auth.type=oauth2 and debezium.sink.iceberg.token=env:UC_TOKEN on Debezium Server. audience: lakekeeper adds iceberg.catalog.audience=lakekeeper, and resource adds iceberg.catalog.resource the same way.
Operator allowlists
(forge-cli #818, since 0.27.0) A contract names the environment variable (credentialEnv or tokenEnv) and the hosts that receive its value: the catalog (binding.location.uri) and, for oauth2, the token endpoint (oauth2ServerUri). Iceberg resolves env:<NAME> on the Kafka Connect worker, or, on embedded Debezium Server, from the fluid process's whole environment, so without a limit a contract could send any variable there to a host it picked. The operator sets that limit in two lists:
| Variable | Entry | Allows |
|---|---|---|
FLUID_ACQUISITION_SECRET_REF_ALLOWLIST | NAME@host | the variable NAME to be sent to host |
FLUID_ACQUISITION_DEPLOYMENT_HOST_ALLOWLIST | host | a hostname the worker will resolve itself |
(since 0.31.0, forge-cli #893) The table shows the NAME@host entry that a catalogAuth variable needs. For an acquisition source's secretRef, the variable takes more forms and covers every scheme: see the allowlist.
For each host the credential reaches, the run needs:
https://. A loopback host included.http://failsfluid validate, and nothing lists it away.- The pairing,
NAME@hostinFLUID_ACQUISITION_SECRET_REF_ALLOWLIST, unless the host is loopback. - A host entry for a hostname, in
FLUID_ACQUISITION_DEPLOYMENT_HOST_ALLOWLIST, because the worker (or Debezium Server) resolves the name after forge-cli's check, so no lookup made by forge-cli shows where it will connect.localhostneeds none.
An IP address keeps the deployment host list's rules instead of needing an entry as a name does: a link-local or cloud metadata address is never allowed, a private one needs no host entry (only the pairing), and a public one only when listed. A loopback host needs neither entry. (since 0.28.0, forge-cli #828)
An OAuth2 credential reaches two hosts, so it needs a pairing for the token endpoint and one for the catalog (one entry covers both when they are the same host, as with the Polaris recipe below). The example contract needs:
export FLUID_ACQUISITION_SECRET_REF_ALLOWLIST="LAKEKEEPER_CREDENTIAL@lakekeeper,LAKEKEEPER_CREDENTIAL@keycloak"
export FLUID_ACQUISITION_DEPLOYMENT_HOST_ALLOWLIST="lakekeeper,keycloak"
Leave the port off: a host written with a port never matches.
Two cautions on how entries match:
- A bare
NAMEentry, with no@host, allows that variable to go to every host. - A listed hostname also covers its subdomains.
So prefer NAME@host, and list the exact host.
The run refuses before it makes any Connect REST call, writes application.properties or reads the variable. fluid validate may run where the operator's lists are not set, so for a host that only lacks an entry it warns, with the export line the run needs (the warning above), and does not fail. It refuses outright, with no export line, an http:// URL and a link-local, unspecified or cloud metadata address, which no entry allows. (since 0.28.0, forge-cli #828) With oauth2ServerUri: http://keycloak:8080/...:
1. iceberg sink (build 'stream_orders'): sink.catalogAuth.oauth2ServerUri must be an https:// URL: the OAuth2 token endpoint receives the credential in LAKEKEEPER_CREDENTIAL (the client id and secret) on every request, and http would carry it in clear text, so a loopback host needs https too
With binding.location.uri: https://169.254.169.254, a cloud metadata address, the message reads as follows. (since 0.28.0, forge-cli #828)
1. iceberg sink (build 'stream_orders'): the Iceberg catalog host '169.254.169.254' (binding.location.uri) is link-local, unspecified or a known cloud metadata endpoint; no Iceberg catalog is ever there, and this is refused even with an allowlist entry
Both lists are operator-only: a value set in a project .env, .env.<env> or FLUID_SECRETS_FILE is ignored (credentials/protected_env.py lists both). Set them in the shell or the CI job that runs fluid. Network safety lists the further metadata addresses that the orchestrator guard, the OpenLineage emitter and the managed Flink host check refuse; this sink check refuses those too. (since 0.28.0, forge-cli #828) It refuses the same addresses as the orchestrator guard, the OpenLineage emitter and the managed Flink host check, even when listed. Before that change it refused link-local and unspecified addresses only.
Related text checks, which apply whether or not the sink has a catalogAuth: binding.location text that reaches the derived sink config may not start with env:, hold ${, or hold a control character, and binding.location.region must be one host label (letters, digits and inner hyphens, at most 63). Only sink.catalogAuth may name a variable. A value is never quoted in the message. With warehouse: "env:AWS_SECRET_ACCESS_KEY":
1. iceberg sink (build 'stream_orders'): binding.location.warehouse starts with env:, or holds ${ or a control character (the value is not shown). The derived sink config hands it to the Kafka Connect worker, where Iceberg's REST catalog replaces a value that starts with env: by that variable from the worker's environment and Kafka Connect resolves a ${provider:key} expression with the worker's config providers, so it could send any variable there to a host the contract chose. Write the value itself; only sink.catalogAuth may name a variable, and the operator pairs it with the hosts it reaches
With region: "eu-west-1.evil.example":
1. iceberg sink (build 'stream_orders'): binding.location.region is not a region name such as eu-central-1 (the value is not shown: at run it may have come from a {{ env.* }} template). The derived sink config passes it to Iceberg's AWS client as client.region, which builds the S3 and Glue endpoint hosts from it, so it must be one host label: letters, digits and inner hyphens, at most 63 characters
Where to set the variable
Iceberg reads the variable in the process that runs the sink, when the sink builds its catalog, from the environment that process started with. A changed value takes effect when that process restarts.
Kafka Connect. The variable belongs in the environment of the Kafka Connect workers that run the sink's tasks. forge-cli cannot see a worker's environment, so neither
fluid validatenor the run checks it. With Docker Compose, for example:services: connect: environment: LAKEKEEPER_CREDENTIAL: ${LAKEKEEPER_CREDENTIAL} # <client-id>:<client-secret>When the variable is unset on the worker, the connector is still created, and on a catalog that requires a token its sink task fails; see Caveats.
Embedded Debezium Server. forge-cli starts Debezium Server with its own environment, so the variable belongs in the environment of the
fluidprocess that runs the build:export LAKEKEEPER_CREDENTIAL='<client-id>:<client-secret>' fluid apply contract.fluid.yaml --mode amend-and-build --build-id cdc_orders --yesThe run checks that the variable is set and not empty before it writes
application.properties. Only its presence is tested; the value is never logged. Without it the run stops:iceberg sink preflight failed: iceberg sink (build 'cdc_orders'): sink.catalogAuth.credentialEnv names LAKEKEEPER_CREDENTIAL, which is unset or empty in the runner's environment. The embedded Debezium Server inherits that environment, and Iceberg drops a catalog property whose env: variable is unset, so the sink would reach the catalog without credentials. Set LAKEKEEPER_CREDENTIAL before the runfluid validatedoes not make this check, since the variable may be set only where the build runs.
What fluid validate refuses
fluid validate refuses each case below. The Kafka Connect and embedded Debezium Server runs refuse the same cases before they create anything, the message prefixed with iceberg sink preflight failed (see `fluid validate`):, except a build that writes no derived Iceberg sink: its run does not reach the sink checks, so only fluid validate refuses catalogAuth there. The examples change one thing in the example contract.
A malformed catalogAuth. A problem is usually reported twice: once by the schema, naming the path, and once by the sink check, saying what to do. With credentialEnv: LK-CREDENTIAL:
❌ Invalid FLUID contract (2 error(s)) (schema v0.7.6)
Validation completed in 0.001s
Validation Errors:
==================
1. builds[0].properties.sink.catalogAuth.credentialEnv: does not match '^[A-Za-z_][A-Za-z0-9_]*(?![\\s\\S])' (value not shown)
2. iceberg sink (build 'stream_orders'): sink.catalogAuth.credentialEnv must NAME an environment variable (letters, digits and _, not starting with a digit, nothing after the name, not even a newline); the value is not shown, because it may be a pasted secret. Put the secret in that variable, not in the contract
A pasted <client-id>:<client-secret> and a name with a trailing newline draw the same two lines. For each other problem, the sink check's line, which follows the schema's:
A token-shaped name:
2. iceberg sink (build 'stream_orders'): sink.catalogAuth.credentialEnv looks like a token, not an environment variable name: it holds a run of 20 or more letters and digits, with a digit, between underscores, the shape of a personal access token. The value is not shown. Put the token in an environment variable and name that variable here (a real name with such a run: split it with _)An
oauth2ServerUrithat does not start with a lowercasehttp://orhttps://(HTTPS://..., or no scheme), or that has auser:password@part:2. iceberg sink (build 'stream_orders'): sink.catalogAuth.oauth2ServerUri must be an absolute http(s) URL of the identity provider's token endpoint, starting with a lowercase http:// or https:// (Iceberg treats any other spelling as a path on the catalog and sends the credentials there), with no user:password@ part (for Keycloak, <keycloak>/realms/<realm>/protocol/openid-connect/token); the value is not shown, because a user:password@ part may hold the client secret. The client id and secret go in the variable credentialEnv namesA
${...}expression, a control character, or anenv:value inoauth2ServerUri,scope,audienceorresource, here inscope:2. iceberg sink (build 'stream_orders'): sink.catalogAuth.scope holds a ${...} expression. Debezium Server expands one in application.properties and Kafka Connect sends it to Iceberg as literal text, so the sink would differ by engine. Write the value itself; only the secret comes from the environment, through credentialEnv 2. iceberg sink (build 'stream_orders'): sink.catalogAuth.scope contains a control character, such as a line break or a tab; the value is not shown. Write it on one line 2. iceberg sink (build 'stream_orders'): sink.catalogAuth.scope starts with env:, which Iceberg resolves from the environment (and drops when the variable is unset). Write the value itself; only the secret comes from the environment, through credentialEnvA missing field, a field the type does not take, an empty optional field, and an unknown type:
2. iceberg sink (build 'stream_orders'): sink.catalogAuth.scope is required for type oauth2 2. iceberg sink (build 'stream_orders'): sink.catalogAuth of type oauth2 does not take ['tokenEnv']; it takes ['audience', 'credentialEnv', 'oauth2ServerUri', 'resource', 'scope'] 2. iceberg sink (build 'stream_orders'): sink.catalogAuth.audience must be a non-empty string when set 2. iceberg sink (build 'stream_orders'): sink.catalogAuth.type must be one of: oauth2, bearer
Every Iceberg sink message, in fluid validate's output, the run preflight's log and a run error, passes through forge-cli's secret redactor: a user:password@ part of a URL (a catalog uri, an override warehouse), a key=value secret, and the value of the variable credentialEnv or tokenEnv names once the embedded Debezium run has read it, show as ***REDACTED***. The schema's lines have these forms, and none quotes the value: 'scope' is a required property, tokenEnv is not allowed here, does not match '<pattern>' (value not shown), must not match '<pattern>' (value not shown), fails minLength: 1 (value not shown) and fails enum: ['oauth2', 'bearer'] (value not shown). At the edges the two checks differ: the schema alone refuses spaces around oauth2ServerUri, which the sink check, the one the runs use, trims; the sink check alone refuses a scope of only spaces.
A build that writes no derived Iceberg sink. A Kafka Connect build with another sink.format, or a Debezium build in bring-your-own or managed mode:
1. build 'stream_orders': sink.catalogAuth has no effect: it configures the Iceberg sink config forge-cli derives for a kafka-connect build with sink.format: iceberg or an embedded debezium build, and this build writes no such sink. Remove it
An iceberg sink on another engine, dlt here:
1. iceberg sink (build 'stream_orders'): sink.catalogAuth has no effect on engine 'dlt': only the kafka-connect and debezium runners derive an Iceberg sink config. Remove it
A sink config forge-cli does not derive. A hand-written sink_connector_config, or a hand-written server.sink.config on Debezium Server, is pushed as written. The error lists the properties to write into it yourself:
1. iceberg sink (build 'stream_orders'): sink.catalogAuth applies to a sink config forge-cli derives, and this build's sink config is hand-written (properties.kafka-connect.sink_connector_config), so nothing reads it. Set the catalog's auth properties in the sink config yourself (set iceberg.catalog.rest.auth.type to oauth2, iceberg.catalog.credential to env:LAKEKEEPER_CREDENTIAL, iceberg.catalog.oauth2-server-uri to <oauth2ServerUri>, iceberg.catalog.scope to <scope>), or remove sink.catalogAuth
With iceberg_sink_enabled: false and no hand-written config, the reason reads this build does not derive its sink config (derivation is turned off). On Debezium Server the listed properties are bare keys (rest.auth.type to oauth2, credential to env:LAKEKEEPER_CREDENTIAL, ...), as server.sink.config takes them.
A catalog not reached over REST. For glue; nessie, bigquery, hive, jdbc, hadoop and dynamodb draw the same error with their own kind in it:
1. iceberg sink (build 'stream_orders'): sink.catalogAuth configures an Iceberg REST catalog's auth, and the glue catalog is not reached over REST (the sink builds Iceberg's glue catalog), so nothing would read it. Remove sink.catalogAuth, or use a REST catalog kind
An override that also sets the catalog's auth. iceberg_catalog_overrides or a sink_connector_config merged over a derived config (Kafka Connect), or server.sink.config with server.sink.iceberg_sink_enabled: true (Debezium Server), may not set rest.auth.type, credential, token, oauth2-server-uri, scope, audience, resource, rest.sigv4-enabled or a header.Authorization in any case:
1. iceberg sink (build 'stream_orders'): sink.catalogAuth and iceberg_catalog_overrides both set the catalog's auth (iceberg.catalog.credential), so which one reaches the catalog is ambiguous (Iceberg uses a token over a credential when it gets both). Remove those keys from iceberg_catalog_overrides, or remove sink.catalogAuth
A literal secret in an override. Where no catalogAuth applies, an override or a hand-written sink config that sets credential or token to a literal value is a warning (next to a catalogAuth that applies, the override is refused, above), because the secret sits in the contract, and forge-cli would push it to the Kafka Connect REST API or pass it to Debezium Server. Under --strict, fluid validate exits 1 on it. A value that starts with env: or carries a ${...} expression, such as a Kafka Connect config provider reference, draws no warning:
✅ Valid FLUID contract (schema v0.7.6)
⚠️ 1 warning(s)
Validation completed in 0.001s
Validation Warnings:
====================
1. iceberg sink (build 'stream_orders'): iceberg_catalog_overrides sets iceberg.catalog.credential to a literal value (not shown), so the secret is inlined into the sink config forge-cli pushes to the Kafka Connect REST API. Use sink.catalogAuth, or set iceberg.catalog.credential to env:<VARIABLE>, which Iceberg resolves from the environment of the process that runs the sink
On Debezium Server the warning names debezium.server.sink.config and says the value is passed to Debezium Server. The runs log the warning and go on.
What catalogAuth does not cover:
- Other readers of the table. It authenticates the streaming sink only. On
platform: snowflake, the Snowflake module still creates no catalog integration for a REST catalog, andfluid validatestill warns about it (Iceberg prerequisite checks). - SigV4. There is no SigV4 type, and an override that turns on
rest.sigv4-enabledis refused next tocatalogAuth. - The value. forge-cli never reads the secret, so a wrong client id, secret or token shows up only when the sink calls the identity provider or the catalog.
Recipes
Lakekeeper and Keycloak
This follows the setup forge-cli's live test (tests/integration/test_lakekeeper_oauth_live.py) was written against, with Keycloak 26.7.5 and Lakekeeper v0.13.6. That test serves both over http, which 0.27.0 refuses for catalogAuth, so its three streaming tests are skipped until the stack runs TLS; only its Lakekeeper-direct test runs. The https URLs below are not exercised by it. It follows the Keycloak recipe in Lakekeeper's authentication guide.
In the Keycloak realm Lakekeeper trusts (iceberg in the example):
- Create a client scope
lakekeeperwith an Audience mapper that addslakekeeperto the access token'saudclaim. - Create a client for the sink,
fluid-sinksay, with client authentication on, Service accounts roles on (the client-credentials grant), and Standard Token Exchange on (Caveats says why). Add thelakekeeperscope to the client as Optional: a token then carries thelakekeeperaudience only when it is requested withscope=lakekeeper, which is whatcatalogAuth.scoperequests. - Set the variable on the workers to
<client-id>:<client-secret>, the client's id and the secret from its Credentials tab.
A realm imported from a JSON file that lists clientScopes gets none of Keycloak's built-in scopes. The basic scope carries the sub claim Lakekeeper takes the principal's id from, so define it in the file too, as the live test's realm does.
In Lakekeeper:
LAKEKEEPER__OPENID_PROVIDER_URI=https://keycloak:8443/realms/iceberg
LAKEKEEPER__OPENID_AUDIENCE=lakekeeper
Lakekeeper reads the realm's discovery document from LAKEKEEPER__OPENID_PROVIDER_URI and checks a token's issuer against it. Keycloak derives the issuer from the host the token was requested from, so oauth2ServerUri should reach Keycloak by the same host as LAKEKEEPER__OPENID_PROVIDER_URI (keycloak:8443 in the example). Lakekeeper accepts a token issued under another host name only when LAKEKEEPER__OPENID_ADDITIONAL_ISSUERS lists that issuer.
In the live test, Lakekeeper v0.13.6 refused a request with no token, a malformed token, and a token issued for another audience. It accepted a token with no aud claim at all, although LAKEKEEPER__OPENID_AUDIENCE was set.
Polaris
With Polaris's internal authentication, Polaris issues the token itself. The expose's location and the build's sink, the rest as in the example:
location:
catalog: polaris
uri: https://polaris:8181/api/catalog
warehouse: analytics # the Polaris catalog's name
# database, table, bucket and region as in the example
sink:
format: iceberg
catalogAuth:
type: oauth2
credentialEnv: POLARIS_CREDENTIAL # its value: a Polaris principal's <client-id>:<client-secret>
oauth2ServerUri: https://polaris:8181/api/catalog/v1/oauth/tokens
scope: PRINCIPAL_ROLE:ALL
The catalog and the token endpoint share the host polaris, so the operator needs POLARIS_CREDENTIAL@polaris and polaris in the two lists. oauth2ServerUri is Polaris's own token endpoint here, which Iceberg would also use without it; catalogAuth requires it anyway, so the contract names where the credential goes. PRINCIPAL_ROLE:ALL requests all of the principal's roles. To activate fewer, list them, space-separated, as PRINCIPAL_ROLE:<role name>.
With an external identity provider, Polaris validates tokens the provider issues, and its internal token endpoint answers HTTP 501 when its authentication type is external. Set oauth2ServerUri to the provider's token endpoint and scope to the scope the provider expects, and keep credentialEnv for the provider's client. Which Polaris principal and roles the token maps to is Polaris configuration; see Identity Providers in the Polaris documentation.
Unity Catalog OSS
Unity Catalog OSS offers no client-credentials grant for a sink to use, so the sink presents a bearer token:
location:
catalog: unity
uri: https://unity:8080/api/2.1/unity-catalog/iceberg
warehouse: unity # the Unity catalog's name
# database, table, bucket and region as in the example
sink:
format: iceberg
catalogAuth:
type: bearer
tokenEnv: UC_TOKEN
The operator pairs the variable with the catalog host: UC_TOKEN@unity in FLUID_ACQUISITION_SECRET_REF_ALLOWLIST and unity in FLUID_ACQUISITION_DEPLOYMENT_HOST_ALLOWLIST. The token does not come from forge-cli: you obtain it, and when you replace it, set the new value in the variable and restart the process that runs the sink. Name the variable in tokenEnv; a token pasted there is refused when it has the token shape above.
Caveats
Keycloak needs Standard Token Exchange. The published Apache Iceberg Kafka Connect sink (1.9.2 on Confluent Hub) refreshes its token through OAuth 2.0 Token Exchange (RFC 8693), and Iceberg 1.9.2 has no property that turns it off (
token-exchange-enabledarrives in Iceberg 1.10.0). Keycloak (26.7.5 in the live test, which showed this when it last ran on http and is skipped in 0.27.0) refuses that exchange unless the client has Standard Token Exchange enabled, so enable it on the sink's client. Without it, the sink cannot refresh its token.The catalog can move the token endpoint. Iceberg applies the
overridesof the catalog'sGET /v1/configresponse over the sink's own properties,oauth2-server-uriincluded, before it sets up the session that authenticates the sink's catalog calls. A catalog can therefore have the sink send its credential to another endpoint. UsecatalogAuthonly with a catalog you trust with the credential.An unset variable drops the property. Iceberg leaves out a property whose
env:variable is unset. Withcredentialgone, the sink sends its catalog requests with no token. On Kafka Connect nothing stops this before the sink starts: forge-cli cannot see the worker's environment, the connector is created and staysRUNNING, and its task fails. In the live test against Lakekeeper, when it last ran on http (its streaming tests are skipped in 0.27.0), the task failed with this trace, and no table was written:org.apache.iceberg.exceptions.NotAuthorizedException: Not authorized: Missing Authorization HeaderThe embedded Debezium Server run refuses to start instead (Where to set the variable).
Set the variable where the sink runs, and limit what connectors can read. Iceberg resolves
env:in any catalog property from the whole environment of the sink's process. On a Kafka Connect worker, any connector config can name any variable the worker has, and send its value as acredentialto theoauth2-server-urithe same config names. Give the workers only the variables their sinks need, and limit who can create or change connectors.
What a DynamoDB, JDBC or BigQuery sink needs
(forge-cli #710, since 0.20.0) Apache Iceberg's DynamoDbCatalog and JdbcCatalog refuse to start without a warehouse, and its BigQueryMetastoreCatalog refuses to start without gcp.bigquery.project-id. A sink config forge-cli derives now carries them, and fluid validate and the run preflight refuse a build whose sink would start without them. With #707 and #709 alone forge-cli derived neither and checked for neither, so the connector failed when it started.
DynamoDB and JDBC. The warehouse is location.warehouse. Without one, forge-cli derives it from an explicit location.bucket on platform: aws (s3://) or platform: gcp (gs://): <scheme>://<bucket>/<path>, where path defaults to <database>/<table>/. A bucket on any other platform derives nothing, and the account-derived bucket a Glue table falls back to is never used, because no module creates it for a table in another catalog. A DynamoDB expose that a Kafka Connect build writes:
exposes:
- exposeId: orders
kind: table
binding:
platform: aws
format: iceberg
location:
catalog: dynamodb
bucket: acme-lake # the warehouse derives from it
database: streaming
table: orders
region: eu-west-1
The table and catalog keys of the sink config the Kafka Connect runner derives from it:
{
"iceberg.tables": "streaming.orders",
"iceberg.catalog.catalog-impl": "org.apache.iceberg.aws.dynamodb.DynamoDbCatalog",
"iceberg.catalog.warehouse": "s3://acme-lake/streaming/orders/",
"iceberg.catalog.io-impl": "org.apache.iceberg.aws.s3.S3FileIO",
"iceberg.catalog.client.region": "eu-west-1"
}
The sink's own warehouse property counts too: iceberg.catalog.warehouse in iceberg_catalog_overrides or sink_connector_config on Kafka Connect, warehouse in server.sink.config on embedded Debezium Server. With no location.warehouse, no bucket to derive one from and no override, fluid validate fails, and so does the run, before it creates anything:
1. iceberg sink (build 'stream_orders'): dynamodb catalog requires binding.location.warehouse (an object-store location), or a binding.location.bucket on platform aws or gcp to derive it from, or the sink's warehouse property in an override; the dynamodb catalog refuses to start without a warehouse
jdbc needs location.uri as well. A location.warehouse of only whitespace counts as unset.
BigQuery. A catalog: bigquery expose maps to the catalog's own properties:
binding.location | Derived sink config |
|---|---|
project | gcp.bigquery.project-id. Required: without it, or with only whitespace, fluid validate and the run refuse the build, unless an override sets that property |
region | gcp.bigquery.location. The config sets no client.region for this catalog |
a gs:// warehouse, else bucket and path | warehouse: the gs:// storage dbt-bigquery and the GCP module use, gs://<bucket> plus path when it is set |
The Kafka Connect runner passes them with the iceberg.catalog. prefix, and the embedded Debezium Server runner with debezium.sink.iceberg.. Iceberg on BigQuery via dbt shows the derived config for its example binding. Without project:
1. iceberg sink (build 'stream_events'): bigquery catalog requires binding.location.project (the sink's gcp.bigquery.project-id), or that property in an override; the bigquery catalog refuses to start without it
A warehouse with another scheme, or no gs:// warehouse and no bucket, derives no warehouse: the config sets none, and fluid validate warns without refusing. On Kafka Connect, table auto-create then fails: with iceberg.tables.auto-create-enabled the sink calls createNamespace for each table it creates, which BigQueryMetastoreCatalog refuses without a warehouse, even in a dataset that exists. Tables that exist need no warehouse. Embedded Debezium Server does not boot without debezium.sink.iceberg.warehouse, which has no default. On platform: gcp the Iceberg prerequisite checks already require a bucket or a gs:// warehouse.
A bucket written as a {{ env.* }} template. fluid validate reads such a bucket as written. When a variable it names, such as LAKE_ENV in acme-{{ env.LAKE_ENV }}-lake, is unset or empty where validate runs, the warehouse cannot be derived there, and validate warns and names the variable instead of asking for a bucket:
1. iceberg sink (build 'stream_orders'): the dynamodb catalog's warehouse derives from binding.location.bucket 'acme-{{ env.LAKE_ENV }}-lake', and LAKE_ENV is unset or empty here, so it cannot be derived at validate time. Set it where the sink runs: the runner refuses the build when the bucket does not resolve there, because the dynamodb catalog refuses to start without a warehouse
The run preflight checks the variable again where the sink config is derived. When it is unset or empty there, the preflight refuses the build instead of pushing a warehouse in a bucket the contract does not name, such as acme--lake. That includes a run from a plan, whose embedded contract it reads as written:
iceberg sink preflight failed: iceberg sink (build 'stream_orders'): the dynamodb catalog's warehouse derives from binding.location.bucket 'acme-{{ env.LAKE_ENV }}-lake', and LAKE_ENV is unset or empty in the runner's environment, so the bucket does not resolve: the sink would get a warehouse in a bucket the contract does not name, or none, and the dynamodb catalog refuses to start without a warehouse. Set it here, or set binding.location.warehouse
The preflight refuses a DynamoDB or JDBC sink, a BigQuery sink on embedded Debezium Server, and a BigQuery sink on Kafka Connect with auto-create on (streamingSink.autoCreate: true, or iceberg.tables.auto-create-enabled in an override). A Kafka Connect BigQuery sink reads the warehouse only to create tables, so without auto-create the run warns and pushes no warehouse. A warehouse an override sets is kept, and the bucket's variables are not checked then. They are not checked for a hand-written sink config forge-cli does not derive either.
Which exposes a streaming sink writes
(forge-cli #710, since 0.20.0) A Kafka Connect or embedded Debezium Server build whose Iceberg sink config forge-cli derives writes the Iceberg exposes its outputs name. An Iceberg expose here is one with an Iceberg format whose binding.platform is not confluent: a Tableflow expose is published by its own module. fluid validate, the run preflight and both runners resolve the exposes the same way, so they name the same tables. On 0.19.0 and earlier, and with #707 and #709 alone, a derived sink wrote the contract's first Iceberg expose, whatever the build's outputs named.
Two Kafka Connect builds, one per expose (each expose's contract and each build's source are left out):
exposes:
- exposeId: orders
kind: table
binding:
platform: aws
format: iceberg
location: {bucket: acme-lake, database: sales, table: orders, region: eu-west-1}
- exposeId: refunds
kind: table
binding:
platform: aws
format: iceberg
location: {bucket: acme-lake, database: sales, table: refunds, region: eu-west-1}
builds:
- id: stream_orders
pattern: acquisition
engine: kafka-connect
outputs: [orders]
properties:
sink: {format: iceberg}
- id: stream_refunds
pattern: acquisition
engine: kafka-connect
outputs: [refunds]
properties:
sink: {format: iceberg}
stream_orders pushes iceberg.tables=sales.orders and stream_refunds pushes iceberg.tables=sales.refunds. With #707 and #709 alone, stream_refunds pushed iceberg.tables=sales.orders too, and fluid validate, the preflight and the run all passed.
Kafka Connect writes one expose, because the derived config carries one
iceberg.tablesentry. The build'soutputsmust name exactly one Iceberg expose; a build with nooutputsis accepted only when the contract has exactly one. Otherwisefluid validateand the run preflight refuse it. Withoutputs: [orders, refunds]onstream_refunds:1. iceberg sink (build 'stream_refunds'): its outputs ['orders', 'refunds'] name 2 of the Iceberg sink exposes ['orders (sales.orders)', 'refunds (sales.refunds)']; a derived Kafka Connect sink writes one expose (one iceberg.tables entry). List exactly one of them in the build's outputs, split the build into one build per expose, or hand-write the sink config (properties.kafka-connect.sink_connector_config)Outputs that name no Iceberg expose are refused the same way. With #707 and #709 alone they drew only a warning that the join is implicit.
Embedded Debezium Server writes every captured table under one
table-namespace, through one catalog. It writes the Iceberg exposes itsoutputsname, or all of the contract's with nooutputs, and is refused when:- its outputs name none of them;
- they sit in more than one
binding.location.database; - they resolve to different catalogs. The error names the settings that differ, such as
catalog,uriorwarehouse. A Glue warehouse is a per-table prefix, so it is not compared, and the sink takes the first expose's; - they are DynamoDB or JDBC exposes whose warehouses, derived from
location.bucket, differ. Such a catalog creates every missing table under the one warehouse the sink is given, and each derived warehouse is that expose's own table prefix. Set onelocation.warehouseon those exposes, or split the build.
One embedded Debezium Server build over both exposes above (its
sourceleft out), withrefundsmoved todatabase: finance:- id: cdc_sales pattern: acquisition engine: debezium outputs: [orders, refunds] properties: sink: {format: iceberg} debezium: deployment: {mode: embedded}fluid validaterefuses it:1. iceberg sink (build 'cdc_sales'): a derived Debezium Server sink writes every captured table under one table-namespace, but the exposes its outputs ['orders', 'refunds'] name, ['orders (sales.orders)', 'refunds (finance.refunds)'], sit in the databases ['finance', 'sales']. Give them one binding.location.database, split the build into one build per database, or hand-write the sink config (properties.debezium.server.sink.config)A config that names its own tables. A hand-written
sink_connector_configorserver.sink.configthat forge-cli does not derive from, and an override that setsiceberg.tables(Kafka Connect) ortable-namespace(Debezium Server), behave as before: the config is checked against the first Iceberg expose, and outputs that name no Iceberg expose draw the warning that the join is implicit.
Kafka Connect: catalog-impl or type, never both
Apache Iceberg refuses a catalog configured with both type and catalog-impl. On 0.19.0 and earlier the Kafka Connect sink config for a Glue table carried both, and the sink failed at startup with:
java.lang.IllegalArgumentException: Cannot create catalog iceberg, both type and catalog-impl are set
The derived config now carries one selector, as the Debezium Server config already did. The table and catalog keys for a Glue expose (bucket: acme-lake, path: bronze/orders, database: bronze, table: orders, region: eu-west-1, no location.catalog):
{
"iceberg.tables": "bronze.orders",
"iceberg.catalog.catalog-impl": "org.apache.iceberg.aws.glue.GlueCatalog",
"iceberg.catalog.warehouse": "s3://acme-lake/bronze/orders",
"iceberg.catalog.io-impl": "org.apache.iceberg.aws.s3.S3FileIO",
"iceberg.catalog.client.region": "eu-west-1"
}
iceberg_catalog_overrides and a hand-written sink_connector_config are merged over the derived config, so an override that sets the other selector key would bring the failure back. fluid validate refuses it:
1. iceberg sink (build 'stream_orders'): the sink config would carry both iceberg.catalog.type (from iceberg_catalog_overrides) and iceberg.catalog.catalog-impl (from the derived glue catalog config); Iceberg's CatalogUtil refuses a catalog with both type and catalog-impl set, so the sink never starts. Keep one, and change catalogs with binding.location.catalog rather than an override
To move a sink to another catalog, change binding.location.catalog, not the selector keys.
On AWS: a table in another catalog
An Iceberg expose on platform: aws whose location.catalog is anything other than glue:
Gets its S3 bucket and nothing in Glue. The module creates no Glue database, Glue table or Lake Formation resource for it, and does not import a Glue table of the same name into state.
fluid policy compilewrites the bucket entry with noglue.tableentry. An expose with nolocation.catalog, orcatalog: glue, emits exactly what it did before.Is not looked up in Glue.
fluid diffreports itnot_checked(table lives in Iceberg catalog lakekeeper; Glue is not inspected), andfluid testreportsTable not checkedinstead of failing on a Glue table that does not exist.Cannot carry Lake Formation governance.
governance.lakeFormation,policy.authz.columnRestrictionsandpolicy.authz.rowFiltersare refused by catalog name atfluid validateand at apply (lake-formation-needs-glue-catalog,column-restriction-unenforceable,row-filter-unenforceable), instead of being written against a Glue table that does not exist:1. exposes[orders] declares governance.lakeFormation, but its Iceberg table lives in the 'lakekeeper' catalog (location.catalog), not in AWS Glue. Lake Formation governs only Glue Data Catalog tables, so its grants, LF-tags and filters would have no table to name and would not be applied. Govern access in the lakekeeper catalog itself and remove governance.lakeFormation from this binding. Remove location.catalog (or set it to 'glue') to keep the table in the Glue catalog under Lake Formation.Has
accessPolicy.grantsreported as unenforced, with a warning that points at the catalog rather than at Lake Formation grants:1. accessPolicy.grants are not enforced on aws binding(s) orders (lakekeeper): their Iceberg tables live in a catalog other than Glue, and the AWS emitter writes access only as Lake Formation grants on a Glue table. Grant access in that catalog.
Grant access in the catalog itself; forge-cli writes no grant there. (since 0.33.0, forge-cli #993) For a Lakekeeper table that changes: fluid policy apply applies the grants in Lakekeeper, from the bindings fluid policy compile writes.
Upgrading an AWS contract that names another catalog
0.19.0 and earlier created a Glue database and table for every AWS Iceberg expose that names location.database and location.table, whatever its location.catalog. After the upgrade, the OpenTofu state of such a contract still holds them while the module no longer declares them, so the next tofu plan would destroy them, and destroying a Glue database deletes every table in it, including tables created outside FLUID. fluid apply stops before it plans (the remediation list, which repeats the commands, is abridged):
❌ iceberg_catalog_move_blocked [ERR_ICEBERG_CATALOG_MOVE_BLOCKED]
kind: iceberg-catalog-move
error: iceberg catalog move blocked — this contract's OpenTofu state holds 2 Glue catalog resource(s) for Iceberg table(s) that now live in another catalog:
exposes[orders]: location.catalog lakekeeper
aws_glue_catalog_database.bronze_orders_stream_streaming
aws_glue_catalog_table.bronze_orders_stream_streaming_orders
forge-cli no longer creates a Glue table for an Iceberg table in a non-Glue catalog (it was a second claim on the table's name, without its metadata), so applying now would plan to DESTROY these resources, and destroying a Glue database deletes every table in it, including tables created outside FLUID.
Drop each from this contract's state, then re-run apply:
tofu -chdir=.fluid/iac/aws/bronze_orders_stream state rm aws_glue_catalog_database.bronze_orders_stream_streaming
tofu -chdir=.fluid/iac/aws/bronze_orders_stream state rm aws_glue_catalog_table.bronze_orders_stream_streaming_orders
`tofu state rm` touches ZERO bytes of infrastructure: the resources stay in AWS, and only this contract's claim on them is released. Delete a Glue table by hand once nothing reads it, and a Glue database only once it holds nothing else. If the table belongs in Glue, remove location.catalog (or set it to 'glue') instead.
remediation: [...]
(forge-cli #709, since 0.20.0) The exposes[orders] line keeps its expose id, and each printed tofu state rm command stays on one line, so a copied line runs with its address. On #707 alone the line printed as exposes: location.catalog lakekeeper, and a long command could wrap onto a second line.
Run the
tofu state rmcommands it prints, one per Glue resource, in the formtofu -chdir=<module directory> state rm <address>(each argument shell-quoted when it needs to be). For the example contract:tofu -chdir=.fluid/iac/aws/bronze_orders_stream state rm aws_glue_catalog_database.bronze_orders_stream_streaming tofu -chdir=.fluid/iac/aws/bronze_orders_stream state rm aws_glue_catalog_table.bronze_orders_stream_streaming_orderstofu state rmchanges nothing in AWS. It releases this contract's claim on the resources, which stay where they are.Run
fluid applyagain.Delete the Glue table by hand once nothing reads it, and the Glue database only once it holds nothing else.
If the table belongs in Glue after all, remove location.catalog (or set it to glue) instead. There is no flag that skips the guard. Before it raises, the apply logs a structured iceberg_catalog_move_blocked event with the addresses, the exposes and the commands. On AWS the guard concerns an Iceberg expose that names a location.database and a catalog other than Glue. The same guard covers Snowflake.
(forge-cli #709, since 0.20.0) A moved expose's Glue resources are flagged when its own Glue table is in state, which shows that an earlier release created them for this expose. A Glue database that only a since-removed expose created, a parquet expose say, is not a catalog move: the plan's destroy of it is left to the OpenTofu data-loss gate. On #707 alone the guard flagged such a database, and the apply could not get past it. An expose that names a location.database and no location.table has no Glue table to show this: an earlier release created only its Glue database, so that database is flagged when state holds it and the module no longer declares it.
(forge-cli #709, since 0.20.0) When the guard cannot read the state, or its check fails, the apply continues without it and logs an iceberg_catalog_move_probe_skipped WARNING that names the reason and the exposes, for example:
{"time": "...", "level": "WARNING", "name": "fluid.cli", "message": "iceberg_catalog_move_probe_skipped", "provider": "aws", "reason": "the state could not be read: `tofu state pull` failed: Error: Failed to load state: AccessDenied: Access Denied", "exposes": [{"expose": "orders", "catalog": "lakekeeper"}], "remedy": "if the plan below destroys resources an older forge-cli created for these exposes, do NOT pass --allow-data-loss: release them with `tofu state rm` and re-run apply"}
The OpenTofu data-loss gate still stops a plan that would destroy the resources. Release them with tofu state rm as above rather than passing --allow-data-loss. On #707 alone a failed check was logged at debug level, and a state that could not be read was not reported. The same pattern guards packaging ownership transitions.
Upgrading a Snowflake contract that names another catalog
(forge-cli #709, since 0.20.0) 0.19.0 and earlier created a Snowflake EXTERNAL VOLUME for a platform: snowflake Iceberg expose whose location.catalog is lakekeeper or bigquery, or is spelled iceberg-rest, and dbt wrote the table onto it as a Snowflake-managed table. The module now creates no volume for those catalogs, since Snowflake does not manage them. The guard covers hive, jdbc, hadoop and dynamodb too, which also got a volume and which fluid validate now refuses. A volume the expose names itself, in binding.icebergConfig.properties.external_volume, is not concerned: no release created it. When the contract's state still holds the volume, fluid apply stops before it plans instead of dropping it (the remediation list is abridged):
❌ iceberg_catalog_move_blocked [ERR_ICEBERG_CATALOG_MOVE_BLOCKED]
kind: iceberg-catalog-move
error: iceberg catalog move blocked — this contract's OpenTofu state holds 1 Snowflake EXTERNAL VOLUME(s) that this contract's configuration no longer declares:
snowflake_external_volume.sales_orders_lake_vol_FLUID_SALES_ORDERS_LAKE_VOL
The volume is named for the contract, not for an expose, so the state does not say which expose it was created for. Possible causes: this contract was applied by a forge-cli release that gave an Iceberg table in a catalog Snowflake does not manage an EXTERNAL VOLUME (this release gives it none, and dbt writes it as an externally cataloged table); or this change removed a Snowflake-managed Iceberg expose, or moved one to another catalog. Applying now would plan to DROP the volume, and any Snowflake-managed Iceberg table written onto it still uses it.
Iceberg exposes whose catalog earlier releases gave an EXTERNAL VOLUME:
exposes[orders_iceberg]: location.catalog lakekeeper
Drop each from this contract's state, then re-run apply:
tofu -chdir=.fluid/iac/snowflake/sales_orders_lake state rm snowflake_external_volume.sales_orders_lake_vol_FLUID_SALES_ORDERS_LAKE_VOL
`tofu state rm` touches ZERO bytes of infrastructure: the resources stay in Snowflake, and only this contract's claim on them is released. Drop a volume by hand (DROP EXTERNAL VOLUME) only once no Iceberg table uses it. If an Iceberg table belongs in Snowflake's own catalog, remove its location.catalog (or set it to 'snowflake') instead.
remediation: [...]
(forge-cli #710, since 0.20.0) The message names both possible causes because the state cannot tell them apart: an earlier release that gave the volume to an expose in a catalog Snowflake does not manage, or a Snowflake-managed Iceberg expose that this change removed or moved to another catalog. The guard blocks the same applies as before. With #707 and #709 alone the message said forge-cli no longer creates such a volume, and listed the moved exposes as the tables it was held for.
- Run the printed command,
tofu -chdir=.fluid/iac/snowflake/<safe-id> state rm snowflake_external_volume.<name>. It changes nothing in Snowflake. - Run
fluid applyagain. - Drop the volume by hand (
DROP EXTERNAL VOLUME) only once no Iceberg table uses it. A Snowflake-managed table written onto it still does.
If the table belongs in Snowflake's own catalog, remove location.catalog (or set it to snowflake) instead. The volume is named per contract (FLUID_<PRODUCT_ID>_VOL), not per expose, so the Snowflake guard has no per-expose resource to check: the volume is flagged when it is in state, an expose moved, and the module no longer declares it. The guard finds the volume by the name derived from the contract id, not from the expose's location, so it also stops an upgrade whose edit changed location.warehouse to the catalog's warehouse name (warehouse: analytics) or removed location.iam_role_arn.
Other commands
dbt-bigquery. An expose that names a catalog other than
bigqueryis left out ofcatalogs.yml, with a warning, instead of becoming a BigLake table. Onplatform: gcp,fluid validateaccepts such a catalog's warehouse name and refuses a warehouse in another object store (s3://,abfss://).Confluent Tableflow. A
platform: confluentexpose publishes only to AWS Glue. Alocation.catalogother thanglueis afluid validateerror, and the module creates no catalog integration for it. (forge-cli #710, since 0.20.0) With nolocation.catalogthe expose reads asglue, so dbt-snowflake'scatalogs.ymlwritescatalog_linked_database_type: gluefor it.fluid policy compile. A Snowflake-managed Iceberg table compiles to Snowflake grants. A table in another catalog gets no Glue grant, and a warning to enforce access in that catalog. (forge-cli #710, since 0.20.0) A Confluent Tableflow expose compiles to its S3 bucket and the Glue table Tableflow publishes. The Tableflow module names that table for the topic (location.topic, elselocation.table, else the expose id) and publishes it intolocation.database, or, with none, into the database Tableflow names after the Kafka cluster id. For this binding, which sets nodatabase(fluid validatewarns about that):binding: platform: confluent format: iceberg location: environment_id: env-abc123 kafka_cluster_id: lkc-xyz789 topic: orders bucket: acme-tableflow region: eu-west-1 confluent_role_arn: arn:aws:iam::123456789012:role/tableflowa
readgrant compiles to ans3.bucketbinding onacme-tableflowand this Glue binding:{ "provider": "aws", "resource_type": "glue.table", "resource_id": "lkc-xyz789.orders", "database": "lkc-xyz789", "table": "orders", "region": "eu-west-1", "principal": "group:analysts@acme.com", "actions": ["glue:GetTable", "glue:GetDatabase", "athena:StartQueryExecution", "athena:GetQueryResults"] }With neither
databasenorkafka_cluster_id, the database is unknown: the expose gets the bucket binding only, and a warning.fluid policy compileprints each warning.fluid validate. A crash inside the Iceberg sink, Confluent or Iceberg prerequisite check is an error ("the contract was NOT checked for ..."), not a note printed only with--verbose. Twocatalog: snowflakeexposes that derive one EXTERNAL VOLUME on different storage are refused at validate instead of failingfluid applymid-emit. The full list is in Iceberg catalog checks.
On 0.19.0 and earlier
Each emitter classified location.catalog by hand, and they disagreed:
catalog: lakekeeperstreamed over REST, while dbt'scatalogs.ymlwrote a Snowflake-managed (built_in) table and the AWS module created a Glue database and table of the same name.- The streaming-sink check required
uriandwarehouseonly for the literalrest. - On Snowflake,
hive,jdbc,hadoopanddynamodbbecame Snowflake-managed tables, andfluid validateasked alakekeeperexpose for ans3://orgs://warehouse. - A Confluent binding published to Glue whatever catalog it named, and dbt-bigquery made a BigLake table for any catalog.
- A Kafka Connect sink on Glue failed at startup, as shown above.
- An unknown value fell back differently in each emitter, so a typo split one table across catalogs.
fluid policy compilecompiled every Iceberg expose off GCP to AWS S3 and Glue grants, whatever its platform.- A Kafka Connect or Debezium Server sink config forge-cli derived wrote the contract's first Iceberg expose, whatever the build's
outputsnamed. - A derived DynamoDB, JDBC or BigQuery sink config carried no warehouse unless
location.warehouseset one, and a BigQuery one nogcp.bigquery.project-id. - A crash inside an Iceberg or Confluent check of
fluid validatewas printed only with--verbose, and the contract passed unchecked. - Neither streaming runner checked its Iceberg sink before it created anything.
Masking at landing
exposes[].policy.privacy.masking is applied by the DuckDB runner inside the same COPY that lands the data, after the quality gates have judged the source values. The local file, the S3 object, the file a BigQuery load job reads, and the dead-letter file all hold the treated values.
exposes:
- exposeId: orders_raw
kind: table
binding:
platform: local
format: parquet
location:
path: out/orders.parquet
policy:
privacy:
masking:
- column: customer_email
strategy: hash
- column: amount
strategy: mask
params: { keepLast: 2 }
contract:
schema: []
Set the salt in the build's environment, never in the contract:
export FLUID_PII_HASH_SECRET="$(openssl rand -hex 32)"
fluid apply contract.fluid.yaml --mode amend-and-build --build-id ingest_orders --yes
customer_email 6c70c366520af6f72a1bad762aa6ee64689255873a371818e8c858271d3548c8
amount **.9
| Strategy | What lands | Parameters and secret |
|---|---|---|
hash | Lowercase hex SHA-256 of the salt followed by the value. The same value hashes the same, so joins across products that share the salt still work. | Salt from the variable params.saltEnv names, default FLUID_PII_HASH_SECRET. At least 16 bytes. |
mask | Every character replaced by * except the first keepFirst (default 0) and last keepLast (default 4). Length is kept. A value no longer than keepFirst + keepLast is masked entirely. | keepFirst, keepLast. No secret. |
tokenize | 32 hex characters of an HMAC-SHA256 of the value. The same token the tokenize_pii pre-land hook produces. | Key from the variable params.keyEnv names, default FLUID_PII_TOKENIZATION_KEY. At least 32 bytes. |
encrypt | aesgcm:v1: followed by AES-GCM output. Reversible with the key, not deterministic, so joins on it do not work. | Key from the variable params.keyEnv names, default FLUID_PII_ENCRYPTION_SECRET_KEY: base64 of 16, 24 or 32 bytes (openssl rand -base64 32). |
The build refuses to land rather than land a column untreated. These are all refused:
k_anonymity, which is a property of a whole table and not of one value- a parameter the strategy does not take, and a literal
salt,keyorsecretparameter - a secret variable that is unset or too short
- a masked column that the expose declares with a type other than a string type, because a treated column always lands as a string
duckdb.refused masking: masking hash on column 'customer_email' needs a salt in the environment
variable FLUID_PII_HASH_SECRET, which is unset or empty. Refusing to land the column untreated ...
If the expose declares its columns, write each masked column as varchar. The refusal message above offers string, but the schema-drift check compares the type names DuckDB reports for the source, so a column declared string fails the run with source schema drift detected (measured on 0.18.1, with and without schemaPolicy set). See Schema evolution.
Masking is the DuckDB runner's. A build on another engine, or a Python hybrid-reference build, does not apply it. A build with inline SQL (properties.sql) whose expose declares masking is refused with MaskingNotAppliedError rather than landed in cleartext; see Production troubleshooting. The strategies and the policy.privacy.masking schema are described in Governance policy.
fluid verify checks the landed result whatever wrote it. It reads every non-null value of each masked column and fails the column if a value lacks its strategy's shape. It does this for local files, for S3 with Glue through Athena, and for BigQuery:
🔍 Dimension 2: Masking
✅ PASS - every non-null value has its strategy's shape: customer_email (hash), amount (mask)
Platform-native dynamic masking, such as a BigQuery policy tag that masks at query time, is a different mechanism and is not emitted from this block. See Governance.
Delivery guarantees
delivery:
guarantee: at_least_once # at_most_once | at_least_once | exactly_once
dlq:
enabled: true
maxRecordsBeforeAbort: 1000
alertOn: [quality_gate_failed, destination_write_failed]
alertOn accepts pii_classification_failed, schema_violation, destination_write_failed and quality_gate_failed.
As of 0.18.1, the duckdb engine does not read delivery: a build with guarantee: exactly_once runs, because capability negotiation reads builds[].capabilities (see Asking for a capability). The delivery.dlq keys are read by other engines and by fluid verify, not by the DuckDB runner (see Quality gates and the dead-letter queue).
Schema evolution
What happens when the source's columns change is decided by the expose, not by a key under the build:
exposes:
- exposeId: orders_raw
kind: table
binding: { ... }
contract:
schemaPolicy: strict # strict | discover_and_freeze | evolve_safe | evolve_all
schema:
- { name: order_id, type: bigint }
- { name: customer_email, type: varchar }
At the start of a run, the engine compares the columns it reads with the expose's declared contract.schema. The first expose in exposes is the one compared. builds[].outputs decides which expose the DuckDB build writes, but as of 0.18.1 it does not change which expose the drift check reads: a second build whose expose is not exposes[0] is compared against exposes[0], so when its source columns differ from the schema declared on exposes[0] and exposes[0] sets schemaPolicy: discover_and_freeze, that build fails with source schema drift detected. With an empty schema: [] there is nothing to compare and the check does not run. When schemaPolicy is not set, the check runs as evolve_safe, which is not the schema's own default of strict.
| Change in the source | strict | discover_and_freeze | evolve_safe | evolve_all |
|---|---|---|---|---|
| Column added | Fails | Fails | Included | Included |
| Column removed | Fails | Fails | Warns | Dropped |
| Numeric type widened | Fails | Fails | Accepted | Accepted |
| Numeric type narrowed | Fails | Fails | Fails | Cast |
A failure raises SchemaDriftError, before anything is written:
✗ source schema drift detected
why baseline=sha256:ef7417...; current=sha256:c41252...; created_at/removed→fail
fix Review contract.exposes[].contract.schemaPolicy; if policy=evolve_safe, this is expected.
If strict/discover_and_freeze, update the contract or fix the source.
Decisions are deterministic: the same two column sets always give the same outcome.
properties.schemaEvolution is not enforced
properties.schemaEvolution.policy, onAddedColumn, onRemovedColumn and onTypeChange validate, but as of 0.18.1 no runner reads them. A build with schemaEvolution.policy: strict and a source that gained a column runs and lands the new column. Set schemaPolicy on the expose instead.
Quality gates and the dead-letter queue
quality:
gates:
- rule: not_null
columns: [order_id]
severity: error
- rule: range
column: amount
min: 0
max: 1000000
severity: error
onError: route_to_dlq
On the duckdb engine, the gates run inside the COPY. A row that passes every gate lands; a row that fails any gate does not, and goes to the dead-letter queue instead. The run still succeeds. With one blank order_id in the CSV:
duckdb.dlq stream=orders bad_records=1 on_error=route_to_dlq
{"reason": "not_null gate failed on column 'order_id'", "record": {"amount": 5.0, "created_at": "2026-10-02", "customer_email": "grace@example.com", "order_id": null}, "run_id": "<run-id>", "stream": "orders", "timestamp": "2026-10-05T00:58:29Z", "hook_trace": []}
The file is .fluid/dlq/<run-id>/<stream>.ndjson. Masked columns are masked in it too.
What the DuckDB runner evaluates, as of 0.18.1:
- Rules:
not_null(withcolumns),range(column,min,max) andregex(column,pattern). The schema also acceptsunique,row_count_anomalyandfreshness; the DuckDB runner skips those without a message. severityis required by the schema and does not change what the DuckDB runner does with a failing row.onErrortakesroute_to_dlq,abort_runorbest_effort, andfailis rejected by the schema. The DuckDB runner behaves the same for all three: bad rows go to the dead-letter queue and the run succeeds. A run is only promoted to failed on the valuefail, whichfluid validatedoes not accept.delivery.dlq.maxRecordsBeforeAbortanddelivery.dlq.sinkare not read. The queue is always.fluid/dlq/and its size is not capped. A contract withmaxRecordsBeforeAbort: 0and one bad row runs to completion.quality.anomalies(record_count_dropand the other signals) are accepted by the schema and are not read.
fluid verify prints three probes for each acquisition build after the run: run_state_succeeded, records_landed and no_unexpected_dlq_overflow. As of 0.18.1 the DuckDB run record has no dlq_records field, so the third probe always reports dlq_records=0, whatever went to the queue.
Pre-land hooks
preLand is a list of hook names: dlp_scan, tokenize_pii, quality_gate and emit_lineage_input.
preLand: [dlp_scan, quality_gate]
On the duckdb engine, quality_gate selects the gate logic above and needs no hook of its own, and emit_lineage_input is skipped. dlp_scan and tokenize_pii run after the file has landed, on a sample of up to 1000 rows. They report which columns look like PII (in the run record's facets.pii_findings) and do not change what was written. To change landed values, use masking at landing.
Cost tracking and budget gates
cost:
budget:
monthly: { rows: 1000000 } # rows, bytes ("50GB") and computeMinutes
onExceed: abort # warn | abort
chargeback:
team: ingestion
As of 0.18.1, no engine enforces cost.budget while it runs. A build with monthly.rows: 1, onExceed: abort and a three-row source runs and lands all three rows. The only place the budget is read is the cost_within_budget probe of fluid verify, which compares the run's row count with monthly.rows and ignores bytes and computeMinutes:
❌ cost_within_budget: records_used=3.0 row_cap=1
A failed probe counts as a mismatch. fluid verify --strict downgrades it to a warning, and --fail-on-warning makes it fail the command.
BudgetExceededError exists, and its message points to Cost tracking. That page covers the per-run cost of the LLM-backed fluid forge commands, not the acquisition budget described here. chargeback is accepted and not read.
Lineage emission
A DuckDB acquisition run emits an OpenLineage RunEvent pair, a start and a complete or fail, naming the source it read and the expose it wrote.
The emitter is chosen by environment, not by a key in the contract. With no endpoint configured the events are dropped:
export OPENLINEAGE_URL=https://marquez.example.com
Emitting needs the lineage extra: pip install 'data-product-forge[lineage]'. (since 0.28.0, forge-cli #837)
FLUID_OPENLINEAGE_URL takes precedence over OPENLINEAGE_URL. The endpoint path defaults to api/v1/lineage (change it with FLUID_OPENLINEAGE_ENDPOINT), and OPENLINEAGE_API_KEY or FLUID_OPENLINEAGE_API_KEY sets the bearer token. A private or loopback endpoint is allowed unless FLUID_OPENLINEAGE_ALLOW_PRIVATE=false; link-local addresses, such as cloud metadata endpoints, are blocked either way.
The schema's lineage block has one key, emit, and no runner reads it. A build with lineage: { emit: false } still emits when OPENLINEAGE_URL is set. Out-of-tree emitters subclass LineageEmitter from fluid_build.api.lineage.
Image signature verification (Cosign)
properties.airbyte.image_signature and properties.kafka-connect.image_signature accept a verifier (cosign), a publicKey, and slsaProvenance (required, optional or disabled):
airbyte:
connector_image: airbyte/source-postgres
image_signature:
verifier: cosign
publicKey: ${COSIGN_PUBLIC_KEY}
slsaProvenance: required
As of 0.18.1, fluid apply does not run this check. The Airbyte runner verifies an image only when a verifier object is passed to it, and the build dispatcher that fluid apply goes through does not pass one. No runner reads the Kafka Connect block. A contract with image_signature validates and applies without a Cosign check, so do not rely on it as a gate yet. When a check does run and fails, the build raises SupplyChainViolationError, whose doc link prints fluid verify-signature; that page covers signing fluid bundle archives and not connector images.
Catalog registration
catalog:
register: [datahub, openmetadata]
documentation: auto # auto | manual | none
register accepts datahub, openmetadata, datamesh_manager, unity, glue and snowflake_horizon. The CLI registers each target when you run fluid publish, not at apply time. fluid publish --dry-run prints acquisition publish (plan only) <product>/<build> → <target> for each one. A target with no endpoint configured in the environment is reported as not configured, and the other targets still run.
Out-of-tree registrars implement the CatalogRegistrar protocol in fluid_build.api.catalog.
Concurrency and state
concurrency:
lock:
scope: product # product | build
onContended: abort # abort | queue | replace
timeout: PT10M
As of 0.18.1 the block validates and nothing acquires the lock: no runner calls the state store's acquire_lock, so two concurrent runs of one build both proceed. LockHeldError and its queue hint exist for when it is wired in.
Run records, cursors and the dead-letter queue live in .fluid/ next to the contract. The default store is FileStateStore; an out-of-tree store implements the StateStore protocol in fluid_build.api.state.
Top-level retention
The top-level retention: block declares how long run records, run logs, lineage events and dead-letter entries should be kept. Durations are ISO-8601, so P90D, not 90d; a value like 90d fails validation.
retention:
runState: P30D
runLogs: P90D
lineage: P365D
dlq: P180D
These four values are also the defaults.
fluid retention sweep deletes records older than a horizon. As of 0.18.1 it does not read the contract:
fluid retention sweep --state-root .fluid --json
The command takes only --state-root and --json. It applies the four defaults above to every product under the state root. A product that declares runState: P365D still has its run records deleted after 30 days, and a key you leave out gets its default, not "never sweep". Declaring a longer horizon does not protect a run record today.
Authoring an acquisition contract
You do not have to write the YAML by hand. fluid init --discover introspects a source and emits one Bronze contract per discovered stream:
fluid init demo --discover file:///data/csv-tree
fluid init demo --discover "postgres://user@host:5432/dbname"
🔍 Discovering streams at file:///data/csv-tree…
✓ contract.orders.fluid.yaml (4 cols)
✓ Emitted 1 contract(s). Next: `fluid validate <file>`.
Discovery reads the database's information_schema for Postgres and MySQL, and walks the directory for a file source. As of 0.18.1, a Postgres URI whose server cannot be reached fails with Unknown secret storage found: 'local_file' under the heading connectivity probe failed, which hides the real connection error. A file:// URI that points inside the contract's directory works. For postgres:// and mysql:// URIs, nothing in the connection is redacted: the password in the URI is written verbatim into builds[].properties.source.connection.password, so delete that password: line and add secretRef: env://<NAME> before you commit the file (see fluid init --discover). The emitted contract uses fluidVersion: 0.7.3, and it validates as is.
A discovered contract that points at a file source outside its own directory is subject to the sandbox rules above. A file:// URI that is outside the contract's directory fails with DuckDB's own Permission Error ... file system operations are disabled by configuration, without the FLUID_DUCKDB_ALLOWED_DIRS hint that a plain path gets. Move the contract next to the data, or write the source as a plain path and allow its directory.
To migrate existing tooling, fluid import converts Meltano projects, Airbyte workspaces, dlt pipelines and Singer tap configs into acquisition contracts.
See also
- Product Types: SDP, ADP, CDP: the vocabulary that gates composition
- Postgres → DuckDB walkthrough: an end-to-end example
- DuckDB sandbox: what contract SQL and acquisition builds can read and write
fluid init --discover: onboarding for source-aligned ingestionfluid runs,fluid retention,fluid secrets: day-2 operations- API stability: the
fluid_build.apisurface for out-of-tree runners and registrars - Typed CLI errors: the error catalog, including
CapabilityMismatchError,SchemaDriftErrorandBudgetExceededError