快速入门:排查 ARM 模板 JSON 部署问题

本快速入门介绍如何排查 Azure 资源管理器模板(ARM 模板)JSON 部署错误。 你将设置一个存在错误的模板,并了解如何修复错误。

Azure 资源管理器模板是定义项目基础结构和配置的 JavaScript 对象表示法 (JSON) 文件。 模板使用声明性语法。 你可以在不编写用于创建部署的编程命令序列的情况下,描述预期部署。

有三种类型的错误与部署相关:

  • 验证错误发生在部署开始之前,由文件中的语法错误造成。 像 Visual Studio Code 这样的代码编辑器可以识别这些错误。
  • 当运行部署命令但未部署资源时,将发生预检验证错误。 这些错误是部署未开始的情况下出现的。 例如,如果某个参数值不正确,则会在预检验证中发现错误。
  • 部署错误发生在部署过程中,只能通过评估 Azure 环境中的部署进度来发现。

所有类型的错误都会返回用于排查部署问题的错误代码。 验证错误和预检错误会显示在活动日志中,但不会显示在部署历史记录中。

先决条件

若要完成本快速入门,需要准备好以下各项:

创建包含错误的模板

复制以下模板并将其保存在本地。 你将使用此文件来排查验证错误、预检错误和部署错误。 本快速入门假设你已将文件命名为 troubleshoot.json,但可以使用任意名称。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameterss": {
    "storageAccountType": {
      "type": "string",
      "defaultValue": "Standard_LRS",
      "allowedValues": [
        "Standard_LRS",
        "Standard_GRS",
        "Standard_ZRS",
        "Premium_LRS"
      ]
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "prefixName": {
      "type": "string"
    }
  },
  "variables": {
    "storageAccountName": "[concat(parameters('prefixName'), uniquestring(resourceGroup().id))]"
  },
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2021-04-01",
      "name": "[variables('storageAccountName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "[parameters('storageAccountType')]"
      },
      "kind": "StorageV2",
      "properties": {}
    }
  ],
  "outputs": {
    "storageAccountName": {
      "type": "string",
      "value": "[variables('storageAccountName')]"
    },
    "vnetResult": {
      "type": "object",
      "value": "[reference(resourceId('Microsoft.Network/virtualNetworks', 'doesnotexist'), '2021-03-01', 'Full')]"
    }
  }
}

修复验证错误

在 Visual Studio Code 中打开该文件。 parameterss: 下的波浪线表示错误。 将鼠标指针悬停在错误上可查看验证错误。

Visual Studio Code 的屏幕截图,突出显示了模板验证错误,并用红色波浪线标记了代码中拼写错误的“parameterss:”。

你会注意到,variablesresources 存在错误,原因是“未定义参数引用”。 若要显示模板的验证错误,请选择“视图”>“问题” 。

Visual Studio Code 的屏幕截图,显示了“问题”选项卡,其中列出了“变量”和“资源”部分的未定义参数引用错误。

所有错误都由元素名称拼写不正确导致。

"parameterss": {

错误消息指出:“模板验证失败:在类型为“模板”的对象上找不到成员“parameterss”。路径为“parameterss”,第 4 行,第 16 位。”

参数的 ARM 模板语法显示 parameters 是正确的元素名称。

要修复验证错误和“未定义参数引用”错误,请更正拼写并保存文件。

"parameters": {

修复预检错误

要生成预检验证错误,需要对 prefixName 参数使用不正确的值。

本快速入门使用作为 troubleshootRG 资源组名称,但可以使用任意名称。

az group create --name troubleshootRG --location chinanorth
az deployment group create \
  --resource-group troubleshootRG \
  --template-file troubleshoot.json \
  --parameters prefixName=long!!StoragePrefix

模板未通过预检验证,部署不会运行。 prefixName 超过 11 个字符,并且包含特殊字符和大写字母。

存储名称的长度必须介于 3 到 24 个字符之间,并且只能使用小写字母和数字。 前缀值创建了无效的存储名称。 有关详细信息,请参阅解决存储帐户名称错误。 要修复预检错误,请使用长度在 11 个字符以内且仅包含小写字母或数字的前缀。

由于部署未运行,因此没有部署历史记录。

Azure 资源组概述页面的屏幕截图,显示了由于预检错误而导致部署历史记录部分为空。

活动日志显示预检错误。 选择日志可查看错误的详细信息。

Azure 资源组活动日志的屏幕截图,显示了带有红色感叹号图标的预检错误条目。

修复部署错误

使用有效的前缀值(例如 storage)运行部署。

az group create --name troubleshootRG --location chinanorth
az deployment group create \
  --resource-group troubleshootRG \
  --template-file troubleshoot.json \
  --parameters prefixName=storage

系统将开始部署,并在部署历史记录中显示部署详细信息。 部署失败,因为 outputs 引用资源组中不存在的虚拟网络。 但是,存储帐户没有错误,因此部署了资源。 部署历史记录显示部署失败。

Azure 资源组概述页面的屏幕截图,显示了失败的部署,部署历史记录部分中带有红色感叹号图标。

若要修复部署错误,请更改引用函数以使用有效资源。 有关详细信息,请参阅解决“找不到资源”错误。 对于本快速入门,请删除 vnetResult 之前的逗号和所有 vnetResult。 保存文件,并重新运行部署。

"vnetResult": {
  "type": "object",
  "value": "[reference(resourceId('Microsoft.Network/virtualNetworks', 'doesnotexist'), '2021-03-01', 'Full')]"
}

修复验证错误、预检错误和部署错误后,以下模板将部署存储帐户。 部署历史记录和活动日志将显示部署成功。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storageAccountType": {
      "type": "string",
      "defaultValue": "Standard_LRS",
      "allowedValues": [
        "Standard_LRS",
        "Standard_GRS",
        "Standard_ZRS",
        "Premium_LRS"
      ]
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "prefixName": {
      "type": "string"
    }
  },
  "variables": {
    "storageAccountName": "[concat(parameters('prefixName'), uniquestring(resourceGroup().id))]"
  },
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2021-04-01",
      "name": "[variables('storageAccountName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "[parameters('storageAccountType')]"
      },
      "kind": "StorageV2",
      "properties": {}
    }
  ],
  "outputs": {
    "storageAccountName": {
      "type": "string",
      "value": "[variables('storageAccountName')]"
    }
  }
}

清理资源

不再需要 Azure 资源时,请删除资源组。

az group delete --name troubleshootRG

若要从门户中删除资源组,请执行以下步骤:

  1. 在 Azure 门户中的搜索框内输入“资源组”。
  2. 在“按名称筛选”字段中输入资源组名称。
  3. 选择资源组名称。
  4. 选择“删除资源组”。
  5. 若要确认删除,请输入资源组名称,然后选择“删除”。

后续步骤

在本快速入门中,你已了解如何排查 ARM 模板部署错误。