Pulumi Azure Classic v6 迁移指南：关键变更与升级策略

前言

Pulumi Azure Classic 提供商的 v6 版本是该系列自 2022 年 4 月以来的首个重大更新。作为基于 Terraform 提供商 v4 版本的升级，本次更新引入了一些重要的破坏性变更。本文将深入解析这些变更，并提供详细的迁移指导，帮助开发者顺利完成从 v5 到 v6 的过渡。

升级前的准备工作

在开始迁移前，强烈建议先升级到 v5.89.0 版本，并解决所有弃用警告。这一步骤至关重要，它能帮助您提前识别并处理潜在问题，使后续的 v6 迁移更加顺畅。

关键变更解析

1. 订阅 ID 成为必填项

变更内容： v6 版本中，订阅 ID 现在成为强制要求配置项。这一变更适用于所有认证方式，包括 CLI 认证。

配置方式：

• 环境变量：ARM_SUBSCRIPTION_ID
• 提供商配置属性：subscriptionId

技术背景： 这一变更源于 Azure API 对订阅上下文的严格要求，确保所有操作都在明确的订阅范围内执行，提高操作的安全性和可追溯性。

2. 资源提供商管理机制重构

v5 版本会自动管理一个预定义的资源提供商列表，除非显式禁用 skipProviderRegistration 选项。v6 对此进行了重大改进：

新配置选项：

• resourceProviderRegistrations：指定要自动管理的资源提供商集合

  • core：最小化集合（基础订阅必需）
  • extended：扩展集合（社区推荐）
  • all：完整集合（覆盖所有功能）
  • none：不自动管理
  • legacy：向前兼容的旧版集合（未来将移除）

• resourceProvidersToRegisters：额外指定的资源提供商名称列表

最佳实践： 生产环境建议从 core 开始，根据实际需求逐步添加，避免不必要的权限分配。

3. 枚举值大小写敏感化

变更影响： 多个资源的枚举属性现在严格区分大小写。这一变更提高了配置的精确性，解决了长期存在的差异问题。

迁移步骤：

1. 升级到 v6 后执行预览操作
2. 检查报告的大小写问题
3. 根据提示修正程序中的枚举值

典型受影响资源（部分示例）：

• appservice.AppService：dotnetFrameworkVersion等
• compute.VirtualMachine：多个磁盘相关属性
• network命名空间下多个资源的协议类型
• storage.Account：多种账户配置属性

完整列表请参考官方文档中的详细表格。

已移除资源的处理策略

有替代方案的资源

这些资源已被新资源取代，迁移相对简单：

旧资源	新资源
core.TemplateDeployment	core.ResourceGroupTemplateDeployment
sql命名空间下多个资源	迁移到 mssql 命名空间对应资源

迁移方法： 保持逻辑名称不变，更新资源类型，调整不兼容的属性。

已退役的服务和资源

这些资源没有直接替代方案，需要特殊处理：

典型案例：

• appservice.Environment：由 ASE v3 (appservice.EnvironmentV3) 取代
• Azure Media Services 相关资源：服务已退役
• MySQL 单服务器相关资源：迁移到 Flexible Server

处理建议：

1. 从状态中移除旧资源
2. 使用替代方案重新创建
3. 规划适当的数据迁移方案

资源属性变更详解

v6 版本中约有 150 个资源经历了属性变更，主要分为以下几类：

1. 不再计算的属性（16 个）：

   • 可能需要使用 ignoreChanges 忽略差异

2. 默认值变更（31 个）：

   • 检查现有配置是否符合新默认值预期

3. 新增必填属性（4 个资源）：

   • 确保为这些资源添加必要属性

4. 移除的废弃属性（32 个）：

   • 其中 10 个来自 KubernetesCluster 资源

特殊注意事项

apimanagement.ApiTag 资源实例需要重新创建，以便在资源 ID 中包含标签修订信息。这一变更确保了资源标识的完整性和一致性。

迁移检查清单

1. [ ] 升级到 v5.89.0 并解决所有弃用警告
2. [ ] 确保配置了订阅 ID
3. [ ] 审查并调整资源提供商管理策略
4. [ ] 修正所有枚举值的大小写问题
5. [ ] 替换已废弃的资源类型
6. [ ] 处理已退役服务的迁移方案
7. [ ] 检查并适应属性变更
8. [ ] 特殊处理需要重建的资源

结语

Pulumi Azure Classic v6 的迁移虽然涉及多项变更，但通过系统性的规划和执行，可以确保过渡平稳。建议在测试环境中先行验证迁移方案，特别是对于生产环境关键资源。通过这次升级，您将获得更稳定、更符合现代 Azure API 规范的开发体验。