企业官网建设流程全解析

从 CHANGELOG 看 terraform-aws-eks 模块演进：v21 系列功能全景与升级实战指南

【免费下载链接】terraform-aws-eksTerraform module to create Amazon Elastic Kubernetes (EKS) resources 🇺🇦项目地址: https://gitcode.com/GitHub_Trending/te/terraform-aws-eks

terraform-aws-eks 是 Terraform 社区中用于创建 Amazon EKS（Kubernetes）资源的开源模块，本文以仓库根目录下的 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.1（2026-07-31 发布），上一个功能版本 v21.24.0 发布于 2026-06-24。CHANGELOG 完整记录了从 v11.0.0（2020-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.0（2025-07-23）是 v21 系列的起点，其破坏性变更核心是：

• 最低 Terraform 版本提升到1.5.7
• 最低 AWS provider 版本提升到6.0
• 对应地，TLS provider 最低版本提升到v4.0.0

这与仓库 versions.tf 中的声明一致（required_version = ">= 1.5.7"，aws >= 6.52——后者在 v21 系列后续版本中进一步抬高）。升级到 v21 之前，务必先确认本地 Terraform CLI 与 AWS provider 满足上述最低要求。

2.2 变量命名全面去前缀化

v21.0.0 的升级文档 docs/UPGRADE-21.0.md 列出了大量重命名，核心思路是去除变量名中冗余的cluster_前缀，与 AWS 底层 API 对齐：

升级时若沿用旧变量名，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 访问管理（CAM）API。

在 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.md）：

• resolve_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.0（2024-12-04）首次加入 EKS Auto Mode 支持，此后经历了大量迭代修正：

• v20.31.1 ~ v20.31.6、v21.3.2 等版本修复了启用/禁用 Auto Mode 时的 IAM 角色创建、自定义节点池、集群替换等问题；
• v21.3.0 支持"仅创建自定义节点池（custom node pools only）"；
• v20.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 = true+compute_config = { enabled = true }

注意：由于 EKS Auto Mode API 的限制，禁用 Auto Mode 时必须显式设置compute_config = { enabled = false }并执行一次 apply，单纯移除compute_config块无法完成禁用（见 README.md 中的 CAUTION 提示）。

3.2 EKS Provisioned Control Plane

v21.10.0（2025-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 Capabilities

v21.13.0（2026-01-13）新增 EKS Capabilities 支持。仓库为此提供了独立的 examples/eks-capabilities 示例目录，读者可结合实际场景参考。

3.4 EKS Hybrid Nodes（混合节点）

v20.31.0 与 Auto Mode 同批引入 EKS Hybrid Nodes 支持，v21.11.0（2026-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 网络 CIDR；
• access_entries中以type = "HYBRID_LINUX"注册混合节点角色；
• 通过security_group_additional_rules放行本地网络的混合流量。

3.5 Karpenter 子模块的持续进化

Karpenter 是 CHANGELOG 中出现频率最高的关键词之一，其演进脉络清晰反映了 Karpenter 上游项目的发展：

• v18.31.0（2022-11-21）：新增 Karpenter 子模块；
• v19.18.0（2023-11-01）：支持 Karpenter v1beta1；
• v20.24.0（2024-08-19）：支持 Karpenter v1 控制器 IAM 角色权限；
• v20.10.0（2024-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.0（2026-04）：分别升级支持 Karpenter v1.11、v1.12；
• v21.8.0（2025-10-27）：允许对控制器角色使用内联策略，以规避策略大小LimitExceeded错误；
• v21.20.0（2026-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 Protection（v21.1.0）：集群删除保护，对应变量deletion_protection；
• Control Plane Egress Mode（v21.24.0）：支持control_plane_egress_mode（AWS_MANAGED/CUSTOMER_ROUTED），透传至 main.tf 的vpc_config；
• Addonnamespace_config（v21.21.0）：为 EKS addon 指定命名空间配置；
• node repair 配置（v20.33.0、v21.9.0）：托管节点组与集群级别的节点修复参数（max_parallel_nodes_repaired_count、node_repair_config_overrides等）；
• update_config.update_strategy（v21.14.0）：托管节点组更新策略；
• AL2023 与加速型 AMI 扩展（v20.37.0、v20.25.0、v21.17.0）：AL2023 ARM64 NVIDIA、Bottlerocket FIPS、Windows 2025 AMI 等；
• EFA 支持增强（v20.4.0、v20.28.0、v21.23.0）：EFA 资源、efa-only网络接口、嵌套虚拟化与network_performance_options。

四、如何解读破坏性变更并规划升级

4.1 主版本升级的通用方法

1. 先读 CHANGELOG 中该主版本的 BREAKING CHANGES 段，逐条对照自己的配置是否命中；
2. 再读对应版本号的升级指南，本仓库为每个主版本都保留了独立文档：docs/UPGRADE-19.0.md、docs/UPGRADE-20.0.md、docs/UPGRADE-21.0.md；
3. 确认最低版本门槛：Terraform 与 AWS provider 版本（可对照 versions.tf）；
4. 在非生产环境先行验证，重点观察terraform plan中标记为"替换（replace）"的资源。

4.2 升级中容易踩的坑（来自 CHANGELOG 与升级文档）

• 命名冲突与资源替换：v21 大量变量重命名，配合state mv可避免资源重建；例如cluster_security_group_*系列重命名为security_group_*；
• 加密配置语义变化：v21 中若想用自定义 KMS 密钥禁用 Secret 加密，需设置encryption_config = null（v20 是{}）；由于 EKS 已默认对 Secret 静态加密，禁用行为已被 AWS 托管，见 docs/UPGRADE-21.0.md；
• EFA 与 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 六年记录，可以归纳出几条清晰的演进主线：

1. 拥抱 AWS 原生能力而非自造轮子：从aws-authConfigMap 迁移到 cluster access entry、从 IRSA 转向 Pod Identity、从自管理 addons 转向 EKS addons API（bootstrap_self_managed_addons在 v21 被硬编码为false并忽略，避免集群重建）；
2. 最小权限与安全默认：endpoint 默认私有访问（v19 起endpoint_public_access默认false）、IMDSv2、hop limit 收紧、resolve_conflicts_on_create默认NONE；
3. 类型化与可维护性：v21 将大量any类型变量改为详细的object类型定义（见 README.md 中 Inputs 表格），在 plan 阶段即可暴露配置错误；数据源查询通过新增partition、account_id变量减少 API 调用；
4. 紧跟上游生态：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