准备 PostgreSQL VM、持久盘、备份和网络入口。
用 OpenBao PKI 签发 PostgreSQL server 证书，包含 Instance host 的 DNS SAN 与 hostaddr 的 IP SAN；配置 PostgreSQL 强制 TLS。
创建 PostgreSQL controller 管理 role 和管理 database 连接权限。
在 OpenBao KV v2 写入管理 role 凭据。
配置 OpenBao Kubernetes auth、controller policy 和面向 ESO 的读取 policy。
安装 ESO，配置独立的管理凭据同步身份和租户凭据读取身份。管理员在 controller namespace 创建管理 ExternalSecret，确认管理 Secret 已同步；另创建供租户使用的 ClusterSecretStore。
创建公开 CA bundle ConfigMap，并挂载到 controller 和需要直接验证数据库的应用。
部署 controller，再创建 Instance；等待 Ready 后才创建 Tenant。

任何一步都不得把真实密码、Token、kubeconfig 或 CA 私钥提交进 Git。

Controller 配置合同

当前 manager 支持 --database-secret-namespace（默认 POD_NAMESPACE，为空则停用 Instance 观测）与 --database-root-cert（公开 PostgreSQL CA PEM 路径）。Deployment 通过 downward API 获取 namespace，Secret 权限由该 namespace 的 Role 授予。

以下表格区分已实现的认证参数与尚待实现的供应/交付参数。必填项缺失、路径无效或 duration 不为正数时，进程必须在启动 manager 前失败；不得等到 reconcile 时才逐个资源报告配置错误。

CLI flag	必填/默认	说明
`--openbao-address`	已实现，默认空	HTTPS API 地址；为空时关闭认证会话
`--openbao-consumer-address`	默认同 `--openbao-address`	写入 Tenant status，必须能被预期外部消费者解析
`--openbao-auth-mount`	已实现，`kubernetes`	Kubernetes auth mount 名称
`--openbao-auth-role`	已实现，启用时必填	OpenBao 登录 role
`--openbao-ca-cert`	已实现，默认系统信任根	OpenBao 公开 CA PEM 路径
`--openbao-kv-mount`	`kv`	KV v2 mount；开发可显式用 `secret`
`--openbao-service-account-namespace`	已实现，启用时必填	TokenRequest 目标 SA 的固定 namespace
`--openbao-service-account-name`	已实现，启用时必填	TokenRequest 目标 SA 名称
`--openbao-token-audience`	已实现，`openbao`	SA JWT audience，必须匹配 OpenBao role
`--openbao-tenant-base-path`	默认 `postgresql-tenants`	controller 专属 mount-relative 前缀
`--external-secret-store-name`	必填	controller 创建的 ExternalSecret 固定引用
`--database-root-cert`	已实现	只读 PEM trust bundle，不含私钥；沿用 Instance 连接配置
`--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。

集群内与 systemd 共用 Kubernetes 认证

controller 是 API 客户端，不要求部署为 Pod。OpenBao 认证直接复用 manager 已加载的 Kubernetes 配置：集群外可用标准 --kubeconfig（或 KUBECONFIG），集群内可使用 in-cluster 配置。禁止另要求 /var/run/secrets/.../token 文件或解析 kubeconfig 中的 bearer token。每次 Bao 登录前通过 TokenRequest 申请新的短期 SA JWT，Kubernetes JWT 与 Bao token 的生命周期分别由 API 签发和官方 SDK 续期管理；不把 kubeconfig 本身当成永久有效凭据。

管理员为 controller 的实际 Kubernetes 身份授予目标 namespace 内 create serviceaccounts/token，用 resourceNames 限定目标 SA；示例见最小 RBAC。集群外 RoleBinding subject 对应 kubeconfig 的用户/组，集群内可绑定 manager SA；登录目标 SA 可以独立于调用者身份。 controller 不创建 SA、Role/RoleBinding，也不向自己授予权限。不要求 get secrets 来获取 JWT。 OpenBao role 还需限制 SA 名称、namespace 与 audience，TokenReview reviewer 身份由管理员配置。

示例启动参数（仅示意，不包含真实 kubeconfig 或凭据）：

manager --kubeconfig=/etc/ayatori/controller.kubeconfig \
  --database-secret-namespace=ayatori-system \
  --openbao-address=https://bao.example:8200 \
  --openbao-auth-role=ayatori-database \
  --openbao-service-account-namespace=ayatori-system \
  --openbao-service-account-name=database-openbao-login

这里的认证成功只开放 manager readiness，不代表 Database 已具备供应或交付能力。实例管理 Secret 的 namespace 同样由参数指定，systemd 模式不依赖 POD_NAMESPACE 环境变量。

Tenant 不能选择任意凭据路径。凭据必须能随 Database 保留并安全交付给被授权的新 Tenant；原 <base-path>/<namespace>/<metadata.name> 定位规则不再直接作为新 API 合同。动态供应位置使用 <base-path>/<Database UID>；导入使用 Database 的显式 credentialRef，不要求搬迁已有凭据。供应流程须先记录原 mount/path，不能在配置变化后重新推导位置。 consumer URL 仍使用无认证信息的 KV v2 API URL。

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、评估现有 Database 与绑定，并走明确迁移。资源记录应能定位原凭据，不能根据新部署参数静默切换；不再使用 registry 保存安装身份。

PostgreSQL 管理 role

生产部署禁止使用 superuser。管理 role 至少需要：

连接管理 database、读取必要 catalog；
创建/修改受管 login role；
创建 database 并指定 owner；
撤销 PUBLIC CONNECT、授予租户 role CONNECT；
连接租户 database 并创建实例实际支持、租户申请的 extension；
Delete 时禁止连接、终止目标 database session、删除已验证归属的 database/role。

部分 PostgreSQL 操作天然要求较高权限，尤其终止其他 session 和安装某些 extension。第一版使用原生非 superuser 的 CREATEDB/CREATEROLE 方案，不引入 SECURITY DEFINER 管理接口。对自行创建的 owner 显式建立 SET membership，再以 owner 管理 ACL 与扩展；已有对象仍须逐资源核实授权，不能凭基础属性接管。需要 superuser 的扩展不能扩大 controller 权限。真实权限矩阵见 Instance 原生管理观测。

OpenBao 与 ESO

controller policy 仅允许在固定 tenant base path 下 create/read/update/delete KV v2 data 和 metadata，Delete 必须能永久删除全部版本及 metadata；不读取管理凭据路径。

管理凭据由管理员维护的 ExternalSecret 同步到 controller namespace；其 ESO 身份只读对应管理路径，不能供 Tenant 使用。租户 ESO 身份只读 tenant base path，不得读取 PostgreSQL 管理凭据。controller 不创建或修改管理 ExternalSecret／Secret。 ClusterSecretStore 由平台管理员创建，controller 只引用，不创建或修改 Store。 controller 创建的 ExternalSecret 与 Tenant 同 namespace；其 ownerReference 和 Retain 时的保留/清理须与凭据交付协议一起确定，不能把投射关系等同于 Database 的 GC 关系。目标 Secret 包含固定七键：username、password、database、host、hostaddr、port、 sslmode。

Kubernetes RBAC

controller 按用例读/写 Instance、Database、Tenant 及其 status/finalizer 和 Event。
Database 不设置随 Tenant 级联删除的 ownerReference；导入、预留、回收和重新绑定授权限管理员。
controller 可在 Tenant namespace 创建、读取、更新、删除 ExternalSecret，并只读检查对应 Secret 是否完成投射。
namespace 用户可以管理本 namespace Tenant，但不能管理 Instance、Store、controller 配置或其他 namespace 的 ExternalSecret。
controller 只在自身 namespace 读取所引用管理 Secret 的 data，不获得跨 namespace 的管理 Secret 读取权限。Instance 不允许自选 Secret namespace。
对应用目标 Secret，controller 无需读取 data；验证登录使用从 OpenBao 读取的应用凭据，只检查 Secret 存在性和 ESO 状态。

升级与回滚

v1alpha1 尚不承诺跨版本转换。升级前备份 CR/绑定、PostgreSQL 数据与 OpenBao，先在隔离 Kind 环境运行 E2E。禁止在同一组 CR 上同时运行两个 controller 版本。若新版本在执行任何破坏性迁移前失败，可回滚镜像；涉及 API/storage 或凭据定位迁移时，必须先写独立升级规格和回滚步骤。

上线验证

PostgreSQL TLS 与备份验证
  -> OpenBao auth/policy 验证
  -> ClusterSecretStore Ready
  -> controller Ready/leader elected
  -> Instance Ready
  -> 测试 Tenant Ready
  -> DNS host 与 IP hostaddr 分别登录
  -> 删除测试 Tenant 并验证所选策略

生产 homelab 上线前还必须完成 security.md 的权限检查和 operations.md 的备份/逃生检查。

10 KiB Raw Blame History Unescape Escape

部署与配置

依赖与顺序