第二次执行Azure Bicep脚本时出现'agentPoolProfile.vnetSubnetID'属性修改不允许的错误

问题原因 #

你遇到的这个错误核心在于：AKS代理池的vnetSubnetID是不可变属性。一旦AKS集群创建完成，这个属性就无法被修改——哪怕你传入的是和初始值完全相同的子网ID。当你第二次执行部署命令时，Azure Resource Manager（ARM）会对比现有集群配置与模板配置，只要模板中包含这个属性，哪怕值没变化，ARM也会尝试执行更新操作，而该属性的不可变性会直接触发PropertyChangeNotAllowed错误。

解决方案 #

这里提供两种可行的解决方式，你可以根据实际场景选择：

方案1：在Bicep中添加ignoreChanges修饰符（推荐）

通过@ignoreChanges()修饰符告诉ARM忽略agentPoolProfiles[0].vnetSubnetID属性的变更检测，这样后续部署时，ARM会跳过对这个属性的验证，不会再触发错误。

修改后的AKS资源代码如下：

resource aks 'Microsoft.ContainerService/managedClusters@2021-02-01' = {
  name: 'playground-cluster0'
  location: resourceGroup().location
  identity: {
    type:'UserAssigned'
    userAssignedIdentities: {
      '${aksManagedIdentity.id}': {}
    }
  }
  sku: {
    name: 'Basic'
    tier: 'Free'
  }
  // 添加ignoreChanges修饰符，忽略vnetSubnetID的变更检测
  @ignoreChanges('agentPoolProfiles[0].vnetSubnetID')
  properties: {
    kubernetesVersion: '1.21.2'
    dnsPrefix: 'playground'
    enableRBAC: true
    networkProfile: {
      networkPlugin: 'azure'
      networkPolicy: 'calico'
    }
    aadProfile: {
      managed: true
      enableAzureRBAC: true
    }
    autoUpgradeProfile: {}
    apiServerAccessProfile: {
      enablePrivateCluster: false
    }
    agentPoolProfiles: [
      {
        name: 'aksnodes'
        count: 1
        vmSize: 'Standard_B2s'
        osDiskSizeGB: 30
        osDiskType: 'Managed'
        vnetSubnetID: virtualNetwork.properties.subnets[0].id
        osType: 'Linux'
        maxCount: 1
        minCount: 1
        enableAutoScaling: true
        type: 'VirtualMachineScaleSets'
        mode: 'System'
        orchestratorVersion: null
      }
    ]
  }
}

方案2：分离VNet与AKS的部署

如果你不想使用ignoreChanges，可以将虚拟网络和AKS集群的部署流程拆分：

• 第一步：单独部署虚拟网络的Bicep文件（比如命名为vnet.bicep），完成VNet和子网的创建。
• 第二步：在AKS的Bicep文件中，使用existing关键字引用已创建的虚拟网络，再传入子网ID。这种方式下，后续部署AKS时，只要不修改vnetSubnetID的值，就不会触发错误。

示例AKS引用现有VNet的代码片段：

// 引用已存在的虚拟网络
resource virtualNetwork 'Microsoft.Network/virtualNetworks@2021-02-01' existing = {
  name: 'aksVirtualNetwork'
}

// 后续AKS资源定义中依然使用virtualNetwork.properties.subnets[0].id作为vnetSubnetID

验证修改 #

修改完成后，再次执行你的部署命令：

az deployment group create --resource-group showcase-kevinplayground2 -f cluster.bicep

这次部署应该可以成功完成，ARM会忽略vnetSubnetID属性的检查，仅更新其他允许变更的配置。

内容的提问来源于stack exchange，提问作者Kevin Coulombe