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

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

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

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

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

Обучающие материалы

Дополнительные сведения о наборе средств тестирования шаблонов 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

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

Чтобы добавить собственный тест, создайте файл с соглашением об именовании: Your-Custom-Test-Name.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 Pipeline. С помощью конвейера можно запускать тест при каждом обновлении шаблона или запускать его в процессе развертывания.

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

• Запуск тестов шаблона ARM TTK
• Средство тестирования шаблонов 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.
• Дополнительные сведения о тестах для всех файлов см. в разделе "Тестовые случаи для всех файлов".
• Модуль Learn, охватывающий использование набора средств тестирования, см. в статье "Проверка ресурсов Azure" с помощью набора средств тестирования шаблонов ARM.