From 0101de3ffa8fdfcc0bba2d27787b63f8eba1c6d4 Mon Sep 17 00:00:00 2001 From: panxiao81 Date: Thu, 10 Sep 2026 18:03:05 +0000 Subject: [PATCH] docs: define controller connection flags --- docs/deployment.md | 27 +++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/docs/deployment.md b/docs/deployment.md index 055af16..c4de169 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -25,19 +25,26 @@ ## Controller 配置合同 -具体 CLI flag/env 名称将在实现时按下表确定；语义和作用域已经固定： +controller 使用以下 CLI flags。必填项缺失、路径无效或 duration 不为正数时，进程必须 +在启动 manager 前失败；不得等到 reconcile 时才逐个资源报告配置错误。 -| 配置 | 必填/默认 | 说明 | +| CLI flag | 必填/默认 | 说明 | | --- | --- | --- | -| OpenBao internal API address | 必填 | controller 可访问的 HTTPS 地址 | -| OpenBao consumer API address | 默认同 internal | 写入 Tenant status，必须能被预期外部消费者解析 | -| OpenBao auth mount | 默认 `kubernetes` | Kubernetes auth mount 名称 | -| OpenBao auth role | 必填 | controller ServiceAccount 对应 role | -| OpenBao KV mount | 默认 `kv` | KV v2 mount；开发可显式用 `secret` | +| `--openbao-address` | 必填 | controller 可访问的 OpenBao API address | +| `--openbao-consumer-address` | 默认同 `--openbao-address` | 写入 Tenant status，必须能被预期外部消费者解析 | +| `--openbao-auth-mount` | `kubernetes` | Kubernetes auth mount 名称 | +| `--openbao-auth-role` | 必填 | controller ServiceAccount 对应 role | +| `--openbao-kv-mount` | `kv` | KV v2 mount；开发可显式用 `secret` | +| `--openbao-service-account-token-path` | `/var/run/secrets/kubernetes.io/serviceaccount/token` | Kubernetes auth 使用的投射 token 文件 | | `--openbao-tenant-base-path` | 默认 `postgresql-tenants` | controller 专属 mount-relative 前缀 | -| ESO ClusterSecretStore name | 必填 | controller 创建的 ExternalSecret 固定引用 | -| CA bundle path | 必填（TLS） | 只读 PEM trust bundle，不含私钥 | -| reconcile timeout | 有安全默认 | 单轮外部操作的总期限 | +| `--external-secret-store-name` | 必填 | controller 创建的 ExternalSecret 固定引用 | +| `--postgresql-ca-bundle-path` | PostgreSQL TLS 模式必填 | 只读 PEM trust bundle，不含私钥 | +| `--reconcile-timeout` | `30s` | 单轮 reconcile 中外部操作的总期限，必须大于零 | + +address 必须是绝对 `http` 或 `https` URL，不允许 userinfo、query 或 fragment，末尾 `/` +在规范化后移除。mount、auth mount 和 base path 都使用 mount-relative path 语义，不以 +`/` 开头，不含空段、`.` 或 `..`；base path 还不得编码 KV v2 的 `data`/`metadata` +API 层。生产环境的 `--openbao-address` 必须使用 HTTPS；HTTP 只用于明确的开发 fixture。 Tenant 路径固定推导为 `//`。namespace/name 都已通过 Kubernetes 名称校验，因此不再允许 CR 提供任意路径。KV v2 API URL 使用 consumer