Delen via


Test-toolkit voor ARM-sjablonen gebruiken

De test-toolkit voor Azure Resource Manager-sjablonen (ARM-sjabloon) controleert of uw sjabloon gebruikmaakt van aanbevolen procedures. Wanneer uw sjabloon niet voldoet aan aanbevolen procedures, wordt er een lijst met waarschuwingen met de voorgestelde wijzigingen geretourneerd. Met behulp van de test-toolkit leert u 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 welke tests worden uitgevoerd.

De toolkit bevat vier sets tests:

Opmerking

De test-toolkit is alleen beschikbaar voor ARM-sjablonen. Gebruik bicep-linter om Bicep-bestanden te valideren.

Trainingsmateriaal

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

  1. Als u nog geen PowerShell hebt, installeert u PowerShell in Windows.

  2. Download het meest recente .zip-bestand voor de test-toolkit en pak het uit.

  3. Start PowerShell.

  4. Navigeer naar de map waarin u de test-toolkit hebt uitgepakt. Navigeer in die map naar de map arm-ttk.

  5. 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
    
  6. Importeer de module.

    Import-Module .\arm-ttk.psd1
    
  7. Gebruik de volgende opdracht om de tests uit te voeren:

    Test-AzTemplate -TemplatePath \path\to\template
    

Installeren op Linux

  1. Als u nog geen PowerShell hebt, installeert u PowerShell in Linux.

  2. Download het meest recente .zip-bestand voor de test-toolkit en pak het uit.

  3. Start PowerShell.

    pwsh
    
  4. Navigeer naar de map waarin u de test-toolkit hebt uitgepakt. Navigeer in die map naar de map arm-ttk.

  5. 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
    
  6. Importeer de module.

    Import-Module ./arm-ttk.psd1
    
  7. Gebruik de volgende opdracht om de tests uit te voeren:

    Test-AzTemplate -TemplatePath /path/to/template
    

Installeren in Mac OS

  1. Als u nog geen PowerShell hebt, installeert u PowerShell in macOS.

  2. coreutils installeren:

    brew install coreutils
    
  3. Download het meest recente .zip-bestand voor de test-toolkit en pak het uit.

  4. Start PowerShell.

    pwsh
    
  5. Navigeer naar de map waarin u de test-toolkit hebt uitgepakt. Navigeer in die map naar de map arm-ttk.

  6. 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
    
  7. Importeer de module.

    Import-Module ./arm-ttk.psd1
    
  8. Gebruik de volgende opdracht om de tests uit te voeren:

    Test-AzTemplate -TemplatePath /path/to/template
    

Resultaatopmaak

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

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

Tests met een waarschuwing worden geel weergegeven en worden 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 parameter opgeeft, zoekt de toolkit in die map naar een sjabloon met de -TemplatePath naam azuredeploy.json of maintemplate.json. Deze sjabloon wordt eerst getest en vervolgens alle andere sjablonen in de map en de bijbehorende submappen getest. De andere sjablonen worden getest als gekoppelde sjablonen. Als uw pad een bestand bevat met de naamcreateUiDefinition.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.jsonen 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 heeft vier mappen die de standaardtests bevatten 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 een objectparameter of een tekenreeksparameter. Normaal gesproken gebruikt u een of meer, 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 op de hele sjabloon moet uitvoeren. 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 een specifieke syntaxis wordt gebruikt.

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

Sjablonen valideren voor Azure Marketplace

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, zal Azure Marketplace uw aanbieding sneller goedkeuren. 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 eerst de resultaten die rood gemarkeerd zijn corrigeren voordat de aanbiedingen in de Marketplace worden geaccepteerd. We raden u aan alle resultaten te corrigeren die geel zijn gemarkeerd.

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 overzichtssectie bevat testfouten die kunnen worden geïnterpreteerd als waarschuwingen. Het oplossen van de fouten is optioneel, maar wordt ten zeerste 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 indienen

Nadat u de benodigde oplossingen hebt aangebracht, voert u de test-toolkit opnieuw uit. Voordat u uw aanbieding indient bij Azure Marketplace, moet u ervoor zorgen dat er geen fouten optreden.

Integreren met Azure Pipelines

U kunt de test-toolkit toevoegen aan uw Azure Pipeline. 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 de YAML-definitie van de 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.

Voor release-pijplijn:

{
  "environment": {},
  "enabled": true,
  "continueOnError": true,
  "alwaysRun": false,
  "displayName": "Run Best Practices Tests",
  "timeoutInMinutes": 0,
  "condition": "succeeded()",
  "task": {
    "id": "e213ff0f-5d5c-4791-802d-52ea3e7be1f1",
    "versionSpec": "2.*",
    "definitionType": "task"
  },
  "inputs": {
    "targetType": "inline",
    "filePath": "",
    "arguments": "",
    "script": "Import-Module $(ttk.folder)/arm-ttk/arm-ttk.psd1 -Verbose\n$testOutput = @(Test-AzTemplate -TemplatePath \"$(sample.folder)\")\n$testOutput\n\nif ($testOutput | ? {$_.Errors }) {\n   exit 1 \n} else {\n    Write-Host \"##vso[task.setvariable variable=result.best.practice]$true\"\n    exit 0\n} \n",
    "errorActionPreference": "continue",
    "failOnStderr": "true",
    "ignoreLASTEXITCODE": "false",
    "pwsh": "true",
    "workingDirectory": ""
  }
}

Voor de YAML-definitie van de pijplijn:

- pwsh: |
   Import-Module $(ttk.folder)/arm-ttk/arm-ttk.psd1 -Verbose
   $testOutput = @(Test-AzTemplate -TemplatePath "$(sample.folder)")
   $testOutput
   
   if ($testOutput | ? {$_.Errors }) {
      exit 1 
   } else {
       Write-Host "##vso[task.setvariable variable=result.best.practice]$true"
       exit 0
   } 
  errorActionPreference: continue
  failOnStderr: true
  displayName: 'Run Best Practices Tests'
  continueOnError: true

Volgende stappen