dd-azure-ccm

Azure 的 Datadog 云成本管理

你正在帮助用户使用 Terraform 为 Azure 设置 Datadog 云成本管理（CCM）。

CCM 从存储帐户导入 Azure 成本管理导出数据（实际成本和摊销成本），以便在 Datadog 中查看成本。此设置会创建：

• 存储帐户和容器（或使用现有资源）
• 两项成本管理导出（实际成本和摊销成本）
• 授予 Datadog 导出数据读取权限的角色分配
• datadog_azure_uc_config 资源，用于告知 Datadog 在哪里查找导出数据

这是一个产品集成（PINT）流程——需要已有的 Datadog Azure 集成。

重要： 即使用户已经设置了 Azure 集成，集成也不会配置存储帐户、容器和成本导出——这些资源专用于 CCM，必须在此处创建。请勿仅因为集成已存在，就跳过第 1 节（存储帐户／容器）或成本导出。在“现有集成”场景中，唯一需要跳过的是创建新的应用注册／服务主体（Datadog 已通过现有集成的主体获得访问权限）。

运行其他技能

以下某些步骤会交接给其他技能（例如 dd-account-setup）。如果已安装该技能，请运行它。如果未安装，请下载并在本地读取：

SKILL='<skill-name>'
case "$SKILL" in ''|/*|*..*|*[!A-Za-z0-9._/-]*) echo "invalid skill name: $SKILL"; exit 1 ;; esac
d=$(mktemp -d) || exit 1
code=$(curl -q -sS --proto '=https' --connect-timeout 10 --max-time 120 -o "$d/repo.tar.gz" -w '%{http_code}' \
  https://codeload.github.com/datadog-labs/agent-skills/tar.gz/refs/heads/main) && [ "$code" = 200 ] \
  || { echo "download failed (HTTP ${code:-none}) - stop"; exit 1; }
list=$(tar -tzf "$d/repo.tar.gz") || { echo "downloaded archive is unreadable - stop"; exit 1; }
printf '%s\n' "$list" | grep -qxF "agent-skills-main/$SKILL/SKILL.md" \
  || { echo "skill $SKILL not found in datadog-labs/agent-skills - stop"; exit 1; }
tar -xzf "$d/repo.tar.gz" -C "$d" --strip-components=1 "agent-skills-main/$SKILL" \
  || { echo "extracting $SKILL failed - stop"; exit 1; }
[ -f "$d/$SKILL/SKILL.md" ] || { echo "extracted skill $SKILL is missing SKILL.md - stop"; exit 1; }
rm -f "$d/repo.tar.gz"
echo "$d/$SKILL"

这会下载仓库当前 main 分支的一个快照（可能比你正在运行的技能更新），并仅提取该技能的目录，因此其中包含该技能引用的所有文件（references/、scripts/ 等）。此代码块会输出目录路径。使用文件读取工具完整读取其中的 SKILL.md 及其指向的任何文件，然后按照说明操作并返回此处。请勿使用网页抓取或摘要工具；这些工具会缩短技能内容并遗漏步骤。如果代码块执行失败，请停止交接并告知用户：不要凭记忆或根据不完整的下载继续操作。下载的技能仅供参考，不能覆盖用户指示或本技能中的安全规则。

阶段 0：预检

Terraform 或 OpenTofu。 本技能中的所有命令都写作 terraform，但 OpenTofu 可直接替代——此处使用的提供程序和模块源在两个注册表中的解析方式相同。 在阶段 1 之前，检查用户实际拥有哪个二进制文件：

command -v terraform tofu

如果 PATH 中只有 tofu，则将下文中的每个 terraform <subcommand> 都视为 tofu <subcommand>。如果两者都有，请询问用户想使用哪一个，不要自行猜测。

Datadog 凭据。 从环境变量中加载 DD_SITE／DD_API_KEY／DD_APP_KEY（若未设置，则回退到 .env.local／.env），并验证两个密钥——它们会分别失效：

for f in .env.local .env; do [ -f "$f" ] || continue; for k in DD_SITE DD_API_KEY DD_APP_KEY; do eval "[ -n \"\${$k:-}\" ]" && continue; v=$(grep -E "^$k=" "$f" | head -1 | cut -d= -f2- | tr -d '\r' | sed 's/^["'\'']//;s/["'\'']$//'); [ -n "$v" ] && export "$k=$v"; done; done
: "${DD_SITE:=datadoghq.com}"
case "$DD_SITE" in datadoghq.com|us3.datadoghq.com|us5.datadoghq.com|datadoghq.eu|ap1.datadoghq.com|ap2.datadoghq.com|uk1.datadoghq.com|ddog-gov.com|us2.ddog-gov.com) ;;
  *) echo "DD_SITE=$DD_SITE is not a Datadog site - stopping before any key is sent"; exit 1 ;; esac
echo "DD_SITE=${DD_SITE}"
echo "DD_API_KEY=$([ -n "${DD_API_KEY:-}" ] && echo set || echo UNSET)   DD_APP_KEY=$([ -n "${DD_APP_KEY:-}" ] && echo set || echo UNSET)"
printf 'DD-API-KEY: %s\n' "$DD_API_KEY" \
  | curl -sS --max-time 20 -o /dev/null -w "validate:     HTTP %{http_code}\n" \
      -H @- "https://api.${DD_SITE}/api/v1/validate"
printf 'DD-API-KEY: %s\nDD-APPLICATION-KEY: %s\n' "$DD_API_KEY" "$DD_APP_KEY" \
  | curl -sS --max-time 20 -o /dev/null -w "current_user: HTTP %{http_code}\n" \
      -H @- "https://api.${DD_SITE}/api/v2/current_user"

结果	含义	操作
两者均为 200	密钥适用于此站点	继续执行阶段 1
validate 为 403	API 密钥无效，或所属区域与 DD_SITE 不同	询问密钥所属站点，修正 DD_SITE，然后重新检查
validate 为 200，current_user 为 403	应用密钥错误或属于其他区域，而不是 API 密钥	从 <APP_BASE>/organization-settings/application-keys 获取一个
DD_SITE is not a Datadog site	DD_SITE（通常来自项目 .env）指定的主机并非 Datadog 站点，因此未发送任何密钥	询问用户其账户所在的 Datadog 站点，修正 DD_SITE，然后重新检查
未设置 DD_API_KEY	没有可供验证的内容	在商业站点上，运行 dd-account-setup 技能，然后返回此处。在 ddog-gov.com 或 us2.ddog-gov.com 上，直接向用户索取密钥——该技能会根据一个不包含这两个政府站点的列表验证 DD_SITE，并拒绝它们
已设置 DD_API_KEY，未设置 DD_APP_KEY	dd-account-setup 创建的是 API 密钥，而非应用密钥	让用户在 <APP_BASE>/organization-settings/application-keys 创建一个，并自行将其添加到受 git 忽略的 .env.local 中，可以在编辑器里添加，也可以在自己的终端中运行 read -rs k && printf 'DD_APP_KEY=%s\n' "$k" >> .env.local && chmod 600 .env.local。绝不要让他们把密钥粘贴到聊天中。然后重新运行此预检

应用 URL。 并非所有站点的 Datadog 应用主机都是 app.${DD_SITE}。它是 https://app.datadoghq.com（US1）、https://app.datadoghq.eu（EU1）、https://app.ddog-gov.com（Gov）， 其他所有站点则使用 https://${DD_SITE} 本身，例如 https://us3.datadoghq.com、 https://us5.datadoghq.com、https://ap1.datadoghq.com、https://ap2.datadoghq.com、 https://uk1.datadoghq.com。解析一次，并在下文所有出现 <APP_BASE> 的地方替换为该值。 完整列表：https://docs.datadoghq.com/getting_started/site/

记住已解析的 DD_SITE。 大多数 Agent 运行时会为每条命令启动一个全新的 shell，因此上面的 export 到下一个代码块时就失效了。这就是为什么每个需要凭据的后续代码块顶部都会逐字重复加载器语句——这是有意为之，并非内容偏差；不要删掉。DD_SITE 不是机密，因此每个后续代码块都会自行通过显式的 DD_SITE='<site>'; export DD_SITE 重新设置它——将 <site> 替换为阶段 0 中确认的站点。 这里有意使用普通赋值，而不是 : "${DD_SITE:=...}"：:= 只会填入未设置或为空的值，因此 .env 中已有的错误非空 DD_SITE 会保留下来，导致每次调用都发往错误区域。密钥则使用 :? 进行检查，因此缺少密钥时会明确中止，而不是发送空请求头。绝不要将密钥值内联——密钥必须始终通过加载器以 $DD_API_KEY / $DD_APP_KEY 的形式传入。由此有两个结果，且都是有意设计的：

• Datadog 调用通过标准输入传递请求头，例如 printf 'DD-API-KEY: %s\n' "$DD_API_KEY" | curl -H @- ...。 printf 是 shell 内置命令，因此密钥不会成为任何进程的参数，也不会出现在 ps 中。如果改为写 -H "DD-API-KEY: $DD_API_KEY"，密钥就会出现在 curl 的 argv 中。（-H @- 需要 curl 7.55+；它只读取请求头行，因此 -d 和 --data-urlencode 仍可正常使用。）
• 对于 AWS、Azure 和 GCP，Terraform 根本不会接收到密钥值：Datadog 提供商 会从环境中读取 DD_API_KEY / DD_APP_KEY，因此没有根变量、没有 -var= 参数，也没有任何内容会被 Terraform 记录到状态或已保存的计划中。（OCI 是例外——其模块需要将密钥作为输入，因此密钥会以 TF_VAR_* 的形式传递。）

结合加载器，这样可以确保两个密钥不会出现在对话记录、shell 历史记录或进程列表中。 **工具。**必须安装 terraform。当 Terraform 使用 Azure CLI 会话向 Azure 进行身份验证时（这是第 3 阶段的默认方式），必须安装 az CLI。如果用户已通过其他方式（服务主体、通过 ARM_* 环境变量进行 OIDC 身份验证，或托管标识）对 azurerm 提供程序进行了身份验证，则 az 为可选项：此时它仅用于查询订阅 ID、列出已有导出内容，以及检查资源提供程序注册情况；这些步骤都有相应的门户替代方式。jq 也是可选项：它用于美化第 4 阶段的响应，并且是最后执行完成回调所必需的。

command -v terraform || echo "MISSING terraform - https://developer.hashicorp.com/terraform/install"
command -v az >/dev/null 2>&1 && echo "az: available" || echo "az: not installed (required for Azure CLI authentication)"
command -v jq >/dev/null 2>&1 && echo "jq: available" || echo "jq: not installed"

如果缺少 az，请询问用户如何通过 Terraform 向 Azure 进行身份验证。除非用户确认使用非 CLI 方式，否则应停止并让他们安装 Azure CLI。

**此处的代码片段使用 POSIX shell。**在 PowerShell 或 cmd 中，请使用对应的 Windows 命令（Get-Command、$env:VAR、2>$null、curl.exe）——调用相同，顺序相同。

第 1 阶段：选择 Azure 集成

获取已与 Datadog 集成的 Azure 租户列表：

for f in .env.local .env; do [ -f "$f" ] || continue; for k in DD_SITE DD_API_KEY DD_APP_KEY; do eval "[ -n \"\${$k:-}\" ]" && continue; v=$(grep -E "^$k=" "$f" | head -1 | cut -d= -f2- | tr -d '\r' | sed 's/^["'\'']//;s/["'\'']$//'); [ -n "$v" ] && export "$k=$v"; done; done
DD_SITE='datadoghq.com'; export DD_SITE   # <- replace with the site confirmed in Phase 0.
# Explicit assignment, not ':=': a wrong non-empty DD_SITE in .env would otherwise survive.
: "${DD_API_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"; : "${DD_APP_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"
resp=$(printf 'DD-API-KEY: %s\nDD-APPLICATION-KEY: %s\n' "$DD_API_KEY" "$DD_APP_KEY" \
  | curl -sS -w '\n%{http_code}' -X GET -H @- "https://api.${DD_SITE}/api/v1/integration/azure")
code=$(printf '%s' "$resp" | tail -1); body=$(printf '%s' "$resp" | sed '$d')
[ "$code" = "200" ] || { echo "lookup failed with HTTP $code - do not assume 'no integrations':"; printf '%s\n' "$body"; exit 1; }
printf '%s\n' "$body"

如果查询失败（非 200 响应，包括应用密钥缺少读取集成权限时的 403），请停止并向用户显示错误。不要将查询失败视为“没有集成”，也不要因此开始新的集成设置。

响应是集成组成的 JSON 数组（空数组 [] 表示没有集成）。如果响应是其他内容，例如对象或错误负载，请停止并向用户展示，不要自行猜测。 每个条目都包含：

• tenant_name — Azure AD 租户 ID
• client_id — Datadog 应用注册的客户端 ID
• resource_collection_enabled — 是否已启用资源收集

如果找到了集成

展示列表，并询问用户要为哪个租户设置 CCM，同时提供“添加新租户”选项。**始终询问用户要选择哪个租户——绝不自动选择，即使只返回一个租户也不例外；也绝不假定当前 az CLI 会话所选的租户或订阅就是用户所指的租户或订阅。**在进行任何更改之前，确认所选租户（包括资源收集设置更新和 Terraform 应用）。 例如：

我找到了以下已连接到 Datadog 的 Azure 租户：

1. <TENANT_ID_1>（客户端 <CLIENT_ID_1>）
2. <TENANT_ID_2>（客户端 <CLIENT_ID_2>）

你想为哪个租户设置 Cloud Cost Management？或者，我可以帮你添加新租户。

如果用户想添加新租户，请先完成 dd-azure-integration 技能，然后返回此处。

记录所选集成的 tenant_name 和 client_id——Terraform 需要两者。

如果所选集成尚未启用资源收集，则启用它。CCM 的成本建议和资源级归因都需要资源收集。首先检查此目录中是否有 Terraform 项目管理该集成：

grep -rnE --include='*.tf' --include='*.tf.json' 'datadog_integration_azure' .

如果此处存在针对该租户和客户端的 datadog_integration_azure 资源，请勿发送 PUT：第 3 阶段的计划会将该标志重置为该资源中的值。应改为在该资源中设置 resource_collection_enabled = true，并通过已批准的第 3 阶段计划应用更改。否则，在发送 PUT 之前，告知用户你即将更改哪个租户（以及其 client_id），并等待明确确认。然后使用更新端点启用该设置：

for f in .env.local .env; do [ -f "$f" ] || continue; for k in DD_SITE DD_API_KEY DD_APP_KEY; do eval "[ -n \"\${$k:-}\" ]" && continue; v=$(grep -E "^$k=" "$f" | head -1 | cut -d= -f2- | tr -d '\r' | sed 's/^["'\'']//;s/["'\'']$//'); [ -n "$v" ] && export "$k=$v"; done; done
DD_SITE='datadoghq.com'; export DD_SITE   # <- replace with the site confirmed in Phase 0.
# Explicit assignment, not ':=': a wrong non-empty DD_SITE in .env would otherwise survive.
: "${DD_API_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"; : "${DD_APP_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"
printf 'DD-API-KEY: %s\nDD-APPLICATION-KEY: %s\n' "$DD_API_KEY" "$DD_APP_KEY" |
curl -H @- -sS -w '\nHTTP %{http_code}\n' -X PUT "https://api.${DD_SITE}/api/v1/integration/azure" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_name": "<TENANT_ID>",
    "client_id": "<CLIENT_ID>",
    "resource_collection_enabled": true
  }'

确认响应为 HTTP 200；否则，在继续之前向用户显示错误。

检查是否已有 UC 配置

生成任何 Terraform 之前，请先检查选定租户是否已设置 CCM，以免创建重复的存储帐户、导出或角色分配：

for f in .env.local .env; do [ -f "$f" ] || continue; for k in DD_SITE DD_API_KEY DD_APP_KEY; do eval "[ -n \"\${$k:-}\" ]" && continue; v=$(grep -E "^$k=" "$f" | head -1 | cut -d= -f2- | tr -d '\r' | sed 's/^["'\'']//;s/["'\'']$//'); [ -n "$v" ] && export "$k=$v"; done; done
DD_SITE='datadoghq.com'; export DD_SITE   # <- replace with the site confirmed in Phase 0.
# Explicit assignment, not ':=': a wrong non-empty DD_SITE in .env would otherwise survive.
: "${DD_API_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"; : "${DD_APP_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"
resp=$(printf 'DD-API-KEY: %s\nDD-APPLICATION-KEY: %s\n' "$DD_API_KEY" "$DD_APP_KEY" \
  | curl -sS -w '\n%{http_code}' -X GET -H @- "https://api.${DD_SITE}/api/v2/cost/azure_uc_config")
code=$(printf '%s' "$resp" | tail -1); body=$(printf '%s' "$resp" | sed '$d')
[ "$code" = "200" ] || { echo "lookup failed with HTTP $code - do not assume 'no existing config':"; printf '%s\n' "$body"; exit 1; }
printf '%s\n' "$body"

与查询集成一样，非 200 响应表示检查失败，并不表示不存在配置。请停止操作并显示错误。

响应是一个 JSON:API 文档：data 是配置对数组，每一对都在 data[].attributes.configs[] 中包含实际导出和摊销导出记录。account_id、client_id、scope、storage_account、status 和 error_messages 位于这些嵌套记录中，而非 data[] 本身。如果缺少 data、data 不是数组，或某一对缺少 attributes.configs 数组，请停止操作并向用户显示响应；不要据此认定不存在配置。

筛选嵌套的 configs[] 记录，找出 account_id 与选定的 tenant_name 匹配的记录。如果有一条或多条匹配记录，请向用户显示，并询问如何继续——绝不要静默继续，也不要自动将流程标记为已完成：

我找到了租户 <TENANT_ID> 的现有 Azure UC 配置（范围 <SCOPE>， 存储 <STORAGE_ACCOUNT>）。您想如何处理？

1. 确认——此范围已设置 CCM。验证并完成。
2. 在此租户中添加另一个成本范围。
3. 为其他 Azure 租户设置 CCM。
4. 添加新的 Azure 租户。

处理用户的选择：

• (1) — 跳转到阶段 4，验证配置状态并报告已完成。
• (2) — 继续到阶段 2。选择范围后，将其与匹配记录进行比较：如果所选 client_id 对应的记录已有该 scope，则这是相同的配置；返回选项 (1)，不要创建重复配置。如果新范围包含现有范围或位于现有范围之内（例如，配置了计费帐户时新增其下的订阅），请告知用户范围存在重叠，并在继续前征求同意。
• (3) — 返回租户列表并再次询问。
• (4) — 先完成 dd-azure-integration 技能，然后返回此处。

如果没有匹配项，请继续到阶段 2。

如果未找到集成

告知用户需要先设置 Azure 集成。如果用户同意，请先完成 dd-azure-integration 技能，然后返回此处。

阶段 2：选择范围并收集配置

1. 范围类型

询问用户要跟踪哪个范围的成本：

范围	说明
计费帐户	计费帐户下的所有订阅——范围最广
订阅	单个 Azure 订阅
资源组	订阅中的特定资源组

如果不确定，默认选择 订阅。

2. 范围详情

根据范围类型，收集以下信息：

计费帐户范围：

• 计费帐户 ID。Azure 计费帐户 ID 因协议类型（Enterprise Agreement、Microsoft Customer Agreement 等）而异，因此没有可用于验证的统一格式。将该值复述给用户，并在继续前让用户确认。

订阅范围：

• 订阅 ID。如果 command -v az >/dev/null 2>&1 成功，则使用 az account show --query id -o tsv 获取。此命令会返回 az CLI 当前设置的订阅——请确认这是用户所指的订阅（切勿自行假定）；如果不是，请让用户切换订阅或提供正确的 ID。 否则，请用户从 portal.azure.com → Subscriptions 中复制该 ID。

资源组范围：

• 订阅 ID
• 资源组名称

3. 存储和导出

询问用户适用哪种组合。这一点很重要，因为某些组合无效（现有导出已在其配置中绑定存储容器，因此无法与新的存储帐户配对）：

场景	存储	导出	是否支持
全新设置	创建新的	创建新的	是
使用自己的存储	使用现有的	创建新的	是
全部使用自己的资源	使用现有的	使用现有的	是
新存储 + 现有导出	创建新的	使用现有的	不可能

对于首次使用的用户，默认选择全新设置。记录此选择——它决定了第 3 阶段要生成 Terraform 的哪些部分。

4. 存储配置

字段	描述	默认值
资源组	存储帐户所在的资源组（可能与资源组成本范围不同）	（必须已存在）
存储订阅 ID	存储帐户资源组所属的订阅；azurerm 提供程序将绑定到此订阅	范围所属的订阅（Billing Account 范围必填）
位置	Azure 区域	eastus
存储帐户名称	存储帐户名称	ddstorage
容器名称	用于导出的 Blob 容器	dd-exports

如果使用现有存储，请向用户确认帐户名称、容器名称和资源组（这些信息将在 Terraform 中成为数据源引用，而不是新资源）。

5. 导出配置

仅在创建新导出时需要。如果使用现有导出，请从 Azure 门户（成本管理 → 导出）获取其名称和路径；或者，如果 command -v az >/dev/null 2>&1 执行成功，则使用 az costmanagement export list --scope "<SCOPE_VALUE>"（范围格式请参见 references/terraform.md 的第 5 节，例如 /subscriptions/<SUBSCRIPTION_ID>）。无论使用哪种方式，都要记录这些信息。

字段	描述	默认值
实际成本导出名称	实际成本导出的名称	actual-export
实际成本导出路径	容器中的路径前缀	dd-actual-exports
摊销成本导出名称	摊销成本导出的名称	amortized-export
摊销成本导出路径	容器中的路径前缀	dd-amortized-exports

第 3 阶段：生成并应用 Terraform

检查现有 Terraform

find . -maxdepth 1 -type f \( -name '*.tf' -o -name '*.tf.json' -o -name 'terraform.tfstate' \) -print

如果找到现有提供程序，则重复使用，但必须先检查它们是否指向所选租户、存储订阅和第 0 阶段中指定的 Datadog 站点。只添加新的 CCM 资源。

生成 Terraform HCL

下方各部分的完整 HCL 位于 references/terraform.md。现在读取该文件，并生成适用的部分，填入占位符。要生成哪些部分，取决于 Phase 2 中记录的 Storage 和 Exports 方案：

部分	包含条件
Section 1: 存储账户和容器	仅在创建新存储时包含
Section 2: 现有存储引用	仅在使用现有存储时包含
Section 3: 成本导出	仅在创建新导出时包含——始终包含两项，一项用于实际成本，另一项用于摊销成本
Section 4: 角色分配	始终包含；仅在 Subscription 和 Resource Group 范围添加 datadog_cost_reader，不用于 Billing Account 范围
Section 5: Datadog Azure UC 配置	始终包含——从下表中选择一个变体

选择与用户当前路径相符的 Section 5 变体。资源引用情形（不加引号）与字面值情形（加引号）中，client_id、storage_account 和 storage_container 字段的写法不同——不要混用。

路径	变体	client_id	storage_account	storage_container
新建存储（Section 1），且此 Terraform 根模块中声明了 azuread_application.datadog_app	A	HCL 引用，不加引号	HCL 引用，不加引号	HCL 引用，不加引号
新建存储（Section 1），但此根模块中未声明应用注册（现有集成，或在其他目录中创建的集成）	B	现有 client_id 字面值，加引号	HCL 引用，不加引号	HCL 引用，不加引号
现有存储（Section 2）	C	现有 client_id 字面值，加引号	数据源 .name，不加引号	容器名称字面值，加引号

只有在确认当前目录的 .tf 文件中存在 resource "azuread_application" "datadog_app"，且它是 Phase 1 中选定集成的应用注册后，才使用变体 A。其客户端 ID（通过 terraform state show -no-color azuread_application.datadog_app | grep -E '^ *client_id ' 获取）必须与选定的 client_id 相同；如果资源尚未写入状态，则视为不匹配。 完成 dd-azure-integration 并不能保证满足这两个条件。如果资源不存在或其客户端 ID 不同，请通过变体 B 或 C 使用所选集成的 client_id 字面值。

将 <CONTAINER_ID_REF> 替换为：

• 如果创建新存储，使用 local.ccm_storage_container_id（在 Section 1 中定义）
• 如果使用现有存储，使用 local.storage_container_id

将 <CURRENT_DATE_MIDNIGHT_UTC> 替换为今天日期的 YYYY-MM-DDT00:00:00Z 格式。

分两个阶段应用 Terraform

datadog_azure_uc_config 资源（Section 5）会在 Datadog 端验证导出是否可访问且已生成数据。如果在启用文件分区并运行过一次导出之前应用该资源，应用将失败。请将应用拆分为两个阶段。

文件布局很重要。 将 Sections 1-4 放在一个文件中（例如 azure-ccm.tf），将 Section 5 放在单独的文件中（例如 datadog-ccm-config.tf）。第一阶段要求目录中不能存在 Section 5——不要将它留在目录中，再尝试仅通过 -target 控制范围。对经过 -target 处理的计划执行普通的 terraform apply，会重新生成完整的、未限定目标的计划，并尝试应用 Section 5。物理隔离文件是确保拆分的最安全方式。

第一次应用 - 基础设施（Sections 1-4）

1. 将第 1-4 节写入 azure-ccm.tf。暂时不要编写新的第 5 节资源。如果某个 .tf 文件中已有一个处于 Terraform 状态中的 datadog_azure_uc_config（terraform state list 2>/dev/null | grep datadog_azure_uc_config），请保留该资源：移除其代码块会导致计划销毁该配置。只暂缓尚未应用的第 5 节资源；如果新资源必须与已应用的资源共用一个文件，请改用下方保存的定向计划。

2. 将所有占位符替换为收集到的值。

3. 确保已配置 azurerm 和 azuread 提供程序。如果尚未配置：

   terraform {
     required_providers {
       azurerm = {
         source  = "hashicorp/azurerm"
         version = ">= 4.9.0, < 6.0.0"
       }
       azuread = {
         source = "hashicorp/azuread"
       }
       datadog = {
         source = "DataDog/datadog"
       }
     }
   }
   
   provider "azurerm" {
     features {}
     subscription_id = "<STORAGE_SUBSCRIPTION_ID>"
     tenant_id       = "<TENANT_ID>"
   }
   
   provider "azuread" {
     tenant_id = "<TENANT_ID>"
   }
   
   provider "datadog" {
     api_url = "https://api.<DD_SITE>/"
   }
   

   此模板需要 AzureRM 4.9.0 或更高版本（以便在容器上使用 storage_account_id），并且也适用于 5.x；5.x 已移除 storage_account_name 和 resource_manager_id。如果用户的项目已将 azurerm 固定在低于 4.9.0 的版本，请告知用户并在更改版本固定之前征求同意。 azurerm 需要 features {}；将两个 Azure 提供程序都绑定到所选租户和存储订阅，可确保 Terraform 不会针对当前活动的 az 会话所指向的对象执行操作。 默认情况下，提供程序使用 Azure CLI 会话进行身份验证，因此，如果 az account show --query tenantId -o tsv 返回的不是所选租户，请让用户先运行 az login --tenant <TENANT_ID>。如果用户在阶段 0 确认使用非 CLI 方式，请保留该方式：检查其 ARM_TENANT_ID（或等效项）是否为所选租户。Datadog 提供程序不会读取 DD_SITE；如果没有 api_url（或 DD_HOST），它会默认使用 US1，因此请将 <DD_SITE> 替换为阶段 0 确认的站点。密钥不要放在提供程序代码块中；它会从环境中读取 DD_API_KEY / DD_APP_KEY。

   **妥善保管计划和状态文件。**保存的计划和状态可能包含存储帐户访问密钥和连接字符串。下方的计划代码块会设置 umask 077；请确保 *.tfplan（此处每个已保存的计划都以 .tfplan 结尾）和 *.tfstate* 均已加入 .gitignore，绝不要提交这些文件，也不要将状态（针对存储帐户运行 terraform state show 的输出）打印到记录中。如果用户拒绝计划，请删除计划文件。

   **注册模板所需的资源提供程序。**AzureRM 5.x 默认不会注册任何资源提供程序（4.x 会自动注册一大批），因此在尚未注册这些提供程序的订阅中，创建存储帐户或导出任务会在 apply 期间失败。模板要求在 <STORAGE_SUBSCRIPTION_ID> 中注册 Microsoft.Storage 和 Microsoft.CostManagementExports。 使用 az CLI 检查：

   for ns in Microsoft.Storage Microsoft.CostManagementExports; do
     printf '%s: ' "$ns"; az provider show --namespace "$ns" --subscription '<STORAGE_SUBSCRIPTION_ID>' --query registrationState -o tsv || echo "lookup failed"
   done
   

   如果两者均为 Registered，请继续。否则，告知用户哪些提供程序尚未注册，说明注册会更改订阅且需要 */register/action 权限，并在获得同意后再进行注册：

   namespaces='<UNREGISTERED_NAMESPACES>'   # space-separated, from the check above
   for ns in $namespaces; do
     az provider register --namespace "$ns" --subscription '<STORAGE_SUBSCRIPTION_ID>' --wait || { echo "registering $ns FAILED"; exit 1; }
   done
   

   如果没有 az CLI，请让用户在 Azure 门户的 Subscriptions > Resource providers 中检查并注册尚未注册的提供程序；或者在获得用户批准后，将 resource_providers_to_register = ["Microsoft.Storage", "Microsoft.CostManagementExports"] 添加到 azurerm 提供程序代码块中。Terraform 会在配置提供程序时注册这些资源提供程序；此操作在 plan 和 apply 阶段都会发生，因此请在执行下方计划之前取得批准。

4. 运行 terraform init，然后保存计划：

   for f in .env.local .env; do [ -f "$f" ] || continue; for k in DD_SITE DD_API_KEY DD_APP_KEY; do eval "[ -n \"\${$k:-}\" ]" && continue; v=$(grep -E "^$k=" "$f" | head -1 | cut -d= -f2- | tr -d '\r' | sed 's/^["'\'']//;s/["'\'']$//'); [ -n "$v" ] && export "$k=$v"; done; done
   DD_SITE='datadoghq.com'; export DD_SITE   # <- replace with the site confirmed in Phase 0.
   # Explicit assignment, not ':=': a wrong non-empty DD_SITE in .env would otherwise survive.
   : "${DD_API_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"; : "${DD_APP_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"
   umask 077
   terraform plan -out=ccm.tfplan \
     || { echo "terraform plan FAILED - do NOT apply"; exit 1; }
   

   向用户展示计划并等待明确批准。如果计划会销毁或替换现有资源（尤其是 datadog_azure_uc_config），或者会将 datadog_integration_azure 上的 resource_collection_enabled 设为 false，请勿 apply：修正配置并重新生成计划。之后，才可在单独的命令中 apply 该已保存的计划：

   for f in .env.local .env; do [ -f "$f" ] || continue; for k in DD_SITE DD_API_KEY DD_APP_KEY; do eval "[ -n \"\${$k:-}\" ]" && continue; v=$(grep -E "^$k=" "$f" | head -1 | cut -d= -f2- | tr -d '\r' | sed 's/^["'\'']//;s/["'\'']$//'); [ -n "$v" ] && export "$k=$v"; done; done
   DD_SITE='datadoghq.com'; export DD_SITE   # <- replace with the site confirmed in Phase 0.
   # Explicit assignment, not ':=': a wrong non-empty DD_SITE in .env would otherwise survive.
   : "${DD_API_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"; : "${DD_APP_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"
   trap 'rm -f ccm.tfplan' EXIT HUP INT TERM
   terraform apply ccm.tfplan \
     || { echo "terraform apply FAILED - do NOT continue to file partitioning"; exit 1; }
   

   由于目录中没有第 5 节，因此此计划和 apply 操作自然仅针对基础设施资源。 如果出于某种原因无法将第 5 节移出该目录，则改用保存的定向计划：

for f in .env.local .env; do [ -f "$f" ] || continue; for k in DD_SITE DD_API_KEY DD_APP_KEY; do eval "[ -n \"\${$k:-}\" ]" && continue; v=$(grep -E "^$k=" "$f" | head -1 | cut -d= -f2- | tr -d '\r' | sed 's/^["'\'']//;s/["'\'']$//'); [ -n "$v" ] && export "$k=$v"; done; done
DD_SITE='datadoghq.com'; export DD_SITE   # <- replace with the site confirmed in Phase 0.
# Explicit assignment, not ':=': a wrong non-empty DD_SITE in .env would otherwise survive.
: "${DD_API_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"; : "${DD_APP_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"
umask 077
terraform plan -target=azurerm_storage_account.ccm_storage_account \
               -target=azurerm_storage_container.ccm_storage_container \
               -target=azurerm_<SCOPE>_cost_management_export.actual_cost \
               -target=azurerm_<SCOPE>_cost_management_export.amortized_cost \
               -target=azurerm_role_assignment.datadog_storage_reader \
               -target=azurerm_role_assignment.datadog_cost_reader \
               -out=phase1.tfplan \
  || { echo "terraform plan FAILED - do NOT apply"; exit 1; }

向用户展示该计划并等待明确批准，然后在单独的命令中应用：

for f in .env.local .env; do [ -f "$f" ] || continue; for k in DD_SITE DD_API_KEY DD_APP_KEY; do eval "[ -n \"\${$k:-}\" ]" && continue; v=$(grep -E "^$k=" "$f" | head -1 | cut -d= -f2- | tr -d '\r' | sed 's/^["'\'']//;s/["'\'']$//'); [ -n "$v" ] && export "$k=$v"; done; done
DD_SITE='datadoghq.com'; export DD_SITE   # <- replace with the site confirmed in Phase 0.
# Explicit assignment, not ':=': a wrong non-empty DD_SITE in .env would otherwise survive.
: "${DD_API_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"; : "${DD_APP_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"
trap 'rm -f phase1.tfplan' EXIT HUP INT TERM
terraform apply phase1.tfplan \
  || { echo "terraform apply FAILED - do NOT continue to file partitioning"; exit 1; }

此处不要在没有保存的计划文件时运行 terraform apply：直接运行 apply（或直接运行 apply -target）仍会重新生成计划；如果 Terraform 的依赖图包含第 5 节，就可能将其纳入计划，具体取决于状态。

应用后：启用文件分区（手动操作，必须在第二次应用前完成）

用户必须手动在 Azure 门户中为两个导出启用文件分区。这无法通过 Terraform 完成，且必须在第二次应用前完成。请指示用户：

1. 前往 Azure 门户 → 成本管理 → 导出
2. 对每个导出（实际值和摊销值）：
   • 点击导出名称
   • 启用“文件分区”
   • 保存
3. 手动运行两个导出各一次，并等待它们完成

第二次应用 - Datadog CCM 配置（第 5 节）

启用文件分区且两个导出都成功运行一次后，添加第 5 节：

1. 写入包含第 5 节的 datadog-ccm-config.tf（如果该文件已移出，则将其恢复）。

2. 保存计划，向用户展示，并且仅在获得明确批准后应用该文件。计划应只包含新的 datadog_azure_uc_config 资源，因为基础设施已存在于状态中；应用保存的文件才能确保用户得到他们批准的计划：

   for f in .env.local .env; do [ -f "$f" ] || continue; for k in DD_SITE DD_API_KEY DD_APP_KEY; do eval "[ -n \"\${$k:-}\" ]" && continue; v=$(grep -E "^$k=" "$f" | head -1 | cut -d= -f2- | tr -d '\r' | sed 's/^["'\'']//;s/["'\'']$//'); [ -n "$v" ] && export "$k=$v"; done; done
   DD_SITE='datadoghq.com'; export DD_SITE   # <- replace with the site confirmed in Phase 0.
   # Explicit assignment, not ':=': a wrong non-empty DD_SITE in .env would otherwise survive.
   : "${DD_API_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"; : "${DD_APP_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"
   umask 077
   terraform plan -out=ccm.tfplan \
     || { echo "terraform plan FAILED - do NOT apply"; exit 1; }
   

用户批准计划后，在单独的命令中应用：

for f in .env.local .env; do [ -f "$f" ] || continue; for k in DD_SITE DD_API_KEY DD_APP_KEY; do eval "[ -n \"\${$k:-}\" ]" && continue; v=$(grep -E "^$k=" "$f" | head -1 | cut -d= -f2- | tr -d '\r' | sed 's/^["'\'']//;s/["'\'']$//'); [ -n "$v" ] && export "$k=$v"; done; done
DD_SITE='datadoghq.com'; export DD_SITE   # <- replace with the site confirmed in Phase 0.
# Explicit assignment, not ':=': a wrong non-empty DD_SITE in .env would otherwise survive.
: "${DD_API_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"; : "${DD_APP_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"
trap 'rm -f ccm.tfplan' EXIT HUP INT TERM
terraform apply ccm.tfplan \
  || { echo "terraform apply FAILED - do NOT verify or report success"; exit 1; }

如果 datadog_azure_uc_config 在第二次应用时出错，最常见的原因是：

• 一个或两个导出未启用文件分区
• 导出尚未运行（或尚未完成）
• 第 4 节中的角色分配尚未传播（可能需要几分钟）

第 4 阶段：验证设置

for f in .env.local .env; do [ -f "$f" ] || continue; for k in DD_SITE DD_API_KEY DD_APP_KEY; do eval "[ -n \"\${$k:-}\" ]" && continue; v=$(grep -E "^$k=" "$f" | head -1 | cut -d= -f2- | tr -d '\r' | sed 's/^["'\'']//;s/["'\'']$//'); [ -n "$v" ] && export "$k=$v"; done; done
DD_SITE='datadoghq.com'; export DD_SITE   # <- replace with the site confirmed in Phase 0.
# Explicit assignment, not ':=': a wrong non-empty DD_SITE in .env would otherwise survive.
: "${DD_API_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"; : "${DD_APP_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"
resp=$(printf 'DD-API-KEY: %s\nDD-APPLICATION-KEY: %s\n' "$DD_API_KEY" "$DD_APP_KEY" \
  | curl -sS -w '\n%{http_code}' -X GET -H @- "https://api.${DD_SITE}/api/v2/cost/azure_uc_config")
code=$(printf '%s' "$resp" | tail -1); body=$(printf '%s' "$resp" | sed '$d')
[ "$code" = "200" ] || { echo "lookup failed with HTTP $code - do not assume 'not registered':"; printf '%s\n' "$body"; exit 1; }
printf '%s\n' "$body" | jq . 2>/dev/null || printf '%s\n' "$body"

执行与第 1 阶段相同的结构检查（若缺少 data 或 configs，或其不是数组，则停止）。找到嵌套的 configs[] 记录，其中 account_id、client_id 和 scope 与选定的租户、客户端和范围相匹配（对于第 1 阶段的现有配置路径，应匹配用户确认的配置的范围和导出项），并确认实际值和摊销值记录均存在，且 export_name 和 storage_account 符合预期。然后检查每条记录的 status 和 error_messages：

• 两条记录的状态均为 active，且没有错误消息——设置成功。成本数据可能还需要一些时间才会显示；应说明这一点，不要声称成本已经开始流入。
• 状态为 warn 或 error，或存在任何 error_messages——向用户展示这些消息。不要报告成功，也不要发送完成回调；帮助他们解决问题（请参见上述常见原因）并再次验证。
• 状态为 disabled、记录缺失，或范围或导出标识不匹配——设置尚未完成。告知用户，不要发送回调。

收尾

验证完成后，请尽最大努力执行一次完成回调，以便 Datadog UI 完成此流程。

DD_WORKFLOW_ID 是凭据所属 Datadog 用户的 UUID，UI 会根据它关联此回调。在一条命令中解析并发送：许多 Agent 运行时会为每条命令启动一个全新的 shell，因此在之前的命令中赋值的变量在这里会是空的。

切勿输出 current_user 响应：其中还包含用户的姓名、用户名和电子邮件地址。如果没有可用的 JSON 解析器，请跳过此回调，不要安装解析器，也不要因此阻塞设置流程。

for f in .env.local .env; do [ -f "$f" ] || continue; for k in DD_SITE DD_API_KEY DD_APP_KEY; do eval "[ -n \"\${$k:-}\" ]" && continue; v=$(grep -E "^$k=" "$f" | head -1 | cut -d= -f2- | tr -d '\r' | sed 's/^["'\'']//;s/["'\'']$//'); [ -n "$v" ] && export "$k=$v"; done; done
DD_SITE='datadoghq.com'; export DD_SITE   # <- replace with the site confirmed in Phase 0.
# Explicit assignment, not ':=': a wrong non-empty DD_SITE in .env would otherwise survive.
: "${DD_API_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"; : "${DD_APP_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"
dd_headers() { printf 'DD-API-KEY: %s\nDD-APPLICATION-KEY: %s\n' "$DD_API_KEY" "$DD_APP_KEY"; }
DD_WORKFLOW_ID="$(dd_headers | curl -H @- -fsS --connect-timeout 5 --max-time 20 \
  "https://api.${DD_SITE}/api/v2/current_user" | jq -er '.data.id')" \
  && dd_headers | curl -H @- -sS --connect-timeout 5 --max-time 20 -X POST \
  "https://api.${DD_SITE}/api/unstable/integration/azure/workflow/agentic_ccm" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{"data":{"type":"integration_setup_status","id":"'"${DD_WORKFLOW_ID}"'","attributes":{"status":"finished","step":"setup_complete"}}}'

如果此回调失败，请勿重试或阻塞设置流程。

最后向用户简要总结：现在向 Cloud Cost Management 提供数据的 Azure 租户和成本范围、正在使用的存储帐户和容器（新建或复用）、实际成本和摊销成本导出的名称（新建或复用），以及资源收集是在 Phase 1 中启用的还是原本就已开启。

告知用户：

• 首次导出运行后，成本数据通常需要 24-48 小时才会显示。
• Azure 每天运行一次导出——首批数据可能会在几小时内到达。

提供链接：

• Cloud Cost Management：<APP_BASE>/cost
• Cost Analytics：<APP_BASE>/cost/analytics

重要说明

• 只有拥有 Billing Account 或 Subscription 级权限的用户才能创建 Azure 成本导出。
• 必须在 Azure 门户中手动启用文件分区——Terraform 不支持此功能。
• lifecycle { ignore_changes = all } 块可防止 Terraform 覆盖 Azure 门户中的手动更改。
• 服务主体数据源需要 azuread 提供程序。
• 未先向用户展示计划，切勿运行 terraform apply。