从 CHANGELOG 看 terraform-aws-eks 模块演进v21 系列功能全景与升级实战指南【免费下载链接】terraform-aws-eksTerraform module to create Amazon Elastic Kubernetes (EKS) resources 项目地址: https://gitcode.com/GitHub_Trending/te/terraform-aws-eksterraform-aws-eks 是 Terraform 社区中用于创建 Amazon EKSKubernetes资源的开源模块本文以仓库根目录下的 CHANGELOG.md 为骨架梳理该模块从 v11 到 v21 的完整演进脉络重点解读当前 v21 系列的核心功能EKS Auto Mode、Provisioned Control Plane、EKS Capabilities、Hybrid Nodes、Karpenter 子模块等以及每次主版本升级背后的破坏性变更。读完本文你将掌握如何依据版本变更记录评估升级影响、如何结合 main.tf 与 versions.tf 验证功能实现以及如何安全地从 v20 升级到 v21。一、版本现状与发布节奏截至 CHANGELOG 记录的最新版本该模块当前处于v21.24.12026-07-31 发布上一个功能版本 v21.24.0 发布于 2026-06-24。CHANGELOG 完整记录了从 v11.0.02020-03-31到 v21.24.1 的全部版本节点跨度六年是观察该模块设计理念变化的一手资料。从发布频率看v21 系列保持着月度功能发布 不定期补丁修复的节奏例如2026 年 5 月一个月内连续发布 v21.22.0、v21.21.0、v21.20.0、v21.19.1 等多个版本部分版本在同一天发布多个如 v21.1.1、v21.1.2、v21.1.3 均发布于 2025-08-24说明团队在收到 issue 反馈后能够快速出补丁。版本号遵循语义化版本SemVer规范主版本号变更如 v20 → v21意味着存在破坏性变更BREAKING CHANGES在 CHANGELOG 中会以⚠ BREAKING CHANGES标记次版本号增加代表新增功能补丁版本号增加代表 bug 修复。二、v21 主版本一次全面的接口重构2.1 版本门槛升级v21.0.02025-07-23是 v21 系列的起点其破坏性变更核心是最低 Terraform 版本提升到1.5.7最低 AWS provider 版本提升到6.0对应地TLS provider 最低版本提升到v4.0.0这与仓库 versions.tf 中的声明一致required_version 1.5.7aws 6.52——后者在 v21 系列后续版本中进一步抬高。升级到 v21 之前务必先确认本地 Terraform CLI 与 AWS provider 满足上述最低要求。2.2 变量命名全面去前缀化v21.0.0 的升级文档 docs/UPGRADE-21.0.md 列出了大量重命名核心思路是去除变量名中冗余的cluster_前缀与 AWS 底层 API 对齐v20 旧变量名v21 新变量名cluster_namenamecluster_versionkubernetes_versioncluster_enabled_log_typesenabled_log_typescluster_compute_configcompute_configcluster_encryption_configencryption_configcluster_endpoint_private_accessendpoint_private_accesscluster_addonsaddonscluster_identity_providersidentity_providerscluster_security_group_idsecurity_group_idcluster_timeoutstimeouts升级时若沿用旧变量名terraform plan会报未声明变量错误因此需要配合terraform state mv或直接修改配置后重新规划。完整的重命名清单请查阅 docs/UPGRADE-21.0.md。2.3 aws-auth 的彻底退出与访问入口接管这是模块历史上最重要的架构决策之一跨越了两个主版本v20.0.0用 EKS 集群访问入口cluster access entry替换aws-authConfigMap 的使用见 CHANGELOG v20.0.0 条目并将aws-auth相关资源移入独立子模块v21.0.0彻底删除aws-auth子模块默认认证模式为API_AND_CONFIG_MAP全面转向 EKS 访问管理CAMAPI。在 main.tf 中可以看到bootstrap_cluster_creator_admin_permissions被硬编码为false因为该设置是集群创建时的一次性操作、之后无法通过 API 修改。模块改用enable_cluster_creator_admin_permissions变量通过访问入口在任意时刻授予/回收管理员权限——这正是 CHANGELOG 中反复出现的以访问入口替代 aws-auth设计理念的落地实现。2.4 addons 默认行为的收紧v21 对 EKS addons 的两个默认值做了安全取向的调整见 docs/UPGRADE-21.0.mdresolve_conflicts_on_create默认值从OVERWRITE改为NONE创建时不自动覆盖冲突配置避免意外篡改most_recent默认值从false改为true默认跟随 addon 最新可用版本同时 docs/UPGRADE-20.0.md 记录了resolve_conflicts被拆分为resolve_conflicts_on_create/resolve_conflicts_on_update两个参数的演进过程。这些变更共同降低了模块对集群现有配置的过度干预让用户对 addon 版本拥有更明确的控制权。三、v21 系列的新功能亮点源码级验证3.1 EKS Auto Mode 支持CHANGELOG v20.31.02024-12-04首次加入 EKS Auto Mode 支持此后经历了大量迭代修正v20.31.1 ~ v20.31.6、v21.3.2 等版本修复了启用/禁用 Auto Mode 时的 IAM 角色创建、自定义节点池、集群替换等问题v21.3.0 支持仅创建自定义节点池custom node pools onlyv20.33.1 允许 Auto Mode 自定义节点池使用EC2访问入口类型v21.16.0 曾为 Auto Mode 节点 IAM 角色增加 ECR Public 权限v21.16.1 又因问题 #3665 回退该变更——这提醒我们Auto Mode 的 IAM 权限边界仍在持续打磨中。在 main.tf 中compute_config动态块将node_pools、node_role_arn透传给aws_eks_cluster其中node_role_arn会优先取模块创建的aws_iam_role.eks_auto[0].arn。配置示例可参考 examples/eks-auto-mode/main.tf其中展示了两个典型场景使用内置节点池compute_config { enabled true, node_pools [general-purpose] }仅创建 IAM 资源供自定义节点池使用create_auto_mode_iam_resources truecompute_config { enabled true }注意由于 EKS Auto Mode API 的限制禁用 Auto Mode 时必须显式设置compute_config { enabled false }并执行一次 apply单纯移除compute_config块无法完成禁用见 README.md 中的 CAUTION 提示。3.2 EKS Provisioned Control Planev21.10.02025-11-27新增 Provisioned Control Plane 支持用于为更大规模工作负载提供更高容量的控制平面。合法 tier 取值为standard、tier-xl、tier-2xl、tier-4xl、tier-8xl。在 main.tf 中对应control_plane_scaling_config动态块control_plane_scaling_config { tier tier-xl }3.3 EKS Capabilitiesv21.13.02026-01-13新增 EKS Capabilities 支持。仓库为此提供了独立的 examples/eks-capabilities 示例目录读者可结合实际场景参考。3.4 EKS Hybrid Nodes混合节点v20.31.0 与 Auto Mode 同批引入 EKS Hybrid Nodes 支持v21.11.02026-01-05更新了 Hybrid Node IAM 角色权限。Hybrid Nodes 允许将本地on-premises服务器通过 SSM 或 IAM Roles Anywhere 接入 EKS 集群仓库中 modules/hybrid-node-role 子模块专门负责创建对应的 IAM 角色完整示例见 examples/eks-hybrid-nodes。配置要点包括remote_network_config声明远端节点/ Pod 网络 CIDRaccess_entries中以type HYBRID_LINUX注册混合节点角色通过security_group_additional_rules放行本地网络的混合流量。3.5 Karpenter 子模块的持续进化Karpenter 是 CHANGELOG 中出现频率最高的关键词之一其演进脉络清晰反映了 Karpenter 上游项目的发展v18.31.02022-11-21新增 Karpenter 子模块v19.18.02023-11-01支持 Karpenter v1beta1v20.24.02024-08-19支持 Karpenter v1 控制器 IAM 角色权限v20.10.02024-05-09支持 Pod Identity 关联v21.0.0移除 IRSA 原生支持EKS Pod Identity 默认启用create_pod_identity_association默认true移除 Karpenter v1 之前的旧控制器策略v21.2.0、v21.3.1与上游同步控制器策略与权限v21.18.0、v21.19.02026-04分别升级支持 Karpenter v1.11、v1.12v21.8.02025-10-27允许对控制器角色使用内联策略以规避策略大小LimitExceeded错误v21.20.02026-05-06为 Karpenter 节点 IAM 角色信任策略增加可选的aws:SourceAccount条件。子模块当前的能力矩阵创建 IAM 控制器角色、Pod Identity 关联、节点 IAM 角色、访问入口、SQS 队列与 EventBridge 规则见 modules/karpenter/README.md其中还展示了复用现有节点 IAM 角色create_node_iam_role false与跳过访问入口创建create_access_entry false等进阶用法。3.6 其他值得关注的能力Deletion Protectionv21.1.0集群删除保护对应变量deletion_protectionControl Plane Egress Modev21.24.0支持control_plane_egress_modeAWS_MANAGED/CUSTOMER_ROUTED透传至 main.tf 的vpc_configAddonnamespace_configv21.21.0为 EKS addon 指定命名空间配置node repair 配置v20.33.0、v21.9.0托管节点组与集群级别的节点修复参数max_parallel_nodes_repaired_count、node_repair_config_overrides等update_config.update_strategyv21.14.0托管节点组更新策略AL2023 与加速型 AMI 扩展v20.37.0、v20.25.0、v21.17.0AL2023 ARM64 NVIDIA、Bottlerocket FIPS、Windows 2025 AMI 等EFA 支持增强v20.4.0、v20.28.0、v21.23.0EFA 资源、efa-only网络接口、嵌套虚拟化与network_performance_options。四、如何解读破坏性变更并规划升级4.1 主版本升级的通用方法先读 CHANGELOG 中该主版本的 BREAKING CHANGES 段逐条对照自己的配置是否命中再读对应版本号的升级指南本仓库为每个主版本都保留了独立文档docs/UPGRADE-19.0.md、docs/UPGRADE-20.0.md、docs/UPGRADE-21.0.md确认最低版本门槛Terraform 与 AWS provider 版本可对照 versions.tf在非生产环境先行验证重点观察terraform plan中标记为替换replace的资源。4.2 升级中容易踩的坑来自 CHANGELOG 与升级文档命名冲突与资源替换v21 大量变量重命名配合state mv可避免资源重建例如cluster_security_group_*系列重命名为security_group_*加密配置语义变化v21 中若想用自定义 KMS 密钥禁用 Secret 加密需设置encryption_config nullv20 是{}由于 EKS 已默认对 Secret 静态加密禁用行为已被 AWS 托管见 docs/UPGRADE-21.0.mdEFA 与 placement group 行为变化v21 起enable_efa_support只在节点组层级生效模块不再自动挑选可用区用户必须显式指定正确的subnet_ids见 docs/UPGRADE-21.0.md 的 Before/After 示例节点组默认值收紧IMDS hop limit 从 2 降到 1、ami_type默认AL2023_x86_64_STANDARD、enable_monitoring默认false、use_latest_ami_release_version默认true这些都会在升级后产生 plan 差异cluster_identity_providers.issuer_url变为必填此前不正确的默认值已移除关联 Kubernetes 上游 PR升级 v21 后必须显式提供。4.3 旧版本用户如何过渡CHANGELOG 明确提示仍依赖aws-auth子模块的用户可以固定v20.x版本约束version ~ v20.0继续使用。同理若你的环境暂时无法满足 AWS provider 6.52与 Terraform 1.5.7的要求v20 系列仍是可用的过渡版本。五、从历史变更看模块的设计哲学梳理 CHANGELOG 六年记录可以归纳出几条清晰的演进主线拥抱 AWS 原生能力而非自造轮子从aws-authConfigMap 迁移到 cluster access entry、从 IRSA 转向 Pod Identity、从自管理 addons 转向 EKS addons APIbootstrap_self_managed_addons在 v21 被硬编码为false并忽略避免集群重建最小权限与安全默认endpoint 默认私有访问v19 起endpoint_public_access默认false、IMDSv2、hop limit 收紧、resolve_conflicts_on_create默认NONE类型化与可维护性v21 将大量any类型变量改为详细的object类型定义见 README.md 中 Inputs 表格在 plan 阶段即可暴露配置错误数据源查询通过新增partition、account_id变量减少 API 调用紧跟上游生态Karpenter 版本从 v0.x 到 v1.12 的同步、AL2023/Bottlerocket/Windows 多种 OS 变体的持续扩充、EFA 与高性能计算场景的深耕ML capacity block、efa-only、network_performance_options。六、结语与跟进建议CHANGELOG 是理解 terraform-aws-eks 模块最直接、最权威的入口。建议开发者在每次升级前完整阅读目标版本的 CHANGELOG 条目与对应的 docs/UPGRADE-*.md 升级指南结合 main.tf、node_groups.tf 与各子模块modules/eks-managed-node-group、modules/self-managed-node-group、modules/fargate-profile、modules/karpenter、modules/hybrid-node-role核对变量透传与默认值参考 examples 下的六个官方示例Auto Mode、Capabilities、Hybrid Nodes、Managed Node Group、Karpenter、Self-Managed Node Group进行对标验证。本模块遵循语义化版本管理破坏性变更全部集中在主版本号变更中只要按上述流程执行升级路径是清晰且可控的。【免费下载链接】terraform-aws-eksTerraform module to create Amazon Elastic Kubernetes (EKS) resources 项目地址: https://gitcode.com/GitHub_Trending/te/terraform-aws-eks创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考