Menggunakan toolkit uji templat ARM

Artikel
03/20/2024

Toolkit pengujian templat Azure Resource Manager (templat ARM) memeriksa apakah templat Anda menggunakan praktik yang direkomendasikan. Saat templat Anda tidak sesuai dengan praktik yang direkomendasikan, templat akan menampilkan daftar peringatan dengan perubahan yang disarankan. Dengan menggunakan toolkit pengujian, Anda dapat mempelajari cara menghindari masalah umum dalam pengembangan templat. Artikel ini menjelaskan cara menjalankan toolkit pengujian dan cara menambahkan atau menghapus tes. Selengkapnya tentang cara menjalankan pengujian atau cara menjalankan pengujian tertentu, lihat Parameter pengujian.

Toolkit adalah sekumpulan skrip PowerShell yang dapat dijalankan dari perintah di PowerShell atau CLI. Tes ini adalah rekomendasi tetapi bukan persyaratan. Anda dapat memutuskan tes mana yang relevan dengan tujuan Anda dan menyesuaikan tes mana yang akan dijalankan.

Toolkit ini berisi empat set tes:

Catatan

Toolkit uji hanya tersedia untuk templat ARM. Untuk memvalidasi file Bicep, gunakan linter Bicep.

Sumber daya pelatihan

Untuk mempelajari toolkit pengujian template ARM selengkapnya dan untuk panduan praktik langsung, lihat Memvalidasi sumber daya Azure dengan menggunakan Toolkit Pengujian Template ARM.

Penginstalan pada Windows

Jika Anda belum memiliki PowerShell, instal PowerShell di Windows.
Unduh file .zip terbaru untuk toolkit pengujian dan ekstrak.
Mulai PowerShell.
Navigasi ke folder tempat Anda mengekstrak toolkit pengujian. Dalam folder tersebut, navigasi ke folder arm-ttk.
Jika kebijakan eksekusi Anda memblokir skrip dari Internet, Anda perlu membuka blokir file skrip. Pastikan Anda berada di folder arm-ttk.
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Impor modul.
```
Import-Module .\arm-ttk.psd1
```
Untuk menjalankan pengujian, gunakan perintah berikut:
```
Test-AzTemplate -TemplatePath \path\to\template
```

Penginstalan pada Linux

Jika Anda belum memiliki PowerShell, instal PowerShell di Linux.
Unduh file .zip terbaru untuk toolkit pengujian dan ekstrak.
Mulai PowerShell.
```
pwsh
```
Navigasi ke folder tempat Anda mengekstrak toolkit pengujian. Dalam folder tersebut, navigasi ke folder arm-ttk.
Jika kebijakan eksekusi Anda memblokir skrip dari Internet, Anda perlu membuka blokir file skrip. Pastikan Anda berada di folder arm-ttk.
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Impor modul.
```
Import-Module ./arm-ttk.psd1
```
Untuk menjalankan pengujian, gunakan perintah berikut:
```
Test-AzTemplate -TemplatePath /path/to/template
```

Penginstalan pada macOS

Jika anda belum memiliki PowerShell, instal PowerShell on macOS.
Instal coreutils:
```
brew install coreutils
```
Unduh file .zip terbaru untuk toolkit pengujian dan ekstrak.
Mulai PowerShell.
```
pwsh
```
Navigasi ke folder tempat Anda mengekstrak toolkit pengujian. Dalam folder tersebut, navigasi ke folder arm-ttk.
Jika kebijakan eksekusi Anda memblokir skrip dari Internet, Anda perlu membuka blokir file skrip. Pastikan Anda berada di folder arm-ttk.
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Impor modul.
```
Import-Module ./arm-ttk.psd1
```
Untuk menjalankan pengujian, gunakan perintah berikut:
```
Test-AzTemplate -TemplatePath /path/to/template
```

Format Hasil

Tes yang lulus ditampilkan dalam warna hijau dan diawali dengan [+] .

Tes yang gagal ditampilkan dalam warna merah dan diawali dengan [-] .

Pengujian dengan peringatan ditampilkan dengan warna kuning dan diawali dengan [?].

Cuplikan layar hasil pengujian dalam warna yang berbeda untuk lulus, gagal, dan peringatan.

Hasil teksnya adalah:

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.

Parameter pengujian

Saat Anda memberikan parameter -TemplatePath, toolkit akan mencari templat bernama azuredeploy.json atau maintemplate.json di folder tersebut. Toolkit menguji templat ini terlebih dahulu dan kemudian menguji semua templat lain di folder dan subfoldernya. Templat lainnya diuji sebagai templat yang ditautkan. Jika jalur Anda menyertakan file bernama createUiDefinition.json, jalur tersebut menjalankan pengujian yang relevan dengan definisi antarmuka pengguna. Pengujian juga dijalankan untuk file parameter dan semua file JSON (JavaScript Object Notation) dalam folder.

Test-AzTemplate -TemplatePath $TemplateFolder

Untuk menguji satu file di folder itu, tambahkan parameter -File. Namun, folder tersebut harus tetap memiliki templat utama bernama azuredeploy.json atau maintemplate.json.

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

Secara default, semua pengujian dijalankan. Untuk menentukan pengujian individual yang akan dijalankan, gunakan parameter -Test dan berikan nama pengujian. Untuk nama pengujian, lihat templat ARM, file parameter, createUiDefinition.json, dan semua file.

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

Melakukan kustomisasi pengujian

Anda dapat menyesuaikan tes default atau membuat tes Anda sendiri. Jika Anda ingin menghapus pengujian secara permanen, hapus file .test.ps1 dari folder.

Toolkit ini memiliki empat folder berisi tes default yang dijalankan untuk jenis file tertentu:

Templat ARM: \arm-ttk\testcases\deploymentTemplate
File parameter: \arm-ttk\testcases\deploymentParameters
createUiDefinition.json: \arm-ttk\testcases\CreateUIDefinition
Semua file: \arm-ttk\testcases\AllFiles

Tambahkan pengujian kustom

Untuk menambahkan pengujian Anda sendiri, buat file dengan konvensi penamaan: Your-Custom-Test-Name.test.ps1.

Pengujian bisa mendapatkan templat sebagai parameter objek atau parameter string. Biasanya, Anda menggunakan satu atau yang lain, tetapi Anda dapat menggunakan keduanya.

Gunakan parameter objek saat Anda perlu mendapatkan bagian templat dan beriterasi melalui propertinya. Pengujian yang menggunakan parameter objek memiliki format berikut:

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

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

Objek templat memiliki properti berikut ini:

$schema
contentVersion
parameters
variables
resources
outputs

Misalnya, Anda bisa mendapatkan kumpulan parameter dengan $TemplateObject.parameters.

Gunakan parameter string saat Anda perlu melakukan operasi string pada seluruh templat. Pengujian yang menggunakan parameter string memiliki format berikut:

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

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

Misalnya, Anda dapat menjalankan ekspresi reguler parameter string untuk melihat apakah sintaks tertentu digunakan.

Untuk mempelajari lebih lanjut penerapan pengujian, lihat pengujian lain di folder tersebut.

Memvalidasi templat untuk Marketplace Azure

Untuk menerbitkan penawaran ke Marketplace Azure, gunakan toolkit pengujian untuk memvalidasi templat. Saat templat Anda lulus pengujian validasi, Marketplace Azure akan menyetujui penawaran Anda dengan lebih cepat. Jika mereka gagal dalam pengujian, penawaran akan gagal sertifikasi.

Penting

Uji Marketplace ditambahkan pada Juli 2022. Perbarui modul jika Anda memiliki versi yang lebih lama.

Menjalankan pengujian di lingkungan Anda

Setelah menginstal toolkit dan mengimpor modul, jalankan cmdlet berikut untuk menguji paket Anda:

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

Menafsirkan hasilnya

Pengujian mengembalikan hasil dalam dua bagian. Bagian pertama mencakup pengujian yang wajib. Hasil pengujian ini ditampilkan di bagian ringkasan.

Penting

Anda harus memperbaiki hasil apa pun dengan warna merah sebelum penawaran Marketplace diterima. Sebaiknya perbaiki hasil apa pun yang kembali berwarna kuning.

Hasil teksnya adalah:

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

Bagian di bawah bagian ringkasan mencakup kegagalan pengujian yang dapat ditafsirkan sebagai peringatan. Memperbaiki kegagalan bersifat opsional tetapi sangat disarankan. Kegagalan sering menunjuk ke masalah umum yang menyebabkan kegagalan ketika pelanggan menginstal penawaran Anda.

Untuk memperbaiki pengujian Anda, ikuti kasus pengujian yang berlaku untuk Anda:

Kirim penawaran

Setelah melakukan perbaikan yang diperlukan, jalankan kembali toolkit pengujian. Sebelum mengirimkan penawaran Anda ke Marketplace Azure, pastikan Anda tidak mengalami nol kegagalan.

Berintegrasi dengan Azure Pipeline

Anda dapat menambahkan toolkit pengujian ke Azure Pipeline Anda. Dengan sebuah alur, Anda dapat menjalankan pengujian setiap kali templat diperbarui, atau menjalankannya sebagai bagian dari proses penyebaran Anda.

Cara termudah untuk menambahkan toolkit pengujian ke alur Anda adalah dengan ekstensi pihak ketiga. Dua ekstensi berikut tersedia:

Atau, Anda dapat menerapkan tugas Anda sendiri. Contoh berikut menunjukkan cara mengunduh toolkit pengujian.

Untuk Alur Rilis:

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

Untuk definisi YAML Alur:

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

Contoh berikutnya memperlihatkan cara menjalankan pengujian.