Utiliser un kit de ressources de test de modèle ARM

Article
03/20/2024

Le kit de ressources de test de modèles Azure Resource Manager (ARM) vérifie si un modèle applique les pratiques recommandées. Lorsque votre modèle n’est pas conforme aux pratiques recommandées, il retourne une liste d’avertissements avec les modifications suggérées. Avec le kit de ressources de test, vous pouvez apprendre à éviter les problèmes courants liés au développement de modèles. Cet article explique les procédures d’exécution du kit de ressources de test, et d’ajout ou de suppression 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.

Le kit de ressources 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 pas des exigences. Vous pouvez choisir les tests qui sont pertinents pour vos objectifs et personnaliser les tests à exécuter.

Le kit de ressources contient quatre ensembles de tests :

Notes

Le kit de ressources de test est disponible seulement pour les modèles ARM. Pour valider des fichiers Bicep, utilisez le linter Bicep.

Ressources de formation

Pour en savoir plus sur le kit de ressources de test de modèle ARM et pour obtenir une aide pratique, consultez Valider des ressources Azure à l’aide du kit de ressources 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 kit de ressources de test et extrayez-le.
Démarrez PowerShell.
Accédez au dossier dans lequel vous avez extrait le kit de ressources 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. Vérifiez que vous êtes bien 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 kit de ressources de test et extrayez-le.
Démarrez PowerShell.
```
pwsh
```
Accédez au dossier dans lequel vous avez extrait le kit de ressources 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. Vérifiez que vous êtes bien 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 kit de ressources de test et extrayez-le.
Démarrez PowerShell.
```
pwsh
```
Accédez au dossier dans lequel vous avez extrait le kit de ressources 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. Vérifiez que vous êtes bien 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 réussis s’affichent en vert et sont précédés de [+] .

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

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

Capture d’écran des résultat de test avec des couleurs différentes pour réussite, échec et avertissement.

Résultats de texte :

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 paramètre -TemplatePath, le kit de ressources 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 comprend un fichier nommé createUiDefinition.json, il exécute les tests qui sont pertinents pour la définition de l’interface utilisateur. Les tests sont également exécutés pour les fichiers de paramètres et tous les fichiers JSON dans le dossier.

Test-AzTemplate -TemplatePath $TemplateFolder

Pour tester un fichier dans ce dossier, ajoutez le paramètre -File. 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 les tests individuels à exécuter, utilisez le paramètre -Test et fournissez le nom du test. Pour les noms de test, consultez modèles ARM, fichiers de paramètres, createUiDefinition.json et 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.

Le kit de ressources contient 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 respectant la convention d’affectation de noms : Nom-de-votre-test-personnalisé.test.ps1.

Le test peut obtenir le modèle sous la forme d’un paramètre d’objet ou d’un 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 d’objet lorsque vous devez obtenir une section du modèle et itérer au sein de ses propriétés. Un test qui utilise le paramètre d’objet 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 de modèle présente 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 de chaîne lorsque vous devez effectuer une opération de chaîne sur l’ensemble du modèle. Un test qui utilise le paramètre de chaîne 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 de chaîne pour voir si une syntaxe spécifique est utilisée.

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

Valider des 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. Si vos modèles réussissent les tests de validation, la Place de marché Azure approuvera votre offre plus rapidement. S’ils échouent aux tests, la certification de l’offre échouera.

Important

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

Exécuter les tests dans votre environnement

Après avoir installé le kit de ressources 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 retournent des résultats dans deux sections. La première section inclut les tests obligatoires. Les résultats de ces tests sont affichés dans la section récapitulative.

Important

Vous devez corriger les résultats en rouge pour que l’offre de la Place de marché soit acceptée. Nous vous recommandons de corriger les résultats affichés en jaune.

Résultats de texte :

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 figurant sous la section récapitulative comprend les échecs aux tests qui peuvent être interprétés comme des avertissements. La correction des échecs est facultative mais fortement recommandée. Les échecs pointent souvent vers des problèmes courants qui provoquent des échecs lorsqu’un client installe votre offre.

Pour corriger vos tests, suivez le cas de test applicable :

Soumettre l’offre

Après avoir apporté les corrections nécessaires, réexécutez le kit de ressources de test. Avant de soumettre votre offre à la Place de marché Azure, vérifiez que vous avez zéro échec.

Intégrer à Azure Pipelines

Vous pouvez ajouter le kit de ressources de test à votre pipeline Azure. 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 le kit de ressources de test à votre pipeline consiste à utiliser des extensions tierces. Les deux extensions suivantes sont disponibles :

Run ARM TTK Tests (Exécuter les tests de modèle ARM TTK)
ARM Template Tester (Testeur de modèle ARM)

Vous pouvez également implémenter vos propres tâches. L’exemple suivant illustre la procédure de téléchargement du kit de ressources 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 du 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 illustre la procédure d’exécution des tests.