企业官网建设流程全解析

Terraform AWS Provider 数据源 aws_imagebuilder_image 完全指南：查询 EC2 Image Builder 镜像的构建版本与产物信息

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

aws_imagebuilder_image是 Terraform AWS Provider 提供的数据源（Data Source），用于按 ARN 查询 AWS EC2 Image Builder 已构建完成的镜像，返回其构建版本 ARN、关联的镜像配方/容器配方、分发配置、基础设施配置、镜像扫描与测试配置，以及 AMI/容器镜像等输出产物等完整信息。本文以 imagebuilder_image.html.markdown 文档为主体，结合仓库内 image_data_source.go 等源码实现，系统讲解该数据源的用法、参数、属性以及底层读取原理，帮助你直接在 HCL 中引用最新构建版本或精确构建版本，并将其 ARN 传递给其他资源。

数据源概述

aws_imagebuilder_image数据源用于获取 EC2 Image Builder 中某个镜像（Image）的详细信息。在 Image Builder 中，镜像构建完成后会以形如arn:aws:imagebuilder:us-west-2:123456789012:image/my-image/1.0.0/1的 ARN 存在，其中包含配方版本（1.0.0）与构建序号（1）两部分。该数据源弥补了aws_imagebuilder_image资源在"只读查询、跨配置引用"场景下的不足：当你不希望在配置中管理镜像的生命周期，而只是想读取已有镜像的元数据时，使用数据源即可。

在仓库中，该数据源的定义位于 image_data_source.go，通过// @SDKDataSource("aws_imagebuilder_image", name="Image")注解注册，属于 Image Builder 服务包的一部分（参见 service_package_gen.go）。它与同名的aws_imagebuilder_image资源（实现见 image.go）共享大量扁平化（flatten）辅助函数，因此数据源导出的属性与资源的只读属性高度一致。

基础用法：查询最新构建版本

最典型的场景是查询 AWS 官方预置的公共镜像。Image Builder 会为公共镜像持续发布新版本，而 ARN 后缀使用通配符x.x.x时，数据源会自动解析为当前最新的构建版本：

data "aws_imagebuilder_image" "example" { arn = "arn:aws:imagebuilder:us-west-2:aws:image/amazon-linux-2-x86/x.x.x" }

在真实配置中，为兼容不同 AWS 分区（如aws、aws-cn、aws-us-gov）与当前 Region，更稳健的写法是借助aws_partition与aws_region数据源动态拼接 ARN。仓库的验收测试 image_data_source_test.go 正是采用这种写法：

data "aws_partition" "current" {} data "aws_region" "current" {} data "aws_imagebuilder_image" "test" { arn = "arn:${data.aws_partition.current.partition}:imagebuilder:${data.aws_region.current.region}:aws:image/amazon-linux-2-x86/x.x.x" }

获取到数据源后，可通过data.aws_imagebuilder_image.example.build_version_arn等属性将其 ARN 或元数据传递给aws_imagebuilder_image_recipe、aws_imagebuilder_image_pipeline等资源，例如将公共镜像 ARN 作为自建配方的parent_image：

resource "aws_imagebuilder_image_recipe" "example" { name = "my-linux-recipe" parent_image = data.aws_imagebuilder_image.example.arn version = "1.0.0" component { component_arn = "arn:aws:imagebuilder:us-west-2:aws:component/amazon-linux-2-update/x.x.x" } }

Argument Reference：参数详解

该数据源支持以下参数，其中arn为必需项，region为可选项：

arn：通配符与精确版本

arn是唯一必需的参数，其在 schema 中被声明为Required的字符串类型，并通过verify.ValidARN做 ARN 格式校验（见 image_data_source.go）。其取值有两种形式：

• 通配符形式：如arn:aws:imagebuilder:us-west-2:aws:image/amazon-linux-2-x86/x.x.x，x.x.x匹配任意语义版本，数据源会返回该镜像的最新构建版本；
• 精确形式：如arn:aws:imagebuilder:us-west-2:123456789012:image/my-image/2020.11.26/1，包含完整语义版本与构建序号，数据源返回该特定构建。

需要注意的是，配置中的arn与返回的build_version_arn并不一定相同。底层 APIGetImage总是返回带完整#.#.#/#后缀的构建版本 ARN，因此通配符输入会被解析为精确输出。仓库源码对此有专门处理（image_data_source.go）：数据源将build_version_arn设置为 API 返回的完整 ARN，同时保留用户配置的通配符arn不回写，避免 Terraform 在 refresh 时因配置与状态不一致而产生计划差异（注释原文：The configured ARN may contain x.x.x wildcards while the API returns the full build version#.#.#/#suffix）。

region：跨区域查询

region参数允许数据源查询非 provider 默认 Region 中的镜像。从源码结构看，该属性由 Provider 的增强 Region 支持机制自动注入（aws_imagebuilder_image资源与数据源共享相同的 Region 注入逻辑，相关验证可参见 image_identity_gen_test.go 中对region属性的断言）。当省略时，默认使用 provider 配置中的 Region。

Attribute Reference：导出的属性

数据源除参数外还会导出以下属性，全部为只读（Computed）。以下按类别组织，并标注了源码中的 schema 声明位置（image_data_source.go）：

身份与版本

配方与配置关联 ARN

由于image_recipe_arn与container_recipe_arn互斥（资源的 schema 中通过ExactlyOneOf保证，见 image.go），数据源返回的属性中只会出现其中一个，另一个在测试中被断言为"不存在"（TestCheckNoResourceAttr，见 image_data_source_test.go）。

扫描与测试配置

• enhanced_image_metadata_enabled（bool）— 是否收集所创建镜像的额外信息（增强镜像元数据）。
• image_scanning_configuration（list，最多 1 个对象）— 镜像扫描配置，包含：
  • image_scanning_enabled（bool）— 创建新镜像时，Image Builder 是否保留 Amazon Inspector 对构建实例运行漏洞扫描的快照；
  • ecr_configuration（list，最多 1 个对象）— ECR 扫描配置：
    • repository_name（string）— Amazon Inspector 扫描容器镜像以识别发现项的容器仓库名称；
    • container_tags（set of string）— Image Builder 应用到待扫描输出容器镜像上的一组标签。
• image_tests_configuration（list，最多 1 个对象）— 镜像测试配置，包含：
  • image_tests_enabled（bool）— 是否启用镜像测试；
  • timeout_minutes（int）— 镜像测试超时前等待的分钟数。

输出资源 output_resources

• output_resources（list，最多 1 个对象）— 镜像构建产生的资源列表，包含两类：
  • amis（set of 对象）— 构建产出的每个 AMI：
    • account_id（string）— AMI 所属账户标识；
    • description（string）— AMI 的描述；
    • image（string）— AMI 的标识符（AMI ID）；
    • name（string）— AMI 的名称；
    • region（string）— AMI 所在 Region；
  • containers（set of 对象）— 构建产出并存储到输出仓库的每个容器镜像：
    • image_uris（set of string）— 创建出的容器镜像 URI 集合；
    • region（string）— 容器镜像所在 Region。

标签

• tags（map of string）— 镜像的资源标签。在源码中通过tftags.TagsSchemaComputed()声明（image_data_source.go），并在读取末尾通过setTagsOut(ctx, image.Tags)写入状态（第 L243 行）。

完整属性示例

以下 HCL 展示了对典型自建 Linux 镜像的属性引用方式：

data "aws_imagebuilder_image" "example" { arn = "arn:aws:imagebuilder:us-west-2:123456789012:image/my-linux-image/x.x.x" } output "build_version" { value = data.aws_imagebuilder_image.example.build_version_arn } output "ami_ids" { value = data.aws_imagebuilder_image.example.output_resources[0].amis[*].image } output "image_recipe" { value = data.aws_imagebuilder_image.example.image_recipe_arn }

源码实现原理：一次读取的背后

理解数据源的读取链路有助于诊断查询问题。核心流程如下：

1. 入口：dataSourceImageRead（image_data_source.go）从状态中取出arn，通过meta.(*conns.AWSClient).ImageBuilderClient(ctx)获取 Image Builder 客户端；
2. 查找：调用findImageByARN（image.go），它构造imagebuilder.GetImageInput{ImageBuildVersionArn: arn}并调用 AWS SDK v2 的GetImageAPI；若返回ResourceNotFoundException，则包装为retry.NotFoundError；若响应为空或Image.State为空，则返回tfresource.NewEmptyResultError()；
3. 设置 ID：d.SetId(aws.ToString(image.Arn))，数据源的 ID 即镜像构建版本 ARN；
4. 属性映射：依次通过flattenImageScanningConfiguration、flattenImageTestsConfiguration、flattenOutputResources等辅助函数将 API 结构体转换为 Terraform 的 list/set 结构，具体实现位于 image.go 与 image_pipeline.go；
5. 标签：通过setTagsOut输出标签。

值得关注的是，findImageByARN同时被同名资源aws_imagebuilder_image的 Create/Read 流程复用（image.go），并在创建时通过waitImageStatusAvailable轮询镜像状态直至Available，其间会经过Pending、Building、Testing、Distributing、Integrating等中间状态（image.go）。这意味着：通过资源刚创建的镜像状态可能尚未最终定型，而数据源读取到的则始终是稳定可用的构建产物——这也是在自动化流水线中优先使用数据源而非资源引用的原因之一。

实战场景

场景一：查询 AWS 官方公共镜像

使用通配符 ARN 即可获得当前 Region 中 Amazon Linux 2 最新公共镜像的构建版本，无需维护版本号：

data "aws_imagebuilder_image" "amazon_linux_2" { arn = "arn:${data.aws_partition.current.partition}:imagebuilder:${data.aws_region.current.region}:aws:image/amazon-linux-2-x86/x.x.x" }

仓库测试TestAccImageBuilderImageDataSource_ARN_aws正是此场景的验证（image_data_source_test.go），它断言name为Amazon Linux 2 x86、os_version为Amazon Linux 2、platform为Linux，且build_version_arn匹配image/amazon-linux-2-x86/\d+\.\d+\.\d+/\d+模式。

场景二：查询自建镜像（与资源联动）

若镜像由本配置中的aws_imagebuilder_image资源创建，可直接用资源 ARN 作为数据源输入，验证或消费其完整元数据：

resource "aws_imagebuilder_image" "test" { image_recipe_arn = aws_imagebuilder_image_recipe.test.arn infrastructure_configuration_arn = aws_imagebuilder_infrastructure_configuration.test.arn } data "aws_imagebuilder_image" "test" { arn = aws_imagebuilder_image.test.arn }

仓库测试TestAccImageBuilderImageDataSource_ARN_self（image_data_source_test.go）对资源与数据源的build_version_arn、date_created、distribution_configuration_arn、enhanced_image_metadata_enabled、image_recipe_arn、image_tests_configuration.#、output_resources.#等属性逐一做了配对断言，确保数据源导出与资源状态完全一致。

场景三：查询容器镜像及扫描配置

对于基于容器配方构建的镜像，数据源会返回container_recipe_arn以及output_resources.0.containers中的image_uris，同时携带扫描配置信息：

resource "aws_imagebuilder_image" "test" { container_recipe_arn = aws_imagebuilder_container_recipe.test.arn infrastructure_configuration_arn = aws_imagebuilder_infrastructure_configuration.test.arn image_scanning_configuration { image_scanning_enabled = true ecr_configuration { repository_name = aws_ecr_repository.test.name container_tags = ["foo", "bar"] } } } data "aws_imagebuilder_image" "test" { arn = aws_imagebuilder_image.test.arn } output "container_uris" { value = data.aws_imagebuilder_image.test.output_resources[0].containers[*].image_uris }

对应验收测试见 image_data_source_test.go，其显式验证了container_recipe_arn、output_resources.0.containers.0.image_uris.#与region在资源与数据源间的一致性。

测试与验证

仓库为aws_imagebuilder_image数据源提供了完整的验收测试（位于 image_data_source_test.go），覆盖三种典型场景：

• 公共 AWS 镜像（TestAccImageBuilderImageDataSource_ARN_aws）：验证通配符 ARN 解析最新版本，以及name、os_version、platform、version、date_created（RFC3339）、output_resources.#等关键字段；
• 自建镜像（TestAccImageBuilderImageDataSource_ARN_self）：通过TestCheckResourceAttrPair断言数据源与aws_imagebuilder_image资源各属性一一对应；
• 容器镜像（TestAccImageBuilderImageDataSource_ARN_containerRecipe）：验证容器配方关联与output_resources.0.containers输出。

若需在本地运行这些测试，可参考仓库 docs/running-and-writing-acceptance-tests.md 配置 AWS 凭据后，使用如下命令（示例，仅验证数据源测试）：

make testacc TESTS=TestAccImageBuilderImageDataSource_ARN_aws PKG=imagebuilder

小结

aws_imagebuilder_image数据源为 Terraform 配置提供了一条只读、幂等地读取 EC2 Image Builder 镜像元数据的途径：通过arn参数配合x.x.x通配符即可始终指向最新构建版本，通过build_version_arn、image_recipe_arn、container_recipe_arn、output_resources、image_scanning_configuration等属性则可获得构建产物与配置细节的完整视图。其底层实现与aws_imagebuilder_image资源共用findImageByARN查询与扁平化辅助函数，保证了数据源导出与资源状态的一致性。在编写依赖镜像 ARN 的配方、流水线或分发配置时，优先使用该数据源是兼顾稳定性与可维护性的推荐做法。

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