pulumi-arm-to-pulumi

重要：必须调整计划

如果你在加载此技能前已经生成迁移计划，则必须：

1. 根据此技能中的工作流和要求检查现有计划
2. 找出其中的遗漏、缺失步骤或错误假设
3. 更新并修订计划，使其符合此技能的指导
4. 继续操作前，先向用户说明调整后的计划

关键成功要求

迁移输出必须满足以下所有要求：

1. 资源覆盖完整

   • ARM 模板中的每个资源都必须：
     • 在 Pulumi 程序中有所表示，或
     • 在最终报告中明确说明未纳入的理由。

2. 成功部署

   • 生成的 Pulumi 程序必须在结构上有效，并能够成功运行 pulumi preview（假定配置正确）。

3. 无差异导入验证（如果导入现有资源）

   • 导入后，pulumi preview 必须显示：
     • 无更新
     • 无替换
     • 无创建
     • 无删除
   • 必须通过预览差异解决工作流处理任何差异。请参阅 arm-import.md。

4. 最终迁移报告

   • 始终输出适用于拉取请求的正式迁移报告。
   • 包含：
     • ARM → Pulumi 资源映射
     • Provider 选择（azure-native 与 azure）
     • 行为差异
     • 缺失步骤或需要手动完成的步骤
     • 验证说明

信息缺失时

如果用户提供的 ARM 模板不完整、含糊或缺少相关文件，请在生成 Pulumi 代码前提出有针对性的问题。

如果不确定导入时如何处理特定资源属性，请在修改 Pulumi 代码前提出有针对性的问题。

迁移工作流

请严格按照以下顺序执行此工作流：

1. 信息收集

1.1 验证 Azure 凭据

运行 Azure CLI 命令（例如 az resource list、az resource show）需要先使用 ESC 登录并运行 az login

• 如果用户已提供 ESC 环境，请使用该环境。
• 如果未指定 ESC 环境，请先询问用户要使用哪个 ESC 环境，然后再运行 Azure CLI 命令。

使用 ESC 配置 Azure CLI：

• ESC 环境可以通过环境变量或 Azure CLI 配置提供 Azure 凭据
• 使用 ESC 登录 Azure 以提供凭据，例如：pulumi env run {org}/{project}/{environment} -- bash -c 'az login --service-principal -u "$ARM_CLIENT_ID" --tenant "$ARM_TENANT_ID" --federated-token "$ARM_OIDC_TOKEN"'。建立会话后，无需继续使用 ESC
• 验证凭据是否可用：az account show
• 确认订阅：az account list --query "[].{Name:name, SubscriptionId:id, IsDefault:isDefault}" -o table

**有关 ESC 的详细信息：**通过调用工具“Skill”并将 name 设为 pulumi-esc，加载 pulumi-esc 技能

1.2 分析 ARM 模板结构

ARM 模板没有 CloudFormation 中“堆栈”的概念。请直接读取 ARM 模板 JSON 文件：

# View template structure
cat template.json | jq '.resources[] | {type: .type, name: .name}'

# View parameters
cat template.json | jq '.parameters'

# View variables
cat template.json | jq '.variables'

提取：

• 资源类型和名称
• 参数及其默认值
• 变量和表达式
• 依赖关系（dependsOn 数组）
• 嵌套模板或链接模板
• Copy 循环（迭代构造）
• 条件部署（condition 属性）

文档：ARM 模板结构

1.3 构建资源清单（如果导入现有资源）

如果 ARM 模板已部署，并且你要导入现有资源：

# List all resources in a resource group
az resource list \
  --resource-group <resource-group-name> \
  --output json

# Get specific resource details
az resource show \
  --ids <resource-id> \
  --output json

# Query specific properties using JMESPath
az resource show \
  --ids <resource-id> \
  --query "{name:name, location:location, properties:properties}" \
  --output json

文档：Azure CLI 文档

2. 代码转换（ARM → PULUMI）

**重要：**将 ARM 转换为 Pulumi 需要手动翻译。ARM 模板没有自动转换工具。你需要负责完成整个转换。

关键转换原则

1. Provider 策略：

   • 默认：使用 @pulumi/azure-native，以完整覆盖 Azure Resource Manager API
   • 备用方案：当 azure-native 不支持特定功能，或需要简化的抽象时，使用 @pulumi/azure（经典 provider）

   文档：

   • Azure Native Provider
   • Azure Classic Provider

2. 语言支持：

   • TypeScript/JavaScript：最常用，IDE 支持出色
   • Python：适合数据团队和 ML 工作流
   • C#：适合 .NET 团队
   • Go：高性能，强类型
   • Java：适合企业 Java 团队
   • YAML：简单的声明式方法
   • 根据用户偏好或现有代码库进行选择

3. 完整覆盖：

   • 转换 ARM 模板中的所有资源
   • 保留所有条件、循环和依赖项
   • 保持参数和变量逻辑

遵循 arm-conversion-patterns.md 中的转换模式。

arm-conversion-patterns.md 提供：

• 参数、变量和输出映射
• Copy 循环、条件和 dependsOn 转换
• 嵌套模板 → ComponentResource
• Azure Classic provider 示例（VNet、App Service）
• TypeScript 输出处理和常见问题

3. 资源导入（现有资源）- 可选

转换后，你可以选择导入现有资源，由 Pulumi 管理。如果用户未提出此要求，可将其作为转换后的后续步骤建议。

重要：当用户要求将现有 Azure 资源导入 Pulumi 时，请参阅 arm-import.md，了解详细的导入流程和零差异验证工作流。

arm-import.md 提供：

• 内联导入 ID 模式和示例
• Azure 资源 ID 格式约定
• 子资源处理（例如，WebAppApplicationSettings）
• 预览解析工作流，用于在导入后实现零差异
• 针对属性冲突的分步调试

关键导入原则

1. 内联导入方法：

   • 使用 import 资源选项和 Azure 资源 ID
   • 不需要单独的导入工具（与 pulumi-cdk-importer 不同）

2. Azure 资源 ID：

   • 遵循可预测的模式：/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
   • 可按约定生成，或通过 Azure CLI 查询

3. 零差异验证：

   • 导入后运行 pulumi preview
   • 使用预览解析工作流解决所有差异
   • 目标：不更新、不替换、不创建、不删除

4. PULUMI 配置

设置与 ARM 模板参数匹配的堆栈配置：

# Set Azure region
pulumi config set azure-native:location eastus --stack dev

# Set application parameters
pulumi config set storageAccountName mystorageaccount --stack dev

# Set secret parameters
pulumi config set --secret adminPassword MyS3cr3tP@ssw0rd --stack dev

5. 验证

如果执行了导入，请在预览中实现零差异后验证迁移：

1. 检查所有导出：

   pulumi stack output
   

2. 验证资源关系：

   pulumi stack graph
   

3. 测试应用功能（如适用）

4. 记录迁移后所需的任何手动步骤

与用户协作

如果用户请求协助规划或执行 ARM 到 Pulumi 的迁移，请使用以上信息引导用户完成转换和导入流程。

详细文档

当用户需要更多信息时，请使用网页抓取工具获取 Pulumi 官方文档中的内容：

• ARM 迁移指南： https://www.pulumi.com/docs/iac/adopting-pulumi/migrating-to-pulumi/from-arm/
• Azure Native Provider： https://www.pulumi.com/registry/packages/azure-native/
• Azure Classic Provider： https://www.pulumi.com/registry/packages/azure/

Microsoft Azure 文档：

• ARM 模板参考： https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/
• Azure CLI 参考： https://learn.microsoft.com/en-us/cli/azure/
• Azure 资源 ID： https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/template-functions-resource

输出格式（必需）

执行迁移时，始终提供：

1. 概览（高层次描述）
2. 迁移计划摘要
   • 已识别的 ARM 模板资源
   • 转换策略（语言、Provider）
   • 导入方式（如适用）
3. Pulumi 代码输出（按文件整理）
   • 主程序文件
   • 组件资源（如有）
   • 配置说明
4. 资源映射表（ARM → Pulumi）
   • ARM 资源类型 → Pulumi 资源类型
   • ARM 资源名称 → Pulumi 逻辑名称
   • 导入 ID（如需导入）
5. 预览解析说明（如需导入）
   • 遇到的差异
   • 采用的解决策略
   • 忽略与新增的属性
6. 最终迁移报告（可直接用于 PR）
   • 变更摘要
   • 测试说明
   • 已知限制
   • 后续步骤
7. 配置设置
   • 必需的配置值
   • pulumi config set 命令示例

确保代码语法有效，并按文件清晰分隔。