diff --git a/mkdocs/docs/configuration.md b/mkdocs/docs/configuration.md index bc514e39af..a39b9300ea 100644 --- a/mkdocs/docs/configuration.md +++ b/mkdocs/docs/configuration.md @@ -339,40 +339,111 @@ catalog: | Key | Example | Description | | ------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------- | -| uri | | URI identifying the REST Server | -| ugi | t-1234:secret | Hadoop UGI for Hive client. | -| credential | t-1234:secret | Credential to use for OAuth2 credential flow when initializing the catalog | -| token | FEW23.DFSDF.FSDF | Bearer token value to use for `Authorization` header | +| uri | | URI identifying the REST Server | +| warehouse | myWarehouse | Warehouse location or identifier to request from the catalog service. May be used to determine server-side overrides, such as the warehouse location. | +| snapshot-loading-mode | refs | The snapshots to return in the body of the metadata. Setting the value to `all` would return the full set of snapshots currently valid for the table. Setting the value to `refs` would load all snapshots referenced by branches or tags. | +| `header.X-Iceberg-Access-Delegation` | `vended-credentials` | Signal to the server that the client supports delegated access via a comma-separated list of access mechanisms. The server may choose to supply access via any or none of the requested mechanisms. When using `vended-credentials`, the server provides temporary credentials to the client. When using `remote-signing`, the server signs requests on behalf of the client. (default: `vended-credentials`) | + +#### Headers in REST Catalog + +To configure custom headers in REST Catalog, include them in the catalog properties with `header.`. This +ensures that all HTTP requests to the REST service include the specified headers. + +```yaml +catalog: + default: + uri: http://rest-catalog/ws/ + credential: t-1234:secret + header.content-type: application/vnd.api+json +``` + +#### Authentication Options + +##### OAuth2 + +| Key | Example | Description | +| ------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------- | +| oauth2-server-uri | | Authentication URL to use for client credentials authentication (default: uri + 'v1/oauth/tokens') | +| token | FEW23.DFSDF.FSDF | Bearer token value to use for `Authorization` header | +| credential | client_id:client_secret | Credential to use for OAuth2 credential flow when initializing the catalog | | scope | openid offline corpds:ds:profile | Desired scope of the requested security token (default : catalog) | | resource | rest_catalog.iceberg.com | URI for the target resource or service | | audience | rest_catalog | Logical name of target resource or service | + +##### SigV4 + +| Key | Example | Description | +| ------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------- | | rest.sigv4-enabled | true | Sign requests to the REST Server using AWS SigV4 protocol | | rest.signing-region | us-east-1 | The region to use when SigV4 signing a request | | rest.signing-name | execute-api | The service signing name to use when SigV4 signing a request | -| oauth2-server-uri | | Authentication URL to use for client credentials authentication (default: uri + 'v1/oauth/tokens') | -| snapshot-loading-mode | refs | The snapshots to return in the body of the metadata. Setting the value to `all` would return the full set of snapshots currently valid for the table. Setting the value to `refs` would load all snapshots referenced by branches or tags. | -| warehouse | myWarehouse | Warehouse location or identifier to request from the catalog service. May be used to determine server-side overrides, such as the warehouse location. | -#### Headers in RESTCatalog +#### Common Integrations & Examples -To configure custom headers in RESTCatalog, include them in the catalog properties with the prefix `header.`. This -ensures that all HTTP requests to the REST service include the specified headers. +##### AWS Glue ```yaml catalog: - default: - uri: http://rest-catalog/ws/ - credential: t-1234:secret - header.content-type: application/vnd.api+json + s3_tables_catalog: + type: rest + uri: https://glue..amazonaws.com/iceberg + warehouse: :s3tablescatalog/ + rest.sigv4-enabled: true + rest.signing-name: glue + rest.signing-region: ``` -Specific headers defined by the RESTCatalog spec include: +##### Unity Catalog -| Key | Options | Default | Description | -| ------------------------------------ | ------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `header.X-Iceberg-Access-Delegation` | `{vended-credentials,remote-signing}` | `vended-credentials` | Signal to the server that the client supports delegated access via a comma-separated list of access mechanisms. The server may choose to supply access via any or none of the requested mechanisms | +```yaml +catalog: + unity_catalog: + type: rest + uri: https:///api/2.1/unity-catalog/iceberg-rest + warehouse: + token: +``` + +##### R2 Data Catalog + +```yaml +catalog: + r2_catalog: + type: rest + uri: + warehouse: + token: +``` + +##### Lakekeeper + +```yaml +catalog: + lakekeeper_catalog: + type: rest + uri: + warehouse: + credential: : + oauth2-server-uri: http://localhost:30080/realms//protocol/openid-connect/token + scope: lakekeeper +``` + +##### Apache Polaris + +```yaml +catalog: + polaris_catalog: + type: rest + uri: https://.snowflakecomputing.com/polaris/api/catalog + warehouse: + credential: : + header.X-Iceberg-Access-Delegation: vended-credentials + scope: PRINCIPAL_ROLE:ALL + token-refresh-enabled: true + py-io-impl: pyiceberg.io.fsspec.FsspecFileIO +``` ### SQL Catalog