Test-toolkit voor ARM-sjablonen gebruiken

Artikel
03/20/2024

Met de TEST-toolkit voor Azure Resource Manager-sjablonen (ARM-sjabloon) wordt gecontroleerd of uw sjabloon gebruikmaakt van aanbevolen procedures. Wanneer uw sjabloon niet voldoet aan de aanbevolen procedures, retourneert deze een lijst met waarschuwingen met de voorgestelde wijzigingen. Met behulp van de test-toolkit kunt u leren hoe u veelvoorkomende problemen bij het ontwikkelen van sjablonen kunt voorkomen. In dit artikel wordt beschreven hoe u de test-toolkit uitvoert en hoe u tests toevoegt of verwijdert. Zie Testparameters voor meer informatie over het uitvoeren van tests of het uitvoeren van een specifieke test.

De toolkit is een set PowerShell-scripts die kunnen worden uitgevoerd vanuit een opdracht in PowerShell of CLI. Deze tests zijn aanbevelingen, maar geen vereisten. U kunt bepalen welke tests relevant zijn voor uw doelen en aanpassen welke tests worden uitgevoerd.

De toolkit bevat vier sets tests:

Notitie

De test-toolkit is alleen beschikbaar voor ARM-sjablonen. Als u Bicep-bestanden wilt valideren, gebruikt u de Bicep-linter.

Training en bronnen

Zie Azure-resources valideren met behulp van de TEST-toolkit voor ARM-sjablonen voor meer informatie over de TEST-toolkit voor ARM-sjablonen en voor praktische richtlijnen.

Installeren in Windows

Als u PowerShell nog niet hebt, installeert u PowerShell in Windows.
Download het meest recente .zip-bestand voor de test-toolkit en pak het uit.
Start PowerShell.
Navigeer naar de map waarin u de test-toolkit hebt uitgepakt. Navigeer in die map naar de map arm-ttk .
Als uw uitvoeringsbeleid scripts van internet blokkeert, moet u de blokkering van de scriptbestanden opheffen. Zorg ervoor dat u zich in de map arm-ttk bevindt.
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importeer de module.
```
Import-Module .\arm-ttk.psd1
```
Gebruik de volgende opdracht om de tests uit te voeren:
```
Test-AzTemplate -TemplatePath \path\to\template
```

Installeren in Linux

Als u PowerShell nog niet hebt, installeert u PowerShell in Linux.
Download het meest recente .zip-bestand voor de test-toolkit en pak het uit.
Start PowerShell.
```
pwsh
```
Navigeer naar de map waarin u de test-toolkit hebt uitgepakt. Navigeer in die map naar de map arm-ttk .
Als uw uitvoeringsbeleid scripts van internet blokkeert, moet u de blokkering van de scriptbestanden opheffen. Zorg ervoor dat u zich in de map arm-ttk bevindt.
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importeer de module.
```
Import-Module ./arm-ttk.psd1
```
Gebruik de volgende opdracht om de tests uit te voeren:
```
Test-AzTemplate -TemplatePath /path/to/template
```

Installeren in Mac OS

Als u PowerShell nog niet hebt, installeert u PowerShell op macOS.
coreutils installeren:
```
brew install coreutils
```
Download het meest recente .zip-bestand voor de test-toolkit en pak het uit.
Start PowerShell.
```
pwsh
```
Navigeer naar de map waarin u de test-toolkit hebt uitgepakt. Navigeer in die map naar de map arm-ttk .
Als uw uitvoeringsbeleid scripts van internet blokkeert, moet u de blokkering van de scriptbestanden opheffen. Zorg ervoor dat u zich in de map arm-ttk bevindt.
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importeer de module.
```
Import-Module ./arm-ttk.psd1
```
Gebruik de volgende opdracht om de tests uit te voeren:
```
Test-AzTemplate -TemplatePath /path/to/template
```

Resultaatopmaak

Tests die slagen, worden groen weergegeven en voorafgegaan door [+].

Tests die mislukken, worden rood weergegeven en worden voorafgegaan door [-].

Tests met een waarschuwing worden geel weergegeven en voorafgegaan door [?].

Schermopname van testresultaten in verschillende kleuren voor geslaagd, mislukt en waarschuwing.

De tekstresultaten zijn:

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.

Testparameters

Wanneer u de -TemplatePath parameter opgeeft, zoekt de toolkit in die map naar een sjabloon met de naam azuredeploy.json of maintemplate.json. Deze sjabloon wordt eerst getest en vervolgens worden alle andere sjablonen in de map en de submappen getest. De andere sjablonen worden getest als gekoppelde sjablonen. Als uw pad een bestand bevat met de naam createUiDefinition.json, worden tests uitgevoerd die relevant zijn voor de definitie van de gebruikersinterface. Tests worden ook uitgevoerd voor parameterbestanden en alle JSON-bestanden in de map.

Test-AzTemplate -TemplatePath $TemplateFolder

Als u één bestand in die map wilt testen, voegt u de -File parameter toe. De map moet echter nog steeds een hoofdsjabloon hebben met de naam azuredeploy.json of maintemplate.json.

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

Standaard worden alle tests uitgevoerd. Als u afzonderlijke tests wilt opgeven die moeten worden uitgevoerd, gebruikt u de -Test parameter en geeft u de testnaam op. Zie ARM-sjablonen, parameterbestanden, createUiDefinition.json en alle bestanden voor de testnamen.

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

Tests aanpassen

U kunt de standaardtests aanpassen of uw eigen tests maken. Als u een test definitief wilt verwijderen, verwijdert u het .test.ps1-bestand uit de map.

De toolkit bevat vier mappen met de standaardtests die worden uitgevoerd voor specifieke bestandstypen:

ARM-sjablonen: \arm-ttk\testcases\deploymentTemplate
Parameterbestanden: \arm-ttk\testcases\deploymentParameters
createUiDefinition.json: \arm-ttk\testcases\CreateUIDefinition
Alle bestanden: \arm-ttk\testcases\AllFiles

Een aangepaste test toevoegen

Als u uw eigen test wilt toevoegen, maakt u een bestand met de naamconventie: Your-Custom-Test-Name.test.ps1.

De test kan de sjabloon ophalen als objectparameter of tekenreeksparameter. Normaal gesproken gebruikt u het ene of het andere, maar u kunt beide gebruiken.

Gebruik de objectparameter wanneer u een sectie van de sjabloon wilt ophalen en de eigenschappen ervan wilt doorlopen. Een test die gebruikmaakt van de objectparameter heeft de volgende indeling:

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

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

Het sjabloonobject heeft de volgende eigenschappen:

$schema
contentVersion
parameters
variables
resources
outputs

U kunt bijvoorbeeld de verzameling parameters ophalen met $TemplateObject.parameters.

Gebruik de tekenreeksparameter wanneer u een tekenreeksbewerking moet uitvoeren op de hele sjabloon. Een test die gebruikmaakt van de tekenreeksparameter heeft de volgende indeling:

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

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

U kunt bijvoorbeeld een reguliere expressie van de tekenreeksparameter uitvoeren om te zien of er een specifieke syntaxis wordt gebruikt.

Bekijk de andere tests in die map voor meer informatie over het implementeren van de test.

Sjablonen voor Azure Marketplace valideren

Als u een aanbieding wilt publiceren naar Azure Marketplace, gebruikt u de test-toolkit om de sjablonen te valideren. Wanneer uw sjablonen de validatietests doorstaan, keurt Azure Marketplace uw aanbieding sneller goed. Als ze niet voldoen aan de tests, mislukt de certificering van de aanbieding.

Belangrijk

De Marketplace-tests zijn in juli 2022 toegevoegd. Werk uw module bij als u een eerdere versie hebt.

De tests uitvoeren in uw omgeving

Nadat u de toolkit hebt geïnstalleerd en de module hebt geïmporteerd, voert u de volgende cmdlet uit om uw pakket te testen:

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

De resultaten interpreteren

De tests retourneren resultaten in twee secties. De eerste sectie bevat de tests die verplicht zijn. De resultaten van deze tests worden weergegeven in de samenvattingssectie.

Belangrijk

U moet eventuele resultaten rood herstellen voordat de Marketplace-aanbieding wordt geaccepteerd. We raden u aan om alle resultaten die in het geel worden geretourneerd, op te lossen.

De tekstresultaten zijn:

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

De sectie onder de samenvattingssectie bevat testfouten die kunnen worden geïnterpreteerd als waarschuwingen. Het oplossen van de fouten is optioneel, maar wordt sterk aanbevolen. De fouten wijzen vaak op veelvoorkomende problemen die fouten veroorzaken wanneer een klant uw aanbieding installeert.

Volg de testcase die voor u van toepassing is om uw tests op te lossen:

De aanbieding verzenden

Nadat u de benodigde oplossingen hebt uitgevoerd, voert u de test-toolkit opnieuw uit. Voordat u uw aanbieding naar Azure Marketplace verzendt, moet u ervoor zorgen dat er geen fouten zijn.

Integreren met Azure Pipelines

U kunt de test-toolkit toevoegen aan uw Azure-pijplijn. Met een pijplijn kunt u de test elke keer uitvoeren wanneer de sjabloon wordt bijgewerkt, of deze uitvoeren als onderdeel van uw implementatieproces.

De eenvoudigste manier om de test-toolkit toe te voegen aan uw pijplijn is met extensies van derden. De volgende twee extensies zijn beschikbaar:

U kunt ook uw eigen taken implementeren. In het volgende voorbeeld ziet u hoe u de test-toolkit downloadt.

Voor release-pijplijn:

{
  "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": ""
  }
}

Voor yaml-definitie van pijplijn:

- 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'

In het volgende voorbeeld ziet u hoe u de tests uitvoert.