(terraform-provider-iceberg) branch main updated: docs: complete provider configuration and examples (#106)

[ze...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

zeroshade pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/terraform-provider-iceberg.git


The following commit(s) were added to refs/heads/main by this push:
     new a1173fe  docs: complete provider configuration and examples (#106)
a1173fe is described below

commit a1173fe442817f9daa06e5023816414ca6811ac2
Author: Robert McConnell <ro...@mcc0nnell.org>
AuthorDate: Thu Oct 15 04:20:51 2026 -0700

    docs: complete provider configuration and examples (#106)
---
 docs/index.md    | 166 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 examples/main.tf |  34 ++++++------
 2 files changed, 183 insertions(+), 17 deletions(-)

diff --git a/docs/index.md b/docs/index.md
index 26d43df..65120e2 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -27,6 +27,172 @@ description: |-
 
 Use Terraform to interact with Iceberg REST Catalog instances.
 
+## Example Usage
+
+The provider connects to an Iceberg REST catalog. A basic configuration can
+create a namespace and a table in that namespace:
+
+```terraform
+provider "iceberg" {
+  catalog_uri = "http://localhost:8181"
+}
+
+resource "iceberg_namespace" "analytics" {
+  name = ["analytics"]
+
+  user_properties = {
+    owner = "data-platform"
+  }
+}
+
+resource "iceberg_table" "events" {
+  namespace = iceberg_namespace.analytics.name
+  name      = "events"
+
+  schema = {
+    fields = [
+      {
+        name     = "event_id"
+        type     = "long"
+        required = true
+      },
+      {
+        name     = "event_type"
+        type     = "string"
+        required = true
+      },
+      {
+        name     = "event_time"
+        type     = "timestamp"
+        required = true
+      }
+    ]
+  }
+
+  user_properties = {
+    "write.format.default" = "parquet"
+  }
+}
+```
+
+Namespace names are lists of identifier segments. A catalog that supports
+nested namespaces can use a value such as `["analytics", "production"]`.
+Tables take the namespace as a list and the table name separately, so referring
+to `iceberg_namespace.analytics.name` keeps the relationship explicit in the
+Terraform graph.
+
+See the [`iceberg_namespace`](resources/namespace.md) and
+[`iceberg_table`](resources/table.md) resource pages for the complete schemas,
+imports, schema evolution, partition specifications, and sort orders.
+
+## Provider Configuration
+
+### Catalog URI
+
+`catalog_uri` is the base address of the Iceberg REST catalog deployment. For
+example, the development catalog used by this repository is
+`http://localhost:8181`.
+
+The Iceberg Go client appends the REST API version path itself and first requests
+`/v1/config`. Do not add `/v1` to `catalog_uri`. If the catalog is deployed below
+a base path, include that deployment path in the URI; for example,
+`https://catalog.example.com/iceberg`.
+
+### REST prefix
+
+The Iceberg REST configuration response can provide a `prefix`. That prefix is a
+server-selected routing path used for subsequent catalog requests after
+`/v1/config` is loaded. The Terraform provider does not expose a `prefix`
+argument: the Iceberg Go client reads and applies a prefix returned by the
+catalog automatically.
+
+In other words, configure the catalog deployment URI in `catalog_uri`, not the
+server's REST prefix.
+
+### Catalog type
+
+The provider currently supports Iceberg REST catalogs only. The optional `type`
+argument defaults to `rest`; setting any other value returns an unsupported
+catalog type error.
+
+```terraform
+provider "iceberg" {
+  catalog_uri = "https://catalog.example.com"
+  type        = "rest"
+}
+```
+
+Because `rest` is the default, `type` normally does not need to be set.
+
+### Warehouse
+
+Some REST catalog deployments use a warehouse identifier to select the catalog
+or storage namespace. Set `warehouse` when your catalog requires one. The value
+is sent to the REST catalog during configuration; its expected format is defined
+by the catalog server.
+
+```terraform
+provider "iceberg" {
+  catalog_uri = "https://catalog.example.com"
+  warehouse   = "analytics"
+}
+```
+
+## Authentication
+
+The provider currently supports a static OAuth bearer token and custom request
+headers. Both `token` and `headers` are marked sensitive by the provider.
+
+Keep credentials out of checked-in Terraform files. Sensitive values can still
+be present in Terraform state, so protect state storage according to your
+Terraform deployment's security requirements.
+
+### OAuth bearer token
+
+Set `token` to a bearer token accepted by the Iceberg REST catalog:
+
+```terraform
+variable "iceberg_token" {
+  type      = string
+  sensitive = true
+}
+
+provider "iceberg" {
+  catalog_uri = "https://catalog.example.com"
+  token       = var.iceberg_token
+}
+```
+
+For local use, Terraform can receive the variable from the environment without
+putting the token in a `.tf` file:
+
+```shell
+export TF_VAR_iceberg_token="..."
+terraform plan
+```
+
+### Custom headers
+
+Use `headers` for catalogs that authenticate with an API key or another
+catalog-specific HTTP header, or that require additional routing headers:
+
+```terraform
+variable "iceberg_headers" {
+  type      = map(string)
+  sensitive = true
+}
+
+provider "iceberg" {
+  catalog_uri = "https://catalog.example.com"
+  headers     = var.iceberg_headers
+}
+```
+
+For example, the calling module can supply a sensitive map containing an API-key
+header. Avoid configuring the same `Authorization` header through both `token`
+and `headers`; choose one mechanism for authorization so the request does not
+carry duplicate credentials.
+
 ## Data Sources
 
 - [iceberg_namespace](data-sources/namespace.md) — Read metadata for an existing namespace from the catalog.
diff --git a/examples/main.tf b/examples/main.tf
index 5b8c5b4..96ed4de 100644
--- a/examples/main.tf
+++ b/examples/main.tf
@@ -17,39 +17,39 @@ provider "iceberg" {
   catalog_uri = "http://localhost:8181"
 }
 
-resource "iceberg_namespace" "example" {
-  name = ["example_namespace"]
+resource "iceberg_namespace" "analytics" {
+  name = ["analytics"]
+
   user_properties = {
-    description = "An example namespace"
+    owner = "data-platform"
   }
 }
 
-resource "iceberg_table" "example" {
-  namespace = iceberg_namespace.example.name
-  name      = "example_table"
+resource "iceberg_table" "events" {
+  namespace = iceberg_namespace.analytics.name
+  name      = "events"
 
   schema = {
     fields = [
       {
-        name     = "id"
+        name     = "event_id"
         type     = "long"
         required = true
       },
       {
-        name     = "data"
+        name     = "event_type"
         type     = "string"
-        required = false
+        required = true
       },
       {
-        name = "tags"
-        type = "list"
-        list_properties = {
-          element_id       = 3
-          element_type     = "string"
-          element_required = true
-        }
-        required = false
+        name     = "event_time"
+        type     = "timestamp"
+        required = true
       }
     ]
   }
+
+  user_properties = {
+    "write.format.default" = "parquet"
+  }
 }