NGINX Ingress Controller 升级过程中CRD版本冲突问题解析与解决方案

在Kubernetes集群中部署和管理NGINX Ingress Controller时，版本升级是一个常见的运维操作。然而，从3.x版本升级到4.0.0版本时，部分用户可能会遇到Custom Resource Definitions（CRD）版本冲突的问题，特别是与GlobalConfiguration和TransportServer这两个CRD相关的报错。

问题现象

当用户尝试通过kubectl apply命令应用v4.0.0的CRD定义文件时，系统会返回如下错误信息：

CustomResourceDefinition.apiextensions.k8s.io "globalconfigurations.k8s.nginx.org" is invalid: status.storedVersions[0]: Invalid value: "v1alpha1": must appear in spec.versions

类似错误也会出现在transportservers.k8s.nginx.org这个CRD上。这表明系统检测到存储版本（storedVersions）中包含了v1alpha1版本，但在新版本的CRD定义中已经不再支持这个API版本。

问题根源

这个问题通常出现在长期维护的Kubernetes集群中，特别是那些从早期版本（如3.3.2之前）逐步升级上来的环境。根本原因在于：

1. 历史版本中同时存在v1alpha1和v1两个API版本
2. 虽然v1alpha1的storage属性被设置为false，但系统仍可能将其记录在storedVersions中
3. 升级到4.0.0版本时，CRD定义完全移除了v1alpha1版本支持
4. Kubernetes的API服务器会验证storedVersions中的所有版本都必须存在于spec.versions中

解决方案

对于不存在v1alpha1资源的集群，可以采用以下修复步骤：

1. 首先更新storedVersions状态，移除v1alpha1记录：

kubectl patch customresourcedefinitions transportservers.k8s.nginx.org \
  --subresource='status' \
  --type='merge' \
  -p '{"status":{"storedVersions": ["v1"]}}'

kubectl patch customresourcedefinitions globalconfigurations.k8s.nginx.org \
  --subresource='status' \
  --type='merge' \
  -p '{"status":{"storedVersions": ["v1"]}}'

2. 然后正常应用v4.0.0的CRD定义：

kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v4.0.0/deploy/crds.yaml

技术背景

Kubernetes的CRD版本管理遵循以下原则：

1. 每个CRD可以定义多个API版本（如v1alpha1、v1beta1、v1等）
2. 其中只能有一个版本的storage属性为true，作为持久化存储的版本
3. storedVersions记录了曾经作为存储版本的所有API版本
4. 当删除一个API版本时，必须确保它不出现在storedVersions中

最佳实践建议

1. 在升级前检查现有CRD状态：

   kubectl get crd <crd-name> -o yaml
   

2. 确认集群中没有使用旧版API的资源：

   kubectl get <resource-type> --all-namespaces
   

3. 对于生产环境，建议先在测试环境验证升级过程

4. 考虑使用Helm的crds子目录功能，让Helm管理CRD生命周期（需评估是否符合你的部署策略）

总结

NGINX Ingress Controller从3.x升级到4.0.0时的CRD版本冲突问题，本质上是Kubernetes API版本管理机制与长期升级路径共同作用的结果。通过理解CRD版本管理原理，并按照正确的步骤操作，可以顺利解决这一问题。对于运维团队来说，掌握这些底层机制不仅有助于解决当前问题，也能为未来的版本升级积累宝贵经验。