v1alpha1 API 合同

项目	内容
状态	三资源模型已批准；新增字段与绑定协议待评审
API group/version	`database.ayatori.ddupan.top/v1alpha1`
最后更新	2026-09-24

以系统规格与 ADR-0009 为准。尚未实现新 API，本页不提供可直接 apply 的三资源 YAML，以免把工作名称和未决字段当作已发布合同。

通用约定

Instance 是 cluster-scoped；Tenant 是 namespaced；Database scope 待字段评审。
每类资源提供唯一的 Ready Condition、observedGeneration；phase 用于进度展示，不能单独作为写权限或所有权证明。
引用必须区分定位名称与已绑定 UID；同名新对象不继承绑定。
controller 管理 status；资源侧管理与回收权限不得随 Tenant editor 权限自动授予。
固定默认值使用 CRD defaulting，跨字段/不可变校验使用 CEL 或 controller；并发更新使用 resourceVersion，不增加 mutating webhook 或跨系统事务。
database/role identifier 继续匹配 ^[a-z][a-z0-9_]{0,62}$。
动态申请的 database/loginRole 省略时继续以 Tenant metadata.name 为语义默认值；显式导入资源使用实际目标，不从新 Tenant 名称重新推导。最终互斥字段须经 API 评审。
投射仍位于 Tenant namespace，ExternalSecret 默认命名沿用 <instanceRef>-<metadata.name>-postgresql；目标 Secret 可由申请指定，省略时同名。有效 Instance 名称与 Tenant 名称合计不超过 241 字符；完整名称须满足 API 名称校验。
任何 spec/status/错误不得出现密码、Token 或完整秘密响应。

PostgreSQLInstance

保留管理入口字段：

JSON path	类型	必填/默认	合同
`spec.endpoint.host`	string	必填	PostgreSQL DNS 名；必须被服务端证书 DNS SAN 覆盖
`spec.endpoint.hostaddr`	string	必填	单个 IPv4/IPv6；必须被服务端证书 IP SAN 覆盖
`spec.endpoint.port`	int32	`5432`	1–65535
`spec.endpoint.database`	string	`postgres`	管理连接 database；合法 PostgreSQL identifier
`spec.endpoint.sslMode`	enum	`verify-full`	`disable`、`require`、`verify-ca`、`verify-full`
`spec.adminCredentialRef.name`	string	必填	controller namespace 内的管理 Secret 名称
`spec.adminCredentialRef.usernameKey`	string	`username`	Secret data 中的键名
`spec.adminCredentialRef.passwordKey`	string	`password`	Secret data 中的键名

管理 Secret 固定在 controller namespace，不接受 namespace 或 Bao path。管理员维护其 ExternalSecret，controller 只读；有效用户名/密码变化时重验连接。 endpoint 变化使旧观察失效，不迁移旧服务器的数据，不自动接管旧 UID 的资源。

Status 保留 observedGeneration、postgresqlVersion 和 conditions； phase 为 Pending、Validating、Ready、Deleting，移除 InitializingRegistry。 Ready 要求连接、metadata 与所需管理权限，不要求 registry。实例实际可用扩展来自查询，不提供 allowedExtensions 配置。

开始受管时保存 finalizer；删除时阻止新供应，并检查 Database（含 Released）及未绑定 Tenant 引用。无引用才解除，不级联删除资源；查询失败不能视为无引用。

Database 资源（工作 Kind：PostgreSQLDatabase）

以下是字段职责，不是已批准的 JSON schema：

内容	合同
`instanceRef`	Database 自身必填；定位来源并记录绑定的 Instance UID，不依赖 Tenant 补齐
外部目标	实际 database 名称及已确认的管理范围；操作开始后不可隐式改目标
来源	区分动态供应与管理员显式导入；不能从同名存在推断导入授权
申请预留/绑定	至多一个 Tenant，含 namespace/name/UID；Released 保留旧身份
回收策略	资源侧 Retain（默认）或显式 Delete；普通 Tenant editor 不得扩大授权
观察与进度	实际目标、当前阶段、条件和安全诊断，不保存秘密

概念生命周期包含供应/验证、可绑定、已绑定、Released 和删除；最终 phase 枚举待协议评审。 Released 不自动变成可绑定。Database 不以 Tenant 为 GC owner；使用中的资源受删除保护。

导入的初始检查只读；存在不等于 Ready，也不等于有权交付给任意 Tenant。默认保留不隐含密码、owner、授权或删除的变更许可。

PostgreSQLTenant

保留用户申请与交付职责：

动态申请描述 Instance、所需数据库/登录角色、扩展与目标 Secret；或显式引用管理员已登记的 Database。后者从 Database 获取 Instance，不重复指定来源；两条路径互斥，具体 schema 在 API 切片固定。
绑定前固定有效需求，绑定/开始供应后不能通过改引用或名称迁移资源。
extensions 成功后只允许追加，不自动卸载。
status 展示绑定 Database 身份、Ready、交付 Secret 引用及不含认证信息的 OpenBao URL。
Tenant 删除释放申请，按照 Database 的回收策略处理，不独立持有最终删除授权。

旧 Tenant spec.deletionPolicy 不再作为最终资源回收策略；旧字段表、供应 phase 枚举及仅按 Tenant namespace/name 派生凭据路径的规则不再是实现合同。已有代码没有兼容负担，不保留两套相互覆盖的策略字段。

绑定协议评审要求

实现前必须明确：

资源 scope 与 typed reference 格式，管理员预留/导入与普通申请者的 RBAC 边界。
资源侧排他记录的写入点、双向绑定顺序、API 冲突重试与单边完成恢复。
Tenant UID 变化、对象删除、Released 旧引用与管理员重新授权的判断。
同一物理数据库重复登记的冲突处理；列表查询不是原子认领。
Database 的 role/凭据管理范围、稳定凭据定位、旧访问处置与投射清理顺序。
删除开始后的策略固定点和 Tenant/Database finalizer 配合。

该协议使用 Kubernetes API 持久化，不为它新增 PostgreSQL registry。未完成一致绑定不得供应或交付；外部创建结果不确定按 Conflict 人工处理。

Conditions

每类资源至少提供唯一的 Ready；同类型 Condition 不重复，维护 lastTransitionTime 与 observedGeneration。最低安全错误分类见系统规格。

Conflict 必须说明目标、步骤、已确认与不确定部分及人工核实建议；不能建议清空 status、伪造 Ready 或改密码绕过。可恢复依赖故障退避重试，冲突不忙循环。具体 Reason 在 API 切片固定，Released 不得误报为可立即交付。

实现验收

CRD defaulting、CEL、status subresource、resourceVersion、并发绑定、重启与依赖 watch 使用真实 API server 验证；ownerReference/namespace 删除的实际 GC 使用测试集群。类型、CRD、sample 和 contract tests 必须一起对齐，不以 fake client 替代 API 语义。

7.1 KiB Raw Permalink Blame History Unescape Escape