使用 Terraform AWS Provider 的 aws_network_acls 数据源:按 VPC、标签与过滤器批量查询网络 ACL ID

原创2026-09-18 09:30:531,634 阅读
文章标签:IaC云原生DevOps运维配置管理

使用 Terraform AWS Provider 的 aws_network_acls 数据源:按 VPC、标签与过滤器批量查询网络 ACL ID

aws_network_acls 是 Terraform AWS Provider(terraform-provider-aws)中用于批量查询网络 ACL(Network ACL)ID 列表的数据源,适用于 VPC(Virtual Private Cloud)网络规划与治理场景。通过本文你可以掌握如何在一个 VPC 内一次性取出全部网络 ACL ID、按标签精确筛选,以及借助 filter 子块(例如按子网关联关系)实现更复杂的过滤条件,并了解其底层基于 EC2 DescribeNetworkAcls API 的分页实现与测试验证方式。

数据源定位:批量查询 vs 单资源查询

在网络 ACL 的 Terraform 编排中,Provider 提供了两类查询入口:

  • aws_network_acl:查询单个网络 ACL 的完整属性(规则、关联子网等);
  • aws_network_acls(本文主题):只返回网络 ACL 的 ID 列表,用于批量枚举、配合 for_each/count 做引用或巡检。

官方文档对该数据源的描述为 "Provides a list of network ACL ids for a VPC"(website/docs/d/network_acls.html.markdown),其本质是一次基于 EC2 API 的列表查询,而非读取单个资源详情。与单资源数据源相比,它更轻量、更擅长处理"这个 VPC 里到底有哪些网络 ACL"这类集合型问题。

基础用法:输出 VPC 内全部网络 ACL ID

最直接的用法是仅指定 vpc_id,输出该 VPC 下所有网络 ACL 的 ID:

data "aws_network_acls" "example" {
  vpc_id = var.vpc_id
}

output "example" {
  value = data.aws_network_acls.example.ids
}

几点说明:

  • vpc_id 是可选参数。不指定时,数据源会查询整个 Region 的网络 ACL(此时建议配合 filter 或 tags 收敛结果,避免返回过多数据)。
  • 一个 VPC 创建时会自动生成一个默认网络 ACL,因此即使你没有显式创建任何 aws_network_acl 资源,查询结果也至少会包含该默认 ACL。测试用例 TestAccVPCNetworkACLsDataSource_vpcID 正是利用了这一特性(见下文"测试验证"部分)。
  • ids 是 Computed(计算属性)的字符串列表,可直接用于 for_each 或循环遍历。

按标签筛选:精确定位目标网络 ACL

当 VPC 内存在多个网络 ACL(例如按 Tier 分层规划)时,可以通过 tags 映射进行精确匹配:

data "aws_network_acls" "example" {
  vpc_id = var.vpc_id

  tags = {
    Tier = "Private"
  }
}

tags 的匹配语义是每个标签键值对都必须与目标网络 ACL 上的标签完全一致(AND 语义),最终只返回标签完全匹配的网络 ACL ID。从实现上看,该参数最终会被转换为形如 tag:Tier = "Private" 的 EC2 过滤器(详见"底层实现原理"一节),因此多个标签之间是同时满足的关系。

使用 filter 子块:按子网关联等复杂条件过滤

对于 vpc_id 和 tags 无法表达的查询条件,可以使用一个或多个 filter 子块。下面的示例查询与某个特定子网(aws_subnet.test)关联的网络 ACL:

data "aws_network_acls" "example" {
  vpc_id = var.vpc_id

  filter {
    name   = "association.subnet-id"
    values = [aws_subnet.test.id]
  }
}

filter 子块支持两个参数:

参数 是否必填 说明
name 必填 要过滤的字段名,取值以底层 EC2 DescribeNetworkAcls API 支持的过滤器为准
values 必填 该字段可接受的取值集合,只要命中其中任意一个值,网络 ACL 即被选中(OR 语义)

常见的过滤器字段包括:

  • network-acl-id:按网络 ACL ID 精确匹配;
  • association.subnet-id:按关联子网 ID 匹配;
  • association.association-id:按关联 ID 匹配;
  • vpc-id:按 VPC ID 匹配(与 vpc_id 参数效果一致);
  • tag:<key> / tag-key / tag-value:按标签相关字段匹配。

需要注意:filter 块之间以及 filter 与 vpc_id、tags 之间是**同时生效(AND)的关系;而在单个 filter 块内部,values 中的多个取值是任一命中(OR)**的关系。

参数参考(Argument Reference)

除上述示例用到的参数外,数据源还支持:

  • region - (可选)数据源发起查询的 AWS 区域,默认使用 Provider 配置中设置的区域。该参数将数据源查询范围限定在指定区域。
  • vpc_id - (可选)希望在其中筛选网络 ACL 的 VPC ID。
  • tags - (可选)标签映射,每一对键值都必须与目标网络 ACL 上的标签完全一致。
  • filter - (可选)自定义过滤器子块,支持一个或多个,定义方式如上表。

属性参考(Attribute Reference)

除上述参数外,数据源导出以下属性:

  • id - AWS 区域(数据源自身 ID 被设置为发起查询的区域名,而非某个网络 ACL 的 ID)。
  • ids - 查询到的全部网络 ACL ID 列表。

底层实现原理:从配置到 EC2 API 的调用链

数据源在仓库中的实现位于 internal/service/ec2/vpc_network_acls_data_source.go,注册注解为 @SDKDataSource("aws_network_acls", name="Network ACLs")。其读取流程(dataSourceNetworkACLsRead)清晰地展示了三种筛选条件的组装顺序:

  1. vpc_id 参数 → 通过 newAttributeFilterList 构造 vpc-id 过滤器。该函数对过滤条件按键名排序以保证输出确定性,并对空值直接跳过(internal/service/ec2/filters.go)。
  2. tags 参数 → 通过 newTagFilterList 将每个标签转换为 tag:<key> 形式的过滤器(internal/service/ec2/filters.go)。
  3. filter 子块 → 通过 newCustomFilterList 将 Schema 中的 filter Set 逐块转换为 EC2 Filter,每个块的 name 与 values 一一对应(internal/service/ec2/filters.go)。

组装完成后,调用 findNetworkACLs 执行查询。该函数位于 internal/service/ec2/find.go,其核心行为包括:

  • 使用 EC2 DescribeNetworkAcls 的分页器(ec2.NewDescribeNetworkAclsPaginator)自动翻页,将每一页的 NetworkAcls 追加到结果集中,因此对大规模 VPC 也能完整取回全部网络 ACL;
  • 将 InvalidNetworkACLIDNotFound 错误转换为 retry.NotFoundError,便于上层统一做"未找到"语义处理;
  • 最后将所有结果中的 NetworkAclId 提取为字符串列表写入 ids,并将数据源 id 设置为当前 Region。

从 Schema 定义(internal/service/ec2/vpc_network_acls_data_source.go)还可以确认:ids 与 tags 均为 Computed(只读计算属性),而 vpc_id 为可选项,filter 则复用了 EC2 数据源通用的 customFiltersSchema——这也是整个 EC2 服务中大量"按条件枚举资源"类数据源的统一模式。

测试验证:五种场景覆盖

仓库通过 internal/service/ec2/vpc_network_acls_data_source_test.go 提供了覆盖完整行为的验收测试(acctest):

测试用例 验证点 期望结果
TestAccVPCNetworkACLsDataSource_basic 无任何过滤条件全量查询 ids.# 大于 1
TestAccVPCNetworkACLsDataSource_filter 按 network-acl-id 过滤 ids.# 等于 1
TestAccVPCNetworkACLsDataSource_tags 按标签精确匹配 ids.# 等于 2
TestAccVPCNetworkACLsDataSource_vpcID 按 vpc_id 过滤 ids.# 等于 3(含 VPC 默认网络 ACL)
TestAccVPCNetworkACLsDataSource_empty 无匹配结果 ids.# 等于 0

测试配置(如 internal/service/ec2/vpc_network_acls_data_source_test.go)展示了标准配套写法:先创建 aws_vpc 和两个 aws_network_acl 资源,再通过 depends_on 确保数据源读取时机正确。这组测试既验证了各种过滤组合的正确性,也证实了"VPC 自带默认网络 ACL"这一事实行为。

超时配置(Timeouts)

数据源的读取操作支持超时配置,read 默认值为 20m(website/docs/d/network_acls.html.markdown),与源码中 Timeouts.Read 的 20 * time.Minute 默认值一致(internal/service/ec2/vpc_network_acls_data_source.go)。可通过 timeouts 块按需调整:

data "aws_network_acls" "example" {
  vpc_id = var.vpc_id

  timeouts {
    read = "30m"
  }
}

实战建议

  • 优先收敛查询范围:在大型账号中,建议始终携带 vpc_id 或 filter/tags 之一,避免全 Region 扫描带来不必要的 API 开销;
  • 与单资源数据源配合:需要读取网络 ACL 的规则详情时,可将本数据源的 ids 输出与 aws_network_acl 数据源或资源配合,通过 for_each 逐个处理;
  • 理解默认 ACL:VPC 自带默认网络 ACL 会被计入查询结果,编写依赖数量断言的自动化测试时应将其纳入预期;
  • 过滤器语义:跨块条件为 AND、块内 values 为 OR,规划配置时务必区分两种匹配逻辑。
登录后查看全文
terraform-provider-aws