Terraform AWS Provider 数据源 aws_organizations_policy 完全指南：按 ID 读取 Organizations 策略详情

Terraform AWS Provider 数据源 aws_organizations_policy 完全指南：按 ID 读取 Organizations 策略详情

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

导读

aws_organizations_policy是 Terraform AWS Provider 提供的 Organizations 服务数据源，用于在仅提供策略 ID（形如p-xxxxxxxx）的情况下，读取 AWS Organizations 中某条策略的完整详情——包括 ARN、策略内容（JSON）、名称、描述、类型以及是否为 AWS 托管策略。本文以 关联文档 为核心骨架，结合 数据源源码、资源实现 与 测试用例，讲解其参数、导出属性、底层调用链与典型组合用法，帮助你在不重复维护策略信息的前提下，把已有策略的元数据与内容安全地引入 Terraform 配置。

一、数据源定位：为什么需要按 ID 读取策略

在 AWS Organizations 中，策略（Policy）分为服务控制策略（SCP）、标签策略（Tag Policy）、备份策略（Backup Policy）、AI 服务退出策略、资源控制策略（RCP）等多种类型。策略在组织架构中被挂载到根（Root）、组织单元（OU）或账号（Account）上。

日常运维中，策略 ID 往往是从其他查询结果中获得的，例如：

• 通过aws_organizations_policies_for_target数据源查出某个目标上挂载的全部策略 ID；
• 通过aws_organizations_organization数据源拿到根节点的enabled_policy_types相关策略；
• 从aws_organizations_policy资源（见 资源文档）创建时返回的id属性中获得。

aws_organizations_policy数据源的价值在于：只凭一个 ID，就能把策略的完整信息（含内容全文）拉取到 Terraform 状态中，从而支持后续的引用、比对与合规校验，无需手工粘贴 JSON。

二、快速上手：完整示例

文档给出的 Basic Usage 演示了最典型的"查询→解析"两段式用法：先用aws_organizations_organization获取组织的根 ID，再用aws_organizations_policies_for_target按策略类型过滤出根上挂载的策略，最后用aws_organizations_policy读取第一条策略的详情。

data "aws_organizations_organization" "current" {} data "aws_organizations_policies_for_target" "current" { target_id = data.aws_organizations_organization.current.roots[0].id filter = "SERVICE_CONTROL_POLICY" } data "aws_organizations_policy" "test" { policy_id = data.aws_organizations_policies_for_target.current.policies[0].id }

读取之后，即可在其他资源中引用其内容，例如把策略 JSON 注入审计配置：

output "scp_content" { value = data.aws_organizations_policy.test.content }

要点说明：示例中data.aws_organizations_policies_for_target.current.policies[0].id表示该数据源导出的policies列表中的第一条；若目标上策略较多，也可以改用ids属性配合toset/for_each批量读取（详见第五节）。

三、Argument Reference：必填参数policy_id

aws_organizations_policy数据源仅有一个必填参数：

该参数在 数据源 schema 定义 中对应如下声明：

"policy_id": { Type: schema.TypeString, Required: true, },

policy_id的常见来源包括：

• aws_organizations_policy资源的id属性（创建后返回）；
• aws_organizations_policies_for_target数据源的policies[*].id或ids[*]；
• 通过terraform import导入时使用的p-12345678形式 ID（参见 资源文档的 Import 部分）；
• 控制台或 AWS CLI 中直接获取。

四、Attribute Reference：导出的全部属性

除policy_id外，该数据源还导出以下只读属性，供配置中任意引用：

这些属性与 数据源源码 中定义的 Schema 一一对应，全部标记为Computed: true（即由 API 返回、不可由用户配置）。

其中type的取值集合，与aws_organizations_policies_for_target数据源的filter参数取值（policies_for_target 文档）及aws_organizations_policy资源type参数的合法值（资源文档）保持一致；资源的合法值还包括BEDROCK_POLICY、INSPECTOR_POLICY、S3_POLICY、SECURITYHUB_POLICY、UPGRADE_ROLLOUT_POLICY等新增类型，从源码结构看数据源的枚举值随 AWS SDK 的PolicyType类型演进。

五、组合用法：批量读取目标上的全部策略

原文档示例只读取了policies[0]。在实际场景中，一个目标（根/OU/账号）上可能挂载多条同类型策略，更通用的写法是配合aws_organizations_policies_for_target的ids列表使用for_each批量解析：

data "aws_organizations_organization" "example" {} data "aws_organizations_policies_for_target" "example" { target_id = data.aws_organizations_organization.example.roots[0].id filter = "SERVICE_CONTROL_POLICY" } data "aws_organizations_policy" "example" { for_each = toset(data.aws_organizations_policies_for_target.example.ids) policy_id = each.value } output "policy_names" { value = { for id, ds in data.aws_organizations_policy.example : id => ds.name } }

这种模式把"发现策略"与"读取策略"解耦：前者负责按目标+类型筛选，后者负责逐一取回详情。其背后的数据流是两个数据源各自调用 AWS Organizations API 完成的（详见第六节）。

六、底层实现：从 Terraform 到 DescribePolicy 的调用链

6.1 读取逻辑

数据源的核心读取函数是 dataSourcePolicyRead：

func dataSourcePolicyRead(ctx context.Context, d *schema.ResourceData, meta any) diag.Diagnostics { conn := meta.(*conns.AWSClient).OrganizationsClient(ctx) policyID := d.Get("policy_id").(string) policy, err := findPolicyByID(ctx, conn, policyID) if err != nil { return sdkdiag.AppendErrorf(diags, "reading Organizations Policy (%s): %s", policyID, err) } policySummary := policy.PolicySummary d.SetId(aws.ToString(policySummary.Id)) d.Set(names.AttrARN, policySummary.Arn) d.Set("aws_managed", policySummary.AwsManaged) d.Set(names.AttrContent, policy.Content) d.Set(names.AttrDescription, policySummary.Description) d.Set(names.AttrName, policySummary.Name) d.Set(names.AttrType, policySummary.Type) return diags }

可以看到几个关键实现事实：

• SetId使用策略 ID 本身：数据源读取后把policy_id作为 state 中的 ID，与 资源实现 中d.SetId(aws.ToString(outputRaw.(*organizations.CreatePolicyOutput).Policy.PolicySummary.Id))的做法一致；
• 详情来自两个数据块：Policy.PolicySummary（元数据：ARN、名称、描述、类型、是否 AWS 托管）与Policy.Content（策略正文）共同组成返回结构，这与 AWS SDK 的DescribePolicy输出结构一致；
• 错误处理：读取失败时通过sdkdiag.AppendErrorf返回带上下文的诊断信息，提示无法找到对应策略 ID。

6.2 查询函数 findPolicyByID / findPolicy

数据源与资源共用底层的查找函数，定义于 policy.go：

func findPolicyByID(ctx context.Context, conn *organizations.Client, id string) (*awstypes.Policy, error) { input := organizations.DescribePolicyInput{ PolicyId: aws.String(id), } return findPolicy(ctx, conn, &input) } func findPolicy(ctx context.Context, conn *organizations.Client, input *organizations.DescribePolicyInput) (*awstypes.Policy, error) { output, err := conn.DescribePolicy(ctx, input) if errs.IsA*awstypes.AWSOrganizationsNotInUseException || errs.IsA*awstypes.PolicyNotFoundException { return nil, &retry.NotFoundError{LastError: err} } if err != nil { return nil, err } if output == nil || output.Policy == nil || output.Policy.PolicySummary == nil { return nil, tfresource.NewEmptyResultError() } return output.Policy, nil }

值得注意的边界处理：

• AWSOrganizationsNotInUseException：当账号尚未启用 Organizations（组织未创建）时，API 会抛出此异常，这里被归一化为NotFoundError，Terraform 会报出"读取失败"而非 panic；
• PolicyNotFoundException：传入不存在的policy_id时同样转为NotFoundError；
• 空结果防御：API 返回nil或缺少PolicySummary时返回EmptyResultError，防止下游空指针。

6.3 上游：policies_for_target 的分页查询

当示例同时使用aws_organizations_policies_for_target时，其读取逻辑（policies_for_target_data_source.go）调用organizations.ListPoliciesForTargetAPI，并通过NewListPoliciesForTargetPaginator分页拉取全部策略，再映射出ids列表。这意味着：即使目标上挂载的策略超过单页返回上限，组合用法也能完整枚举。

七、测试与验证：数据源的正确性保证

仓库在 policy_data_source_test.go 中为数据源提供了验收测试（acceptance test）。测试testAccPolicyDataSource_UnattachedPolicy的核心步骤：

1. 创建启用多种策略类型的组织（feature_set = "ALL"，启用 SCP、Tag、Backup、AI 退出策略）；
2. 创建一条允许*操作的策略资源；
3. 用aws_organizations_policy数据源按资源 ID 读取；
4. 断言数据源的policy_id、arn、content、type、name与资源属性完全一致：

resource.TestCheckResourceAttrPair(resourceName, names.AttrID, dataSourceName, "policy_id"), resource.TestCheckResourceAttrPair(resourceName, names.AttrARN, dataSourceName, names.AttrARN), resource.TestCheckResourceAttrPair(resourceName, names.AttrContent, dataSourceName, names.AttrContent), resource.TestCheckResourceAttrPair(resourceName, names.AttrType, dataSourceName, names.AttrType), resource.TestCheckResourceAttrPair(resourceName, names.AttrName, dataSourceName, names.AttrName),

同时，policies_for_target_data_source_test.go 中的集成场景把策略创建、挂载（aws_organizations_policy_attachment，见 attachment 文档）、按目标查询、按 ID 解析串成一条完整链路，验证了"根→OU→策略挂载→查询→解析"全流程的数据一致性。

注意：这些测试需要真实的 AWS Organizations 管理账号环境，通过acctest.PreCheckOrganizationsAccount前置检查跳过未配置的 CI 环境，属于标准的 Terraform Provider 验收测试模式。

八、典型实战：用数据源做策略合规校验

将数据源与content属性结合，可以在纯 Terraform 层面对已有策略做只读校验，例如检测根上是否存在"全 Allow"的宽松 SCP：

data "aws_organizations_organization" "current" {} data "aws_organizations_policies_for_target" "root_scps" { target_id = data.aws_organizations_organization.current.roots[0].id filter = "SERVICE_CONTROL_POLICY" } data "aws_organizations_policy" "root_scp" { for_each = toset(data.aws_organizations_policies_for_target.root_scps.ids) policy_id = each.value } locals { permissive_scps = { for id, ds in data.aws_organizations_policy.root_scp : ds.name => id if length(regexall("\"Effect\"\\s*:\\s*\"Allow\"", ds.content)) > 0 && length(regexall("\"Action\"\\s*:\\s*\"\\*\"", ds.content)) > 0 } } output "permissive_scps" { value = local.permissive_scps }

此例展示了数据源"只读引入外部状态"的核心价值：不修改任何 AWS 资源，仅把策略正文拉入 Terraform 做本地分析，输出不符合预期的策略名称，供人工审计。

九、注意事项与边界情况

1. 策略必须真实存在：policy_id指向不存在的策略时，底层DescribePolicy返回PolicyNotFoundException，数据源读取会失败（详见 findPolicy）。
2. 组织需已启用：未创建组织时 API 返回AWSOrganizationsNotInUseException，同样会报错。
3. AWS 托管策略的特殊性：数据源可以正常读取 AWS 托管策略（aws_managed = true），但 资源实现 在读取到托管策略时会给出警告——它们不能被terraform import管理，引用时应直接使用 ID 或改由数据源获取。因此若你只想"读取"一条托管 SCP 的详情，数据源正是官方推荐的只读途径。
4. 类型枚举差异：type导出值的枚举随 AWS API 演进，policies_for_target 数据源 与 policy 数据源中的枚举集合可能不同步，撰写过滤条件时以 policies_for_target 文档 所列 7 种 filter 为准。

十、相关文档与源码索引

• 本文主体：数据源文档 website/docs/d/organizations_policy.html.markdown
• 数据源实现：internal/service/organizations/policy_data_source.go
• 共用查询函数：internal/service/organizations/policy.go
• 数据源验收测试：internal/service/organizations/policy_data_source_test.go
• 上游按目标查询数据源：policies_for_target 文档 与 实现
• 配套资源：aws_organizations_policy 资源文档、aws_organizations_policy_attachment 资源文档
• 同服务的批量策略列表数据源：aws_organizations_policies 数据源
• 扩展阅读：仓库内基于策略数据做合规分析的指南 Tag Policy 合规指南

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