This is an automated email from the ASF dual-hosted git repository.
JingsongLi pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/terraform-provider-paimon.git
The following commit(s) were added to refs/heads/main by this push:
new 2394668 Update README.md and docs
2394668 is described below
commit 2394668565391a9bd59b8696a034a139fd054a79
Author: JingsongLi <[email protected]>
AuthorDate: Mon Aug 24 10:23:15 2026 +0800
Update README.md and docs
---
README.md | 52 --------------------------------
docs/design.md | 93 ----------------------------------------------------------
docs/index.md | 91 --------------------------------------------------------
3 files changed, 236 deletions(-)
diff --git a/README.md b/README.md
index b24173f..5bbbbcd 100644
--- a/README.md
+++ b/README.md
@@ -42,17 +42,6 @@ Data sources:
- `paimon_database` reads a database and its server metadata.
- `paimon_table` reads a table schema, keys, options, and server metadata.
-Provider capabilities:
-
-- Paimon `/v1/config` discovery and server-supplied catalog prefix
-- optional warehouse selection
-- Bearer token authentication
-- Alibaba Cloud DLF AK/STS signing with default and OpenAPI algorithms
-- automatic STS refresh from a rotating local token file or ECS RAM role
-- custom HTTP headers
-- preservation of server options not managed by Terraform
-- nested Paimon type decoding from the REST wire format
-
## Example
```hcl
@@ -108,49 +97,8 @@ resource "paimon_table" "events" {
}
```
-For an Alibaba Cloud DLF REST endpoint, static AK/STS authentication can be
-configured as follows. Both `/v1/config` and catalog operations are signed.
-
-```hcl
-provider "paimon" {
- uri = "https://dlf.cn-hangzhou.aliyuncs.com";
- token_provider = "dlf"
-
- dlf_access_key_id = var.dlf_access_key_id
- dlf_access_key_secret = var.dlf_access_key_secret
- dlf_security_token = var.dlf_security_token
-}
-```
-
-For renewable STS credentials, use a rotating JSON token file or an ECS RAM
-role instead of static values. The provider reloads dynamic credentials when
-they have less than one hour remaining:
-
-```hcl
-provider "paimon" {
- uri = "https://dlf.cn-hangzhou.aliyuncs.com";
- token_provider = "dlf"
- dlf_token_loader = "local_file"
- dlf_token_path = "/run/secrets/dlf-sts.json"
-}
-```
-
-See [`docs/index.md`](docs/index.md) for the token JSON format, ECS setup, and
-signing-algorithm selection.
-
-Paimon primary key fields are non-null by default. To use nullable primary
-keys, set `options["primary-key.nullable"] = "true"` and set the matching
-field's `nullable` attribute to `true`.
-
## Lifecycle and safety
-In this initial version, `fields`, `partition_keys`, and `primary_keys` are
-immutable Terraform attributes. Changing one produces a table replacement.
-Paimon's managed-table drop operation can delete table data, so inspect plans
-carefully and use Terraform's `prevent_destroy` lifecycle rule for important
-tables. Table `options` and `comment` update in place through Paimon
-`SchemaChange` requests.
-
Only the REST metastore is in scope. Filesystem, Hive, and JDBC catalogs are
not accessed directly because Terraform needs a stable remote control-plane
contract; Paimon's REST OpenAPI provides that contract.
diff --git a/docs/design.md b/docs/design.md
deleted file mode 100644
index b53a28c..0000000
--- a/docs/design.md
+++ /dev/null
@@ -1,93 +0,0 @@
-<!--
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
--->
-
-# Design assessment
-
-This implementation was designed after reviewing Apache
-`terraform-provider-iceberg` main at commit
-`186d4f48b9e98386b044e1367d6fdf8d47a3ff8d` and Apache Paimon master at commit
-`d187f675d04ce5924beee04d0ba9d821dca79de1` on 2026-08-20.
-
-## What transfers from the Iceberg provider
-
-- Terraform Plugin Framework provider/resource/data-source organization
-- lazy catalog initialization so `terraform validate` does not require a live
- service
-- separate user-managed and server-returned property maps
-- stable import identifiers and removal from state after a REST 404
-- explicit lifecycle handling for catalog objects
-
-## What must be Paimon-specific
-
-The Iceberg provider delegates catalog semantics to `iceberg-go`. Paimon does
-not currently provide an equivalent official Go catalog SDK, but it does
-publish a language-neutral OpenAPI contract. This provider therefore contains
-a small Go client for the catalog-control endpoints rather than depending on
-Iceberg types or running Java in the provider process.
-
-Paimon databases are single names rather than Iceberg's segmented namespaces.
-Paimon tables also expose primary keys, partition keys, schema options, table
-comments, audit metadata, and Paimon `SchemaChange` actions. Iceberg partition
-transforms and sort orders do not map directly and were not copied.
-
-## Initial scope
-
-The first implementation supports:
-
-- REST config handshake and catalog prefix discovery
-- database CRUD/read/import and partial option ownership
-- table CRUD/read/import
-- in-place table option and comment updates
-- primitive and structured Paimon type decoding
-- Bearer authentication and static custom headers
-- DLF default and OpenAPI request signing
-- static DLF AK/STS and refreshable local-file/ECS credential sources
-
-The following are intentionally deferred:
-
-- in-place column evolution (add/drop/rename/type/nullability/position)
-- views, functions, branches, tags, partitions, snapshots, and consumers
-- acceptance tests against a packaged REST Catalog server
-- Terraform Registry release automation and generated documentation
-
-## DLF compatibility
-
-The DLF implementation follows Paimon's `DLFAuthProvider`,
-`DLFDefaultSigner`, and `DLFOpenApiSigner` contracts. The default signer uses
-the `DLF4-HMAC-SHA256` credential scope and the OpenAPI signer uses Alibaba
-Cloud's ROA `acs` HMAC-SHA1 authorization format. Paths use Java
-`URLEncoder`-compatible encoding because the exact encoded Paimon REST
-resource path participates in default signing.
-
-Dynamic credentials are loaded lazily and cached. A credential is refreshed
-when its `Expiration` is less than one hour away, matching Paimon's safety
-window. The provider serializes refreshes so concurrent Terraform operations
-do not race to replace the cached token. Static AK/STS values have no
-expiration metadata and therefore are never refreshed.
-
-## Why schema changes replace in v1
-
-Paimon's REST API exposes granular `SchemaChange` actions, but primary-key and
-partition-key evolution is not symmetric with initial creation, and correct
-column matching depends on stable field IDs and nested-field semantics. The
-initial provider marks fields and key lists as replacement attributes rather
-than emitting a partial or ambiguous migration. This is safe from silent
-metadata corruption but can be destructive because dropping a managed table
-may remove data. A follow-up should add tested, ID-based in-place column
-evolution and keep replacement only for unsupported key changes.
diff --git a/docs/index.md b/docs/index.md
index 240d684..840878c 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -31,9 +31,6 @@ provider "paimon" {
token_provider = "bear"
token = var.paimon_token
- headers = {
- "X-Tenant" = "analytics"
- }
}
```
@@ -45,99 +42,11 @@ provider "paimon" {
- `token_provider` (optional): `bear` for Bearer authentication or `dlf` for
Alibaba Cloud DLF AK/STS signing. It is inferred when omitted.
- `token` (optional, sensitive): token used by the `bear` provider.
-- `dlf_region` (optional): region used by the default DLF signer. Standard DLF
- endpoint hostnames are parsed when this is omitted.
-- `dlf_signing_algorithm` (optional): `default` or `openapi`. Endpoints whose
- hostname contains `dlfnext` select `openapi`; all others select `default`.
-- `dlf_access_key_id` and `dlf_access_key_secret` (optional, sensitive): a
- static Alibaba Cloud access key pair.
-- `dlf_security_token` (optional, sensitive): STS token used with the static
- access key pair.
-- `dlf_token_loader` (optional): dynamic credential source, either
- `local_file` or `ecs`.
-- `dlf_token_path` (optional): rotating AK/STS JSON file. Setting a path
- implies the `local_file` loader.
-- `dlf_ecs_metadata_url` (optional): ECS metadata endpoint override. The
- default is
- `http://100.100.100.200/latest/meta-data/Ram/security-credentials/`.
-- `dlf_ecs_role_name` (optional): RAM role name. The provider discovers it
- from the ECS metadata endpoint when omitted.
-- `prefix` (optional): client catalog prefix. A prefix in the server's config
- `overrides` takes precedence.
-- `headers` (optional, sensitive): additional request headers.
The provider first calls `/v1/config`, merges server defaults, client values,
and server overrides in that order, and then uses the resulting `prefix` for
catalog operations.
-## DLF AK/STS authentication
-
-Exactly one DLF credential source must be configured: static AK/STS, a local
-token file, or ECS metadata. DLF authentication signs the initial
-`/v1/config` request as well as every subsequent catalog request. Generated
-signature headers take precedence over entries with the same names in
-`headers`.
-
-### Static AK or STS
-
-```hcl
-provider "paimon" {
- uri = "https://dlf.cn-hangzhou.aliyuncs.com";
- token_provider = "dlf"
-
- dlf_access_key_id = var.dlf_access_key_id
- dlf_access_key_secret = var.dlf_access_key_secret
- dlf_security_token = var.dlf_security_token # omit for long-lived AK
-}
-```
-
-Static credentials are not refreshed. Use a dynamic source for renewable STS
-credentials.
-
-### Rotating local token file
-
-```hcl
-provider "paimon" {
- uri = "https://dlf.cn-hangzhou.aliyuncs.com";
- token_provider = "dlf"
- dlf_token_loader = "local_file"
- dlf_token_path = "/run/secrets/dlf-sts.json"
-}
-```
-
-The file must contain the same field names as Paimon's `DLFToken` JSON:
-
-```json
-{
- "AccessKeyId": "STS....",
- "AccessKeySecret": "...",
- "SecurityToken": "...",
- "Expiration": "2026-08-20T12:00:00Z"
-}
-```
-
-Replace the file atomically and restrict its permissions. The provider caches
-the parsed token and reloads the file before a request when the credential has
-less than one hour remaining. A read or parse failure is retried up to five
-times; token contents are never included in the resulting error.
-
-### ECS RAM role
-
-```hcl
-provider "paimon" {
- uri = "https://dlf.cn-hangzhou.aliyuncs.com";
- token_provider = "dlf"
- dlf_token_loader = "ecs"
-
- # Optional. Otherwise it is discovered from ECS metadata.
- dlf_ecs_role_name = "paimon-terraform-role"
-}
-```
-
-The ECS loader obtains temporary credentials from the instance metadata
-service and refreshes them using the same one-hour safety window. Use
-`dlf_ecs_metadata_url` only for a compatible metadata service or local testing.
-
## Resources and data sources
- [Database resource](resources/database.md)
