Align cluster commands with nested S3 storage access

Cargo.toml

@@ -26,6 +26,7 @@ chrono = "0.4"
 axoupdater = { version = "0.10.2", default-features = false, features = ["blocking", "github_releases"] }
 
 [dev-dependencies]
+uuid = { version = "1", features = ["v4"] }
 tempfile = "3"
 
 [profile.release]

README.md

@@ -377,6 +377,24 @@ rtree cluster create \
   --min-size 2:8 \
   --max-size 64:256 \
   --idle-timeout-minutes 30
+# Or create a cluster with customer-owned S3 storage
+rtree cluster create \
+  --name customer-data \
+  --replicas 1 \
+  --min-size 2:8 \
+  --s3-storage-data-bucket acme-rawtree-data \
+  --s3-storage-data-path rawtree/data \
+  --s3-storage-backups-bucket acme-rawtree-backups \
+  --s3-storage-backups-path rawtree/backups \
+  --s3-storage-role-arn arn:aws:iam::123456789012:role/RawTreeS3Access \
+  --s3-storage-access-external-id rawtree-example
+# Or choose explicit cluster identity with RawTree-managed default storage
+rtree cluster create \
+  --name database-storage \
+  --replicas 1 \
+  --min-size 2:8 \
+  --s3-storage-access-external-id rawtree-database-access \
+  --s3-storage-access-resource-tag rawtree-customer-database
 rtree cluster use production
 rtree cluster status production
 rtree cluster update production --idle-timeout-minutes 60
@@ -394,6 +412,59 @@ catalog. Run `rtree cluster sizes` to see the currently available sizes; add
 `--idle-timeout-minutes` is optional on create and update; omit it to use the
 server default on create, and pass `0` to disable automatic idling.
 
+Cluster creation forwards `--s3-storage-access-external-id` and `--s3-storage-access-resource-tag` when supplied.
+The API generates omitted identity values independently as `rawtree-<UUID>`
+using secure randomness and returns the saved values. The CLI does not generate
+identity values. Both are immutable after creation.
+Custom cluster storage requires `--s3-storage-access-external-id` to match the customer IAM role's
+trust policy. `--s3-storage-access-resource-tag` may be supplied or generated.
+
+Flag names follow the API field paths:
+
+| Flag | API field | Available on |
+| --- | --- | --- |
+| `--s3-storage-data-bucket` | `s3_storage.data.bucket` | Cluster and database creation |
+| `--s3-storage-data-path` | `s3_storage.data.path` | Cluster and database creation |
+| `--s3-storage-backups-bucket` | `s3_storage.backups.bucket` | Cluster and database creation |
+| `--s3-storage-backups-path` | `s3_storage.backups.path` | Cluster and database creation |
+| `--s3-storage-role-arn` | `s3_storage.role_arn` | Cluster and database creation |
+| `--s3-storage-access-external-id` | `s3_storage_access.external_id` | Cluster creation only |
+| `--s3-storage-access-resource-tag` | `s3_storage_access.resource_tag` | Cluster creation only |
+
+Cluster and database creation share `--s3-storage-data-bucket`, `--s3-storage-backups-bucket`, and
+`--s3-storage-role-arn`; all three are required if any destination or role option is supplied. The optional
+`--s3-storage-data-path` and `--s3-storage-backups-path` specify object-key prefixes.
+
+```sh
+rtree --org acme --cluster production database create analytics \
+  --s3-storage-data-bucket acme-rawtree-data \
+  --s3-storage-backups-bucket acme-rawtree-backups \
+  --s3-storage-role-arn arn:aws:iam::123456789012:role/RawTreeS3Access
+```
+
+Database creation reuses the cluster's saved identity: no external ID or tag is
+accepted on database commands. Use `rtree cluster status production` to read the
+External ID for the IAM trust policy and the resource tag value. Tag eligible
+customer buckets and roles with `rawtree.com/cluster=<resource-tag>`.
+
+These flags configure new resources; the API verifies access and provisions
+storage. The CLI does not create AWS buckets or IAM roles or migrate existing
+data. Omitting S3 options uses RawTree-managed cluster storage or, for a database,
+inherits its cluster's storage.
+
+The API payload has an `s3_storage` object containing `data` and `backups`
+destinations (each with `bucket` and optional `path`), plus `role_arn`. List/status
+JSON always includes both destinations with explicit paths for custom storage
+and preserves cluster `s3_storage_access.external_id` and
+`s3_storage_access.resource_tag`; role ARNs and credentials are not returned. Older clusters without
+saved identity show `not configured` in status output.
+
+The former `--s3-data-*`, `--s3-backup-*`, `--s3-backups-*`, `--s3-role-arn`,
+`--s3-storage-external-id`, `--s3-storage-resource-tag`, and legacy database
+identity flags are rejected. This CLI targets
+[Platform PR #1482](https://github.com/rawtreedb/rawtree-platform/pull/1482) and
+must be released with that server contract.
+
 Cluster lifecycle and provisioning changes are asynchronous. The `create`,
 `stop`, `resume`, and `delete` commands return as soon as the API accepts the
 request; they do not wait for the infrastructure operation to finish. After