terraform-provider-aws 6.26.0 版本解析：List 资源、IAM 出站身份联合与 RDS 升级序列控制-二趣网

terraform-provider-aws 6.26.0 版本解析：List 资源、IAM 出站身份联合与 RDS 升级序列控制

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

本篇文章围绕 HashiCorp 官方 AWS Provider（当前仓库 terraform-provider-aws）发布的6.26.0版本变更记录（对应仓库 .changes/6.x/6.26.0.md）展开，逐一拆解本版本新增的 4 个 List 资源、1 个全新 IAM 资源、9 项功能增强与 8 项 Bug 修复。读者阅读后可快速掌握各变更的配置方法、适用场景，并借助仓库源码理解底层实现原理，从而安全、平滑地升级到该版本。

版本概览：一次聚焦「可列举性」与「升级可控性」的发布

6.26.0 于2025 年 12 月 10 日发布（见 .changes/6.x/6.26.0.md），是本仓库 6.x 系列的一个重要里程碑。本版本最突出的主题是List 资源（List Resource）的批量落地——一次性新增了 4 个 List 资源，占全部 5 个新功能的一半以上。

List 资源是 Terraform 1.14 引入的list块查询能力的产物。仓库内的设计文档 docs/list-resources.md 说明：借助list块，用户可以在配置中直接对远端资源进行查询与过滤，Provider 端则通过实现List方法把 AWS API 的列举能力映射为 Terraform 的声明式查询。

除 List 资源外，本版本还围绕RDS 升级序列控制（upgrade_rollout_order）进行了资源与数据源的多点增强，并修复了一批涉及崩溃回归、持久化 Diff、写权限校验的缺陷，整体变更面广但风险点集中。

新增 List 资源：把 AWS 列举 API 转化为声明式查询

List 资源的设计背景

在了解具体资源前，先明确 List 资源的实现约束。docs/list-resources.md 指出，为某个远端资源类型实现 List 资源，需要从三个维度评估：

与其他资源的关系：分为强实体（仅凭自身标识即可读取/列举，如aws_instance）、弱实体（还需关联资源标识，如aws_lb_listener需要 ELB ARN）、属性实体（1:1 或 1:[0,1] 关系）与等待资源；
AWS API 模式：包括 All-Or-One（给标识取单个、不给取全部）、All-Or-Some（给一组标识取一组、不给取全部）、Summary List（列举接口只返回概要信息，需后续 API 补全，典型如标签）；
Terraform 侧考虑：Provider 对资源类型的管理方式会影响 List 实现。

本版本新增的 4 个 List 资源均为可通过自身标识读取的强实体，且全部基于 Summary List 模式实现：列举接口只返回概要（名称/元数据），完整属性在IncludeResource开启时通过额外的读取或批量获取 API 补全。

`aws_batch_job_definition`：基于 SDKv2 资源的 List 化

第一个新增 List 资源是aws_batch_job_definition。其实现位于 internal/service/batch/job_definition_list.go，通过@SDKListResource("aws_batch_job_definition")注解注册，并复用了既有的resourceJobDefinition()schema 与resourceJobDefinitionFlatten展开函数，属于典型的「SDKv2 资源复用式 List」。

实现要点（见 internal/service/batch/job_definition_list.go）：

使用batch.NewDescribeJobDefinitionsPaginator分页遍历DescribeJobDefinitions接口，逐条产出JobDefinition；
过滤掉状态为INACTIVE的作业定义（jobDefinitionStatusInactive），保证查询结果只包含可用的定义；
以JobDefinitionArn作为资源 ID，JobDefinitionName作为展示名；
所有条目一次性通过DescribeJobDefinitions返回，属于 All-Or-One 模式的典型应用。

对应的单元与接受性测试见 internal/service/batch/job_definition_list_test.go。

`aws_codebuild_project`：分页 + 批量补全的 List 实现

aws_codebuild_project的 List 实现位于 internal/service/codebuild/project_list.go，其设计更具代表性：

列举阶段调用codebuild.ListProjects（@SDKListResource注册，见 internal/service/codebuild/project_list.go），该接口只返回项目名称数组，是典型的 Summary List 模式；
当查询请求IncludeResource（即需要完整资源属性）时，实现会对当前页的名称批量调用BatchGetProjects补齐详情，再以projectsByName映射按名称关联（internal/service/codebuild/project_list.go）；
资源 ID 为项目名，ARN 通过awsClient.RegionalARN(ctx, "codebuild", "project/"+projectName)本地拼装，避免额外的 API 调用；
若批量获取时某项目已消失，会打 Warning 并跳过，保证列举过程的健壮性。

测试见 internal/service/codebuild/project_list_test.go。

`aws_lambda_capacity_provider`：Framework List 资源与资源身份支持

aws_lambda_capacity_provider是本版本的双料新增：既以 List 资源形态出现，又在此前版本基础上补充了资源身份（Resource Identity）支持（见 changelog 的 ENHANCEMENTS 小节）。

其 List 实现位于 internal/service/lambda/capacity_provider_list.go，是Framework 原生 List 资源（@FrameworkListResource），与 SDKv2 复用式实现互补：

调用lambda.ListCapacityProviders分页列举（listCapacityProviders，见 internal/service/lambda/capacity_provider_list.go）；
显式跳过Deleting状态的容量提供者；
通过解析 ARN 并strings.TrimPrefix(cpARN.Resource, "capacity-provider:")从 ARN 中还原资源名称，作为展示名（internal/service/lambda/capacity_provider_list.go）；
使用flex.Flatten将 AWS 类型扁平化为 Framework 模型。

资源本体（Schema、CRUD 与身份逻辑）见 internal/service/lambda/capacity_provider.go，身份相关测试在 internal/service/lambda/capacity_provider_identity_gen_test.go。关于资源身份的设计原则可参考 docs/resource-identity.md。

`aws_ssm_parameter`：复用既有 Parameter schema 的 SDK List 资源

aws_ssm_parameter的 List 实现位于 internal/service/ssm/parameter_list.go，同样通过@SDKListResource复用既有resourceParameter()schema（internal/service/ssm/parameter_list.go）：

使用ssm.NewDescribeParametersPaginator对DescribeParameters分页遍历（listParameters，internal/service/ssm/parameter_list.go）；
每个条目以参数Name作为 ID 与展示名；
IncludeResource开启时，通过findParameterByName拉取完整参数信息并resourceParameterFlatten展开，同时写入value属性（internal/service/ssm/parameter_list.go）。

测试见 internal/service/ssm/parameter_list_test.go。

小结：4 个 List 资源覆盖了两种实现路径——SDKv2 资源复用式（Batch、CodeBuild、SSM）与 Framework 原生式（Lambda Capacity Provider），展示了 List 资源在既有资源上的两种主流接入方式。

全新资源：`aws_iam_outbound_web_identity_federation`

除 List 资源外，本版本新增了aws_iam_outbound_web_identity_federation资源，用于管理 IAM 的出站 Web 身份联合（Outbound Web Identity Federation）功能的启用状态。

其实现位于 internal/service/iam/outbound_web_identity_federation.go，几个值得注意的设计点：

单例资源：通过@SingletonIdentity注解声明（internal/service/iam/outbound_web_identity_federation.go），意味着该功能在整个账户内是全局唯一的，Schema 中只有一个issuer_identifier（Computed 属性），无用户可配置参数；
Create 即 Enable：Create直接调用iam.EnableOutboundWebIdentityFederation，完成后从响应中回填issuer_identifier（internal/service/iam/outbound_web_identity_federation.go）；
Delete 即 Disable：Delete调用iam.DisableOutboundWebIdentityFederation，并特殊处理FeatureDisabledException（功能未启用时视为删除成功，避免报错，internal/service/iam/outbound_web_identity_federation.go）；
Read 容错：findOutboundWebIdentityFederation同样把FeatureDisabledException归一化为NotFoundError，交给retry.NotFound处理，从而在功能未启用时安全地从 State 中移除资源（internal/service/iam/outbound_web_identity_federation.go）；
不可更新：结构体组合了framework.WithNoUpdate，任何属性变化都会触发重建。

导入支持：该资源支持按账户 ID 导入（@Testing(importStateIdFunc=importStateIDAccountID, importStateIdAttribute="issuer_identifier")）。测试见 internal/service/iam/outbound_web_identity_federation_test.go 与 internal/service/iam/outbound_web_identity_federation_data_source_test.go。

功能增强：RDS 升级序列、EKS 更新策略与更多参数

RDS 实例与集群：新增`upgrade_rollout_order`属性

本版本为aws_db_instance、aws_rds_cluster两个资源及其数据源（data-source/aws_db_instance、data-source/aws_rds_cluster）同步新增了upgrade_rollout_order属性，用于表达数据库实例在集群升级时的滚动顺序。

以aws_db_instance为例，该属性在 Schema 中被声明为Computed的字符串（见 internal/service/rds/instance.go），在读取阶段从 AWS SDK 的UpgradeRolloutOrder字段回填（internal/service/rds/instance.go）。aws_rds_cluster的对应定义见 internal/service/rds/cluster.go 与展开逻辑 internal/service/rds/cluster.go。

这意味着用户可以在配置中以upgrade_rollout_order = data.aws_rds_cluster.example.upgrade_rollout_order的方式引用该值，实现跨资源编排（例如按序升级集群中的多个实例）。

EKS Node Group：`update_config`支持`update_strategy`

data-source/aws_eks_node_group与resource/aws_eks_node_group均新增了update_config块内的update_strategy属性。

在 internal/service/eks/node_group.go 中，update_strategy被定义为可选字符串，并通过enum.Validate[types.NodegroupUpdateStrategies]()做枚举校验（合法值如DEFAULT、MINIMAL）。它与max_unavailable、max_unavailable_percentage共同构成update_config块（后两者受ExactlyOneOf约束，二选一，且取值范围 1–100，见 internal/service/eks/node_group.go）。数据源侧对应定义见 internal/service/eks/node_group_data_source.go。

配置示例：

resource "aws_eks_node_group" "example" { cluster_name = aws_eks_cluster.example.name node_group_name = "example" node_role_arn = aws_iam_role.example.arn subnet_ids = aws_subnet.example[*].id update_config { update_strategy = "DEFAULT" max_unavailable = 1 } }

Kinesis Analytics v2：支持 Flink 1.20 运行时与加密配置

aws_kinesisanalyticsv2_application获得两项增强：

runtime_environment新增合法值FLINK-1_20；
新增application_configuration.application_encryption_configuration参数。

FLINK-1_20的接受性测试覆盖可见于 internal/service/kinesisanalyticsv2/application_test.go（例如testAccApplicationConfig_basicFlink(rName, "FLINK-1_20")与runtime_environment断言），说明该值已作为受支持版本进入测试矩阵。

Bedrock Agent：新增`session_summary_configuration.max_recent_sessions`

aws_bedrockagent_agent新增memory_configuration下的session_summary_configuration块及其max_recent_sessions参数，用于控制会话摘要保留的最近会话数量。

在 internal/service/bedrockagent/agent.go 中，模型以SessionSummaryConfiguration与MaxRecentSessions（Int64）呈现。测试断言示例：resource.TestCheckResourceAttr(resourceName, "memory_configuration.0.session_summary_configuration.0.max_recent_sessions", "5")（见 internal/service/bedrockagent/agent_test.go）。

配置示例：

resource "aws_bedrockagent_agent" "example" { # ... 其他必填参数 memory_configuration { session_summary_configuration { max_recent_sessions = 5 } } }

ODB 网络对等：支持`odb_network_arn`资源分享模式

aws_odb_network_peering_connection新增了基于odb_network_arn创建网络对等连接的资源分享（resource sharing）模式。相关校验逻辑位于 internal/service/odb/cloud_autonomous_vm_cluster.go：用户必须且只能提供以下组合之一——odb_network_id+cloud_exadata_infrastructure_id，或odb_network_arn+cloud_exadata_infrastructure_arn，否则会返回明确的错误诊断。

S3 Vectors：索引新增加密与元数据配置块

aws_s3vectors_index新增两个配置块：

encryption_configuration：配置索引加密；
metadata_configuration：配置元数据字段。

二者在 internal/service/s3vectors/index.go 中对应模型字段EncryptionConfiguration与MetadataConfiguration，其中metadata_configuration在 Schema 中定义为ListNestedBlock（internal/service/s3vectors/index.go）。

其他增强

aws_lambda_capacity_provider：新增资源身份支持（详见上文 List 资源小节），测试见 internal/service/lambda/capacity_provider_identity_gen_test.go。

Bug 修复：崩溃回归、持久化 Diff 与校验修正

本版本共修复 8 个问题，按影响面可归纳为四类。

崩溃回归修复

aws_ec2_transit_gateway/data-source/aws_ec2_transit_gateway：修复读取与设置encryption_support时可能发生的崩溃（panic）。该问题源自 v6.25.0 引入的回归。相关 Schema 定义见 internal/service/ec2/transitgateway_.go：encryption_support为Optional + Computed，取值经enum.Validate[awstypes.EncryptionSupportOptionValue]校验。

持久化 Diff（perpetual diff）修复

aws_lambda_function：修复image_config中存在null值时反复产生 Diff 的问题；
aws_notifications_event_rule：修复配置中未指定event_pattern参数时反复产生 Diff 的问题。

这两项修复消除了「配置未变、Plan 却始终显示变更」的体验问题。

校验与必填项修正

aws_api_gateway_integration：修复timeout_milliseconds校验逻辑——当response_transfer_mode为STREAM时，允许上限提升至900,000 ms（15 分钟）。实现细节见 internal/service/apigateway/integration.go：validateTimeoutMilliseconds中定义了三个常量minTimeoutMilliseconds = 50、maxTimeoutMillisecondsResponseTransferModeBuffered = 300000、maxTimeoutMillisecondsResponseTransferModeStream = 900000，未指定response_transfer_mode时默认按BUFFERED处理。配套测试见 internal/service/apigateway/integration_test.go；
aws_bedrock_model_invocation_logging_configuration：将logging_config.s3_config.bucket_name、logging_config.cloudwatch_config.log_group_name、logging_config.cloudwatch_config.role_arn及logging_config.cloudwatch_config.large_data_delivery_s3_config.bucket_name标记为Required（必填），避免缺失时产生静默错误。

行为与语义修正

aws_route53_zone：启用加速恢复（accelerated recovery）的操作在配置多个托管区时被强制串行执行，避免并发修改引发状态冲突。相关等待逻辑见 internal/service/route53/accelerated_recovery_status.go：waitUpdateAcceleratedRecoveryCompleted会轮询Enabling/EnablingHostZoneLocked/Disabling/DisablingHostZoneLocked等中间态直至稳定；
aws_sagemaker_model：vpc_config.security_group_ids与vpc_config.subnets被标记为ForceNew，修改将触发资源重建，避免在不可原地变更的字段上进行原地更新；
aws_secretsmanager_secret_version：当 Secret 为 write-only（仅写）模式时，避免发送GetSecretValue读取调用。internal/service/secretsmanager/secret_version.go 中，findSecretVersionForExistence依据hasWriteOnly分支选择仅获取VersionStages的存在性查询，从而省去读取敏感值；读取阶段同样通过flex.HasWriteOnlyValue/flex.GetWriteOnlyStringValue判断是否跳过取值（internal/service/secretsmanager/secret_version.go）。

升级建议与验证清单

基于本版本的变更内容，升级到 6.26.0 前建议关注以下几点：

List 资源为增量能力：aws_batch_job_definition、aws_codebuild_project、aws_lambda_capacity_provider、aws_ssm_parameter均为新增资源类型，不影响既有资源配置，升级后即可在配置中使用list块查询（需 Terraform 1.14+）；
关注破坏性语义调整：aws_sagemaker_model的vpc_config字段改为ForceNew，现有配置若修改该块将触发重建，而非原地更新；
补充必填字段：aws_bedrock_model_invocation_logging_configuration的 4 个字段改为 Required，存量配置需检查是否显式声明；
RDS 升级编排：可利用新增的upgrade_rollout_order属性做跨资源依赖编排，但该属性为 Computed 只读，请勿在配置中写入值；
回归验证：涉及 EC2 Transit Gatewayencryption_support的用户，建议升级后立即执行一次terraform plan与terraform apply验证读取链路正常。

如需深入阅读实现细节，可依次查看 internal/service/batch/job_definition_list.go、internal/service/codebuild/project_list.go、internal/service/lambda/capacity_provider_list.go、internal/service/ssm/parameter_list.go 四个 List 实现，以及 internal/service/iam/outbound_web_identity_federation.go；List 资源的设计原则与实体分类模型可对照 docs/list-resources.md 阅读。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析