快速入门:排查 ARM 模板 JSON 部署问题
本快速入门介绍如何排查 Azure 资源管理器模板(ARM 模板)JSON 部署错误。 你将设置一个存在错误的模板,并了解如何修复错误。
Azure 资源管理器模板是定义项目基础结构和配置的 JavaScript 对象表示法 (JSON) 文件。 模板使用声明性语法。 你可以在不编写用于创建部署的编程命令序列的情况下,描述预期部署。
有三种类型的错误与部署相关:
- 验证错误发生在部署开始之前,由文件中的语法错误造成。 像 Visual Studio Code 这样的代码编辑器可以识别这些错误。
- 当运行部署命令但未部署资源时,将发生预检验证错误。 这些错误是部署未开始的情况下出现的。 例如,如果某个参数值不正确,则会在预检验证中发现错误。
- 部署错误发生在部署过程中,只能通过评估 Azure 环境中的部署进度来发现。
所有类型的错误都会返回用于排查部署问题的错误代码。 验证错误和预检错误会显示在活动日志中,但不会显示在部署历史记录中。
先决条件
若要完成本快速入门,需要准备好以下各项:
- 如果没有 Azure 订阅,请在开始前创建试用版订阅。
- 包含最新 Azure 资源管理器工具扩展的 Visual Studio Code。
- 安装最新版本的 Azure PowerShell 或 Azure CLI。
创建包含错误的模板
复制以下模板并将其保存在本地。 你将使用此文件来排查验证错误、预检错误和部署错误。 本快速入门假设你已将文件命名为 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:
下的波浪线表示错误。 将鼠标指针悬停在错误上可查看验证错误。
你会注意到,variables
和 resources
存在错误,原因是“未定义参数引用”。 若要显示模板的验证错误,请选择“视图”>“问题” 。
所有错误都由元素名称拼写不正确导致。
"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 个字符以内且仅包含小写字母或数字的前缀。
由于部署未运行,因此没有部署历史记录。
活动日志显示预检错误。 选择日志可查看错误的详细信息。
修复部署错误
使用有效的前缀值(例如 storage
)运行部署。
az group create --name troubleshootRG --location chinanorth
az deployment group create \
--resource-group troubleshootRG \
--template-file troubleshoot.json \
--parameters prefixName=storage
系统将开始部署,并在部署历史记录中显示部署详细信息。 部署失败,因为 outputs
引用资源组中不存在的虚拟网络。 但是,存储帐户没有错误,因此部署了资源。 部署历史记录显示部署失败。
若要修复部署错误,请更改引用函数以使用有效资源。 有关详细信息,请参阅解决“找不到资源”错误。 对于本快速入门,请删除 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
若要从门户中删除资源组,请执行以下步骤:
- 在 Azure 门户中的搜索框内输入“资源组”。
- 在“按名称筛选”字段中输入资源组名称。
- 选择资源组名称。
- 选择“删除资源组”。
- 若要确认删除,请输入资源组名称,然后选择“删除”。
后续步骤
在本快速入门中,你已了解如何排查 ARM 模板部署错误。