Merge pull request #178357 from davidsmatlak/ds-tsdocs-1102

Updates ARM troubleshooting docs

Author: ttorble

articles/azure-resource-manager/troubleshooting/common-deployment-errors.md

@@ -0,0 +1,62 @@
+---
+title: Create a troubleshooting template
+description: Describes how to create a template to troubleshoot Azure resource deployed with Azure Resource Manager templates (ARM templates) or Bicep files.
+tags: top-support-issue
+ms.topic: troubleshooting
+ms.date: 11/02/2021
+---
+
+# Create a troubleshooting template
+
+In some cases, the best way to troubleshoot your template is to isolate and test specific parts of it. You can create a troubleshooting template that focuses on the resource that you believe causes the error.
+
+For example, an error occurs when your deployment template references an existing resource. Rather than evaluate an entire deployment template, create a troubleshooting template that returns data about the resource. The output helps you find whether you're passing in the correct parameters, using template functions correctly, and getting the resource you expect.
+
+## Deploy a troubleshooting template
+
+The following ARM template and Bicep file get information from an existing storage account. You run the deployment with Azure PowerShell [New-AzResourceGroupDeployment](/powershell/module/az.resources/new-azresourcegroupdeployment) or Azure CLI [az deployment group create](/cli/azure/deployment/group#az_deployment_group_create). Specify the storage account's name and resource group. The output is an object with the storage account's property names and values.
+
+```json
+{
+  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
+  "contentVersion": "1.0.0.0",
+  "parameters": {
+    "storageName": {
+      "type": "string"
+    },
+    "storageResourceGroup": {
+      "type": "string"
+    }
+  },
+  "variables": {},
+  "resources": [],
+  "outputs": {
+    "exampleOutput": {
+      "value": "[reference(resourceId(parameters('storageResourceGroup'), 'Microsoft.Storage/storageAccounts', parameters('storageName')), '2021-04-01')]",
+      "type": "object"
+    }
+  }
+}
+```
+
+In Bicep, use the `existing` keyword and run the deployment from the resource group where the storage account exists. Use `scope` to access a resource in a different resource group. For more information, see [existing resources](../bicep/resource-declaration.md#existing-resources).
+
+```bicep
+param storageName string
+
+resource stg 'Microsoft.Storage/storageAccounts@2021-04-01' existing = {
+  name: storageName
+}
+
+output exampleOutput object = stg.properties
+```
+
+## Alternate troubleshooting method
+
+If you believe the deployment errors are caused by incorrect dependencies, you can run tests by breaking the template into simplified templates. First, create a template that deploys only a single resource (like a SQL Server). When you're sure the resource deployment is correct, add a resource that depends on it (like a SQL Database). When those two resources are correctly defined, add other dependent resources (like auditing policies). In between each test deployment, delete the resource group to make sure you're adequately testing the dependencies.
+
+## Next steps
+
+- [Common deployment errors](common-deployment-errors.md)
+- [Find error codes](find-error-code.md)
+- [Enable debug logging](enable-debug-logging.md)

articles/azure-resource-manager/troubleshooting/create-troubleshooting-template.md

@@ -0,0 +1,112 @@
+---
+title: Enable debug logging
+description: Describes how to enable debug logging to troubleshoot Azure resources deployed with  Azure Resource Manager templates (ARM templates) or Bicep files.
+tags: top-support-issue
+ms.topic: troubleshooting
+ms.date: 11/02/2021
+ms.custom: devx-track-azurepowershell
+---
+
+# Enable debug logging
+
+To troubleshoot a deployment error, it helps to gather more information. Use Azure PowerShell to enable debug logging. You can get data about a deployment's request and response to learn the cause of the problem. Debug logging works with Azure Resource Manager templates (ARM templates) and Bicep files.
+
+## Get debug information
+
+# [PowerShell](#tab/azure-powershell)
+
+Use [New-AzResourceGroupDeployment](/powershell/module/az.resources/new-azresourcegroupdeployment) to set the `DeploymentDebugLogLevel` parameter to `All`, `ResponseContent`, or `RequestContent`. When debug logging is enabled, a warning is displayed that secrets like passwords or `listKeys` can be logged by commands like [Get-AzResourceGroupDeploymentOperation](/powershell/module/az.resources/get-azresourcegroupdeploymentoperation).
+
+```azurepowershell
+New-AzResourceGroupDeployment `
+  -Name exampledeployment `
+  -ResourceGroupName examplegroup `
+  -TemplateFile azuredeploy.json `
+  -DeploymentDebugLogLevel All
+```
+
+The output shows the debug logging:
+
+```Output
+DeploymentDebugLogLevel : RequestContent, ResponseContent
+```
+
+To view all the properties for deployment operations:
+
+```azurepowershell
+Get-AzResourceGroupDeploymentOperation `
+  -DeploymentName exampledeployment `
+  -ResourceGroupName examplegroup
+```
+
+You can specify a property. For example, the `StatusMessage` property outputs the same data as the Azure CLI `response` property.
+
+```azurepowershell
+(Get-AzResourceGroupDeploymentOperation `
+  -DeploymentName exampledeployment `
+  -ResourceGroupName examplegroup).StatusMessage
+```
+
+Use Azure CLI to get the debug `request` and `response` information. In Az module versions 4.8 and later, `Get-AzResourceGroupDeploymentOperation` doesn't include those properties in output. For a list of available properties, see [outputs](/powershell/module/az.resources/get-azresourcegroupdeploymentoperation#outputs).
+
+# [Azure CLI](#tab/azure-cli)
+
+You can't enable debug logging with Azure CLI but you can retrieve debug logging data.
+
+Get the deployment operations with the following command:
+
+```azurecli
+az deployment operation group list \
+  --resource-group examplegroup \
+  --name exampledeployment
+```
+
+Get the request content with the following command:
+
+```azurecli
+az deployment operation group list \
+  --name exampledeployment \
+  --resource-group examplegroup \
+  --query [].properties.request
+```
+
+Get the response content with the following command:
+
+```azurecli
+az deployment operation group list \
+  --name exampledeployment \
+  --resource-group examplegroup \
+  --query [].properties.response
+```
+
+---
+
+## Nested template
+
+To log debug information for a [nested](../templates/linked-templates.md#nested-template) ARM template, use the [Microsoft.Resources/deployments](/azure/templates/microsoft.resources/deployments) `debugSetting` element.
+
+```json
+{
+  "type": "Microsoft.Resources/deployments",
+  "apiVersion": "2020-10-01",
+  "name": "nestedTemplate",
+  "properties": {
+    "mode": "Incremental",
+    "templateLink": {
+      "uri": "{template-uri}",
+      "contentVersion": "1.0.0.0"
+    },
+    "debugSetting": {
+       "detailLevel": "requestContent, responseContent"
+    }
+  }
+}
+```
+
+Bicep uses [modules](../bicep/modules.md) rather than `Microsoft.Resources/deployments`. With modules, you can reuse your code to deploy a Bicep file from another Bicep file.
+
+## Next steps
+
+- [Common deployment errors](common-deployment-errors.md)
+- [Find error codes](find-error-code.md)
+- [Create troubleshooting template](create-troubleshooting-template.md)

articles/azure-resource-manager/troubleshooting/enable-debug-logging.md

@@ -0,0 +1,206 @@
+---
+title: Find error codes
+description: Describes how to find error codes to troubleshoot Azure resources deployed with Azure Resource Manager templates (ARM templates) or Bicep files.
+tags: top-support-issue
+ms.topic: troubleshooting
+ms.date: 11/02/2021
+ms.custom: devx-track-azurepowershell
+---
+
+# Find error codes
+
+When an Azure resource deployment fails using Azure Resource Manager templates (ARM templates) or Bicep files, and error code is received. This article describes how to find error codes so you can troubleshoot the problem. For more information about error codes, see [common deployment errors](common-deployment-errors.md).
+
+## Error types
+
+There are three types of errors you can receive:
+
+- **Validation errors** occur before a deployment begins and are caused by syntax errors. To identify validation errors, use [Visual Studio Code](https://code.visualstudio.com) with the latest [Bicep extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-bicep) or [Azure Resource Manager Tools extension](https://marketplace.visualstudio.com/items?itemName=msazurermtools.azurerm-vscode-tools).
+- **Preflight validation errors** occur when the deployment begins but resources aren't deployed. For example, an incorrect parameter value or invalid resource name.
+- **Deployment errors** occur during deployment and troubleshooting is needed to find the cause.
+
+Validation and preflight error codes are reported in a resource group's activity log, and the subscription's [activity log](../../azure-monitor/essentials/activity-log.md). An exception is Bicep syntax validation that's only shown in the editor or deployment command's output. Deployment error codes are shown in a resource group's deployment history and activity log.
+
+## Validation errors
+
+Templates are validated during the deployment process and error codes are displayed. Before you run a deployment, you can run validation tests with Azure PowerShell or Azure CLI.
+
+# [Portal](#tab/azure-portal)
+
+An ARM template can be deployed from the portal. If the template has syntax errors, you'll see a validation error when you try to run the deployment. For more information about portal deployments, see [deploy resources from custom template](../templates/deploy-portal.md#deploy-resources-from-custom-template).
+
+The following example attempts to deploy a storage account and a validation error occurs.
+
+:::image type="content" source="media/find-error-code/validation-error.png" alt-text="Screenshot of an Azure portal validation error.":::
+
+Select the message for more details. The template has a syntax error with error code `InvalidTemplate`. The **Summary** shows an expression is missing a closing parenthesis.
+
+:::image type="content" source="media/find-error-code/validation-details.png" alt-text="Screenshot of a validation error message that shows a syntax error.":::
+
+# [PowerShell](#tab/azure-powershell)
+
+To validate an ARM template before deployment run [Test-AzResourceGroupDeployment](/powershell/module/az.resources/test-azresourcegroupdeployment). The same error is shown when you run a deployment.
+
+```azurepowershell
+Test-AzResourceGroupDeployment `
+  -ResourceGroupName examplegroup `
+  -TemplateFile azuredeploy.json
+```
+
+The output displays error codes like `InvalidTemplateDeployment` or `AccountNameInvalid` that you can use to troubleshoot and fix the template.
+
+For a Bicep file, the output for a syntax validation problem shows a parameter error.
+
+```Output
+Test-AzResourceGroupDeployment: Cannot retrieve the dynamic parameters for the cmdlet.
+Cannot find path '/tmp/11111111-1111-1111-1111-111111111111/main.json' because it does not exist.
+```
+
+To get more troubleshooting information, use the Bicep [build](../bicep/bicep-cli.md) command. The output shows each error's line and column number in parentheses, and the error message.
+
+```bicep
+bicep build main.bicep
+```
+
+```Output
+/azuredeploy.bicep(22,51) : Error BCP064: Found unexpected tokens in interpolated expression.
+/azuredeploy.bicep(22,51) : Error BCP004: The string at this location is not terminated due to an
+  unexpected new line character.
+```
+
+There are more PowerShell cmdlets available to validate deployment templates:
+
+- [Test-AzDeployment](/powershell/module/az.resources/test-azdeployment) for subscription level deployments.
+- [Test-AzManagementGroupDeployment](/powershell/module/az.resources/test-azmanagementgroupdeployment)
+- [Test-AzTenantDeployment](/powershell/module/az.resources/test-aztenantdeployment)
+
+# [Azure CLI](#tab/azure-cli)
+
+To validate an ARM template before deployment, run [az deployment group validate](/cli/azure/deployment/group#az_deployment_group_validate). The same error is shown when you run a deployment.
+
+```azurecli
+az deployment group validate \
+  --resource-group examplegroup \
+  --template-file azuredeploy.json
+```
+
+The output displays error codes like `InvalidTemplateDeployment` or `AccountNameInvalid` that you can use to troubleshoot and fix the template.
+
+For a Bicep file, the output shows each error's line and column number in parentheses, and the error message.
+
+```azurecli
+az deployment group validate \
+  --resource-group examplegroup \
+  --template-file main.bicep
+```
+
+```Output
+/azuredeploy.bicep(22,51) : Error BCP064: Found unexpected tokens in interpolated expression.
+/azuredeploy.bicep(22,51) : Error BCP004: The string at this location is not terminated due to an
+  unexpected new line character.
+```
+
+There are more Azure CLI commands available to validate deployment templates:
+
+- [az deployment sub validate](/cli/azure/deployment/sub#az_deployment_sub_validate)
+- [az deployment mg validate](/cli/azure/deployment/mg#az_deployment_mg_validate)
+- [az deployment tenant validate](/cli/azure/deployment/tenant#az_deployment_tenant_validate)
+
+---
+
+## Deployment errors
+
+Several operations are processed to deploy an Azure resource. Deployment errors occur when an operation passes validation but fails during deployment. You can view messages about each deployment operation and each deployment for a resource group.
+
+# [Portal](#tab/azure-portal)
+
+To see messages about a deployment's operations, use the resource group's **Activity log**:
+
+1. Sign in to [Azure portal](https://portal.azure.com).
+1. Go to **Resource groups** and select the deployment's resource group name.
+1. Select **Activity log**.
+1. Use the filters to find an operation's error log.
+
+    :::image type="content" source="./media/find-error-code/activity-log.png" alt-text="Screenshot of the resource group's activity log that highlights a failed deployment.":::
+
+1. Select the error log to see the operation's details.
+
+    :::image type="content" source="./media/find-error-code/activity-log-details.png" alt-text="Screenshot of the activity log details that shows a failed deployment's error message.":::
+
+To view a deployment's result:
+
+1. Go to the resource group.
+1. Select **Settings** > **Deployments**.
+1. Select **Error details** for the deployment.
+
+    :::image type="content" source="media/find-error-code/deployment-error-details.png" alt-text="Screenshot of a resource group's link to error details for a failed deployment.":::
+
+1. The error message and error code `NoRegisteredProviderFound` are shown.
+
+    :::image type="content" source="media/find-error-code/deployment-error-summary.png" alt-text="Screenshot of a message that shows deployment error details.":::
+
+# [PowerShell](#tab/azure-powershell)
+
+To see a deployment's operations messages with PowerShell, use [Get-AzResourceGroupDeploymentOperation](/powershell/module/az.resources/get-azresourcegroupdeploymentoperation).
+
+To show all the operations for a deployment:
+
+```azurepowershell
+Get-AzResourceGroupDeploymentOperation `
+  -DeploymentName exampledeployment `
+  -ResourceGroupName examplegroup
+```
+
+To specify a specific property type:
+
+```azurepowershell
+(Get-AzResourceGroupDeploymentOperation `
+  -DeploymentName exampledeployment `
+  -ResourceGroupName examplegroup).StatusCode
+```
+
+To get a deployment's result, use [Get-AzResourceGroupDeployment](/powershell/module/az.resources/get-azresourcegroupdeployment).
+
+```azurepowershell
+Get-AzResourceGroupDeployment `
+  -DeploymentName exampledeployment `
+  -ResourceGroupName examplegroup
+```
+
+# [Azure CLI](#tab/azure-cli)
+
+To see a deployment's operations messages with Azure CLI, use [az deployment operation group list](/cli/azure/deployment/operation/group#az_deployment_operation_group_list).
+
+To show all the operations for a deployment:
+
+```azurecli
+az deployment operation group list \
+  --name exampledeployment \
+  --resource-group examplegroup \
+  --query "[*].properties"
+```
+
+To specify a specific property type:
+
+```azurecli
+az deployment operation group list \
+  --name exampledeployment \
+  --resource-group examplegroup \
+  --query "[*].properties.statusCode"
+```
+
+To get a deployment's result, use [az deployment group show](/cli/azure/deployment/group#az_deployment_group_show).
+
+```azurecli
+az deployment group show \
+  --resource-group examplegroup \
+  --name exampledeployment
+```
+
+---
+
+## Next steps
+
+- [Common deployment errors](common-deployment-errors.md)
+- [Enable debug logging](enable-debug-logging.md)
+- [Create troubleshooting template](create-troubleshooting-template.md)