Rancher 如何将 Active Directory principalID 从 GUID 反向迁移回 DN？
【免费下载链接】rancherComplete container management platform项目地址: https://gitcode.com/GitHub_Trending/ra/rancher
Rancher 2.7.5 曾把 Active Directory（AD）用户的 principalID 从 DN（distinguished name）迁移为基于 GUID 的形式，这导致部分用户在 2.7.5 中出现了重复账号、GUID 映射到多个 Rancher 用户、重复用户登录失败等问题。如果你需要把这些 GUID 形式的 principalID 反向迁回 DN 形式，Rancher 仓库自带一个反向迁移工具：cleanup/ad-guid-unmigration.sh，它通过 Rancher Agent 以 Job 形式在集群内执行。本文基于仓库中的 ad-guid-README.md 与 ad-guid-unmigration.sh 说明这条操作路径。
适用前提（来自文档 Requirements 一节）：
- 环境中已配置 Active Directory 作为认证提供方。如果 AD 不是当前认证提供方，工具不会做任何操作并直接退出；
- AD 服务账号（service account）必须有权限读取 Rancher 中已知的所有用户；
- 文档建议该脚本在 Rancher v2.7.6 上使用；在 v2.7.5 上运行可能产生性能问题，且脚本自身会额外提示：若在 v2.7.5 上运行后 Rancher 重启，会撤销该工具的效果。
工具会做什么
运行后，工具会遍历所有 Rancher 用户，用已配置的 AD 服务账号查询每个用户的 DN，再在 Rancher 内部查出该用户的 Tokens、ClusterRoleTemplateBindings（CRTB）、ProjectRoleTemplateBindings（PRTB）和 GlobalRoleBindings（GRB）。凡是引用了 GUID 形式 principalID 的对象（包括用户对象本身）都会被更新为 DN 形式的 principalID。
它还会处理两类残留问题：
- 原始迁移到 GUID 过程中被重复创建的用户：工具会把相关 token 和绑定映射回原用户，再删除误建的较新用户；
- 绑定类对象（CRTB/PRTB/GRB）必须以删除再创建的方式迁移，不能原地更新。这意味着这些绑定会得到新名字，新对象上会带有
ad-guid-previous-name标签，值是被删除对象的旧名字（README 将其描述为 annotation，脚本横幅与源码 adunmigration 实现 实现为 label）。如果你使用 Terraform 这类依赖对象名字的外部状态工具，这一点可能造成影响。
执行前的准备
- 先做备份。README 明确建议在运行该工具前对 Rancher 打快照（take a snapshot），以便需要时恢复。
- 确认版本。脚本在非 dry-run 模式下会执行
kubectl get settings server-version --template='{{.value}}'检查 Rancher 版本；若为 v2.7.5，会打印红色警告并要求交互确认后才继续。 - 准备 kubectl 权限。脚本通过 kubectl 在
cattle-system命名空间创建 ServiceAccount、ClusterRole、ClusterRoleBinding 和 Job，并读取 Job Pod 日志，因此运行脚本的机器必须配置好能访问该 Rancher 集群的 kubeconfig。 - 理解脚本的交互确认。脚本执行前会打印横幅（说明它会删除并重建 CRTB/PRTB/GRB、建议先做 Rancher 备份），并要求回答
Do you want to continue? (y/n)；v2.7.5 环境下还会有一次额外确认。
执行反向迁移
脚本用法（来自 README Usage via Rancher Agent 一节）：
./ad-guid-unmigration.sh <AGENT IMAGE> [--dry-run] [--delete-missing]其中<AGENT IMAGE>需要替换为 Rancher Agent 镜像，文档给出的地址是docker.io/rancher/rancher-agent:v2.7.6。两个可选标志的含义：
--dry-run：只运行迁移逻辑，不修改任何 Rancher 数据；预期变更会以日志信息的形式输出。设置了该标志时，--delete-missing不会生效，用户不会被删除；--delete-missing：删除在 Active Directory 中查不到的 Rancher 用户（按 GUID 查询不到）。这是不可逆的用户删除操作，除非确认环境中存在这类残留用户，否则不建议加上。
建议的操作顺序是先跑一次 dry-run，在日志里核对将要变更的对象，再不带--dry-run正式执行：
# 第一步：预演，不改数据，日志中列出将被变更的对象 ./ad-guid-unmigration.sh docker.io/rancher/rancher-agent:v2.7.6 --dry-run # 第二步：确认日志内容无误后，正式执行 ./ad-guid-unmigration.sh docker.io/rancher/rancher-agent:v2.7.6脚本内部的行为：把上述资源清单（cattle-cleanup-sa、cattle-cleanup-binding、cattle-cleanup-role、cattle-cleanup-job，均带rancher-cleanup: "true"标签）通过kubectl apply提交，Job 容器以agent命令运行，环境变量AD_GUID_CLEANUP=true；--dry-run会追加DRY_RUN=true，--delete-missing会追加AD_DELETE_MISSING_GUID_USERS=true（对应入口逻辑见 cmd/agent/main.go 中对AD_GUID_CLEANUP、DRY_RUN、AD_DELETE_MISSING_GUID_USERS三个环境变量的处理）。提交后脚本轮询找到 Job Pod 并kubectl logs -f跟踪输出，Job 成功结束后脚本会自动kubectl delete掉自己创建的资源。
需要说明的是：正式执行期间 AD 登录会被临时禁用，认证代码在迁移状态为 Running 时对登录返回 "login is disabled while migration is running"（见 activedirectory_provider.go）。迁移完成后恢复。
验证结果
工具会把状态写入cattle-system命名空间中名为ad-guid-migration的 ConfigMap：
kubectl -n cattle-system get configmap ad-guid-migration -o yaml判断依据（README Additional notes 一节）：
- 数据键
ad-guid-migration-status的值为Running表示工具正在运行； - 值为
Finished表示已完成； - 如果运行中断在结束之前，状态会停留在
Running，之后再次运行脚本会立即退出。想让它重新运行，要么编辑该 ConfigMap 删掉这个键，要么整个删除这个 ConfigMap，然后重新执行脚本。
源码中还定义了其余状态值（FinishedWithMissing、FinishedWithSkipped、Failed）以及percentDone、skippedUsers、missingUsers等结果字段（见 migrate.go）。状态为FinishedWithMissing或FinishedWithSkipped时，说明存在 AD 中查不到或连接失败被跳过的用户，此时可以在 Rancher 已重启的前提下再手动运行工具尝试处理；Failed表示执行过程中出错，应回看 Job Pod 日志定位。
超时与手动清理
脚本对日志跟踪设置了约 5 分钟的启动超时（每 0.5 秒计一次，超过 600 次即超时）。超时后脚本会打印手动清理命令，可按原样执行，用于删除本次工具创建的对象：
kubectl --namespace=cattle-system delete serviceaccount,job -l rancher-cleanup=true kubectl delete clusterrole,clusterrolebinding -l rancher-cleanup=true这两条命令只删除带rancher-cleanup=true标签的对象，即本次工具注入的 ServiceAccount、Job、ClusterRole、ClusterRoleBinding，不影响 Rancher 自身资源。若 Job 失败需要排查，可用kubectl --namespace=cattle-system get jobs查看状态。
限制与边界
- 绑定对象迁移后名字会变（删除再创建），依赖绑定名字的外部工具可能受影响，旧名字保存在新对象的
ad-guid-previous-name标签中； - 对非 AD 认证环境，工具不做任何事并退出；
- 文档建议目标版本为 v2.7.6，Agent 镜像也应对应使用
v2.7.6标签；在 v2.7.5 上运行存在性能问题和重启后效果被撤销的风险，脚本会阻止式地提示这一点。
【免费下载链接】rancherComplete container management platform项目地址: https://gitcode.com/GitHub_Trending/ra/rancher
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
