Agones项目Kubernetes支持版本升级至1.28/1.29/1.30的技术实践

背景与目标

作为专为游戏服务器设计的Kubernetes原生框架，Agones始终保持着与上游Kubernetes版本的紧密同步。本次技术升级的核心目标是将Agones的Kubernetes支持范围扩展到1.28、1.29和1.30三个版本，同时确保系统在各环境中的稳定运行。这一升级涉及基础设施、工具链、API兼容性等多个维度的协同调整。

核心升级内容

1. 基础设施层适配

集群版本统一化：所有示例集群（包括GKE、AKS、EKS）均升级至1.29版本作为基准。值得注意的是：

• GKE Autopilot模式同样遵循Rapid通道的默认版本策略
• 多云支持方面，AKS和EKS选取各自平台支持的最新稳定版本
• 本地开发环境（Minikube/Kind）同步升级至1.29的最新补丁版本

Terraform模块重构：对install/terraform/modules下的所有基础设施代码进行版本声明更新，确保CI/CD流水线能够正确构建目标版本的测试环境。

2. 开发工具链升级

关键组件版本锁定：

• kubectl工具统一升级至1.29最新补丁版
• Helm pre-delete钩子中的kubectl镜像同步更新
• 构建镜像（build-image/e2e-image）内的工具链版本对齐

客户端库更新：

• 通过go mod将client-go和apiextensions-apiserver升级至1.29对应版本
• 执行完整的vendor依赖更新流程（go mod tidy/vendor）

3. API与代码生成

CRD文档体系重构：

• 更新site/assets/templates/crd-doc-config.json中的API引用链接
• 重新生成所有API参考文档（make gen-api-docs）
• 刷新CRD客户端代码（make gen-crd-code）

嵌入式资源更新：

• 基于1.29集群环境重新生成OpenAPI规范
• 更新安装模板中的Kubernetes资源定义（make gen-install）

4. 文档与配置同步

版本声明统一维护在site/config.toml中，包括：

• 开发环境支持的Kubernetes版本范围（1.28-1.30）
• 各云平台示例集群的推荐版本
• API参考文档的基准版本

关键技术挑战

gRPC依赖传导：当client-go升级引入新版gRPC时，需要同步更新：

• 所有SDK的gRPC基础镜像版本
• C++示例项目的依赖声明
• 重新生成所有语言的gRPC桩代码（约20分钟完整构建周期）

测试矩阵维护：

• E2E测试集群采用版本轮换策略，在us-east1等四个区域分别部署不同版本
• 性能测试集群固定使用us-central1区域的1.29集群
• 通过terraform模块实现集群版本的自动化管理

版本过渡策略：

1. 先添加新版本测试集群并验证通过
2. 更新CI配置启用新版本测试
3. 确认稳定后下线最旧版本支持
4. 同步更新性能测试基础设施

最佳实践建议

对于基于Agones进行二次开发的团队，建议：

1. 在升级前充分测试自定义控制器与1.29 API的兼容性
2. 关注client-go的breaking changes（如废弃API的移除）
3. 开发环境建议使用Kind 1.29集群进行本地验证
4. 生产环境采用渐进式升级策略，先测试节点再控制平面

总结

本次版本升级通过系统化的工程实践，确保了Agones在多Kubernetes版本上的兼容性。特别值得注意的是对gRPC依赖链的精细管理，以及通过基础设施即代码实现的测试环境版本控制。这些经验对于任何基于Kubernetes的Operator开发都具有参考价值，展示了如何在大版本升级过程中保持系统稳定性。