Použití testovací sady nástrojů pro šablony ARM

Článek
03/20/2024

Testovací sada nástrojů šablony Azure Resource Manager (šablona ARM) kontroluje, jestli vaše šablona používá doporučené postupy. Pokud šablona nevyhovuje doporučeným postupům, vrátí seznam upozornění s navrhovanými změnami. Pomocí testovací sady nástrojů se dozvíte, jak se vyhnout běžným problémům při vývoji šablon. Tento článek popisuje, jak spustit testovací sadu nástrojů a jak přidat nebo odebrat testy. Další informace o tom, jak spouštět testy nebo jak spustit konkrétní test, najdete v tématu Parametry testu.

Sada nástrojů je sada skriptů PowerShellu, které je možné spustit z příkazu v PowerShellu nebo rozhraní příkazového řádku. Tyto testy jsou doporučení, ale ne požadavky. Můžete se rozhodnout, které testy jsou relevantní pro vaše cíle, a přizpůsobit, které testy se budou spouštět.

Sada nástrojů obsahuje čtyři sady testů:

Poznámka

Testovací sada nástrojů je k dispozici pouze pro šablony ARM. K ověření souborů Bicep použijte linter Bicep.

Školicí materiály

Další informace o testovací sadě nástrojů šablon ARM a praktické pokyny najdete v tématu Ověření prostředků Azure pomocí testovací sady nástrojů šablon ARM.

Instalace v systému Windows

Pokud ještě nemáte PowerShell, nainstalujte si PowerShell ve Windows.
Stáhněte si nejnovější soubor .zip testovací sady nástrojů a extrahujte ho.
Spusťte PowerShell.
Přejděte do složky, do které jste extrahovali testovací sadu nástrojů. V této složce přejděte do složky arm-ttk .
Pokud vaše zásady spouštění blokují skripty z internetu, budete muset soubory skriptů odblokovat. Ujistěte se, že jste ve složce arm-ttk .
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importujte modul.
```
Import-Module .\arm-ttk.psd1
```
Ke spuštění testů použijte následující příkaz:
```
Test-AzTemplate -TemplatePath \path\to\template
```

Instalace v systému Linux

Pokud ještě nemáte PowerShell, nainstalujte si PowerShell v Linuxu.
Stáhněte si nejnovější soubor .zip testovací sady nástrojů a extrahujte ho.
Spusťte PowerShell.
```
pwsh
```
Přejděte do složky, do které jste extrahovali testovací sadu nástrojů. V této složce přejděte do složky arm-ttk .
Pokud vaše zásady spouštění blokují skripty z internetu, budete muset soubory skriptů odblokovat. Ujistěte se, že jste ve složce arm-ttk .
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importujte modul.
```
Import-Module ./arm-ttk.psd1
```
Ke spuštění testů použijte následující příkaz:
```
Test-AzTemplate -TemplatePath /path/to/template
```

Instalace v systému macOS

Pokud ještě nemáte PowerShell, nainstalujte si PowerShell na macOS.
Nainstalujte coreutils:
```
brew install coreutils
```
Stáhněte si nejnovější soubor .zip testovací sady nástrojů a extrahujte ho.
Spusťte PowerShell.
```
pwsh
```
Přejděte do složky, do které jste extrahovali testovací sadu nástrojů. V této složce přejděte do složky arm-ttk .
Pokud vaše zásady spouštění blokují skripty z internetu, budete muset soubory skriptů odblokovat. Ujistěte se, že jste ve složce arm-ttk .
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importujte modul.
```
Import-Module ./arm-ttk.psd1
```
Ke spuštění testů použijte následující příkaz:
```
Test-AzTemplate -TemplatePath /path/to/template
```

Formát výsledku

Testy, které projdou, se zobrazí zeleně a mají před sebou [+].

Testy, které selžou, se zobrazí červeně a mají před sebou [-].

Testy s upozorněním se zobrazují žlutě a mají před sebou [?].

Snímek obrazovky s výsledky testů v různých barvách pro úspěšné, neúspěšné a upozornění

Textové výsledky jsou:

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

Když zadáte -TemplatePath parametr, sada nástrojů vyhledá v této složce šablonu s názvem azuredeploy.json nebo maintemplate.json. Nejprve otestuje tuto šablonu a pak otestuje všechny ostatní šablony ve složce a jejích podsložkách. Ostatní šablony se testují jako propojené šablony. Pokud vaše cesta obsahuje soubor s názvem createUiDefinition.json, spustí testy, které jsou relevantní pro definici uživatelského rozhraní. Testy se také spouští pro soubory parametrů a všechny soubory JSON ve složce.

Test-AzTemplate -TemplatePath $TemplateFolder

Pokud chcete otestovat jeden soubor v této složce, přidejte -File parametr . Složka ale stále musí obsahovat hlavní šablonu s názvem azuredeploy.json nebo maintemplate.json.

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

Ve výchozím nastavení se spustí všechny testy. Pokud chcete určit jednotlivé testy, které se mají spustit, použijte -Test parametr a zadejte název testu. Názvy testů najdete v tématu Šablony ARM, soubory parametrů, createUiDefinition.json a všechny soubory.

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

Přizpůsobení testů

Výchozí testy si můžete přizpůsobit nebo můžete vytvořit vlastní testy. Pokud chcete trvale odebrat test, odstraňte ze složky soubor .test.ps1 .

Sada nástrojů obsahuje čtyři složky, které obsahují výchozí testy, které se spouští pro konkrétní typy souborů:

Šablony ARM: \arm-ttk\testcases\deploymentTemplate
Soubory parametrů: \arm-ttk\testcases\deploymentParameters
createUiDefinition.json: \arm-ttk\testcases\CreateUIDefinition
Všechny soubory: \arm-ttk\testcases\AllFiles

Přidání vlastního testu

Pokud chcete přidat vlastní test, vytvořte soubor s konvencí vytváření názvů: Your-Custom-Test-Name.test.ps1.

Test může šablonu získat jako parametr objektu nebo řetězcový parametr. Obvykle se používá jeden nebo druhý, ale můžete použít obojí.

Parametr object použijte, když potřebujete získat oddíl šablony a iterovat její vlastnosti. Test, který používá parametr object, má následující formát:

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

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

Objekt šablony má následující vlastnosti:

$schema
contentVersion
parameters
variables
resources
outputs

Kolekci parametrů můžete získat například pomocí $TemplateObject.parameterspříkazu .

Parametr string použijte, když potřebujete provést řetězcovou operaci s celou šablonou. Test, který používá parametr řetězce, má následující formát:

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

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

Můžete například spustit regulární výraz parametru řetězce a zjistit, jestli se používá konkrétní syntaxe.

Další informace o implementaci testu najdete v dalších testech v této složce.

Ověření šablon pro Azure Marketplace

Pokud chcete publikovat nabídku do Azure Marketplace, ověřte šablony pomocí testovací sady nástrojů. Když vaše šablony projdou ověřovacími testy, Azure Marketplace vaši nabídku schválí rychleji. Pokud testy selžou, nabídka se nezdaří s certifikací.

Důležité

Testy z Marketplace byly přidány v červenci 2022. Pokud máte starší verzi, aktualizujte modul.

Spuštění testů ve vašem prostředí

Po instalaci sady nástrojů a importu modulu spusťte následující rutinu k otestování balíčku:

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

Interpretace výsledků

Testy vrátí výsledky ve dvou částech. První část obsahuje povinné testy. Výsledky těchto testů se zobrazí v souhrnné části.

Důležité

Před přijetím nabídky Marketplace musíte opravit všechny výsledky červeně. Doporučujeme opravit všechny výsledky, které se vrátí žlutě.

Textové výsledky jsou:

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

Část pod souhrnným oddílem obsahuje chyby testů, které lze interpretovat jako upozornění. Oprava chyb je volitelná, ale důrazně se doporučuje. Selhání často odkazují na běžné problémy, které způsobují selhání, když zákazník nainstaluje vaši nabídku.

Pokud chcete testy opravit, postupujte podle testovacího případu, který se na vás vztahuje:

Odeslání nabídky

Po provedení všech potřebných oprav znovu spusťte testovací sadu nástrojů. Před odesláním nabídky do Azure Marketplace se ujistěte, že nemáte žádné chyby.

Integrace se službou Azure Pipelines

Testovací sadu nástrojů můžete přidat do kanálu Azure. S kanálem můžete test spustit při každé aktualizaci šablony nebo spustit jako součást procesu nasazení.

Nejjednodušší způsob, jak přidat testovací sadu nástrojů do kanálu, je použít rozšíření třetích stran. K dispozici jsou následující dvě rozšíření:

Nebo můžete implementovat vlastní úlohy. Následující příklad ukazuje, jak stáhnout testovací sadu nástrojů.

Kanál verze:

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

Definice YAML kanálu:

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

Další příklad ukazuje, jak spustit testy.