panxiao81/postgresql-tenant-operator

Fork 0

Files

T

panxiao81 a723372c6e

docs: 完善 v1alpha1 设计与运维合同

2026-09-10 05:23:33 +00:00

5.2 KiB

Raw Permalink Blame History

现有数据库迁移 Runbook

项目	内容
状态	Review；尚未在临时 PostgreSQL 演练
适用范围	任意既有数据库迁移为新建 v1alpha1 Tenant
最后更新	2026-09-10

v1alpha1 不接管现有 database、role 或 OpenBao record。本流程通过逻辑 dump/restore 把数据迁移到 controller 创建的新资源，保留旧资源作为限时回滚点。

以下命令是顺序模板，不可原样复制到真实环境。先把尖括号变量解析成明确值，确认当前连接目标，再逐条执行。dump 可能包含敏感业务数据，必须放在加密临时存储且不得提交 Git。

前置条件

已验证 PostgreSQL/OpenBao 备份和恢复；记录恢复点。
Instance 已 Ready，目标 namespace 存在，ESO ClusterSecretStore Ready。
最终 database/login role 当前由旧应用占用，但改名后的保留名称、新推导的 Bao path 均不存在。
已记录旧 database owner、grants、extensions、locale/encoding、连接配置和验证清单。
已确认应用可停止写入，并确定回滚窗口和负责人。
已确认旧 login role 不被其他 database/应用共享，且角色改名不会破坏未纳入本次维护的依赖。

迁移顺序

1. 盘点与预演

pg_dump --schema-only --no-owner --no-privileges \
  --dbname='<old-admin-connection>' > schema-preview.sql

检查不受 v1alpha1 管理的对象：额外 roles、跨库依赖、FDW、large objects、订阅、显式 tablespace、owner/grant 和不在 allowlist 的 extension。无法映射为单 database + 单 login owner 的环境必须先人工简化，不能让 controller 猜测。

2. 创建一致性 dump

停止应用写入并确认活跃写事务结束，然后创建最终 custom-format dump：

pg_dump --format=custom --no-owner --no-privileges \
  --file='<secure-temp>/tenant.dump' \
  --dbname='<old-admin-connection>'
pg_restore --list '<secure-temp>/tenant.dump'

不要删除旧 database/role。记录停写时间、dump checksum 和 PostgreSQL 版本。

3. 释放最终名称

保持应用停写，终止旧 database 的应用连接。连接其他管理 database，以管理员身份把旧 database 和旧 login role 改为明确的保留名称：

ALTER DATABASE <old_database> RENAME TO <old_database>_retained_<timestamp>;
ALTER ROLE <old_login_role> RENAME TO <old_login_role>_retained_<timestamp>;

identifier 必须由管理员工具安全引用，不能把未经校验的值直接拼入 SQL。PostgreSQL 在角色改名时会清除以旧角色名加盐的 MD5 密码；使用 MD5 的旧环境必须在维护前准备安全的密码重设/回滚方法。SCRAM verifier 不受角色名改动影响，但仍须实际验证回滚登录。

4. 创建受管空目标

应用 PostgreSQLTenant，使用未被占用的 database/loginRole，等待 Ready。确认：

registry 记录 UID 正确；
OpenBao metadata 属于该 Tenant；
ExternalSecret Ready 且目标 Secret 已投射；
新凭据可以通过 DNS host 和 IP hostaddr 分别登录空 database。

5. Restore

从 OpenBao 或目标 Secret 安全取得新应用凭据，不要把密码放进 shell history。以新 login owner 连接目标 database：

pg_restore --exit-on-error --no-owner --no-privileges \
  --dbname='<new-application-connection>' \
  '<secure-temp>/tenant.dump'

extension 应由 Tenant spec 创建。若 dump 仍包含 extension 定义，预演必须确认 restore 行为幂等；不在 allowlist 的 extension 必须在迁移前解决。

6. 验证并切换

对比关键 schema、表数、行数/校验和、sequence、function 和 migration version。
用新 login 验证读写、migration 和应用健康检查。
将应用配置切换到新 Secret 或 OpenBao URL，保持旧数据库只读/停写。
观察一个约定窗口，确认错误率、连接数和关键业务功能。

7. 收尾

回滚窗口结束后，按独立变更删除旧 database/role/旧凭据；它们不属于 controller，禁止通过 Tenant Delete 清理。安全删除 dump 和临时凭据材料，并记录验证结果。

回滚

在新目标出现问题且旧资源仍保留时：

立即停止新目标写入。
评估切换后是否产生新数据；若有，先决定反向迁移或接受丢弃，不能盲目切回。
将应用连接切回 retained database/role；若必须恢复原名称，先确保新受管目标已用 Delete 完整清理或改用不同名称，再安全地反向执行 rename。
恢复旧凭据（MD5 环境可能需要重设），验证旧服务。
保留失败 Tenant 供排障；选择 Retain 或 Delete 前明确其外部资源后果。

若已经删除旧资源，则只能使用已验证备份恢复，不再属于本 runbook 的快速回滚。

演练验收

发布首个可用版本前，必须在临时 PostgreSQL/OpenBao/Kind 环境执行本文并记录：

使用的 PostgreSQL major version 和命令版本；
dump/restore 返回码和对象差异；
DNS/IP TLS 登录结果；
ESO 投射与应用启动结果；
回滚演练结果；
哪些命令或前置检查需要修订。

完成演练前，本文不得标记为 Verified。

5.2 KiB Raw Permalink Blame History Unescape Escape