This feature is not enabled on accounts by default. Contact Technical Support or your Customer Success representative to enable it.
This guide explains how to provision Iceberg catalog resources for your Treasure AI account using the Resource Provisioning API.
Before you can use the Iceberg catalog (create tables, grant permissions, etc.), your account must have its underlying AWS resources provisioned. This includes:
- An S3 bucket for storing Iceberg table data
- A default Glue database for the Iceberg catalog metadata
- An IAM role for reading table data from external services (e.g., Databricks, Snowflake)
Provisioning is a one-time operation per account. Once resources are active, you can create databases, manage permissions, and start writing Iceberg tables.
Only admin users can provision and manage resources.
For authentication details and API endpoints by site, see Use Iceberg Catalog Management API.
Provisioned resources go through the following statuses:
| Status | Description |
|---|---|
creating | Resource provisioning is in progress |
active | Resources are ready to use |
updating | A configuration update (e.g., trust policy) is in progress |
failed | Provisioning failed (can be retried) |
POST /v1/iceberg/catalog/resources
Authorization: TD1 <admin_api_key>Initiates resource provisioning for your account. This is an asynchronous operation — the response returns immediately with an initial creating status.
curl -X POST "https://api-iceberg-mng.us01.treasuredata.com/v1/iceberg/catalog/resources" \
-H "Authorization: TD1 <admin_api_key>" \
-H "Accept: application/json"{
"status": "creating",
"aws_region": "us-east-1",
"aws_account_id": "123456789012",
"iam_role_arn": "arn:aws:iam::123456789012:role/zcpo-hms-tenant-us01_td10000",
"external_location_url": "s3://zcp-us01-td10000-a1b2c3d4/iceberg",
"db_name": "td10000_us01_export",
"db_count": 0,
"updated_at": 1719216000
}| Field | Description |
|---|---|
status | Current provisioning status |
aws_region | AWS region where resources are provisioned |
aws_account_id | AWS account ID hosting the resources |
iam_role_arn | ARN of the table reader IAM role for external access |
external_location_url | S3 location where Iceberg table data is stored |
db_name | Default Glue database name |
db_count | Number of user-created databases (excludes the default export) |
updated_at | Unix timestamp (seconds) of the last status update |
| Status | Condition |
|---|---|
| 403 | Non-admin user, or write-only API key |
| 409 | Resources are already provisioned for the account |
| 500 | Provisioning failed (transient error, can retry) |
GET /v1/iceberg/catalog/resources
Authorization: TD1 <admin_api_key>Returns the current state of provisioned resources, including the live provisioning status.
curl "https://api-iceberg-mng.us01.treasuredata.com/v1/iceberg/catalog/resources" \
-H "Authorization: TD1 <admin_api_key>" \
-H "Accept: application/json"{
"status": "active",
"aws_region": "us-east-1",
"aws_account_id": "123456789012",
"iam_role_arn": "arn:aws:iam::123456789012:role/zcpo-hms-tenant-us01_td10000",
"external_location_url": "s3://zcp-us01-td10000-a1b2c3d4/iceberg",
"db_name": "td10000_us01_export",
"db_count": 0,
"updated_at": 1719216060
}| Status | Condition |
|---|---|
| 403 | Non-admin user, or write-only API key |
| 404 | Resources are not provisioned for the account |
- Start provisioning:
curl -X POST "https://api-iceberg-mng.us01.treasuredata.com/v1/iceberg/catalog/resources" \
-H "Authorization: TD1 <admin_api_key>" \
-H "Accept: application/json"- Poll until the status becomes
active(typically takes 1–2 minutes):
curl "https://api-iceberg-mng.us01.treasuredata.com/v1/iceberg/catalog/resources" \
-H "Authorization: TD1 <admin_api_key>" \
-H "Accept: application/json"- Once the status is
active, you can proceed to grant permissions and create tables.
If provisioning fails (status failed), you can retry by calling the POST endpoint again.
The system will re-attempt resource creation. If the failure persists, contact Treasure AI support.
- Provisioning is a one-time operation. Once resources are
active, calling the provision endpoint again returns a 409 Conflict. - The reader IAM role ARN and S3 location are stable after provisioning — they do not change across trust policy updates.
- The default
exportdatabase is provisioned automatically and cannot be deleted. Additional databases can be created using the Database Management API. - After provisioning, grant users access to databases via the Permission Management API before they can query from Data Workbench.