Verwenden des Resource Manager-Vorlagen-Testtoolkits

Artikel
03/20/2024

Das ARM-Vorlagen-Testtoolkit (Azure Resource Manager) überprüft, ob Ihre Vorlage die empfohlenen Vorgehensweisen umsetzt. Wenn Ihre Vorlage nicht mit den empfohlenen Vorgehensweisen kompatibel ist, wird eine Liste mit Warnungen ausgegeben, die vorgeschlagene Änderungen enthält. Mit dem Testtoolkit erfahren Sie, wie Sie häufige Probleme bei der Vorlagenentwicklung vermeiden. In diesem Artikel wird beschrieben, wie Sie das Testtoolkit ausführen und Tests hinzufügen oder entfernen. Weitere Informationen zur Ausführungsweise von Tests oder eines bestimmten Tests finden Sie unter Testparameter.

Das Toolkit ist ein Satz von PowerShell-Skripts, die über einen Befehl in PowerShell oder in der Befehlszeilenschnittstelle ausgeführt werden können. Diese Tests werden empfohlen, sind aber nicht erforderlich. Sie können entscheiden, welche Tests für Ihre Ziele relevant sind, und anpassen, welche Tests ausgeführt werden.

Das Toolkit enthält vier Testsätze:

Hinweis

Das Testtoolkit ist nur für ARM-Vorlagen verfügbar. Verwenden Sie zum Überprüfen von Bicep-Dateien den Bicep-Linter.

Schulungsressourcen

Weitere Informationen zum ARM-Vorlagen-Testtoolkit und praktische Anleitungen finden Sie unter Überprüfen von Azure-Ressourcen mit dem ARM-Vorlagen-Testtoolkit.

Installieren unter Windows

Wenn Sie noch nicht über PowerShell verfügen, installieren Sie PowerShell unter Windows.
Laden Sie die neueste ZIP-Datei für das Testtoolkit herunter, und extrahieren Sie sie.
Starten Sie PowerShell.
Navigieren Sie zu dem Ordner, in dem Sie das Testtoolkit extrahiert haben. Navigieren Sie in diesem Ordner zum Ordner arm-ttk.
Wenn die Ausführungsrichtlinie Skripts aus dem Internet blockiert, müssen Sie die Blockierung der Skriptdateien deaktivieren. Vergewissern Sie sich, dass Sie sich im Ordner arm-ttk befinden.
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importieren Sie das Modul.
```
Import-Module .\arm-ttk.psd1
```
Verwenden Sie den folgenden Befehl, um die Tests auszuführen:
```
Test-AzTemplate -TemplatePath \path\to\template
```

Installation unter Linux

Wenn Sie noch nicht über PowerShell verfügen, installieren Sie PowerShell unter Linux.
Laden Sie die neueste ZIP-Datei für das Testtoolkit herunter, und extrahieren Sie sie.
Starten Sie PowerShell.
```
pwsh
```
Navigieren Sie zu dem Ordner, in dem Sie das Testtoolkit extrahiert haben. Navigieren Sie in diesem Ordner zum Ordner arm-ttk.
Wenn die Ausführungsrichtlinie Skripts aus dem Internet blockiert, müssen Sie die Blockierung der Skriptdateien deaktivieren. Vergewissern Sie sich, dass Sie sich im Ordner arm-ttk befinden.
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importieren Sie das Modul.
```
Import-Module ./arm-ttk.psd1
```
Verwenden Sie den folgenden Befehl, um die Tests auszuführen:
```
Test-AzTemplate -TemplatePath /path/to/template
```

Installieren unter macOS

Wenn Sie noch nicht über PowerShell verfügen, installieren Sie PowerShell unter macOS.
Installieren Sie coreutils:
```
brew install coreutils
```
Laden Sie die neueste ZIP-Datei für das Testtoolkit herunter, und extrahieren Sie sie.
Starten Sie PowerShell.
```
pwsh
```
Navigieren Sie zu dem Ordner, in dem Sie das Testtoolkit extrahiert haben. Navigieren Sie in diesem Ordner zum Ordner arm-ttk.
Wenn die Ausführungsrichtlinie Skripts aus dem Internet blockiert, müssen Sie die Blockierung der Skriptdateien deaktivieren. Vergewissern Sie sich, dass Sie sich im Ordner arm-ttk befinden.
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importieren Sie das Modul.
```
Import-Module ./arm-ttk.psd1
```
Verwenden Sie den folgenden Befehl, um die Tests auszuführen:
```
Test-AzTemplate -TemplatePath /path/to/template
```

Ergebnisformat

Bestandene Tests werden in Grün mit vorangestelltem [+] angezeigt.

Fehlerhafte Tests werden in Rot mit vorangestelltem [-] angezeigt.

Tests mit einer Warnung werden in Gelb und mit vorangestelltem [?] angezeigt.

Screenshot der Testergebnisse in verschiedenen Farben für Erfolg, Fehler und Warnung.

Die Testergebnisse sind:

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.

Testparameter

Wenn Sie den -TemplatePath-Parameter angeben, sucht das Toolkit in diesem Ordner nach einer Vorlage mit dem Namen azuredeploy.json oder maintemplate.json. Es testet zunächst diese Vorlage und anschließend alle anderen Vorlagen im Ordner und seinen Unterordnern. Die anderen Vorlagen werden als verknüpfte Vorlagen getestet. Wenn Ihr Pfad eine Datei mit dem Namen createUiDefinition.json enthält, werden Tests ausgeführt, die für die Benutzeroberflächendefinition relevant sind. Tests werden auch für Parameterdateien und alle JSON-Dateien im Ordner ausgeführt.

Test-AzTemplate -TemplatePath $TemplateFolder

Fügen Sie den Parameter -File hinzu, um eine Datei in diesem Ordner zu testen. Der Ordner muss jedoch weiterhin über eine Hauptvorlage mit dem Namen azuredeploy.json oder maintemplate.json verfügen.

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

Standardmäßig werden alle Tests ausgeführt. Verwenden Sie den Parameter -Test, um einzelne Tests anzugeben, die ausgeführt werden sollen, und geben Sie den Testnamen an. Die Testnamen finden Sie unter ARM-Vorlagen, Parameterdateien, createUiDefinition.js und alle Dateien.

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

Anpassen der Tests

Sie können die Standardtests anpassen oder eigene Tests erstellen. Wenn Sie einen Test dauerhaft entfernen möchten, löschen Sie die Datei .test.ps1 aus dem Ordner.

Das Toolkit verfügt über vier Ordner, die die Standardtests enthalten, die für bestimmte Dateitypen ausgeführt werden:

ARM-Vorlagen: \arm-ttk\testcases\deploymentTemplate
Parameterdateien: \arm-ttk\testcases\deploymentParameters
createUiDefinition.json: \arm-ttk\testcases\CreateUIDefinition
Alle Dateien: \arm-ttk\testcases\AllFiles

Hinzufügen eines benutzerdefinierten Tests

Wenn Sie einen eigenen Test hinzufügen möchten, erstellen Sie eine Datei mit der Namenskonvention: Your-Custom-Test-Name.test.ps1.

Der Test kann die Vorlage als Objektparameter oder Zeichenfolgenparameter erhalten. In der Regel können Sie nur das eine oder das andere, nicht aber beides verwenden.

Verwenden Sie Objektparameter, wenn Sie die Eigenschaften eines Abschnitts der Vorlage durchgehen müssen. Ein Test, der den Objektparameter verwendet, weist das folgende Format auf:

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

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

Das Vorlagenobjekt weist die folgenden Eigenschaften auf:

$schema
contentVersion
parameters
variables
resources
outputs

Sie können beispielsweise eine Auflistung von Parametern mithilfe von $TemplateObject.parameters abrufen.

Verwenden Sie Zeichenfolgenparameter, wenn Sie einen Zeichenfolgenvorgang für die gesamte Vorlage ausführen müssen. Ein Test, der den Zeichenfolgenparameter verwendet, weist das folgende Format auf:

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

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

Sie können beispielsweise einen regulären Ausdruck des Zeichenfolgenparameters ausführen, um festzustellen, ob eine bestimmte Syntax verwendet wird.

Wenn Sie mehr über das Implementieren des Tests erfahren möchten, sehen Sie sich die anderen Tests in diesem Ordner an.

Überprüfen von Vorlagen für Azure Marketplace

Um ein Angebot im Azure Marketplace zu veröffentlichen, verwenden Sie das Testtoolkit, um die Vorlagen zu überprüfen. Wenn Ihre Vorlagen die Validierungsprüfungen bestehen, wird Ihr Angebot schneller vom Azure Marketplace genehmigt. Wenn Ihre Vorlagen die Tests nicht bestehen, erfolgt keine Zertifizierung für das Angebot.

Wichtig

Die Marketplace-Tests wurden im Juli 2022 hinzugefügt. Aktualisieren Sie Ihr Modul, wenn Sie über eine frühere Version verfügen.

Ausführen der Tests in Ihrer Umgebung

Führen Sie nach der Installation des Toolkits und dem Import des Moduls das folgende Cmdlet aus, um Ihr Paket zu testen:

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

Interpretieren der Ergebnisse

Die Ergebnisse der Tests sind in zwei Abschnitte unterteilt. Der erste Abschnitt enthält die vorgeschriebenen Tests. Die Ergebnisse dieser Tests werden im Abschnitt „Zusammenfassung“ angezeigt.

Wichtig

Sie müssen alle rot markierten Ergebnisse korrigieren, damit das Marketplace-Angebot akzeptiert wird. Es wird empfohlen, alle gelb markierten Ergebnisse zu korrigieren.

Die Testergebnisse sind:

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

Der Abschnitt unter der Zusammenfassung enthält Testfehler, die als Warnungen interpretiert werden können. Das Beheben der Fehler ist optional, wird aber dringend empfohlen. Sie weisen häufig auf allgemeine Probleme hin, die bei der Installation Ihres Angebots durch einen Kunden zu Fehlern führen.

Um Ihre Tests zu beheben, befolgen Sie den für Sie anwendbaren Testfall:

Übermitteln des Angebots

Führen Sie das Testtoolkit erneut aus, nachdem Sie alle erforderlichen Korrekturen vorgenommen haben. Stellen Sie vor der Übermittlung Ihres Angebots an den Azure Marketplace sicher, dass keinerlei Fehler vorliegen.

Integration in Azure Pipelines

Sie können das Testtoolkit zu Ihrer Azure Pipeline hinzufügen. Mit einer Pipeline können Sie den Test bei jeder Aktualisierung der Vorlage oder als Teil des Bereitstellungsprozesses ausführen.

Die einfachste Möglichkeit zum Hinzufügen des Testtoolkits zu Ihrer Pipeline besteht in Erweiterungen von Drittanbietern. Hierfür sind die folgenden beiden Erweiterungen verfügbar:

Sie können auch eigene Aufgaben implementieren. Das folgende Beispiel zeigt, wie Sie das Testtoolkit herunterladen.

Für eine Releasepipeline:

{
  "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 die YAML-Definition einer 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'

Im nächsten Beispiel sehen Sie, wie die Tests ausgeführt werden.