Utilizzare il toolkit di test dei modelli di ARM
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:
- Test case per i modelli di ARM
- Test case per i file di parametri
- Test case per createUiDefinition.json
- Test case per tutti i file
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 [?]
.
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.
Per la pipeline di versione:
{
"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 della pipeline YAML:
- 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
- Per informazioni sui test dei modelli, vedere Test case per i modelli di ARM.
- Per testare i file di parametri, vedere Test case per i file dei parametri.
- Per i test createUiDefinition, vedere Test case per createUiDefinition.json.
- Per informazioni sui test per tutti i file, consultare Test case per tutti i file.
- Per consultare un modulo Learn che illustra l'uso del toolkit di test, vedere Convalidare le risorse di Azure usando il toolkit di test dei modelli di ARM.
Commenti e suggerimenti
https://aka.ms/ContentUserFeedback.
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedereInvia e visualizza il feedback per