docs: 明确凭据路径与 Secret 命名

README.md

@@ -31,7 +31,7 @@ spec:
   loginRole: netbox
   extensions: [pg_trgm]
   credential:
-    secretName: netbox-postgresql
+    secretName: shared-netbox-database-credentials
   deletionPolicy: Retain
 ```
 

docs/api-reference.md

@@ -14,6 +14,9 @@
 
 - PostgreSQL identifier 匹配 `^[a-z][a-z0-9_]{0,62}$`。
 - 所有引用名称使用 Kubernetes DNS label/name 的相应校验。
+- Tenant 的 `spec.instanceRef` 与 `metadata.name` 长度合计不超过 241 个字符，确保派生的
+  `<instanceRef>-<metadata.name>-postgresql` 不超过 Kubernetes DNS subdomain 的
+  253 字符限制。
 - 默认值由 CRD defaulting 提供；需要读取旧值的校验由 CEL 或 webhook 完成。
 - `status` 由 controller 独占写入，禁止出现密码、Token、管理用户名或完整连接串。
 - 两个 Kind 都只承诺一个 `Ready` Condition；调用方不得依赖内部协调阶段。
@@ -68,14 +71,17 @@ namespaced，short name 为 `pgtenant`。
 | `spec.database` | string | `metadata.name` | 合法 PostgreSQL identifier |
 | `spec.loginRole` | string | `metadata.name` | database owner 兼应用 login |
 | `spec.extensions` | set[string] | 空集合 | 必须属于 Instance allowlist；成功创建后只允许追加 |
-| `spec.credential.secretName` | string | `<name>-postgresql` | 同 namespace ESO target Secret 名称 |
+| `spec.credential.secretName` | string | `<instance>-<name>-postgresql` | 合法的同 namespace ESO target Secret 名称 |
 | `spec.deletionPolicy` | enum | `Retain` | `Retain` 或 `Delete` |
 
 Tenant 不声明 OpenBao mount 或 path。controller 使用部署级 mount/base path 和
-`namespace/name` 推导稳定路径，并用 UID metadata 验证所有权。
+`namespace/name` 推导稳定路径，并用 UID metadata 验证所有权。ExternalSecret 固定为
+`<instanceRef>-<metadata.name>-postgresql`；目标 Secret 可以由用户指定，只需
+满足 Kubernetes Secret 名称校验，不限制命名内容；省略时使用相同默认名。
 
 `instanceRef`、`database`、`loginRole` 和 `credential.secretName` 在首次成功创建外部
-状态后不可变。`extensions` 只允许集合不变或追加；移除返回 `ImmutableField`，不会执行
+状态后不可变。
+`extensions` 只允许集合不变或追加；移除返回 `ImmutableField`，不会执行
 `DROP EXTENSION`。`deletionPolicy` 在对象进入删除前可以修改；删除开始后以 finalizer
 首次观察到的值为准，避免清理过程中改变授权范围。
 
@@ -163,6 +169,6 @@ spec:
   loginRole: netbox
   extensions: [pg_trgm]
   credential:
-    secretName: netbox-postgresql
+    secretName: shared-netbox-database-credentials
   deletionPolicy: Retain
 ```

docs/deployment.md

@@ -34,14 +34,19 @@
 | OpenBao auth mount | 默认 `kubernetes` | Kubernetes auth mount 名称 |
 | OpenBao auth role | 必填 | controller ServiceAccount 对应 role |
 | OpenBao KV mount | 默认 `kv` | KV v2 mount；开发可显式用 `secret` |
-| OpenBao tenant base path | 必填 | controller 专属 mount-relative 前缀 |
+| `--openbao-tenant-base-path` | 默认 `postgresql-tenants` | controller 专属 mount-relative 前缀 |
 | ESO ClusterSecretStore name | 必填 | controller 创建的 ExternalSecret 固定引用 |
 | CA bundle path | 必填（TLS） | 只读 PEM trust bundle，不含私钥 |
 | reconcile timeout | 有安全默认 | 单轮外部操作的总期限 |
 
-Tenant 路径固定推导为 `<base-path>/<namespace>/<name>`。namespace/name 都已通过
+Tenant 路径固定推导为 `<base-path>/<namespace>/<metadata.name>`。namespace/name 都已通过
 Kubernetes 名称校验，因此不再允许 CR 提供任意路径。KV v2 API URL 使用 consumer
-address 拼为 `<address>/v1/<mount>/data/<base-path>/<namespace>/<name>`。
+address 拼为 `<address>/v1/<mount>/data/<base-path>/<namespace>/<metadata.name>`。
+
+base path 必须是合法 mount-relative path，不以 `/` 开头且不包含空段、`.`、`..`、
+`data`/`metadata` API 层。ExternalSecret 固定命名为
+`<instanceRef>-<metadata.name>-postgresql`；目标 Secret 可由 Tenant 指定，但名称必须
+满足 Kubernetes Secret 名称校验，不限制命名内容，默认与 ExternalSecret 同名。
 
 配置变化不得隐式迁移既有凭据。修改 KV mount/base path 或 consumer address 前必须
 停止 controller、评估现有 Tenant，并走明确迁移；实现应把 mount/base path 视为安装

docs/specification.md

@@ -127,6 +127,10 @@ Tenant 的 namespace 用于 Kubernetes RBAC 和身份识别，不代表 PostgreS
 | login role | `metadata.name` | 同一 Instance 全局唯一 |
 | deletion policy | `Retain` | `Retain` 或 `Delete` |
 
+Tenant 的 `spec.instanceRef` 与 `metadata.name` 长度合计不得超过 241 个字符，确保
+派生的 ExternalSecret/Secret 默认名称
+`<instanceRef>-<metadata.name>-postgresql` 不超过 Kubernetes 253 字符限制。
+
 database 和 role 名称必须作为 PostgreSQL identifier 参数安全引用，禁止通过字符串
 拼接执行。名称校验必须拒绝空字符串、NUL 和超过 PostgreSQL identifier 长度限制的
 值，并统一限制为小写字母、数字和下划线。
@@ -169,9 +173,11 @@ mount-relative path。controller 对该路径只需要读取权限。
 
 ### 8.3 租户凭据
 
-Tenant 不声明凭据 path。controller 根据部署级 KV mount、base path 和 Tenant identity
-推导唯一的 mount-relative path。推导结果禁止以 `/` 开头，禁止包含空路径段、`.`、
-`..`，也禁止把 KV v2 HTTP API 的 `data` 或 `metadata` 层编码进路径。
+Tenant 不声明凭据 path。controller 根据部署级 KV mount、base path 和 Tenant 的
+namespace/name 推导唯一的 mount-relative path。base path 来自 controller 启动参数
+`--openbao-tenant-base-path`，默认 `postgresql-tenants`。最终路径为
+`<base-path>/<namespace>/<metadata.name>`。推导结果禁止以 `/` 开头，禁止包含空路径段、
+`.`、`..`，也禁止把 KV v2 HTTP API 的 `data` 或 `metadata` 层编码进路径。
 
 新 Tenant 的凭据建立顺序必须可从任意中断点恢复：
 
@@ -216,8 +222,11 @@ sslmode
 ### 8.4 凭据输出与 ExternalSecret
 
 controller 必须根据部署级 base path 推导 Tenant 的 KV path，Tenant 不能选择 mount 或
-任意远端路径。Tenant 可以指定目标 Kubernetes Secret 名称；省略时默认为
-`<tenant-name>-postgresql`。
+任意远端路径。ExternalSecret 固定命名为
+`<instanceRef>-<metadata.name>-postgresql`。Tenant 可以通过
+`spec.credential.secretName` 指定目标 Kubernetes Secret 名称；省略时使用同一默认名。
+自定义名称只需是合法 Kubernetes Secret 名称，不限制命名内容；两者均与 Tenant 位于
+同一 namespace。
 
 controller 必须创建同 namespace ExternalSecret，从固定的 ClusterSecretStore 读取七个
 原子字段。ExternalSecret 及目标 Secret 的名称通过 Tenant status 暴露。controller
@@ -457,8 +466,9 @@ v1alpha1 至少必须提供：
 - v1alpha1 不接管任意现有资源，但必须提供并演练 dump/restore 迁移路径。
 - v1alpha1 同时实现默认 `Retain` 和显式 `Delete`；Delete 必须有 finalizer、所有权验证
   和完整清理路径。
-- OpenBao KV v2 mount 和 base path 是 controller 部署配置，mount 默认 `kv`；Tenant
-  不能选择 mount 或任意远端 path，controller 根据 Tenant identity 推导记录路径。
+- OpenBao KV v2 mount 和 base path 是 controller 部署配置，mount 默认 `kv`，base path
+  由 `--openbao-tenant-base-path` 配置并默认 `postgresql-tenants`；Tenant 不能选择 mount
+  或任意远端 path，controller 根据 namespace/name 推导记录路径。
 - 租户 KV 记录固定写入 `username/password/database/host/hostaddr/port/sslmode` 七个
   原子字段；
   controller 不生成连接 URI，应用负责映射和拼装自身配置。
@@ -493,7 +503,8 @@ checkpoint；PostgreSQL registry 只承担所有权、安装身份和保留状
 - 增加 controller 部署级 OpenBao KV mount 和 TLS 配置；
 - 增加部署级 OpenBao consumer address、ClusterSecretStore 和 KV base path 配置；
 - 删除独立 `ownerRole` 字段，使 login role 成为 database owner；
-- 为 Instance 增加 `hostaddr`，为 Tenant 增加目标 Secret 配置及凭据输出 status；
+- 为 Instance 增加 `hostaddr`，为 Tenant 增加目标 Secret 配置及 Secret/Bao URL 输出
+  status；
 - 按已确认的 identifier 合同收紧校验；
 - 增加 PostgreSQL controller registry，记录基于 UID 的所有权、安装身份和保留状态；
 - 修正凭据 type 中遗留的 rotation 注释；