Activer l’enregistrement du débogage

  • Article

Pour résoudre une erreur de déploiement, vous pouvez activer la journalisation de débogage afin d’obtenir plus d’informations. La journalisation de débogage fonctionne pour les déploiements effectués avec des fichiers Bicep ou des modèles Azure Resource Manager (modèles ARM). Vous pouvez obtenir des données sur la demande et la réponse d’un déploiement de connaître la cause d’un problème.

Avertissement

La journalisation de débogage peut exposer des secrets tels que des mots de passe ou des opérations listKeys. Activez uniquement l’enregistrement de débogage lorsque vous devez résoudre une erreur de déploiement. Une fois le débogage terminé, supprimez l’historique de déploiement de débogage.

Configurer l’enregistrement de débogage

Utilisez Azure PowerShell pour activer la journalisation de débogage qui remplit les propriétés request et response avec des informations de déploiement à des fins de résolution des problèmes. La journalisation de débogage ne peut pas être activée à l’aide d’Azure CLI.

La journalisation de débogage n’est activée que pour le modèle ARM principal ou le fichier Bicep. Si vous utilisez des modèles ARM imbriqués ou des modules Bicep, consultez Débogage d’un modèle imbriqué.

Pour un déploiement de groupe de ressources, utilisez New-AzResourceGroupDeployment afin de définir le paramètre DeploymentDebugLogLevel sur All, ResponseContent ou RequestContent.

Lorsque la journalisation de débogage est activée, un avertissement s’affiche. Il indique que des secrets tels que des mots de passe ou des opérations listKeys peuvent être consignés et affichés lorsque vous utilisez des commandes de type Get-AzResourceGroupDeploymentOperation pour obtenir des informations sur des opérations de déploiement.

New-AzResourceGroupDeployment `
  -Name exampledeployment `
  -ResourceGroupName examplegroup `
  -TemplateFile main.bicep `
  -DeploymentDebugLogLevel All

La sortie du déploiement affiche le niveau de journalisation de débogage.

DeploymentDebugLogLevel : RequestContent, ResponseContent

Le paramètre DeploymentDebugLogLevel est disponible pour d’autres étendues de déploiement : abonnement, groupe d’administration et locataire.

Obtenir des informations de débogage

Une fois la journalisation de débogage activée, vous pouvez obtenir des informations sur les opérations de déploiement. Les cmdlets Azure PowerShell relatives aux opérations de déploiement ne génèrent pas les propriétés request ni response. Vous devez utiliser Azure CLI pour tirer des informations de ces propriétés.

Vous pouvez obtenir des renseignements sur les opérations de déploiement même sans activer la journalisation de débogage avec la commande de déploiement. Utilisez Azure PowerShell ou Azure CLI pour récupérer le code d’état, le message d’état et l’état d’approvisionnement.

Pour un déploiement de groupe de ressources, utilisez Get-AzResourceGroupDeploymentOperation pour obtenir des opérations de déploiement.

Get-AzResourceGroupDeploymentOperation `
  -DeploymentName exampledeployment `
  -ResourceGroupName examplegroup

Vous pouvez spécifier une propriété (par exemple StatusCode, StatusMessage ou ProvisioningState) pour filtrer la sortie.

(Get-AzResourceGroupDeploymentOperation `
  -DeploymentName exampledeployment `
  -ResourceGroupName examplegroup).StatusCode

Pour plus d’informations, consultez la documentation relative aux étendues des opérations de déploiement : abonnement, groupe d’administration et locataire.

Débogage d’un modèle imbriqué

Le modèle ARM principal et les modèles imbriqués possèdent leur propre nom de déploiement et leur propre historique de déploiement. Le module et le fichier Bicep principal utilisent également un nom de déploiement et un historique de déploiement distincts.

Modèle ARM

Pour journaliser les informations de débogage d’un modèle ARM imbriqué, utilisez Microsoft.Resources/deployments avec la propriété debugSetting.

L’exemple suivant montre un modèle imbriqué avec debugSetting pour journaliser la demande et la réponse du déploiement.

"resources": [
  {
    "type": "Microsoft.Resources/deployments",
    "apiVersion": "2021-04-01",
    "name": "nestedTemplateDebug",
    "properties": {
      "mode": "Incremental",
      "template": {
        "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
        "contentVersion": "1.0.0.0",
        "resources": [
          {
            "type": "Microsoft.Storage/storageAccounts",
            "apiVersion": "2022-05-01",
            "name": "[variables('storageAccountName')]",
            "location": "[parameters('location')]",
            "sku": {
              "name": "[parameters('storageAccountType')]"
            },
            "kind": "StorageV2"
          }
        ]
      },
      "debugSetting": {
        "detailLevel": "requestContent, responseContent"
      }
    }
  }
],

Le modèle ARM principal et les modèles imbriqués possèdent leur propre nom de déploiement et leur propre historique de déploiement. Si vous souhaitez que les propriétés request et response contiennent des informations de résolution des problèmes, tenez compte des scénarios de déploiement suivants :

  • Les propriétés request et response contiennent des valeurs null pour le modèle principal et le modèle imbriqué quand DeploymentDebugLogLevel n’est pas activé avec la commande de déploiement.
  • Lorsque la commande de déploiement active DeploymentDebugLogLevel, les propriétés request et response ne contiennent que des informations relatives au modèle principal. Les propriétés du modèle imbriqué comportent des valeurs null.
  • Lorsqu’un modèle imbriqué utilise debugSetting et que la commande de déploiement n’inclut pas DeploymentDebugLogLevel, seul le déploiement du modèle imbriqué comprend des valeurs pour les propriétés request et response. Les propriétés du modèle principal contiennent des valeurs null.
  • Pour obtenir les informations request et response du modèle principal et du modèle imbriqué, spécifiez DeploymentDebugLogLevel dans la commande de déploiement et utilisez debugSetting dans le modèle imbriqué.

Fichier Bicep

La recommandation pour les fichiers Bicep consiste à utiliser des modules plutôt que des modèles imbriqués avec Microsoft.Resources/deployments. Le message d’état, le code d’état et l’état d’approvisionnement incluent des informations relatives au module et au fichier Bicep principal qui permettent de résoudre les problèmes de déploiement.

Si vous activez DeploymentDebugLogLevel avec la commande de déploiement, les propriétés request et response ne contiennent que des informations relatives au déploiement du fichier Bicep principal.

Supprimer l’historique de déploiement de débogage

Une fois le débogage terminé, supprimez l’historique de déploiement pour empêcher toute personne disposant d’un accès d’afficher d’éventuelles informations sensibles enregistrées. Pour chacun des noms de déploiement utilisés lors du débogage, exécutez la commande permettant de supprimer l’historique de déploiement.

Pour supprimer l’historique de déploiement d’un déploiement de groupe de ressources, utilisez Remove-AzResourceGroupDeployment.

Remove-AzResourceGroupDeployment -ResourceGroupName examplegroup -Name exampledeployment

La commande retourne True une fois qu’elle réussit.

Pour plus d’informations sur l’historique de déploiement, consultez la documentation relative aux étendues de déploiement : abonnement, groupe d’administration et locataire.

Étapes suivantes