Terraform AWS Provider 6.56.0 版本解读：ElastiCache 服务更新 Action、S3 桶列表数据源与三个新 List Resource 全解析

Terraform AWS Provider 6.56.0 版本解读：ElastiCache 服务更新 Action、S3 桶列表数据源与三个新 List Resource 全解析

【免费下载链接】terraform-provider-awsThe AWS Provider enables Terraform to manage AWS resources.项目地址: https://gitcode.com/GitHub_Trending/te/terraform-provider-aws

本篇文章以 HashiCorp 官方发布的 Terraform AWS Provider 6.56.0 版本变更记录为核心，逐一拆解该版本新增的 Action、数据源、List Resource 以及若干关键增强与缺陷修复。文章结合仓库源码（internal/service/与internal/provider/）验证了各功能的真实实现细节，帮助读者在升级到 6.56.0 后快速掌握新能力、规避升级风险，并理解 Terraform Plugin Framework 中 Action 与 List Resource 等新式资源类型的落地方式。

一、6.56.0 版本概览

6.56.0（2026 年 7 月 22 日发布）是 AWS Provider 在 v6 主线上的一个功能密集版本，共带来6 项新特性、20 项增强与9 项缺陷修复，覆盖 ElastiCache、S3、EKS、Secrets Manager、MSK、Bedrock Agent、OpenSearch Serverless 等多个服务。其中最有代表性的变化是：

• 新增首个面向 ElastiCache 的 Action 类型资源aws_elasticache_apply_service_update，用于在 Terraform 中直接发起并跟踪服务更新的应用流程；
• 新增aws_s3_buckets数据源，可批量枚举 S3 桶并支持前缀、区域、数量上限过滤；
• 新增3 个 List Resource（aws_eks_addon、aws_s3_bucket_notification、aws_secretsmanager_secret_policy），延续 Provider 将"多实例资源"抽象为列表资源的演进方向；
• Provider 凭证体系支持通过TF_AWS_WEB_IDENTITY_TOKEN环境变量配置 Web Identity Token。

二、新 Action：aws_elasticache_apply_service_update

2.1 背景：Action 是什么

Action 是 Terraform Plugin Framework 提供的一类特殊资源类型，它不维护持久化状态，而是执行一次性的外部操作并跟踪其完成。6.56.0 引入的aws_elasticache_apply_service_update正是用于将 ElastiCache 集群或复制组的服务更新（Service Update）应用到指定节点上。

2.2 参数与 Schema

从 apply_service_update_action.go 的Schema定义可以确认其完整入参：

参数	类型	是否必填	说明
service_update_name	String	是	要应用的服务更新名称，如redis-7-3-20260721
cache_cluster_id	String	否（二选一）	目标 Cache Cluster ID
replication_group_id	String	否（二选一）	目标复制组 ID
timeouts	Block	否	Action 超时控制

cache_cluster_id与replication_group_id通过actionvalidator.Conflicting校验器强制互斥（见源码ConfigValidators），二者只能指定其一。该 Action 默认的 Invoke 超时为1 小时（SetDefaultInvokeTimeout(1 * time.Hour)）。

2.3 执行流程与状态机

Invoke方法的实现展示了完整的执行链路：

1. 读取配置并展开为elasticache.BatchApplyUpdateActionInput，将cache_cluster_id/replication_group_id映射为 API 的CacheClusterIds/ReplicationGroupIds列表；
2. 调用 ElastiCache 的BatchApplyUpdateActionAPI 发起更新；
3. 若 API 返回UnprocessedUpdateActions（存在未处理的更新动作），直接报错并附上ErrorType与ErrorMessage；
4. 通过actionwait.WaitForStatus轮询DescribeUpdateActions，直到UpdateActionStatus变为complete；
5. 轮询过程中将waiting-to-start、in-progress视为过渡态，每 60 秒上报一次进度，超时或进入意外状态（UnexpectedStateError）都会给出明确诊断信息。

由于执行期间会持续推送进度（fwactions.NewSendProgressFunc），该 Action 在terraform apply时会输出"Applying… / started, waiting for completion… / applied successfully"等阶段信息，便于观察长任务进展。

2.4 使用示例

# 先查询可用的服务更新动作 data "aws_elasticache_service_update_actions" "example" { replication_group_id = aws_elasticache_replication_group.example.id } # 对复制组应用最新可用的服务更新 resource "terraform_data" "apply_update" { triggers_replace = data.aws_elasticache_service_update_actions.example.update_actions[0].service_update_name provisioner "local-exec" { command = "true" # 占位，实际由 Action 触发 } } # 6.56.0 之后可直接用 Action 发起应用 # （以下为 Action 的调用形态，具体以 Plugin Framework 对 Action 的声明方式为准）

注意：Action 的执行效果（集群重启、只读等）取决于具体服务更新的属性，建议先在测试集群上验证，再对生产复制组执行。

三、新数据源：aws_elasticache_service_update_actions

与上述 Action 配套，6.56.0 新增了 service_update_actions_data_source.go 实现的数据源aws_elasticache_service_update_actions，用于查询符合条件的服务更新动作列表，可作为 Action 的输入来源。

3.1 过滤参数

参数	类型	说明
cache_cluster_id	String	按 Cache Cluster 过滤（与 replication_group_id 互斥）
replication_group_id	String	按复制组过滤
service_update_status	Set(String)	按服务更新状态过滤，取值来自 AWS SDK 的ServiceUpdateStatus枚举

从源码可以看到，service_update_status使用了fwtypes.SetOfStringEnumType[awstypes.ServiceUpdateStatus]()，即强类型枚举集合，非法取值会在配置校验阶段即被拒绝。底层通过DescribeUpdateActionsAPI 的分页迭代器（elasticache.NewDescribeUpdateActionsPaginator）拉取全部结果。

3.2 输出属性：update_actions

每次查询返回计算属性update_actions（对象列表），每个元素包含：

属性	说明
cache_cluster_id	关联的 Cache Cluster ID
replication_group_id	关联的复制组 ID
engine	引擎类型
service_update_name	服务更新名称
service_update_type	服务更新类型
service_update_severity	严重级别
service_update_status	服务更新状态
update_action_status	更新动作当前状态（如complete、in-progress）
estimated_update_time	预估更新耗时
recommended_apply_by_date	推荐应用截止日期（RFC3339）
release_date	发布日期（RFC3339）

典型用法是先查询目标复制组未完成的服务更新，再将其service_update_name传递给aws_elasticache_apply_service_updateAction，形成"查询 → 应用"的自动化闭环。

四、新数据源：aws_s3_buckets

此前枚举 S3 桶只能使用 AWS CLI，Terraform 侧缺少统一的批量查询能力。6.56.0 新增的 buckets_data_source.go 填补了这一空白。

4.1 过滤参数与输出

参数	类型	是否必填	说明
bucket_region	String	否	按桶所在区域过滤
max_buckets	Int32	否	返回的桶数量上限（注意：底层 API 的MaxBuckets是分页大小，这里实现为总数量上限）
prefix	String	否	按桶名前缀过滤
buckets	List(Object)	计算	桶列表，每项含bucket_arn、bucket_region、creation_date（RFC3339）、name

4.2 实现细节

源码中的findBuckets函数展示了几个值得注意的行为：

• 通过s3.NewListBucketsPaginator自动分页迭代ListBuckets，聚合所有页结果；
• 若配置了max_buckets且大于10000，会被强制钳制到 10000（aws.Int32(10000)，注释明确说明这是 API 的每页上限）；
• 达到数量上限后提前终止分页（output = output[:limit]; break），避免多余 API 调用。

data "aws_s3_buckets" "example" { prefix = "app-" bucket_region = "us-west-2" max_buckets = 50 } output "bucket_names" { value = data.aws_s3_buckets.example.buckets[*].name }

五、三个新 List Resource

List Resource 是 AWS Provider 近年来主推的资源形态：它把"一个服务下所有同类资源"视为一个集合进行枚举与管理，天然适合跨实例的批量操作。6.56.0 一次性新增了三个：

5.1aws_eks_addon：枚举集群中的全部 EKS Add-on

实现位于 addon_list.go。其列表配置 Schema 仅要求一个必填属性：

参数	类型	说明
cluster_name	String	要枚举 Add-on 的 EKS 集群名称

声明方式为@SDKListResource("aws_eks_addon")，底层复用既有resourceAddon()的资源 Schema，并基于 EKSListAddons分页拉取。与aws_eks_addon单实例资源相比，列表形态可直接for_each遍历集群内所有 Add-on 统一管理。

5.2aws_s3_bucket_notification：枚举桶通知配置

实现位于 bucket_notification_list.go。其List方法的工作流颇具代表性：

1. 以当前 Provider 区域为BucketRegion，调用ListBuckets枚举桶（MaxBuckets取请求的Limit）；
2. 跳过目录桶（Directory Bucket）——源码中isDirectoryBucket(bucketName)明确注释"Directory buckets do not support standard notification configuration"；
3. 对每个普通桶读取通知配置（findBucketNotificationConfiguration），不存在则跳过，读取失败仅记录日志继续；
4. 支持include_resource语义：当请求要求包含完整资源数据时，将通知配置展开回填到资源实例。

5.3aws_secretsmanager_secret_policy：枚举密钥资源策略

实现位于 secret_policy_list.go，声明为@SDKListResource("aws_secretsmanager_secret_policy")，复用resourceSecretPolicy()的 Schema，通过 Secrets Manager 客户端分页枚举各 Secret 的资源策略，供需要批量审计或统一管理密钥策略的场景使用。

三个 List Resource 的配套测试（如 addon_list_test.go、bucket_notification_list_test.go、secret_policy_list_test.go）与internal/service/*/testdata/*/list_basic/下的 golden 测试数据，共同验证了列表枚举、区域覆盖（region_override）、include_resource等行为。

六、Provider 增强：TF_AWS_WEB_IDENTITY_TOKEN环境变量

6.56.0 对 Web Identity 凭证配置做了两处调整（对应 issue #48736）：

1. 新增TF_AWS_WEB_IDENTITY_TOKEN环境变量，可直接提供 Web Identity Token 字符串；
2. 修复了此前"必须显式配置web_identity_token或web_identity_token_file之一"的报错，现在任意合法的AWS_WEB_IDENTITY_TOKEN_FILE环境变量值都可直接使用。

6.1 优先级规则

从 provider.go 的expandAssumeRoleWithWebIdentity实现可以确认确切的优先级：

Provider 配置 web_identity_token > Provider 配置 web_identity_token_file > TF_AWS_WEB_IDENTITY_TOKEN 环境变量（作为 token） > AWS_WEB_IDENTITY_TOKEN_FILE 环境变量（作为 token 文件）

即：Provider 配置优先于环境变量；未配置时依次回退到两个环境变量。源码还保证 token 与 token 文件二者必须恰好指定其一（(assumeRole.WebIdentityToken != "") == (assumeRole.WebIdentityTokenFile != "")为真时报错）。

6.2 使用示例

# 方式一：token 文件（既有方式） export AWS_WEB_IDENTITY_TOKEN_FILE=/path/to/token.jwt export AWS_ROLE_ARN=arn:aws:iam::123456789012:role/my-oidc-role # 方式二：直接以环境变量传入 token 字符串（6.56.0 新增） export TF_AWS_WEB_IDENTITY_TOKEN="eyJhbGciOi..." export AWS_ROLE_ARN=arn:aws:iam::123456789012:role/my-oidc-role

# 方式三：在 Provider 块中显式配置（优先级最高） provider "aws" { assume_role_with_web_identity { role_arn = "arn:aws:iam::123456789012:role/my-oidc-role" web_identity_token = "eyJhbGciOi..." } }

该能力对GitHub Actions / GitLab CI 等 OIDC 联邦登录场景尤其有用——CI 中常常只持有 token 字符串而非文件，此前的版本无法直接消费。

七、其他关键增强速览

7.1 EKS 节点组：warm_pool_config

data-source/aws_eks_node_group与resource/aws_eks_node_group同时新增warm_pool_config属性/配置块（issue #48977），支持声明节点组的温池配置（如min_size、max_size、pool_state），配合 EC2 Auto Scaling 温池实现快速横向扩容。

7.2 MSK：IPv6 Bootstrap Broker 地址

aws_msk_cluster与data-source/aws_msk_bootstrap_brokers新增 4 个 IPv6 引导地址属性：

• bootstrap_brokers_ipv6
• bootstrap_brokers_sasl_iam_ipv6
• bootstrap_brokers_sasl_scram_ipv6
• bootstrap_brokers_tls_ipv6

用于在双栈（Dual-stack）VPC 场景下获取基于 IPv6 的客户端引导连接串（issue #48975）。

7.3 OpenSearch Serverless：安全配置的联邦与身份中心选项

aws_opensearchserverless_security_config（资源与数据源）新增两个配置块：

• iam_federation_options：IAM 联邦配置；
• iam_identity_center_options：IAM Identity Center 配置。

同时aws_opensearch_package_association新增了import 支持（issue #46690）。

7.4 Bedrock Agent：托管知识库

• aws_bedrockagent_knowledge_base支持MANAGED类型（type = "MANAGED"）及managed_knowledge_base_configuration块；vector_knowledge_base_configuration.bedrock_embedding_model_configuration下新增audio、video嵌入模型配置块；
• aws_bedrockagent_data_source新增data_source_configuration.managed_knowledge_base_connector_configuration块，并新增timeouts.update（默认30 分钟）。

7.5 其他增强

资源	增强点
aws_autoscaling_group	新增instance_lifecycle_policy配置块
aws_cloudwatch_log_subscription_filter	emit_system_fields支持@source.log取值
aws_flow_log	新增tag_field_specification配置块
aws_guardduty_detector_feature/aws_guardduty_organization_configuration_feature	支持AI_PROTECTION、AI_ANALYST特性名
aws_s3tables_table	metadata.iceberg.properties参数

八、缺陷修复盘点（升级前必读）

8.1 与凭证相关的修复

• Web Identity Token 校验修复：修复了"one ofweb_identity_token,web_identity_token_filemust be specified"的错误，此前即使设置了合法的AWS_WEB_IDENTITY_TOKEN_FILE环境变量也可能被误判为未配置（issue #48736）。

8.2 创建 / 删除流程修复

• aws_bedrockagent_data_source：创建过程中若资源进入FAILED状态则短路等待，避免无谓的长轮询；
• aws_sagemaker_endpoint：重试创建时避免 "Cannot create already existing endpoint" 错误；
• aws_subnet：删除时等待 IPAM 释放其 CIDR 后再返回，避免删除不干净；
• aws_datazone_domain：修复删除时的AccessDeniedException。

8.3 持续漂移（Perpetual Diff）修复

• aws_fsx_lustre_file_system：当sizing_mode为PROPORTIONAL_TO_THROUGHPUT_CAPACITY且未指定size时，data_read_cache_configuration.size不再产生永久性漂移；
• aws_mq_broker：修复 ActiveMQ 代理的shared_resources永久漂移问题；
• aws_mq_configuration：删除时对ConflictException: Configuration ID [...] is in use错误自动重试。

8.4 其他修复

• aws_vpc_ipam_pool：为其他账号中 VPC 创建 IPAM VPC 资源规划池时，不再报 "Error: reading EC2 VPC"。

九、升级建议与总结

6.56.0 是一个以"新资源形态落地"为主题的版本：

1. 如果你使用 ElastiCache：建议先通过aws_elasticache_service_update_actions数据源盘点待应用的服务更新，再决定是否使用新的 Action 自动化应用，注意cache_cluster_id与replication_group_id互斥、默认超时 1 小时；
2. 如果你管理大量 S3 桶：aws_s3_buckets数据源配合prefix/bucket_region/max_buckets可以显著简化桶的批量发现与成本分析工作；
3. EKS / S3 / Secrets Manager 用户：三个新 List Resource 为批量枚举与统一管理提供了更符合声明式习惯的入口；
4. CI/CD 中使用 OIDC 联邦的团队：可立即切换到TF_AWS_WEB_IDENTITY_TOKEN环境变量，减少对 token 文件落盘的依赖；
5. 升级前重点关注 8.2、8.3 节中与创建/删除/漂移相关的修复——这些修复通常意味着行为变化，建议在非生产环境先行验证。

若需深入了解实现细节，可继续阅读仓库中的核心源码：ElastiCache Action 实现、S3 桶数据源、EKS Add-on List Resource 以及 Provider 凭证解析逻辑，并结合各服务的testdata/golden 测试理解其行为预期。

【免费下载链接】terraform-provider-awsThe AWS Provider enables Terraform to manage AWS resources.项目地址: https://gitcode.com/GitHub_Trending/te/terraform-provider-aws