Использование набора средств для тестирования шаблонов ARM

Набор средств для тестирования шаблонов Azure Resource Manager (шаблонов ARM) проверяет, применяются ли в шаблоне правила и рекомендации. Если шаблон не соответствует рекомендациям, инструмент возвращает список предупреждений с предлагаемыми изменениями. С помощью набора средств для тестирования можно избежать распространенных проблем при разработке шаблонов. В этой статье объясняется, как запустить набор средств для тестирования и как добавлять и удалять тесты. Дополнительные сведения о выполнении тестов или какого-то определенного теста см. в разделе Параметры тестирования.

Этот набор средств представляет собой набор скриптов PowerShell, которые можно запускать из командной строки в PowerShell или CLI. Эти тесты являются рекомендуемыми, а не обязательными. Вы можете выбрать, какие из них отвечают вашим целям, и настроить их выполнение.

Набор средств содержит четыре набора тестов:

• Тестовые случаи для шаблонов ARM
• Тестовые случаи для файлов параметров
• Тестовые случаи для createUiDefinition.js
• Тестовые случаи для всех файлов

Учебные ресурсы

Дополнительные сведения о наборе средств для тестирования шаблонов ARM и пошаговые инструкции см. в статье Проверка ресурсов Azure с помощью набора средств для тестирования шаблонов ARM.

Установка в Windows

1. Если у вас еще нет PowerShell, установите PowerShell для Windows.

2. Скачайте последнюю версию ZIP-файла с набором средств для тестирования и извлеките его.

3. Запустите PowerShell.

4. Перейдите в папку, куда извлекли набор средств для тестирования. В этой папке перейдите в подпапку arm-ttk.

5. Если ваша политика выполнения блокирует скрипты из Интернета, вам потребуется их разблокировать. Убедитесь, что находитесь в папке arm-ttk.

   Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
   

6. Импортируйте модуль.

   Import-Module .\arm-ttk.psd1
   

7. Для выполнения тестов используйте следующую команду:

   Test-AzTemplate -TemplatePath \path\to\template
   

Установка в Linux

1. Если у вас еще нет PowerShell, установите PowerShell для Linux.

2. Скачайте последнюю версию ZIP-файла с набором средств для тестирования и извлеките его.

3. Запустите PowerShell.

   pwsh
   

4. Перейдите в папку, куда извлекли набор средств для тестирования. В этой папке перейдите в подпапку arm-ttk.

5. Если ваша политика выполнения блокирует скрипты из Интернета, вам потребуется их разблокировать. Убедитесь, что находитесь в папке arm-ttk.

   Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
   

6. Импортируйте модуль.

   Import-Module ./arm-ttk.psd1
   

7. Для выполнения тестов используйте следующую команду:

   Test-AzTemplate -TemplatePath /path/to/template
   

Установка в macOS

1. Если у вас еще нет PowerShell, установите PowerShell для macOS.

2. Установите coreutils:

   brew install coreutils
   

3. Скачайте последнюю версию ZIP-файла с набором средств для тестирования и извлеките его.

4. Запустите PowerShell.

   pwsh
   

5. Перейдите в папку, куда извлекли набор средств для тестирования. В этой папке перейдите в подпапку arm-ttk.

6. Если ваша политика выполнения блокирует скрипты из Интернета, вам потребуется их разблокировать. Убедитесь, что находитесь в папке arm-ttk.

   Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
   

7. Импортируйте модуль.

   Import-Module ./arm-ttk.psd1
   

8. Для выполнения тестов используйте следующую команду:

   Test-AzTemplate -TemplatePath /path/to/template
   

Формат результата

Пройденные тесты отображаются зеленым цветом и сопровождаются символом [+] .

Непройденные тесты отображаются красным цветом и сопровождаются символом [-] .

Тесты с предупреждением отображаются желтым цветом и имеют приставку [?].

Результаты тестирования:

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.

Параметры тестирования

Если указан параметр -TemplatePath, набор средств ищет в этой папке шаблон под названием azuredeploy.json или maintemplate.json. Сначала он проверяет этот шаблон, а затем — все остальные шаблоны в папке и ее вложенных папках. Все остальные файлы тестируются как связанные шаблоны. Если путь содержит файл под названием createUiDefinition.json, выполняются тесты, относящиеся к определению пользовательского интерфейса. Тесты также выполняются для файлов параметров и всех файлов JSON в папке.

Test-AzTemplate -TemplatePath $TemplateFolder

Чтобы протестировать один файл в этой папке, добавьте параметр -File. При этом папка все равно должна содержать основной шаблон с названием azuredeploy.json или maintemplate.json.

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

По умолчанию выполняются все тесты. Чтобы указать для выполнения определенные тесты, используйте параметр -Test. Сведения о названиях тестов см. в разделах, посвященных шаблонам ARM, файлам параметров, файлу createUiDefinition.json и всем файлам.

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

Настройка тестов

Можно настроить тесты по умолчанию или создать собственные тесты. Если вы хотите полностью удалить тест, удалите из папки файл .test.ps1.

В наборе имеется четыре папки, которые содержат тесты по умолчанию, выполняемые для конкретных типов файлов:

• Шаблоны ARM: \arm-ttk\testcases\deploymentTemplate
• Файлы параметров: \arm-ttk\testcases\deploymentParameters
• Файл createUiDefinition.json: \arm-ttk\testcases\CreateUIDefinition
• Все файлы: \arm-ttk\testcases\AllFiles

Добавление собственного теста

Чтобы добавить собственный тест, создайте файл с именем, задаваемым по следующей схеме: ваш-собственный-тест.test.ps1.

Тест может принимать шаблон в виде параметра-объекта или строкового параметра. Как правило, используется или тот, или другой вариант (но можно использовать оба).

Параметр-объект используется, если необходимо выполнить итерацию по свойствам определенного раздела шаблона. Тест с параметром-объектом имеет следующий формат:

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

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

Объект шаблона имеет следующие свойства:

• $schema
• contentVersion
• parameters
• variables
• resources
• outputs

Например, получить коллекцию параметров можно с помощью объекта $TemplateObject.parameters.

Строковый параметр используется, если необходимо выполнить операцию со строкой для всего шаблона. Тест со строковым параметром имеет следующий формат:

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

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

Например, для строкового параметра можно выполнить регулярное выражение, чтобы узнать, используется ли в нем определенный синтаксис.

Чтобы узнать больше о том, как составить тест, ознакомьтесь с другими тестами в этой папке.

Проверка шаблонов для Azure Marketplace

Чтобы опубликовать предложение в Azure Marketplace, используйте набор средств тестирования для проверки шаблонов. Если шаблоны успешно пройдут необходимые тесты, Azure Marketplace быстрее утвердит ваше предложение. Если шаблоны не пройдут тесты, предложение не сможет получить сертификацию.

Выполнение тестов в локальной среде

Завершив установку набора средств и импорт модуля, выполните следующий командлет для тестирования пакета предложения:

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

Интерпретация результатов

Тесты возвращают результаты, разделенные на два раздела. Первый раздел содержит тесты, которые являются обязательными. Результаты этих тестов отображаются в разделе сводных данных.

Результаты тестирования:

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

Ниже приводится раздел сводных данных со списком непройденных тестов, которые можно считать предупреждениями. Исправление таких ошибок не является обязательным, но настоятельно рекомендуется. Эти ошибки часто указывают на распространенные проблемы, которые могут приводить к сбоям при установке предложения клиентом.

Чтобы исправить результаты, выполните процедуру для подходящего тестового случая:

• Тестовый случай для шаблонов ARM
• Тестовый случай для всех файлов
• Тестовый случай CreateUiDefinition

Отправка предложения

Завершив внесение необходимых исправлений, повторно запустите набор средств для тестирования. Перед отправкой предложения в Azure Marketplace убедитесь, что тесты не возвращают ни одной ошибки.

Интеграция с Azure Pipelines

Вы можете добавить набор средств тестирования в конвейер Azure. С помощью конвейера тест можно выполнять каждый раз при обновлении шаблона или запускать его в рамках процесса развертывания.

Проще всего добавить в конвейер набор средств тестирования с помощью расширений сторонних разработчиков. Доступны два следующих расширения:

• Тесты TTK для шаблона ARM
• Тестировщик шаблонов ARM

Вы также можете реализовать собственные задачи. В примере ниже показано, как скачать набор средств тестирования.

Для конвейера выпуска:

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

Для определения 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'

В следующем примере показано, как запускать тесты.

Для конвейера выпуска:

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

Для определения 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

Дальнейшие действия

• Подробнее о тестах шаблонов см. в разделе Тестовые случаи для шаблонов ARM.
• Чтобы протестировать файлы параметров, см. статью Тестовые случаи для файлов параметров.
• Дополнительные сведения о тестах createUiDefinition см. в статье Тестовые случаи для createUiDefinition.json.
• См. дополнительные сведения о тестах для всех файлов.
• Сведения о модуле Microsoft Learn, посвященном использованию набора средств для тестирования, см. в статье Проверка ресурсов Azure с помощью набора средств для тестирования шаблонов ARM.