Holos平台Zitadel服务ExternalDomain变更操作指南

Holos平台Zitadel服务ExternalDomain变更操作指南

背景说明

在Holos平台部署中，Zitadel作为核心的身份认证与访问管理(IAM)组件，其ExternalDomain配置是系统初始化阶段的关键参数。该参数一旦设定后，若需变更将直接影响整个IAM服务的正常运行，导致出现"Instance not found"等错误。

变更影响

修改ExternalDomain会导致以下问题：

1. 现有身份认证会话失效
2. OAuth/OIDC客户端配置中断
3. 系统API访问权限异常
4. 用户登录流程故障

完整操作流程

准备工作

1. 确保拥有集群管理员权限
2. 准备新的域名SSL证书
3. 通知所有用户服务维护窗口期

执行步骤

1. 暂停相关资源同步

flux suspend ks prod-iam-crdb prod-iam-zitadel

2. 停止运行中的服务

kubectl scale statefulset crdb --replicas 0
kubectl scale deployment zitadel --replicas 0

3. 清理持久化数据

kubectl delete pvc datadir-crdb-{0,1,2}
kubectl delete job crdb-init zitadel-init zitadel-setup

4. 强制应用新配置

kubectl apply --server-side=true -f deploy/clusters/k2/components/prod-iam-crdb/prod-iam-crdb.gen.yaml --force-conflicts
kubectl apply --server-side=true -f deploy/clusters/k2/components/prod-iam-zitadel/prod-iam-zitadel.gen.yaml --force-conflicts

5. 初始化验证 使用默认管理员账户登录新域名：

• 用户名：zitadel-admin@zitadel.[新域名]
• 初始密码：Password1!

注意事项

1. 此操作会导致所有现有IAM数据丢失，需提前备份关键配置
2. 变更后需要更新所有应用的OAuth客户端配置
3. 建议在低峰期执行此操作
4. 操作完成后需重新配置所有集成系统

最佳实践建议

1. 初始部署时仔细规划域名策略
2. 建立域名变更的应急预案
3. 考虑使用泛域名证书简化后续维护
4. 对关键操作进行完整的预演测试

通过遵循本指南，可以确保Zitadel服务的ExternalDomain变更操作安全可靠地完成，最小化对生产环境的影响。