CRD、Operator、Webhook 与 Finalizer 运维
验证：未记录
- 适用版本
- 未记录
- 验证范围
- 尚未登记验证记录。
本文缩写（英文全称与中文含义）
| 缩写 | 英文全称／名称 | 中文含义 |
|---|---|---|
| API | Application Programming Interface | 应用程序编程接口 |
| CR | Custom Resource | Kubernetes 自定义资源对象 |
| CRD | Custom Resource Definition | Kubernetes 自定义资源定义 |
| DNS | Domain Name System | 域名系统 |
| GitOps | GitOps | 以 Git 保存期望状态、由自动化持续协调实际状态的运维方式 |
| LB | Load Balancer | 负载均衡器 |
| RBAC | Role-Based Access Control | 基于角色的访问控制 |
| SAN | Subject Alternative Name | 证书主题备用名称，用于声明域名或 IP |
| YAML | YAML Ain’t Markup Language | 常用于配置文件的数据序列化语言 |
前置：实践约定、已安装的 cert-manager 或其他企业 Operator。先选定一套 Operator 演练，不在同一次变更中升级多个控制器。
1. 盘点所有者与可恢复状态#
以 cert-manager 为例：
kubectl get crd certificates.cert-manager.io -o json | jq '{versions:.spec.versions,storedVersions:.status.storedVersions}'
kubectl -n cert-manager get deploy,pods
kubectl get validatingwebhookconfigurations,mutatingwebhookconfigurations
kubectl -n orders get certificates,certificaterequests
kubectl -n cert-manager logs deployment/cert-manager --since=15m记录 Helm/GitOps 管理者、release、CRD schema、conversion webhook、RBAC、证书、Secret 引用、CR 实例和外部资源。CR 备份可能含敏感配置，限制存储。CRD 删除会连同自定义资源一起删除，不是卸载插件的普通前置步骤。
2. 有序升级#
- 从固定目标 release 获取官方 CRD、controller 和升级说明，检查跨版本支持和存储转换。cert-manager 示例下载命令如下，必须与计划升级的 controller/Chart 对齐：
export CERT_MANAGER_VERSION='vREPLACE_VERSION'
curl -fsSL "https://github.com/cert-manager/cert-manager/releases/download/$CERT_MANAGER_VERSION/cert-manager.crds.yaml" -o reviewed-crds.yaml- 在隔离集群恢复脱敏 CR，先验证新旧 schema 能处理现有对象；只查 YAML apiVersion 不够。
- 按供应商规定顺序升级。需新 conversion webhook 的版本先部署能同时服务新旧版本的 webhook，再增加/切换 CRD 版本；不能通用套用“永远先 CRD”。
- 对已审核 CRD 做 diff/server dry-run，再由唯一所有者应用：
kubectl diff -f reviewed-crds.yaml
kubectl apply --server-side --dry-run=server -f reviewed-crds.yaml
# reviewed-crds.yaml 来自固定 release；确认 diff 后按 GitOps/Helm 既有所有权更新。
kubectl -n cert-manager rollout status deployment/cert-manager --timeout=5m
kubectl -n cert-manager rollout status deployment/cert-manager-webhook --timeout=5mkubectl diff 返回 1 表示有差异；不要误判为工具异常。Helm 的 CRD 安装目录并不保证自动升级/删除 CRD，按具体 chart 的管理策略确认。
3. 存储版本迁移#
以自定义资源 widgets.platform.example.com 为例，只有实际拥有该 CRD 的团队执行：
export CRD='widgets.platform.example.com'
kubectl get crd "$CRD" -o json | jq '{served:[.spec.versions[]|{name,served,storage}],stored:.status.storedVersions}'先保证旧版本 served、新版本 served 且转换可用→将新版本 storage=true→使用该 Kubernetes 版本支持的 Storage Version Migrator 或受控逐对象 read/update 重写→统计全部对象成功且冲突重试完毕→才更新 storedVersions 并移除旧 served/schema。修改 status 列表本身不会重写 etcd 中对象。每阶段做旧/新 API 读写与字段保留测试；保存数据迁移前备份。
4. Webhook 不可用演练#
不要直接关闭生产 webhook。在隔离集群选择已备份配置的测试 webhook：
kubectl get validatingwebhookconfiguration REPLACE_NAME -o yaml
kubectl -n REPLACE_NAMESPACE get svc,endpointslices,pods
kubectl -n REPLACE_NAMESPACE logs deployment/REPLACE_WEBHOOK --since=10m核对 API Server→Service/Pod 防火墙、caBundle 与证书 SAN、过期时间、timeoutSeconds、failurePolicy、namespaceSelector。隔离环境短暂停止测试 webhook 后创建一个匹配资源，记录 Fail 策略下拒绝行为；立即恢复副本/网络并确认创建成功。
恢复优先修 endpoint/证书/控制器；临时 Ignore 会绕过安全策略，只在已定义的应急边界、限时且有审计时使用，恢复后补扫期间创建的对象。
5. Finalizer 卡死与卸载#
kubectl -n orders get certificate REPLACE_CERT -o json | jq '{deletionTimestamp:.metadata.deletionTimestamp,finalizers:.metadata.finalizers,conditions:.status.conditions}'先恢复负责清理的控制器和权限→确认外部证书/DNS/LB/卷的状态→完成清理或明确保留接管→才精确删除阻塞 finalizer。禁止对所有对象 patch finalizers: []。卸载顺序：迁业务→清理 CR→确认外部资源→移除 webhook/controller→最后评审是否删除 CRD。
验收：已有 CR 持续收敛、新 CR 可创建、conversion 双向可读、外部资源无孤儿、升级失败可恢复兼容控制器。schema/数据已不可逆迁移时不承诺 helm rollback 自动恢复。