137 lines
7.5 KiB
Markdown
137 lines
7.5 KiB
Markdown
# 部署与配置
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 状态 | Review |
|
||
| 环境 | homelab Kubernetes + 外部 PostgreSQL/OpenBao |
|
||
| 最后更新 | 2026-09-10 |
|
||
|
||
本文定义 v1alpha1 的运行依赖、启动顺序和部署级配置。当前 manifests 尚未实现这些
|
||
配置，示例是后续实现合同，不可直接用于现有脚手架。
|
||
|
||
## 依赖与顺序
|
||
|
||
1. 准备 PostgreSQL VM、持久盘、备份和网络入口。
|
||
2. 用 OpenBao PKI 签发 PostgreSQL server 证书，包含 Instance `host` 的 DNS SAN 与
|
||
`hostaddr` 的 IP SAN；配置 PostgreSQL 强制 TLS。
|
||
3. 创建 PostgreSQL controller 管理 role 和管理 database 连接权限。
|
||
4. 在 OpenBao KV v2 写入管理 role 凭据。
|
||
5. 配置 OpenBao Kubernetes auth、controller policy 和面向 ESO 的读取 policy。
|
||
6. 在 Kubernetes 安装 ESO，创建可读取租户路径的 `ClusterSecretStore`。
|
||
7. 创建公开 CA bundle ConfigMap，并挂载到 controller 和需要直接验证数据库的应用。
|
||
8. 部署 controller，再创建 Instance；等待 Ready 后才创建 Tenant。
|
||
|
||
任何一步都不得把真实密码、Token、kubeconfig 或 CA 私钥提交进 Git。
|
||
|
||
## Controller 配置合同
|
||
|
||
controller 使用以下 CLI flags。启动入口加载配置、检查本切片必需项并创建共享依赖，
|
||
配置错误在启动 manager 前失败。外部服务暂时不可用由 reconcile 重试，不阻止进程启动。
|
||
|
||
| CLI flag | 必填/默认 | 说明 |
|
||
| --- | --- | --- |
|
||
| `--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-tenant-base-path` | 默认 `postgresql-tenants` | controller 专属 mount-relative 前缀 |
|
||
| `--external-secret-store-name` | Tenant 投射时必填 | controller 创建的 ExternalSecret 固定引用；Instance Ready 不依赖此项 |
|
||
| `--postgresql-ca-bundle-path` | PostgreSQL TLS 模式必填 | 只读 PEM trust bundle，不含私钥 |
|
||
| `--reconcile-timeout` | `30s` | 单轮 reconcile 中外部操作的总期限，必须大于零 |
|
||
|
||
连接地址由 OpenBao SDK 解析，移除末尾 `/`；配置错误不得携带原始地址中的认证信息。
|
||
生产环境使用 HTTPS；HTTP 只用于开发 fixture。consumer URL 的认证信息限制和 Tenant
|
||
派生路径限制由对应输出边界负责，Instance 服务不校验尚未使用的 Tenant 配置。
|
||
Kubernetes auth 使用 SDK 默认的 ServiceAccount token 挂载路径，不单独暴露路径参数。
|
||
|
||
启动时创建一个共享 OpenBao client 和凭据源，再注入 Instance 服务。凭据源在有读取需求且
|
||
token 即将过期时重新登录；每次登录重新读取投射的 ServiceAccount token。token 被撤销导致
|
||
403 时最多重新认证一次，持续 policy 拒绝仍返回错误。
|
||
|
||
每个 Instance 首次使用时读取管理 username/password 并创建自己的 PostgreSQL 连接池。
|
||
后续 reconcile 复用连接池和内存中的凭据，不做自动 PostgreSQL 密码轮换。UID、endpoint
|
||
或管理凭据引用改变时释放旧连接并重新装配；只修改 extension allowlist 不重建连接。
|
||
删除 Instance 或 controller 正常退出时关闭连接池；重启后按需重新读取 Bao。
|
||
仅修改 Bao 中原路径的密码不会触发刷新，管理员需要重启 controller 或修改凭据引用。
|
||
|
||
基础 manager manifest 不携带 OpenBao 地址、role 等环境值。实际部署通过环境专属
|
||
Kustomize overlay 注入上述 args；E2E 由测试 fixture 注入一次性环境配置。
|
||
|
||
Tenant 路径固定推导为 `<base-path>/<namespace>/<metadata.name>`。namespace/name 都已通过
|
||
Kubernetes 名称校验，因此不再允许 CR 提供任意路径。KV v2 API URL 使用 consumer
|
||
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 视为安装
|
||
身份的一部分并在 registry 留存，以便检测错误配置。
|
||
|
||
## PostgreSQL 管理 role
|
||
|
||
生产部署禁止使用 superuser。管理 role 至少需要：
|
||
|
||
- 连接管理 database、读取必要 catalog；
|
||
- 创建/修改受管 login role；
|
||
- 创建 database 并指定 owner；
|
||
- 撤销 `PUBLIC` CONNECT、授予租户 role CONNECT；
|
||
- 连接租户 database 并创建 allowlist extension；
|
||
- 创建和维护 controller 专属 registry schema/table；
|
||
- `Delete` 时禁止连接、终止目标 database session、删除已验证归属的 database/role。
|
||
|
||
部分 PostgreSQL 操作天然要求较高权限，尤其终止其他 session 和安装某些 extension。
|
||
应优先使用 PostgreSQL 预定义角色、受控 SECURITY DEFINER 管理函数或限定数据库的
|
||
授权；任何不得不使用 superuser 的 extension 都必须按实例单独记录，不得扩大默认
|
||
controller 权限。最终可执行 SQL grant 将随 PostgreSQL adapter 集成测试固化。
|
||
|
||
## OpenBao 与 ESO
|
||
|
||
controller policy 分成两个范围：
|
||
|
||
- 只读 Instance 管理凭据路径；
|
||
- 在固定 tenant base path 下 create/read/update/delete KV v2 data 和 metadata，Delete
|
||
必须能永久删除全部版本及 metadata。
|
||
|
||
ESO 使用独立身份，只需读取 tenant base path；它不应读取 PostgreSQL 管理凭据。
|
||
`ClusterSecretStore` 由平台管理员创建，controller 只引用，不创建或修改 Store。
|
||
controller 创建的 ExternalSecret 与 Tenant 同 namespace，并设置 ownerReference；目标
|
||
Secret 包含固定七键：`username`、`password`、`database`、`host`、`hostaddr`、`port`、
|
||
`sslmode`。
|
||
|
||
## Kubernetes RBAC
|
||
|
||
- controller 可读/写 Instance、Tenant 的 status/finalizer 和 Event。
|
||
- controller 可在 Tenant namespace 创建、读取、更新、删除 ExternalSecret，并只读检查
|
||
对应 Secret 是否完成投射。
|
||
- namespace 用户可以管理本 namespace Tenant，但不能管理 Instance、Store、controller
|
||
配置或其他 namespace 的 ExternalSecret。
|
||
- controller 无需读取目标 Secret 的 data；验证登录使用从 OpenBao 读取的应用凭据，
|
||
对 Secret 只检查存在性和 ESO 状态。
|
||
|
||
## 升级与回滚
|
||
|
||
v1alpha1 尚不承诺跨版本转换。升级前备份 CR、PostgreSQL registry 和 OpenBao metadata，
|
||
先在隔离 Kind 环境运行 E2E。禁止在同一组 CR 上同时运行两个 controller 版本。若新版本
|
||
在执行任何破坏性迁移前失败，可回滚镜像；涉及 API/storage 或 registry schema 迁移时，
|
||
必须先写独立升级规格和回滚步骤。
|
||
|
||
## 上线验证
|
||
|
||
```text
|
||
PostgreSQL TLS 与备份验证
|
||
-> OpenBao auth/policy 验证
|
||
-> ClusterSecretStore Ready
|
||
-> controller Ready/leader elected
|
||
-> Instance Ready
|
||
-> 测试 Tenant Ready
|
||
-> DNS host 与 IP hostaddr 分别登录
|
||
-> 删除测试 Tenant 并验证所选策略
|
||
```
|
||
|
||
生产 homelab 上线前还必须完成 [`security.md`](security.md) 的权限检查和
|
||
[`operations.md`](operations.md) 的备份/逃生检查。
|