Använda testverktyg för ARM-mallar

  • Artikel

Testverktyget för Azure Resource Manager-mall (ARM-mall) kontrollerar om mallen använder rekommenderade metoder. När mallen inte är kompatibel med rekommenderade metoder returneras en lista med varningar med de föreslagna ändringarna. Med hjälp av testverktyget kan du lära dig hur du undviker vanliga problem i mallutveckling. I den här artikeln beskrivs hur du kör testverktyget och hur du lägger till eller tar bort tester. Mer information om hur du kör tester eller hur du kör ett visst test finns i Testparametrar.

Verktygslådan är en uppsättning PowerShell-skript som kan köras från ett kommando i PowerShell eller CLI. De här testerna är rekommendationer men inte krav. Du kan bestämma vilka tester som är relevanta för dina mål och anpassa vilka tester som körs.

Verktygslådan innehåller fyra uppsättningar tester:

Anteckning

Testverktyget är endast tillgängligt för ARM-mallar. Om du vill verifiera Bicep-filer använder du Bicep-lintern.

Träningsresurser

Mer information om testverktygen för ARM-mallar och praktisk vägledning finns i Verifiera Azure-resurser med hjälp av testverktyget för ARM-mallar.

Installera i Windows

  1. Om du inte redan har PowerShell installerar du PowerShell i Windows.

  2. Ladda ned den senaste .zip filen för testverktyget och extrahera den.

  3. Starta PowerShell.

  4. Navigera till mappen där du extraherade testverktyget. Navigera till mappen arm-ttk i den mappen.

  5. Om din körningsprincip blockerar skript från Internet måste du avblockera skriptfilerna. Kontrollera att du är i mappen arm-ttk .

    Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File

  6. Importera modulen.

    Import-Module .\arm-ttk.psd1

  7. Kör testerna med följande kommando:

    Test-AzTemplate -TemplatePath \path\to\template

Installera på Linux

  1. Om du inte redan har PowerShell installerar du PowerShell på Linux.

  2. Ladda ned den senaste .zip filen för testverktyget och extrahera den.

  3. Starta PowerShell.

    pwsh

  4. Navigera till mappen där du extraherade testverktyget. Navigera till mappen arm-ttk i den mappen.

  5. Om din körningsprincip blockerar skript från Internet måste du avblockera skriptfilerna. Kontrollera att du är i mappen arm-ttk .

    Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File

  6. Importera modulen.

    Import-Module ./arm-ttk.psd1

  7. Kör testerna med följande kommando:

    Test-AzTemplate -TemplatePath /path/to/template

Installera på macOS

  1. Om du inte redan har PowerShell installerar du PowerShell på macOS.

  2. Installera coreutils:

    brew install coreutils

  3. Ladda ned den senaste .zip filen för testverktyget och extrahera den.

  4. Starta PowerShell.

    pwsh

  5. Navigera till mappen där du extraherade testverktyget. Navigera till mappen arm-ttk i den mappen.

  6. Om din körningsprincip blockerar skript från Internet måste du avblockera skriptfilerna. Kontrollera att du är i mappen arm-ttk .

    Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File

  7. Importera modulen.

    Import-Module ./arm-ttk.psd1

  8. Kör testerna med följande kommando:

    Test-AzTemplate -TemplatePath /path/to/template

Resultatformat

Tester som godkänns visas i grönt och föregås av [+].

Tester som misslyckas visas i rött och föregås av [-].

Tester med en varning visas i gult och föregås av [?].

Skärmbild av testresultat i olika färger för pass, fail och warning.

Textresultaten är:

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.

Testparametrar

När du anger parametern -TemplatePath letar toolkit i mappen efter en mall med namnet azuredeploy.json eller maintemplate.json. Den testar först den här mallen och testar sedan alla andra mallar i mappen och dess undermappar. De andra mallarna testas som länkade mallar. Om sökvägen innehåller en fil med namnet createUiDefinition.json körs tester som är relevanta för UI-definitionen. Tester körs också för parameterfiler och alla JSON-filer i mappen.

Test-AzTemplate -TemplatePath $TemplateFolder

Om du vill testa en fil i mappen lägger du till parametern -File . Mappen måste dock fortfarande ha en huvudmall med namnet azuredeploy.json eller maintemplate.json.

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

Som standard körs alla tester. Om du vill ange enskilda tester som ska köras använder du parametern -Test och anger testnamnet. Testnamnen finns i ARM-mallar, parameterfiler, createUiDefinition.json och alla filer.

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

Anpassa tester

Du kan anpassa standardtesterna eller skapa egna tester. Om du vill ta bort ett test permanent tar du bort .test.ps1-filen från mappen .

Verktygslådan har fyra mappar som innehåller standardtesterna som körs för specifika filtyper:

  • ARM-mallar: \arm-ttk\testcases\deploymentTemplate
  • Parameterfiler: \arm-ttk\testcases\deploymentParameters
  • createUiDefinition.json: \arm-ttk\testcases\CreateUIDefinition
  • Alla filer: \arm-ttk\testcases\AllFiles

Lägga till ett anpassat test

Om du vill lägga till ett eget test skapar du en fil med namngivningskonventionen: Your-Custom-Test-Name.test.ps1.

Testet kan hämta mallen som en objektparameter eller en strängparameter. Vanligtvis använder du den ena eller den andra, men du kan använda båda.

Använd objektparametern när du behöver hämta ett avsnitt i mallen och iterera genom dess egenskaper. Ett test som använder objektparametern har följande format:

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

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

Mallobjektet har följande egenskaper:

  • $schema
  • contentVersion
  • parameters
  • variables
  • resources
  • outputs

Du kan till exempel hämta samlingen med parametrar med $TemplateObject.parameters.

Använd strängparametern när du behöver utföra en strängåtgärd på hela mallen. Ett test som använder strängparametern har följande format:

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

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

Du kan till exempel köra ett reguljärt uttryck för strängparametern för att se om en specifik syntax används.

Mer information om hur du implementerar testet finns i de andra testerna i den mappen.

Verifiera mallar för Azure Marketplace

Om du vill publicera ett erbjudande till Azure Marketplace använder du testverktyget för att verifiera mallarna. När dina mallar klarar valideringstesterna godkänner Azure Marketplace erbjudandet snabbare. Om testerna misslyckas misslyckas certifieringen av erbjudandet.

Viktigt

Marketplace-testerna lades till i juli 2022. Uppdatera modulen om du har en tidigare version.

Köra testerna i din miljö

När du har installerat verktygslådan och importerat modulen kör du följande cmdlet för att testa paketet:

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

Tolka resultatet

Testerna returnerar resultat i två avsnitt. Det första avsnittet innehåller de tester som är obligatoriska. Resultatet av dessa tester visas i sammanfattningsavsnittet.

Viktigt

Du måste åtgärda eventuella resultat i rött innan Marketplace-erbjudandet accepteras. Vi rekommenderar att du åtgärdar eventuella resultat som returneras i gult.

Textresultaten är:

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

Avsnittet under sammanfattningsavsnittet innehåller testfel som kan tolkas som varningar. Det är valfritt att åtgärda felen, men rekommenderas starkt. Felen pekar ofta på vanliga problem som orsakar fel när en kund installerar erbjudandet.

Följ det testfall som gäller för dig för att åtgärda dina tester:

Skicka erbjudandet

När du har gjort nödvändiga korrigeringar kör du testverktyget igen. Innan du skickar in ditt erbjudande till Azure Marketplace kontrollerar du att det inte finns några fel.

Integrera med Azure Pipelines

Du kan lägga till testverktyget i din Azure Pipeline. Med en pipeline kan du köra testet varje gång mallen uppdateras eller köra den som en del av distributionsprocessen.

Det enklaste sättet att lägga till testverktyget i din pipeline är med tillägg från tredje part. Följande två tillägg är tillgängliga:

Eller så kan du implementera dina egna uppgifter. I följande exempel visas hur du laddar ned testverktyget.

För versionspipeline:

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

För YAML-definition för 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'

I nästa exempel visas hur du kör testerna.

För versionspipeline:

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

För YAML-definition för pipeline:

- 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

Nästa steg