Utiliser la boîte à outils de test de modèle ARM

Le kit de test du modèle Azure Resource Manager (modèle ARM) vérifie si votre modèle utilise les pratiques recommandées. Lorsque votre modèle n’est pas conforme aux pratiques recommandées, il renvoie une liste d’avertissements avec les modifications suggérées. En utilisant la boîte à outils de test, vous pouvez apprendre à éviter les problèmes courants dans le développement de modèles. Cet article décrit comment exécuter le kit de test et comment ajouter ou supprimer des tests. Pour plus d’informations sur l’exécution de tests ou sur l’exécution d’un test spécifique, consultez Paramètres de test.

La boîte à outils est un ensemble de scripts PowerShell qui peuvent être exécutés à partir d’une commande dans PowerShell ou CLI. Ces tests sont des recommandations, mais non des exigences. Vous pouvez décider quels tests sont pertinents pour vos objectifs et personnaliser les tests exécutés.

La boîte à outils contient quatre séries de tests :

Remarque

La boîte à outils de test n’est disponible que pour les modèles ARM. Pour valider les fichiers Bicep, utilisez le linter Bicep.

Ressources de formation

Pour en savoir plus sur le kit de test de modèle ARM et pour obtenir des conseils pratiques, consultez Valider les ressources Azure à l’aide du kit de test de modèle ARM.

Installer sur Windows

Si vous n’avez pas encore PowerShell, installez PowerShell sur Windows.
Téléchargez le dernier fichier .zip pour la boîte à outils de test et extrayez-le.
Démarrez PowerShell.
Accédez au dossier dans lequel vous avez extrait la boîte à outils de test. Dans ce dossier, accédez au dossier arm-ttk .
Si votre stratégie d’exécution bloque les scripts provenant d’Internet, vous devez débloquer les fichiers de script. Assurez-vous que vous êtes dans le dossier arm-ttk .
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importez le module .
```
Import-Module .\arm-ttk.psd1
```
Pour exécuter les tests, utilisez la commande suivante :
```
Test-AzTemplate -TemplatePath \path\to\template
```

Installer sur Linux

Si vous n’avez pas encore PowerShell, installez PowerShell sur Linux.
Téléchargez le dernier fichier .zip pour la boîte à outils de test et extrayez-le.
Démarrez PowerShell.
```
pwsh
```
Accédez au dossier dans lequel vous avez extrait la boîte à outils de test. Dans ce dossier, accédez au dossier arm-ttk .
Si votre stratégie d’exécution bloque les scripts provenant d’Internet, vous devez débloquer les fichiers de script. Assurez-vous que vous êtes dans le dossier arm-ttk .
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importez le module .
```
Import-Module ./arm-ttk.psd1
```
Pour exécuter les tests, utilisez la commande suivante :
```
Test-AzTemplate -TemplatePath /path/to/template
```

Installer sur macOS

Si vous n’avez pas encore PowerShell, installez PowerShell sur macOS.
Installez coreutils :
```
brew install coreutils
```
Téléchargez le dernier fichier .zip pour la boîte à outils de test et extrayez-le.
Démarrez PowerShell.
```
pwsh
```
Accédez au dossier dans lequel vous avez extrait la boîte à outils de test. Dans ce dossier, accédez au dossier arm-ttk .
Si votre stratégie d’exécution bloque les scripts provenant d’Internet, vous devez débloquer les fichiers de script. Assurez-vous que vous êtes dans le dossier arm-ttk .
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importez le module .
```
Import-Module ./arm-ttk.psd1
```
Pour exécuter les tests, utilisez la commande suivante :
```
Test-AzTemplate -TemplatePath /path/to/template
```

Format de résultat

Les tests qui réussissent sont affichés en vert et précédés de [+].

Les tests qui échouent sont affichés en rouge et précédés de [-].

Les tests avec un avertissement sont affichés en jaune et précédés de [?].

Capture d’écran des résultats du test en différentes couleurs pour la réussite, l’échec et l’avertissement.

Les résultats textuels sont les suivants :

deploymentTemplate
[+] adminUsername Should Not Be A Literal (6 ms)
[+] apiVersions Should Be Recent In Reference Functions (9 ms)
[-] apiVersions Should Be Recent (6 ms)
    Api versions must be the latest or under 2 years old (730 days) - API version 2019-06-01 of
    Microsoft.Storage/storageAccounts is 760 days old
    Valid Api Versions:
    2021-04-01
    2021-02-01
    2021-01-01
    2020-08-01-preview

[+] artifacts parameter (4 ms)
[+] CommandToExecute Must Use ProtectedSettings For Secrets (9 ms)
[+] DependsOn Best Practices (5 ms)
[+] Deployment Resources Must Not Be Debug (6 ms)
[+] DeploymentTemplate Must Not Contain Hardcoded Uri (4 ms)
[?] DeploymentTemplate Schema Is Correct (6 ms)
    Template is using schema version '2015-01-01' which has been deprecated and is no longer
    maintained.

Paramètres de test

Lorsque vous fournissez le -TemplatePath paramètre, la boîte à outils recherche dans ce dossier un modèle nommé azuredeploy.json ou maintemplate.json. Il teste d’abord ce modèle, puis teste tous les autres modèles du dossier et de ses sous-dossiers. Les autres modèles sont testés en tant que modèles liés. Si votre chemin d’accès inclut un fichier nommé createUiDefinition.json, il exécute des tests pertinents pour la définition de l’interface utilisateur. Des tests sont également exécutés pour les fichiers de paramètres et tous les fichiers JSON du dossier.

Test-AzTemplate -TemplatePath $TemplateFolder

Pour tester un fichier dans ce dossier, ajoutez le -File paramètre. Toutefois, le dossier doit toujours avoir un modèle principal nommé azuredeploy.json ou maintemplate.json.

Test-AzTemplate -TemplatePath $TemplateFolder -File cdn.json

Par défaut, tous les tests sont exécutés. Pour spécifier des tests individuels à exécuter, utilisez le -Test paramètre et indiquez le nom du test. Pour connaître les noms des tests, consultez Modèles ARM, fichiers de paramètres, createUiDefinition.jsonet tous les fichiers.

Test-AzTemplate -TemplatePath $TemplateFolder -Test "Resources Should Have Location"

Personnaliser les tests

Vous pouvez personnaliser les tests par défaut ou créer vos propres tests. Si vous souhaitez supprimer définitivement un test, supprimez le fichier .test.ps1 du dossier.

La boîte à outils comporte quatre dossiers qui contiennent les tests par défaut exécutés pour des types de fichiers spécifiques :

Modèles ARM : \arm-ttk\testcases\deploymentTemplate
Fichiers de paramètres : \arm-ttk\testcases\deploymentParameters
createUiDefinition.json: \arm-ttk\testcases\CreateUIDefinition
Tous les fichiers : \arm-ttk\testcases\AllFiles

Ajouter un test personnalisé

Pour ajouter votre propre test, créez un fichier avec la convention de nommage : Your-Custom-Test-Name.test.ps1.

Le test peut obtenir le modèle en tant que paramètre d’objet ou paramètre de chaîne. En règle générale, vous utilisez l’un ou l’autre, mais vous pouvez utiliser les deux.

Utilisez le paramètre object lorsque vous avez besoin d’obtenir une section du modèle et d’itérer dans ses propriétés. Un test qui utilise le paramètre object a le format suivant :

param(
  [Parameter(Mandatory=$true,Position=0)]
  [PSObject]
  $TemplateObject
)

# Implement test logic that evaluates parts of the template.
# Output error with: Write-Error -Message

L’objet modèle possède les propriétés suivantes :

$schema
contentVersion
parameters
variables
resources
outputs

Par exemple, vous pouvez obtenir la collection de paramètres avec $TemplateObject.parameters.

Utilisez le paramètre string lorsque vous devez effectuer une opération de chaîne sur l’ensemble du modèle. Un test qui utilise le paramètre string a le format suivant :

param(
  [Parameter(Mandatory)]
  [string]
  $TemplateText
)

# Implement test logic that performs string operations.
# Output error with: Write-Error -Message

Par exemple, vous pouvez exécuter une expression régulière du paramètre string pour voir si une syntaxe spécifique est utilisée.

Pour en savoir plus sur l’implémentation du test, consultez les autres tests dans ce dossier.

Valider les modèles pour la Place de marché Azure

Pour publier une offre sur la Place de marché Azure, utilisez le kit de ressources de test pour valider les modèles. Lorsque vos modèles réussissent les tests de validation, la Place de marché Azure approuve votre offre plus rapidement. S’ils échouent aux tests, l’offre échouera à la certification.

Important

Les tests Marketplace ont été ajoutés en juillet 2022. Mettez à jour votre module si vous disposez d’une version antérieure.

Exécutez les tests dans votre environnement

Après avoir installé le kit d’outils et importé le module, exécutez l’applet de commande suivante pour tester votre package :

Test-AzMarketplacePackage -TemplatePath "Path to the unzipped package folder"

Interpréter les résultats

Les tests renvoient les résultats en deux sections. La première section comprend les tests obligatoires. Les résultats de ces tests sont affichés dans la section récapitulative.

Important

Vous devez corriger tous les résultats en rouge avant que l’offre Marketplace ne soit acceptée. Nous vous recommandons de corriger tous les résultats qui reviennent en jaune.

Les résultats textuels sont les suivants :

Validating nestedtemplates\AzDashboard.json
    [+] adminUsername Should Not Be A Literal (210 ms)
    [+] artifacts parameter (3 ms)
    [+] CommandToExecute Must Use ProtectedSettings For Secrets (201 ms)
    [+] Deployment Resources Must Not Be Debug (160 ms)
    [+] DeploymentTemplate Must Not Contain Hardcoded Url (13 ms)
    [+] Location Should Not Be Hardcoded (31 ms)
    [+] Min and Max Value Are Numbers (4 ms)
    [+] Outputs Must Not Contain Secrets (9 ms)
    [+] Password params must be secure (3 ms)
    [+] Resources Should Have Location (2 ms)
    [+] Resources Should Not Be Ambiguous (2 ms)
    [+] Secure Params In Nested Deployments (205 ms)
    [+] Secure String Parameters Cannot Have Default (3 ms)
    [+] URIs Should Be Properly Constructed (190 ms)
    [+] Variables Must Be Referenced (9 ms)
    [+] Virtual Machines Should Not Be Preview (173 ms)
    [+] VM Size Should Be A Parameter (165 ms)
Pass : 99
Fail : 3
Total: 102
Validating StartStopV2mkpl_1.0.09302021\anothertemplate.json
    [?] Parameters Must Be Referenced (86 ms)
        Unreferenced parameter: resourceGroupName
        Unreferenced parameter: location
        Unreferenced parameter: azureFunctionAppName
        Unreferenced parameter: applicationInsightsName
        Unreferenced parameter: applicationInsightsRegion

La section sous la section récapitulative comprend les échecs de test qui peuvent être interprétés comme des avertissements. La correction des pannes est facultative mais fortement recommandée. Les échecs sont souvent le signe de problèmes courants qui provoquent des échecs lorsqu’un client installe votre offre.

Pour corriger vos tests, suivez le cas de test qui vous concerne :

Envoyer l’offre

Après avoir apporté les correctifs nécessaires, réexécutez la boîte à outils de test. Avant de soumettre votre offre à la Place de marché Azure, assurez-vous que vous n’avez aucun échec.

Intégrer à Azure Pipelines

Vous pouvez ajouter le kit de ressources de test à votre Azure Pipeline. Avec un pipeline, vous pouvez exécuter le test chaque fois que le modèle est mis à jour ou l’exécuter dans le cadre de votre processus de déploiement.

Le moyen le plus simple d’ajouter la boîte à outils de test à votre pipeline consiste à utiliser des extensions tierces. Les deux extensions suivantes sont disponibles :

Vous pouvez également mettre en œuvre vos propres tâches. L’exemple suivant montre comment télécharger la boîte à outils de test.

Pour le pipeline de mise en production :

{
  "environment": {},
  "enabled": true,
  "continueOnError": false,
  "alwaysRun": false,
  "displayName": "Download TTK",
  "timeoutInMinutes": 0,
  "condition": "succeeded()",
  "task": {
    "id": "e213ff0f-5d5c-4791-802d-52ea3e7be1f1",
    "versionSpec": "2.*",
    "definitionType": "task"
  },
  "inputs": {
    "targetType": "inline",
    "filePath": "",
    "arguments": "",
    "script": "New-Item '$(ttk.folder)' -ItemType Directory\nInvoke-WebRequest -uri '$(ttk.uri)' -OutFile \"$(ttk.folder)/$(ttk.asset.filename)\" -Verbose\nGet-ChildItem '$(ttk.folder)' -Recurse\n\nWrite-Host \"Expanding files...\"\nExpand-Archive -Path '$(ttk.folder)/*.zip' -DestinationPath '$(ttk.folder)' -Verbose\n\nWrite-Host \"Expanded files found:\"\nGet-ChildItem '$(ttk.folder)' -Recurse",
    "errorActionPreference": "stop",
    "failOnStderr": "false",
    "ignoreLASTEXITCODE": "false",
    "pwsh": "true",
    "workingDirectory": ""
  }
}

Pour la définition YAML de pipeline :

- pwsh: |
   New-Item '$(ttk.folder)' -ItemType Directory
   Invoke-WebRequest -uri '$(ttk.uri)' -OutFile "$(ttk.folder)/$(ttk.asset.filename)" -Verbose
   Get-ChildItem '$(ttk.folder)' -Recurse
   
   Write-Host "Expanding files..."
   Expand-Archive -Path '$(ttk.folder)/*.zip' -DestinationPath '$(ttk.folder)' -Verbose
   
   Write-Host "Expanded files found:"
   Get-ChildItem '$(ttk.folder)' -Recurse
  displayName: 'Download TTK'

L’exemple suivant montre comment exécuter les tests.