Terraform AWS Provider 中 aws_arcregionswitch_plan 数据源:读取 ARC Region Switch 切换计划的完整指南
Terraform AWS Provider 中 aws_arcregionswitch_plan 数据源:读取 ARC Region Switch 切换计划的完整指南
本文围绕 Terraform AWS Provider 的数据源 aws_arcregionswitch_plan 展开。该数据源用于从 AWS ARC(Application Recovery Controller)Region Switch 服务中读取一个既有的容灾切换计划(Plan),获取其恢复策略、目标区域、RTO、执行角色、标签等属性。读完本文,你将了解该数据源的完整参数与导出属性、它在源码中的读取链路(GetPlan → Flatten → ListTagsForResource),以及如何与 aws_arcregionswitch_plan 资源配合在 Terraform 配置中引用已纳管的切换计划。
1. 数据源定位:为什么需要读取 Plan
ARC Region Switch 是 AWS 提供的区域级容灾能力:预先定义好一套“切换计划”(Plan),当主区域发生不可恢复故障时,按预编排的工作流将流量与资源切换到备用区域。Terraform 侧由 plan.go 中的 aws_arcregionswitch_plan 资源负责创建和修改计划,而本文档对应的 plan_data_source.go 则负责“只读引用”——当你需要在一个 Terraform 模块或输出中消费既有 Plan 的元数据(例如把 execution_role 暴露给下游资源、用 primary_region 做分支判断)时,就使用该数据源,而不必重复声明计划本身。
数据源注册带有如下注解(见 plan_data_source.go):
// @FrameworkDataSource("aws_arcregionswitch_plan", name="Plan")
// @Tags(identifierAttribute="arn")
// @Region(overrideDeprecated=true)
// @Testing(altRegionTfVars=true)
其中 @Region(overrideDeprecated=true) 正是文档中 region 参数被标记为 Deprecated 的原因:ARC Region Switch 的 Plan 是全局性质的标识(以 ARN 寻址),单独在数据源上覆盖 region 的意义有限,因此被弃用,仅保留向后兼容。
2. 基本用法(Example Usage)
文档给出的基本用法是直接用 Plan 的 ARN 查询:
data "aws_arcregionswitch_plan" "example" {
arn = "arn:aws:arcregionswitch:us-west-2:123456789012:plan/example-plan"
}
ARN 格式为 arn:aws:arcregionswitch:<region>:<account>:plan/<plan-name>。更常见的实战写法是让数据源直接引用资源创建的 Plan(这种写法也用于仓库的验收测试 plan_data_source_test.go):
data "aws_arcregionswitch_plan" "test" {
arn = aws_arcregionswitch_plan.test.arn
}
resource "aws_arcregionswitch_plan" "test" {
name = "my-plan"
execution_role = aws_iam_role.test.arn
recovery_approach = "activePassive"
regions = ["us-west-2", "us-east-1"]
primary_region = "us-west-2"
workflow {
workflow_target_action = "activate"
workflow_target_region = "us-east-1"
step {
name = "basic-step"
execution_block_type = "ManualApproval"
execution_approval_config {
approval_role = aws_iam_role.test.arn
timeout_minutes = 60
}
}
}
}
上例取自验收测试配置 plan_data_source_test.go:测试中 Plan 的 execution_role 指向一个信任 arc-region-switch.amazonaws.com 服务主体的 IAM 角色,recovery_approach 使用 activePassive(活动/被动),regions 至少包含两个区域(主区域与备用区域),并声明了一个包含手动审批步骤(ManualApproval + execution_approval_config)的工作流。测试随后断言数据源与资源在 arn、name、execution_role、recovery_approach、regions、workflow、%{tags} 等属性上逐一对齐,并验证了 tags.Name、tags.Environment 两个标签键的读出结果。
3. 参数说明(Argument Reference)
数据源支持的入参如下,与 plan_data_source.go 中 Schema 方法的定义一一对应:
| 参数 | 必填/可选 | 说明 |
|---|---|---|
arn |
必填 | ARC Region Switch Plan 的 ARN。源码中该属性挂载了 fwvalidators.ARN() 校验器(plan_data_source.go),配置阶段即会做 ARN 格式校验 |
region |
可选(Deprecated) | 资源所在区域。默认使用 provider 配置中设置的 Region。该服务按全局寻址(测试注释中说明“Cross-region test cases will succeed because aws_arcregionswitch_plan is global”,见 plan_data_source_test.go),跨区域读取同一 Plan 也能成功,因此覆盖 region 的能力已被弃用 |
4. 导出属性(Attribute Reference)
数据源在入参之外导出以下属性(定义见 plan_data_source.go 的 Schema 与 planDataSourceModel 模型):
| 属性 | 类型 | 说明 |
|---|---|---|
description |
string | 计划的描述 |
execution_role |
string | 执行计划所用的 IAM 角色 ARN(资源侧为必填项,数据源侧只读返回) |
name |
string | 计划名称 |
owner |
string | 计划的属主 |
primary_region |
string | 主区域 |
recovery_approach |
string | 恢复策略(如测试中使用的 activePassive) |
recovery_time_objective_minutes |
number(Int32) | 恢复时间目标,单位分钟 |
regions |
list of string | 计划覆盖的区域列表,使用 fwtypes.ListOfStringType 类型 |
tags |
map of string | 资源上的标签映射。注意其定义为 tftags.TagsAttributeComputedOnly(),即纯计算属性,不受 provider 默认标签策略影响 |
updated_at |
string | 计划最后更新时间,使用 timetypes.RFC3339Type 自定义类型,保证值为 RFC3339 时间戳 |
version |
string | 计划版本 |
5. 源码级读取链路:Read 函数如何组装状态
数据源的 Read 方法(plan_data_source.go)执行了四步操作,完整呈现了该数据源的工作机制:
- 获取客户端:
conn := d.Meta().ARCRegionSwitchClient(ctx),从 provider 元数据中取得 ARC Region Switch 的 SDK 客户端; - 按 ARN 查询 Plan:调用
findPlanByARN(ctx, conn, data.ARN.ValueString())。该函数(plan.go)底层执行conn.GetPlan(ctx, &arcregionswitch.GetPlanInput{Arn: aws.String(arn)}),并做了两层错误归一化:- SDK 返回
ResourceNotFoundException时,包装为retry.NotFoundError; - 响应体为空时,返回
EmptyResultError。
- SDK 返回
- 属性平铺:
fwflex.Flatten(ctx, plan, &data)将 SDK 返回的awstypes.Plan结构体按tfsdk标签映射到数据源模型; - 单独拉取标签:ARC Region Switch 的
GetPlan不返回标签,因此源码额外调用listTags(tags_gen.go,底层为ListTagsForResourceAPI)获取标签,再经setTagsOut写入 provider 的标签上下文,最终填充tags属性。
每一步都通过 smerr.AddEnrich / smerr.AddError 附带资源 ID(即 ARN)富化错误信息,便于诊断定位到具体资源。
值得与资源侧对比的一点:资源 aws_arcregionswitch_plan 在 Create 后需要等待最终一致性(waitPlanCreated,见 plan.go,含 Route53 健康检查步骤的额外等待逻辑),而数据源是一次性读取,不引入等待——这意味着如果数据源读取时机紧贴 Plan 创建,理论上可能读到尚不存在的资源,此时上述 NotFound 归一化会把错误清晰地呈现为“资源未找到”,由用户在配置中自行建立依赖关系(如引用 aws_arcregionswitch_plan.test.arn 会自动形成数据源对资源的隐式依赖)。
6. 标签与跨区域测试验证
- 标签验证:plan_data_source_tags_gen_test.go 与 plan_data_source_test.go 覆盖了数据源标签读出的多个场景(含 provider 默认标签合并、标签忽略规则等,对应的测试配置生成在 testdata/Plan/data.tags 等目录);
- 跨区域覆盖:
TestAccARCRegionSwitchPlanDataSource_regionOverride(plan_data_source_test.go)以“资源 region × 数据源 region”的 2×2 组合运行,验证即便显式设置region,跨区域查询同一 Plan ARN 也能成功——这从测试层面印证了第 3 节中region参数被弃用的判断依据。
7. 使用建议与适用前提
- 适用前提:环境中已存在由
aws_arcregionswitch_plan资源(或 AWS 控制台/其他工具)创建的 Plan,且当前凭据具备读取该服务及ListTagsForResource的权限; - 依赖顺序:在 Terraform 中建议通过
arn = aws_arcregionswitch_plan.xxx.arn的方式引用,让 Terraform 自动处理数据源与资源间的依赖,避免读取尚未创建完成的 Plan; - 弃用告警:配置中如仍在使用
region参数会收到弃用提示,建议移除并依赖 provider 级别的 region 配置; - 属性消费:由于
tags是 ComputedOnly 属性,数据源的标签值反映的是远端实际标签,不会合并 provider 的默认标签策略,消费标签时需注意这一点。