Terraform AWS Provider 之 aws_opensearchserverless_collection 数据源：完整参数与源码级解析

Terraform AWS Provider 之 aws_opensearchserverless_collection 数据源：完整参数与源码级解析

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

本指南以 AWS 官方 Terraform Provider 仓库中的 opensearchserverless_collection 数据源文档 为核心，系统讲解如何通过aws_opensearchserverless_collection数据源查询 AWS OpenSearch Serverless Collection（集合）的元数据，覆盖参数约束、全部导出属性，并结合仓库源码剖析其基于BatchGetCollectionAPI 的底层实现与测试验证。读完本文，你将能够准确地在 Terraform 配置中按id或name读取 Collection 信息，并将其 ARN、端点地址、加密配置等属性安全地注入到其他资源中。

数据源概述与适用场景

aws_opensearchserverless_collection是 AWS Provider 提供的只读数据源（data source），用于获取 AWS OpenSearch Serverless Collection 的详细信息。在 Terraform 中，数据源承担"查询现状、读取元数据"的职责，与aws_opensearchserverless_collection资源（负责创建、更新、删除）形成互补关系。

典型应用场景包括：

• 跨资源引用：将已有 Collection 的arn、collection_endpoint、kms_key_arn等属性注入到 IAM 策略、安全组、监控告警等下游资源中；
• 基础设施导入后的状态补充：对于通过terraform import或控制台创建的资源，用数据源在配置中声明其存在并读取属性；
• 避免硬编码：在多个配置之间共享 Collection 标识，只维护一份名称或 ID 即可动态获取全部元数据。

从仓库源码注释（collection_data_source.go 中的@FrameworkDataSource注解）可以确认，该数据源基于 HashiCorp 的Terraform Plugin Framework实现，并与 Collection 资源共用同一套 AWS SDK 调用与查询逻辑。

基础用法示例

原文档给出的最简配置如下（示例出处）：

data "aws_opensearchserverless_collection" "example" { name = "example" }

执行terraform apply（或terraform plan）后，即可通过data.aws_opensearchserverless_collection.example引用该 Collection 的各类属性，例如：

output "collection_arn" { value = data.aws_opensearchserverless_collection.example.arn } output "collection_endpoint" { value = data.aws_opensearchserverless_collection.example.collection_endpoint }

需要注意的是，数据源查询的是已存在的 Collection。若目标 Collection 尚未创建，更合适的做法是先声明aws_opensearchserverless_collection资源，或采用下文"与资源配合使用"的写法，由资源创建后数据源立即读取。

参数（Argument Reference）

数据源的全部参数均为可选，但存在严格的互斥约束。原文档参数表如下：

核心约束：id 与 name 必须二选一

原文档通过醒目的提示强调了查询条件规则：

恰好需要id与name其中之一（Exactly one ofidornameis required）

也就是说，id与name不能同时设置，也不能都不设置。这一约束并不仅停留在文档层面，而是由源码中的 Schema 校验器强制执行的。在 collection_data_source.go 中可以看到：

• id字段声明了stringvalidator.ConflictsWith(name)（与name冲突）和stringvalidator.ExactlyOneOf(name)（二选一必填）；
• name字段声明了stringvalidator.ConflictsWith(id)。

这意味着即便绕过文档，直接向 Provider 提交不合法配置，也会在terraform validate/terraform plan阶段被立即拒绝，属于框架层面的静态校验，无需发起任何 AWS API 调用。

region 参数的作用

region用于指定查询目标区域，默认为 Provider 配置中的区域。结合 collection.go 中WithRegionModel的嵌入，以及数据源模型同样继承自framework.WithRegionModel（collection_data_source.go），可以确认该数据源支持"多区域显式指定"能力：当 Collection 位于非默认区域时，可显式传入region完成跨区域查询。

属性参考（Attribute Reference）

除上述参数外，数据源在读取成功后导出以下全部属性：

属性语义的源码级印证

这些属性与数据源 Schema 定义一一对应（collection_data_source.go），其中几个关键点值得展开：

• created_date与last_modified_date的时间格式：AWS OpenSearch Serverless 返回的是 Unix 毫秒时间戳，数据源在读取后通过time.UnixMilli(...).Format(time.RFC3339)转换为 RFC3339 字符串（collection_data_source.go），因此 Terraform 状态中的日期是标准 ISO 8601 格式，便于直接与其他时间字符串比较或写入告警规则。
• failure_code与failure_reason：当 Collection 创建或删除失败时（状态为FAILED），资源实现会从 API 返回中提取FailureCode与FailureMessage用于错误提示（collection.go）。数据源导出这两个字段，便于在查询到异常状态的 Collection 时快速定位问题。
• standby_replicas与type：对应 AWS 枚举StandbyReplicas（ENABLED/DISABLED）与CollectionType（SEARCH/TIMESERIES/VECTORSEARCH）。资源侧的 Schema 校验通过enum.FrameworkValidate强约束这些取值（collection.go）。
• tags：数据源以TagsAttributeComputedOnly()声明（collection_data_source.go），即只读导出，不可在数据源上修改标签。

源码级原理：数据源读取流程

为了更准确地使用该数据源，理解其底层调用链会很有帮助。数据源的Read方法执行流程如下（collection_data_source.go）：

1. 获取客户端：通过d.Meta().OpenSearchServerlessClient(ctx)取得当前 Provider 配置下的 OpenSearch Serverless AWS SDK v2 客户端；
2. 解析配置：将用户的 Terraform 配置反序列化到collectionDataSourceModel；
3. 按 ID 查询或按名称查询：
   • 若设置了id，调用findCollectionByID；
   • 若设置了name，调用findCollectionByName；
   • 两个函数最终都调用 AWS SDK 的BatchGetCollectionAPI，分别传入Ids或Names参数（find.go）；
4. 结果反序列化：通过flex.Flatten将 API 返回的CollectionDetail结构体映射到数据源模型，其中CreatedDate、LastModifiedDate两个字段做特殊的毫秒时间戳转换；
5. 写入状态：将结果写入 Terraform State，供其他资源引用。

findCollectionByID/findCollectionByName中对ResourceNotFoundException的显式捕获并转换为retry.NotFoundError（find.go），保证"Collection 不存在"这一场景能够被框架正确识别为友好的 not-found 语义，而不是抛出一个原始 AWS 错误。

与资源配合使用：实战配置

基础场景：先创建后读取

参考仓库中数据源的验收测试配置（collection_data_source_test.go），可以写出资源与数据源协同的完整示例。由于 OpenSearch Serverless Collection 必须先配置加密安全策略，示例还引入了aws_opensearchserverless_security_policy：

resource "aws_opensearchserverless_security_policy" "test" { name = "example" type = "encryption" policy = jsonencode({ Rules = [ { Resource = ["collection/example"] ResourceType = "collection" } ] AWSOwnedKey = true }) } resource "aws_opensearchserverless_collection" "test" { name = "example" depends_on = [aws_opensearchserverless_security_policy.test] } # 通过 id 查询 data "aws_opensearchserverless_collection" "by_id" { id = aws_opensearchserverless_collection.test.id } # 通过 name 查询 data "aws_opensearchserverless_collection" "by_name" { name = aws_opensearchserverless_collection.test.name } output "endpoint" { value = data.aws_opensearchserverless_collection.by_id.collection_endpoint } output "kms_key" { value = data.aws_opensearchserverless_collection.by_name.kms_key_arn }

该示例同时演示了id与name两种查询路径的等价性，并印证了测试中对数据源属性与资源属性逐项比对（TestCheckResourceAttrPair）的行为（collection_data_source_test.go）：数据源读出的arn、collection_endpoint、dashboard_endpoint、description、kms_key_arn、standby_replicas、type等属性应与对应资源完全一致。

查询已有 Collection

对于已通过其他方式（控制台、AWS CLI、导入）存在的 Collection，直接按名称查询即可：

data "aws_opensearchserverless_collection" "existing" { name = "my-existing-collection" } resource "aws_iam_policy" "aoss_access" { name = "aoss-collection-access" policy = jsonencode({ Version = "2012-10-17" Statement = [ { Effect = "Allow" Action = ["aoss:APIAccessAll"] Resource = [data.aws_opensearchserverless_collection.existing.arn] } ] }) }

这里将数据源的arn直接用于 IAM 策略，避免了在策略中硬编码 ARN，是数据源最典型的生产级用法。

使用注意事项与边界

1. 查询条件互斥：id与name二选一，同时设置或都不设置都会导致校验失败（由 Schema 的ExactlyOneOf/ConflictsWith在plan阶段拦截）。
2. 数据源是只读的：它不会创建、修改或删除 Collection，只负责读取状态；创建 Collection 请使用 aws_opensearchserverless_collection 资源。
3. 区域默认行为：未指定region时使用 Provider 的默认区域；跨区域查询需显式设置region。
4. 时间字段格式：created_date、last_modified_date在状态中以 RFC3339 字符串呈现（内部由 Unix 毫秒转换而来）。
5. 运行前提：该数据源是 AWS Provider 的一部分，使用时需在required_providers中声明hashicorp/aws，并配置有效的 AWS 凭证与目标区域权限（至少需要 OpenSearch Serverless 的读取权限）。

相关资源延伸阅读

• opensearchserverless_collection 资源文档：数据源的"写入端"对应资源，包含type、standby_replicas、encryption_config、vector_options等创建参数说明；
• collection_data_source.go：数据源完整实现，Schema 定义与Read流程；
• collection.go：Collection 资源实现，含创建/删除等待逻辑（默认 20 分钟超时）；
• find.go：findCollectionByID/findCollectionByName底层查询函数；
• collection_data_source_test.go：数据源验收测试，演示id与name两种查询路径及属性一致性校验。

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