Utilizzare il toolkit di test dei modelli di ARM

Articolo
05/15/2024

Il toolkit di test del modello di Azure Resource Manager (modello di ARM) verifica se il modello rispetta le procedure consigliate. Se il modello non è conforme alle procedure consigliate, restituisce un elenco di avvisi con le modifiche suggerite. L'uso del toolkit di test consente di apprendere come evitare i problemi comuni durante lo sviluppo dei modelli. Questo articolo descrive come eseguire il toolkit di test e come aggiungere o rimuovere test. Per ulteriori informazioni su come eseguire i test o un test specifico, vedere Parametri di test.

Il toolkit è un set di script di PowerShell eseguibile tramite un comando in PowerShell o nell'interfaccia della riga di comando. Questi test sono elementi consigliati e non requisiti. È possibile decidere quali test sono rilevanti per gli obiettivi e personalizzare la scelta dei test da eseguire.

Il toolkit contiene quattro set di test:

Nota

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

Risorse di formazione

Per altre informazioni sul toolkit di test dei modelli di ARM e per indicazioni pratiche, vedere Convalidare le risorse di Azure usando il toolkit di test dei modelli di ARM.

Esegui l’installazione in Windows

Se non è già disponibile, installare PowerShell in Windows.
Scaricare il file .zip più recente per il toolkit di test, quindi estrarre il contenuto.
Avviare PowerShell.
Passare alla cartella in cui è stato estratto il toolkit di test. All'interno di questa cartella, scegliere la cartellaarm-ttk.
Se i criteri di esecuzione bloccano gli script provenienti da Internet, è necessario sbloccare i file di script. Assicurarsi di essere nella cartella arm-ttk.
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importare il modulo.
```
Import-Module .\arm-ttk.psd1
```
Per eseguire i test, utilizzare il comando seguente:
```
Test-AzTemplate -TemplatePath \path\to\template
```

Installare in Linux

Se non è già disponibile, installare PowerShell in Linux.
Scaricare il file .zip più recente per il toolkit di test, quindi estrarre il contenuto.
Avviare PowerShell.
```
pwsh
```
Passare alla cartella in cui è stato estratto il toolkit di test. All'interno di questa cartella, scegliere la cartellaarm-ttk.
Se i criteri di esecuzione bloccano gli script provenienti da Internet, è necessario sbloccare i file di script. Assicurarsi di essere nella cartella arm-ttk.
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importare il modulo.
```
Import-Module ./arm-ttk.psd1
```
Per eseguire i test, utilizzare il comando seguente:
```
Test-AzTemplate -TemplatePath /path/to/template
```

Eseguire l'installazione in macOS

Se non è già disponibile, installare PowerShell in macOS.
Installare coreutils:
```
brew install coreutils
```
Scaricare il file .zip più recente per il toolkit di test, quindi estrarre il contenuto.
Avviare PowerShell.
```
pwsh
```
Passare alla cartella in cui è stato estratto il toolkit di test. All'interno di questa cartella, scegliere la cartellaarm-ttk.
Se i criteri di esecuzione bloccano gli script provenienti da Internet, è necessario sbloccare i file di script. Assicurarsi di essere nella cartella arm-ttk.
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importare il modulo.
```
Import-Module ./arm-ttk.psd1
```
Per eseguire i test, utilizzare il comando seguente:
```
Test-AzTemplate -TemplatePath /path/to/template
```

Formato del risultato

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

I test non superati vengono visualizzati in rosso e preceduti da [-].

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

Screenshot of test results in different colors for pass, fail, and warning.

I risultati in formato 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

Se si specifica il parametro -TemplatePath, il toolkit cerca in questa cartella un modello denominato azuredeploy.json o maintemplate.json. In primo luogo viene eseguito il test di questo modello e poi di tutti gli altri modelli, nella cartella e nelle relative sottocartelle. Gli altri modelli vengono testati come modelli collegati. Se il percorso include un file denominato createUiDefinition.json, esso esegue i test rilevanti per la definizione dell'interfaccia utente. I test vengono eseguiti anche per i file dei parametri e per tutti i file JSON presenti nella cartella.

Test-AzTemplate -TemplatePath $TemplateFolder

Per testare un file nella cartella, aggiungere il parametro -File. 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 parametro -Test e specificare il nome del test. Per i nomi dei test, vedere Modelli di ARM, file dei parametri, createUiDefinition.jsone tutti i file.

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

Personalizzare i test

È possibile personalizzare i test predefiniti o creare nuovi test. Se si desidera rimuovere definitivamente un test, eliminare il file .test.ps1 dalla cartella.

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

Modelli di ARM: \arm-ttk\testcases\deploymentTemplate
File dei 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 di oggetto o come parametro di stringa. In genere, si usa uno o l'altro, ma è possibile utilizzare entrambi.

Usare il parametro di oggetto quando si deve ottenere una sezione del modello ed eseguire l'iterazione delle sue proprietà. Se un test usa il parametro di oggetto avrà 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 del 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 di stringa quando si deve eseguire un'operazione di stringa sull'intero modello. Se un test usa il parametro di stringa avrà 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 di stringa per verificare se viene utilizzata una sintassi specifica.

Per altre informazioni sull'implementazione del test, vedere gli altri test presenti nella cartella.

Convalidare i modelli per Azure Marketplace

Per pubblicare un'offerta in Azure Marketplace, utilizzare il toolkit di test per convalidare i modelli. Se i modelli superano i test di convalida, Azure Marketplace approverà l'offerta più rapidamente. Se invece non superano i test, l'offerta non otterrà la certificazione.

Importante

I test di Marketplace sono stati aggiunti a luglio 2022. Aggiornare il modulo se si utilizza una versione precedente.

Eseguire i test nell'ambiente in uso

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 i risultati in due sezioni. La prima sezione include i test obbligatori. I risultati di questi test vengono visualizzati nella sezione di riepilogo.

Importante

Prima dell’accettazione dell'offerta in Marketplace è necessario correggere gli eventuali risultati di colore rosso. È consigliabile correggere tutti i risultati restituiti di colore giallo.

I risultati in formato 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 sotto la sezione di riepilogo include gli errori di test che possono essere interpretati come avvisi. La correzione degli errori è facoltativa ma è vivamente consigliata. Spesso gli errori indicano dei problemi comuni che causano errori quando un cliente installa l'offerta.

Per correggere i test, attenersi al test case applicabile:

Inviare l'offerta

Dopo aver apportato le correzioni necessarie, eseguire nuovamente il toolkit di test. Prima di inviare l'offerta ad Azure Marketplace, assicurarsi che non siano presenti 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 si aggiorna il modello o eseguirlo come parte del processo di distribuzione.

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

In alternativa, è possibile implementare attività proprie. L'esempio seguente mostra come scaricare il toolkit di test.

Per la pipeline di versione:

{
  "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 della pipeline YAML:

- 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'esempio seguente mostra come eseguire i test.