使用 Terraform AWS Provider 的 aws_network_acls 数据源:按 VPC、标签与过滤器批量查询网络 ACL ID
使用 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)清晰地展示了三种筛选条件的组装顺序:
vpc_id参数 → 通过newAttributeFilterList构造vpc-id过滤器。该函数对过滤条件按键名排序以保证输出确定性,并对空值直接跳过(internal/service/ec2/filters.go)。tags参数 → 通过newTagFilterList将每个标签转换为tag:<key>形式的过滤器(internal/service/ec2/filters.go)。filter子块 → 通过newCustomFilterList将 Schema 中的filterSet 逐块转换为 EC2Filter,每个块的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,规划配置时务必区分两种匹配逻辑。