Terraform AWS Provider 中 aws_arcregionswitch_plan 数据源:读取 ARC Region Switch 切换计划的完整指南

原创2026-09-16 15:56:281,757 阅读
文章标签:IaC云原生DevOps运维配置管理

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)执行了四步操作,完整呈现了该数据源的工作机制:

  1. 获取客户端:conn := d.Meta().ARCRegionSwitchClient(ctx),从 provider 元数据中取得 ARC Region Switch 的 SDK 客户端;
  2. 按 ARN 查询 Plan:调用 findPlanByARN(ctx, conn, data.ARN.ValueString())。该函数(plan.go)底层执行 conn.GetPlan(ctx, &arcregionswitch.GetPlanInput{Arn: aws.String(arn)}),并做了两层错误归一化:
    • SDK 返回 ResourceNotFoundException 时,包装为 retry.NotFoundError;
    • 响应体为空时,返回 EmptyResultError。
  3. 属性平铺:fwflex.Flatten(ctx, plan, &data) 将 SDK 返回的 awstypes.Plan 结构体按 tfsdk 标签映射到数据源模型;
  4. 单独拉取标签:ARC Region Switch 的 GetPlan 不返回标签,因此源码额外调用 listTags(tags_gen.go,底层为 ListTagsForResource API)获取标签,再经 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 的默认标签策略,消费标签时需注意这一点。

8. 相关仓库位置

内容 路径
数据源文档页 website/docs/d/arcregionswitch_plan.html.markdown
数据源实现 internal/service/arcregionswitch/plan_data_source.go
资源实现(对照参考) internal/service/arcregionswitch/plan.go
数据源验收测试 internal/service/arcregionswitch/plan_data_source_test.go
标签生成代码 internal/service/arcregionswitch/tags_gen.go
服务包注册 internal/service/arcregionswitch/service_package_gen.go
服务包说明 internal/service/arcregionswitch/README.md
登录后查看全文
terraform-provider-aws