Korzystanie z zestawu narzędzi do testowania szablonu usługi ARM

Artykuł
03/20/2024

Zestaw narzędzi do testowania szablonu usługi Azure Resource Manager (szablon usługi ARM) sprawdza, czy szablon używa zalecanych rozwiązań. Jeśli szablon nie jest zgodny z zalecanymi rozwiązaniami, zwraca listę ostrzeżeń z sugerowanymi zmianami. Korzystając z zestawu narzędzi do testowania, możesz dowiedzieć się, jak uniknąć typowych problemów podczas tworzenia szablonów. W tym artykule opisano sposób uruchamiania zestawu narzędzi do testowania oraz sposobu dodawania lub usuwania testów. Aby uzyskać więcej informacji na temat uruchamiania testów lub uruchamiania określonego testu, zobacz Parametry testu.

Zestaw narzędzi to zestaw skryptów programu PowerShell, które można uruchamiać za pomocą polecenia w programie PowerShell lub interfejsie wiersza polecenia. Te testy są zaleceniami, ale nie wymaganiami. Możesz zdecydować, które testy są istotne dla Twoich celów i dostosować, które testy są uruchamiane.

Zestaw narzędzi zawiera cztery zestawy testów:

Uwaga

Zestaw narzędzi do testowania jest dostępny tylko dla szablonów usługi ARM. Aby zweryfikować pliki Bicep, użyj linteru Bicep.

Zasoby szkoleniowe

Aby dowiedzieć się więcej na temat zestawu narzędzi do testowania szablonu usługi ARM i uzyskać praktyczne wskazówki, zobacz Weryfikowanie zasobów platformy Azure przy użyciu zestawu narzędzi do testowania szablonu usługi ARM.

Instalowanie w systemie Windows

Jeśli nie masz jeszcze programu PowerShell, zainstaluj program PowerShell w systemie Windows.
Pobierz najnowszy plik .zip dla zestawu narzędzi do testowania i wyodrębnij go.
Uruchom program PowerShell.
Przejdź do folderu, w którym wyodrębniono zestaw narzędzi do testowania. W tym folderze przejdź do folderu arm-ttk .
Jeśli zasady wykonywania blokują skrypty z Internetu, należy odblokować pliki skryptów. Upewnij się, że jesteś w folderze arm-ttk .
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Zaimportuj moduł.
```
Import-Module .\arm-ttk.psd1
```
Aby uruchomić testy, użyj następującego polecenia:
```
Test-AzTemplate -TemplatePath \path\to\template
```

Instalowanie w systemie Linux

Jeśli nie masz jeszcze programu PowerShell, zainstaluj program PowerShell w systemie Linux.
Pobierz najnowszy plik .zip dla zestawu narzędzi do testowania i wyodrębnij go.
Uruchom program PowerShell.
```
pwsh
```
Przejdź do folderu, w którym wyodrębniono zestaw narzędzi do testowania. W tym folderze przejdź do folderu arm-ttk .
Jeśli zasady wykonywania blokują skrypty z Internetu, należy odblokować pliki skryptów. Upewnij się, że jesteś w folderze arm-ttk .
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Zaimportuj moduł.
```
Import-Module ./arm-ttk.psd1
```
Aby uruchomić testy, użyj następującego polecenia:
```
Test-AzTemplate -TemplatePath /path/to/template
```

Instalowanie w systemie macOS

Jeśli nie masz jeszcze programu PowerShell, zainstaluj program PowerShell w systemie macOS.
Zainstaluj program coreutils:
```
brew install coreutils
```
Pobierz najnowszy plik .zip dla zestawu narzędzi do testowania i wyodrębnij go.
Uruchom program PowerShell.
```
pwsh
```
Przejdź do folderu, w którym wyodrębniono zestaw narzędzi do testowania. W tym folderze przejdź do folderu arm-ttk .
Jeśli zasady wykonywania blokują skrypty z Internetu, należy odblokować pliki skryptów. Upewnij się, że jesteś w folderze arm-ttk .
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Zaimportuj moduł.
```
Import-Module ./arm-ttk.psd1
```
Aby uruchomić testy, użyj następującego polecenia:
```
Test-AzTemplate -TemplatePath /path/to/template
```

Format wyniku

Testy zakończone powodzeniem są wyświetlane w kolorze zielonym i poprzedzone ciągiem [+].

Testy zakończone niepowodzeniem są wyświetlane na czerwono i poprzedzone ciągiem [-].

Testy z ostrzeżeniem są wyświetlane w kolorze żółtym i poprzedzone ciągiem [?].

Zrzut ekranu przedstawiający wyniki testów w różnych kolorach dla powodzenia, niepowodzenia i ostrzeżenia.

Wyniki tekstowe to:

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.

Parametry testu

Po podaniu parametru -TemplatePath zestaw narzędzi szuka w tym folderze szablonu o nazwie azuredeploy.json lub maintemplate.json. Najpierw testuje ten szablon, a następnie testuje wszystkie inne szablony w folderze i jego podfolderach. Pozostałe szablony są testowane jako połączone szablony. Jeśli ścieżka zawiera plik o nazwie createUiDefinition.json, uruchamia testy istotne dla definicji interfejsu użytkownika. Testy są również uruchamiane dla plików parametrów i wszystkich plików JSON w folderze.

Test-AzTemplate -TemplatePath $TemplateFolder

Aby przetestować jeden plik w tym folderze, dodaj -File parametr . Jednak folder musi mieć szablon główny o nazwie azuredeploy.json lub maintemplate.json.

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

Domyślnie wszystkie testy są uruchamiane. Aby określić poszczególne testy do uruchomienia, użyj parametru -Test i podaj nazwę testu. Aby uzyskać nazwy testów, zobacz szablony usługi ARM, pliki parametrów, createUiDefinition.json i wszystkie pliki.

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

Dostosowywanie testów

Możesz dostosować domyślne testy lub utworzyć własne testy. Jeśli chcesz trwale usunąć test, usuń plik test.ps1 z folderu .

Zestaw narzędzi zawiera cztery foldery zawierające domyślne testy uruchamiane dla określonych typów plików:

Szablony usługi ARM: \arm-ttk\testcases\deploymentTemplate
Pliki parametrów: \arm-ttk\testcases\deploymentParameters
createUiDefinition.json: \arm-ttk\testcases\CreateUIDefinition
Wszystkie pliki: \arm-ttk\testcases\AllFiles

Dodawanie testu niestandardowego

Aby dodać własny test, utwórz plik z konwencją nazewnictwa: Your-Custom-Test-Name.test.ps1.

Test może pobrać szablon jako parametr obiektu lub parametr ciągu. Zazwyczaj należy użyć jednego lub drugiego, ale można użyć obu tych metod.

Użyj parametru obiektu, jeśli musisz pobrać sekcję szablonu i wykonać iterację po jego właściwościach. Test używający parametru obiektu ma następujący format:

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

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

Obiekt szablonu ma następujące właściwości:

$schema
contentVersion
parameters
variables
resources
outputs

Na przykład możesz pobrać kolekcję parametrów za pomocą polecenia $TemplateObject.parameters.

Użyj parametru string, jeśli musisz wykonać operację ciągu na całym szablonie. Test używający parametru ciągu ma następujący format:

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

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

Można na przykład uruchomić wyrażenie regularne parametru ciągu, aby sprawdzić, czy jest używana określona składnia.

Aby dowiedzieć się więcej na temat implementowania testu, zapoznaj się z innymi testami w tym folderze.

Weryfikowanie szablonów dla Azure Marketplace

Aby opublikować ofertę Azure Marketplace, użyj zestawu narzędzi do testowania, aby zweryfikować szablony. Gdy szablony przejdą testy weryfikacyjne, Azure Marketplace szybciej zatwierdź ofertę. Jeśli test zakończy się niepowodzeniem, oferta zakończy się niepowodzeniem.

Ważne

Testy witryny Marketplace zostały dodane w lipcu 2022 r. Zaktualizuj moduł, jeśli masz starszą wersję.

Uruchamianie testów w środowisku

Po zainstalowaniu zestawu narzędzi i zaimportowaniu modułu uruchom następujące polecenie cmdlet, aby przetestować pakiet:

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

Interpretacja wyników

Testy zwracają wyniki w dwóch sekcjach. Pierwsza sekcja zawiera testy, które są obowiązkowe. Wyniki tych testów są wyświetlane w sekcji podsumowania.

Ważne

Przed zaakceptowaniem oferty w witrynie Marketplace należy naprawić wszystkie wyniki na czerwono. Zalecamy naprawienie wszystkich wyników zwracanych w kolorze żółtym.

Wyniki tekstowe to:

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

Sekcja poniżej sekcji podsumowania zawiera błędy testów, które można interpretować jako ostrzeżenia. Naprawianie błędów jest opcjonalne, ale zdecydowanie zalecane. Błędy często wskazują na typowe problemy, które powodują błędy podczas instalowania oferty przez klienta.

Aby naprawić testy, postępuj zgodnie z przypadkiem testowym, który ma zastosowanie do Ciebie:

Prześlij ofertę

Po wprowadzeniu niezbędnych poprawek uruchom ponownie zestaw narzędzi do testowania. Przed przesłaniem oferty do Azure Marketplace upewnij się, że masz zerowe błędy.

Integracja z usługą Azure Pipelines

Możesz dodać zestaw narzędzi do testowania do usługi Azure Pipeline. Za pomocą potoku można uruchomić test za każdym razem, gdy szablon jest aktualizowany lub uruchamiać go w ramach procesu wdrażania.

Najprostszym sposobem dodania zestawu narzędzi do testowania do potoku jest użycie rozszerzeń innych firm. Dostępne są następujące dwa rozszerzenia:

Możesz też zaimplementować własne zadania. W poniższym przykładzie pokazano, jak pobrać zestaw narzędzi do testowania.

W przypadku potoku wydania:

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

W przypadku definicji YAML potoku:

- 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'

W następnym przykładzie pokazano, jak uruchomić testy.