ARM テンプレートテストツールキットを使用する

2025-05-03

Azure Resource Manager テンプレート (ARM テンプレート) テストツールキットでは、テンプレートで推奨されるプラクティスが使用されているかどうかを確認します。テンプレートが推奨されるプラクティスに準拠していない場合は、推奨される変更を含む警告の一覧が返されます。テストツールキットを使用すると、テンプレート開発で一般的な問題を回避する方法を学習できます。この記事では、テストツールキットを実行する方法と、テストを追加または削除する方法について説明します。テストを実行する方法、または特定のテストを実行する方法の詳細については、「テストパラメーター」を参照してください。

ツールキットは、PowerShell または CLI のコマンドから実行できる一連の PowerShell スクリプトです。これらのテストは推奨事項ですが、要件ではありません。目標に関連するテストを決定し、実行するテストをカスタマイズできます。

ツールキットには、次の 4 つのテストセットが含まれています。

注

テストツールキットは ARM テンプレートでのみ使用できます。 Bicep ファイルを検証するには、 Bicep リンターを使用します。

トレーニングリソース

ARM テンプレートテストツールキットの詳細とハンズオンガイダンスについては、 ARM テンプレートテストツールキットを使用した Azure リソースの検証に関するページを参照してください。

Windows にインストールする

PowerShell をまだお持ちでない場合は、 Windows に PowerShell をインストールします。
テストツールキットの最新の .zip ファイルをダウンロードして展開します。
PowerShell を起動します。
テストツールキットを抽出したフォルダーに移動します。そのフォルダー内で、 arm-ttk フォルダーに移動します。
実行ポリシーでインターネットからのスクリプトがブロックされている場合は、スクリプトファイルのブロックを解除する必要があります。 arm-ttk フォルダーにいることを確認します。
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
モジュールをインポートします。
```
Import-Module .\arm-ttk.psd1
```
テストを実行するには、次のコマンドを使用します。
```
Test-AzTemplate -TemplatePath \path\to\template
```

Linux にインストールする

PowerShell をまだお持ちでない場合は、 Linux に PowerShell をインストールします。
テストツールキットの最新の .zip ファイルをダウンロードして展開します。
PowerShell を起動します。
```
pwsh
```
テストツールキットを抽出したフォルダーに移動します。そのフォルダー内で、 arm-ttk フォルダーに移動します。
実行ポリシーでインターネットからのスクリプトがブロックされている場合は、スクリプトファイルのブロックを解除する必要があります。 arm-ttk フォルダーにいることを確認します。
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
モジュールをインポートします。
```
Import-Module ./arm-ttk.psd1
```
テストを実行するには、次のコマンドを使用します。
```
Test-AzTemplate -TemplatePath /path/to/template
```

macOS へのインストール

PowerShell をまだお持ちでない場合は、 macOS に PowerShell をインストールします。
coreutils をインストールします。
```
brew install coreutils
```
テストツールキットの最新の .zip ファイルをダウンロードして展開します。
PowerShell を起動します。
```
pwsh
```
テストツールキットを抽出したフォルダーに移動します。そのフォルダー内で、 arm-ttk フォルダーに移動します。
実行ポリシーでインターネットからのスクリプトがブロックされている場合は、スクリプトファイルのブロックを解除する必要があります。 arm-ttk フォルダーにいることを確認します。
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
モジュールをインポートします。
```
Import-Module ./arm-ttk.psd1
```
テストを実行するには、次のコマンドを使用します。
```
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という名前のファイルが含まれている場合は、UI 定義に関連するテストを実行します。パラメーターファイルとフォルダー内のすべての JSON ファイルについてもテストが実行されます。

Test-AzTemplate -TemplatePath $TemplateFolder

そのフォルダー内の 1 つのファイルをテストするには、 -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 ファイルを削除します。

ツールキットには、特定のファイルの種類に対して実行される既定のテストを含む 4 つのフォルダーがあります。

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 はより迅速にオファリングを承認します。テストに合格しない場合、提供される製品の認定が取得できません。

重要

Marketplace テストは 2022 年 7 月に追加されました。以前のバージョンがある場合は、モジュールを更新します。

環境内でテストを実行する

ツールキットをインストールしてモジュールをインポートした後、次のコマンドレットを実行してパッケージをテストします。

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

結果を解釈する

テストは 2 つのセクションで結果を返します。最初のセクションには、必須のテストが含 まれています。これらのテストの結果が概要セクションに表示されます。

重要

Marketplace オファーが受け入れられる前に、赤で表示されている結果を修正する必要があります。黄色で返される結果を修正することをお勧めします。

テキストの結果は次のとおりです。

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

概要セクションの下のセクションには、警告として解釈できるテストエラーが含まれています。エラーの修正は省略可能ですが、強くお勧めします。多くの場合、エラーは、顧客がオファーをインストールするときにエラーを引き起こす一般的な問題を示しています。

テストを修正するには、該当するテストケースに従います。

オファーを送信する

必要な修正を行った後、テストツールキットを再実行します。 Azure Marketplace にオファーを送信する前に、エラーがないことを確認してください。

Azure Pipelines との統合

テストツールキットを Azure Pipeline に追加できます。パイプラインを使用すると、テンプレートが更新されるたびにテストを実行したり、デプロイプロセスの一部として実行したりできます。

テストツールキットをパイプラインに追加する最も簡単な方法は、サードパーティの拡張機能を使用する方法です。次の 2 つの拡張機能を使用できます。

または、独自のタスクを実装することもできます。次の例は、テストツールキットをダウンロードする方法を示しています。

リリースパイプラインの場合:

{
  "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 モジュールについては、 ARM テンプレートテストツールキットを使用した Azure リソースの検証に関するページを参照してください。

次の方法で共有

ARM テンプレート テスト ツールキットを使用する

トレーニング リソース