Usare il toolkit di test del modello di Resource Manager

  • Articolo

Il toolkit di test del modello di Azure Resource Manager (modello ARM) verifica se il modello usa le procedure consigliate. Quando il modello non è conforme alle procedure consigliate, restituisce un elenco di avvisi con le modifiche suggerite. Usando il toolkit di test, è possibile informazioni su come evitare problemi comuni nello sviluppo di modelli. Questo articolo descrive come eseguire il toolkit di test e come aggiungere o rimuovere test. Per altre informazioni su come eseguire test o come eseguire un test specifico, vedere Parametri di test.

Il toolkit è un set di script di PowerShell che possono essere eseguiti da un comando in PowerShell o nell'interfaccia della riga di comando. Questi test sono raccomandazioni ma non requisiti. È possibile decidere quali test sono rilevanti per gli obiettivi e personalizzare quali test vengono eseguiti.

Il toolkit contiene quattro set di test:

Nota

Il toolkit di test è disponibile solo per i modelli di Resource Manager. Per convalidare i file Bicep, usare linter Bicep.

Risorse di formazione

Per altre informazioni sul toolkit di test dei modelli di Arm e per indicazioni dettagliate, vedere Convalidare le risorse di Azure usando ARM Template Test Toolkit.

Eseguire l'installazione in Windows

  1. Se powerShell non è già disponibile, installare PowerShell in Windows.

  2. Scaricare il file di .zip più recente per il toolkit di test ed estrarlo.

  3. Avviare PowerShell.

  4. Passare alla cartella in cui è stato estratto il toolkit di test. All'interno di tale cartella passare alla cartella arm-ttk .

  5. Se i criteri di esecuzione bloccano gli script da Internet, è necessario sbloccare i file di script. Assicurarsi di essere nella cartella arm-ttk .

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

  6. Importare il modulo.

    Import-Module .\arm-ttk.psd1

  7. Per eseguire i test, usare il comando seguente:

    Test-AzTemplate -TemplatePath \path\to\template

Installare in Linux

  1. Se powerShell non è già disponibile, installare PowerShell in Linux.

  2. Scaricare il file di .zip più recente per il toolkit di test ed estrarlo.

  3. Avviare PowerShell.

    pwsh

  4. Passare alla cartella in cui è stato estratto il toolkit di test. All'interno di tale cartella passare alla cartella arm-ttk .

  5. Se i criteri di esecuzione bloccano gli script da Internet, è necessario sbloccare i file di script. Assicurarsi di essere nella cartella arm-ttk .

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

  6. Importare il modulo.

    Import-Module ./arm-ttk.psd1

  7. Per eseguire i test, usare il comando seguente:

    Test-AzTemplate -TemplatePath /path/to/template

Eseguire l'installazione in macOS

  1. Se powerShell non è già disponibile, installare PowerShell in macOS.

  2. Installare coreutils:

    brew install coreutils

  3. Scaricare il file di .zip più recente per il toolkit di test ed estrarlo.

  4. Avviare PowerShell.

    pwsh

  5. Passare alla cartella in cui è stato estratto il toolkit di test. All'interno di tale cartella passare alla cartella arm-ttk .

  6. Se i criteri di esecuzione bloccano gli script da Internet, è necessario sbloccare i file di script. Assicurarsi di essere nella cartella arm-ttk .

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

  7. Importare il modulo.

    Import-Module ./arm-ttk.psd1

  8. Per eseguire i test, usare il comando seguente:

    Test-AzTemplate -TemplatePath /path/to/template

Formato del risultato

I test che superano vengono visualizzati in verde e preceduti da [+].

I test che hanno esito negativo vengono visualizzati in rosso e preceduti da [-].

I test con un avviso vengono visualizzati in giallo e preceduto da [?].

Screenshot dei risultati dei test in colori diversi per il passaggio, l'esito negativo e l'avviso.

I risultati del testo sono:

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.

Parametri di test

Quando si specifica il parametro, il -TemplatePath toolkit cerca in tale cartella un modello denominato azuredeploy.json o maintemplate.json. Testa prima questo modello e quindi verifica tutti gli altri modelli nella cartella e le relative sottocartelle. Gli altri modelli vengono testati come modelli collegati. Se il percorso include un file denominato createUiDefinition.json, esegue test rilevanti per la definizione dell'interfaccia utente. I test vengono eseguiti anche per i file di parametri e tutti i file JSON nella cartella.

Test-AzTemplate -TemplatePath $TemplateFolder

Per testare un file in tale cartella, aggiungere il -File parametro . Tuttavia, la cartella deve comunque avere un modello principale denominato azuredeploy.json o maintemplate.json.

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

Per impostazione predefinita, vengono eseguiti tutti i test. Per specificare singoli test da eseguire, usare il -Test parametro e specificare il nome del test. Per i nomi di test, vedere Modelli di Resource Manager, file di parametri, createUiDefinition.json e tutti i file.

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

Personalizzare i test

È possibile personalizzare i test predefiniti o creare test personalizzati. Se si vuole rimuovere definitivamente un test, eliminare il file con estensione test.ps1 dalla cartella.

Il toolkit include quattro cartelle che contengono i test predefiniti eseguiti per tipi di file specifici:

  • Modelli arm: \arm-ttk\testcases\deploymentTemplate
  • File di parametri: \arm-ttk\testcases\deploymentParameters
  • createUiDefinition.json: \arm-ttk\testcases\CreateUIDefinition
  • Tutti i file: \arm-ttk\testcases\AllFiles

Aggiungere un test personalizzato

Per aggiungere un test personalizzato, creare un file con la convenzione di denominazione: Your-Custom-Test-Name.test.ps1.

Il test può ottenere il modello come parametro oggetto o un parametro stringa. In genere, si usa uno o l'altro, ma è possibile usare entrambi.

Usare il parametro dell'oggetto quando è necessario ottenere una sezione del modello e scorrere le relative proprietà. Un test che usa il parametro dell'oggetto ha il formato seguente:

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

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

L'oggetto modello ha le proprietà seguenti:

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

Ad esempio, è possibile ottenere la raccolta di parametri con $TemplateObject.parameters.

Usare il parametro stringa quando è necessario eseguire un'operazione stringa sull'intero modello. Un test che usa il parametro stringa ha il formato seguente:

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

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

Ad esempio, è possibile eseguire un'espressione regolare del parametro stringa per verificare se viene usata una sintassi specifica.

Per altre informazioni sull'implementazione del test, esaminare gli altri test in tale cartella.

Convalidare i modelli per Azure Marketplace

Per pubblicare un'offerta in Azure Marketplace, usare il toolkit di test per convalidare i modelli. Quando i modelli superano i test di convalida, Azure Marketplace approva l'offerta più rapidamente. Se hanno esito negativo, l'offerta avrà esito negativo.

Importante

I test del Marketplace sono stati aggiunti nel luglio 2022. Aggiornare il modulo se è disponibile una versione precedente.

Eseguire i test nell'ambiente

Dopo aver installato il toolkit e importato il modulo, eseguire il cmdlet seguente per testare il pacchetto:

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

Interpretare i risultati

I test restituiscono risultati in due sezioni. La prima sezione include i test obbligatori. I risultati di questi test vengono visualizzati nella sezione riepilogo.

Importante

È necessario correggere tutti i risultati in rosso prima che l'offerta del Marketplace venga accettata. È consigliabile correggere tutti i risultati restituiti in giallo.

I risultati del testo sono:

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 sezione seguente nella sezione riepilogo include errori di test che possono essere interpretati come avvisi. La correzione degli errori è facoltativa ma altamente consigliata. Gli errori spesso puntano a problemi comuni che causano errori quando un cliente installa l'offerta.

Per correggere i test, seguire il test case applicabile all'utente:

Inviare l'offerta

Dopo aver apportato eventuali correzioni necessarie, eseguire nuovamente il toolkit di test. Prima di inviare l'offerta a Azure Marketplace, assicurarsi di avere zero errori.

Eseguire l'integrazione con Azure Pipelines

È possibile aggiungere il toolkit di test alla pipeline di Azure. Con una pipeline è possibile eseguire il test ogni volta che il modello viene aggiornato o eseguito come parte del processo di distribuzione.

Il modo più semplice per aggiungere il toolkit di test alla pipeline è con estensioni di terze parti. Sono disponibili due estensioni seguenti:

In alternativa, è possibile implementare le proprie attività. Nell'esempio seguente viene illustrato come scaricare il toolkit di test.

Per la pipeline di rilascio:

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

Per la definizione YAML della 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'

Nell'esempio successivo viene illustrato come eseguire i test.

Per la pipeline di rilascio:

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

Per la definizione YAML della 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

Passaggi successivi