Terraform AWS Provider 数据源aws_savingsplans_offerings完全指南查询与筛选 AWS Savings Plans 产品【免费下载链接】terraform-provider-awsThe AWS Provider enables Terraform to manage AWS resources.项目地址: https://gitcode.com/GitHub_Trending/te/terraform-provider-aws导读aws_savingsplans_offerings是 Terraform AWS Provider 提供的只读数据源Data Source用于查询当前账号所在区域可购买的 AWS Savings Plans 产品清单Offering并支持按产品类型、时长、支付方式、区域等多维度过滤。本文基于该数据源在仓库中的官方文档website/docs/d/savingsplans_offerings.html.markdown并结合其底层源码savingsplans_offerings_data_source.go与集成测试savingsplans_offerings_data_source_test.go系统讲解全部入参、返回属性、过滤块用法及底层调用原理帮助你在 IaC 中按需检索并交叉引用 Savings Plans 产品信息为后续购买aws_savingsplans_savings_plan资源提供精确的数据支撑。数据源概览与工作原理aws_savingsplans_offerings属于 AWS Provider 中 Savings Plans 服务names.SavingsPlans下的只读查询能力它本身不创建、不修改任何云资源而是将 AWS 的DescribeSavingsPlansOfferingsAPI 查询结果映射为 Terraform 状态中的offerings列表。从仓库的服务包注册文件可以看到该数据源与aws_savingsplans_savings_plan数据源一同注册在FrameworkDataSources中类型名为aws_savingsplans_offerings服务名为names.SavingsPlans对应 go.mod 中声明的 AWS SDK for Go v2 依赖github.com/aws/aws-sdk-go-v2/service/savingsplans v1.40.0见 go.mod。它基于 Terraform Plugin Framework 实现而非旧版 SDKv2由newOfferingsDataSource工厂函数创建运行时通过 Provider 配置中的SavingsPlansClient发起 API 调用。底层调用链为Read方法 →flex.Expand将 Terraform 配置展开为DescribeSavingsPlansOfferingsInput→findOfferings分页拉取全部结果 →flex.Flatten将 API 返回的SavingsPlanOffering结构写入状态。基本用法原文档给出的最小可用配置如下仅通过product_type与region过滤即可拿到该区域下所有符合条件的 EC2 Savings Plans 产品data aws_savingsplans_offerings example { product_type EC2 filter { name region values [us-west-2] } }仓库中的集成测试savingsplans_offerings_data_source_test.go给出了一个更精确的筛选组合——同时约束产品类型、使用类型与时长将结果收敛到唯一一条记录data aws_savingsplans_offerings test { product_type EC2 usage_types [USW2-EC2SP:a1.1yrAllUpfront] durations [31536000] filter { name region values [us-west-2] } }其中31536000是一年对应的秒数365 × 24 × 3600USW2-EC2SP:a1.1yrAllUpfront是 us-west-2 区域 a1 实例族、1 年全预付 EC2 Savings Plans 的 usage type。测试随后断言offerings.#非空且该列表恰好包含一条预期记录说明筛选参数组合越精确返回结果越收敛适合在配置中直接交叉引用。拿到数据后典型的消费方式是遍历offerings并读取offering_id配合aws_savingsplans_savings_plan资源创建实际计划output first_offering_id { value data.aws_savingsplans_offerings.example.offerings[0].offering_id }参数参考Argument Reference数据源支持以下全部为可选的查询参数。从数据源 Schema 定义看参数语义与 AWS SDK 的DescribeSavingsPlansOfferingsInput一一对应未提供的参数不参与过滤。参数类型说明currencies可选字符串集合币种列表如USD。Schema 中为SetOfStringEnumType[awstypes.CurrencyCode]即只能填 AWS 定义的币种枚举descriptions可选字符串集合产品描述列表用于按描述精确匹配durations可选整数集合时长列表单位秒如315360001 年、157680006 个月filter可选块Block列表过滤器列表详见下文 Filter 块offering_ids可选字符串集合指定的 Offering ID 列表用于精确锁定产品operations可选字符串集合操作列表operation 维度过滤payment_options可选字符串集合支付方式枚举集合如All Upfront、Partial Upfront、No Upfront定义于awstypes.SavingsPlanPaymentOptionplan_types可选字符串集合计划类型枚举集合如EC2Instance、Compute定义于awstypes.SavingsPlanTypeproduct_type可选字符串产品类型如EC2、Fargate、Lambda、SageMaker定义于awstypes.SavingsPlanProductTyperegion可选字符串查询区域默认取 Provider 配置中设定的 Regionservice_codes可选字符串集合服务代码列表如ComputeSavingsPlansusage_types可选字符串集合使用类型列表如USW2-EC2SP:a1.1yrAllUpfront两点需要特别注意集合类参数在 Schema 中使用 Set 语义fwtypes.SetOfStringType、fwtypes.SetOfInt64Type因此配置中参数顺序不影响查询结果重复值会被去重。枚举类参数在 Schema 层做了类型校验StringEnumType/SetOfStringEnumType填入不合法取值会在terraform plan/apply阶段直接报错而不是等到 AWS API 返回错误这能显著缩短反馈链路。Filter 块详解filter是嵌套块可声明多个各过滤器之间为 AND 关系参数类型说明name必填字符串过滤属性名定义于awstypes.SavingsPlanOfferingFilterAttribute。从测试用例看至少支持region按区域过滤实际还包含instanceFamily等 AWS 定义的属性values必填字符串列表过滤值列表多个值之间为 OR 关系如[us-west-2, us-east-1]在原文档与测试中最常见的用法是按区域过滤。需要说明的是查询发生在哪个区域由region参数控制默认使用 Provider 配置的区域而filter中的region过滤器则用于进一步限定返回产品的区域两者用途不同前者决定向哪个区域的 Savings Plans API 发起请求后者决定返回哪些区域的产品。由于 AWS Savings Plans 产品是跨区域可见的实践中常将两者搭配使用。返回值参考Attribute Reference除入参外数据源唯一导出的顶层属性是offerings其类型为对象列表每个对象包含如下字段字段说明currency币种如USDdescription产品描述如1 year All Upfront a1 EC2 Instance Savings Plan in us-west-2duration_seconds时长秒如31536000offering_id产品唯一 ID购买时使用operation操作如RunInstances测试中断言为空字符串payment_option支付方式如All Upfrontplan_type计划类型如EC2Instanceproduct_types适用产品类型列表如[EC2]properties属性列表键值对详见下文service_code服务代码如ComputeSavingsPlansusage_type使用类型如USW2-EC2SP:a1.1yrAllUpfrontproperties属性参考每个property是键值对结构字段说明name属性名定义于awstypes.SavingsPlanOfferingPropertyKey如instanceFamily、regionvalue属性值如a1、us-west-2properties用于表达产品在实例族、区域等维度上的附加属性。集成测试对返回对象做了逐字段精确断言savingsplans_offerings_data_source_test.go其中properties恰好为[{name: instanceFamily, value: a1}, {name: region, value: us-west-2}]这印证了属性列表的结构与取值方式。源码级实现原理Schema 与模型定义数据源整体采用 Plugin Framework 模式offeringsDataSource内嵌framework.DataSourceWithModel[offeringsDataSourceModel]Schema 在 Schema 方法 中声明模型结构则在文件后半部分定义。offerings是DataSourceComputedListOfObjectAttribute[offeringModel]即只计算Computed不可由用户直接写入的对象列表filter是ListNestedBlock其name与values均为 Required。模型字段上的flex:nameFilters标签说明 Terraform 侧的filter块会映射为 AWS API 侧的Filters参数。Read 流程与分页Read方法第 105-132 行的执行路径清晰可循从 Provider Meta 获取SavingsPlansClient用req.Config.Get读取配置并做错误富集smerr.AddEnrich用flex.Expand将模型展开为DescribeSavingsPlansOfferingsInput调用findOfferings拉取全量结果用flex.Flatten把[]awstypes.SavingsPlanOffering折叠回Offerings字段并写入状态。findOfferings第 134-151 行内部依赖生成的分页函数describeSavingsPlansOfferingsPages见 list_pages_gen.go它循环调用conn.DescribeSavingsPlansOfferings以NextToken为空作为最后一页的判断条件将每页的SearchResults累积到切片中返回。这意味着即使某类产品数量巨大、API 分页返回数据源也会自动聚合为完整的offerings列表无需用户感知分页。该分页函数由internal/generate/listpages生成器产出generate.go中的//go:generate go run ../../generate/listpages/main.go -ListOpsDescribeSavingsPlans,DescribeSavingsPlansOfferings指令记录了生成来源。测试验证集成测试TestAccSavingsPlansOfferingsDataSource_basicsavingsplans_offerings_data_source_test.go通过acctest.ParallelTest并行执行使用ProtoV5ProviderFactories并用statecheck.ExpectKnownValue对offerings[0]的每个字段做精确断言currency、description、duration_seconds、offering_id、operation、payment_option、plan_type、product_types、properties、service_code、usage_type 全部校验同时resource.TestCheckResourceAttrSet(dataSourceName, offerings.#)保证结果非空。这套断言同时反向充当了本文档参数与属性语义的“可执行规范”可作为理解字段取值范围的权威参考。实战建议多条件组合收敛结果product_type、usage_types、durations与filter(region)组合使用可把返回集收敛到个位数甚至单条记录避免在配置中使用count/for_each做过多的索引兜底。在配置中动态消费offerings是列表可通过[0]取首条或for表达式遍历结合toset去重、按payment_option或plan_type二次筛选可灵活构建购买清单。区域一致性如需查询非 Provider 默认区域的产品显式设置region参数如需跨区域聚合可在filter中列出多个区域值。类型安全优先使用枚举类取值币种、支付方式、计划类型、产品类型Schema 会在 plan 阶段提前拦截非法输入。总结aws_savingsplans_offerings将 AWS Savings Plans 产品目录的查询能力以声明式数据源形式接入 Terraform 工作流支持 11 类入参、自定义过滤块以及结构化offerings返回底层通过分页调用DescribeSavingsPlansOfferings保证结果完整性。配合仓库中的实现源码savingsplans_offerings_data_source.go、分页生成代码list_pages_gen.go与集成测试savingsplans_offerings_data_source_test.go你既能获得开箱即用的查询能力也能深入理解其字段语义与调用链路为 Savings Plans 的选型与购买自动化提供可靠的数据基础。【免费下载链接】terraform-provider-awsThe AWS Provider enables Terraform to manage AWS resources.项目地址: https://gitcode.com/GitHub_Trending/te/terraform-provider-aws创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考