Aracılığıyla paylaş


ARM şablonu test araç setini kullanma

Azure Resource Manager şablonu (ARM şablonu) test araç seti, şablonunuzun önerilen uygulamaları kullanıp kullanmadığını denetler. Şablonunuz önerilen uygulamalarla uyumlu olmadığında, önerilen değişikliklerin yer aldığı bir uyarı listesi döndürür. Test araç setini kullanarak şablon geliştirmede sık karşılaşılan sorunları önlemeyi öğrenebilirsiniz. Bu makalede test araç setinin nasıl çalıştırılacağı ve testlerin nasıl ekleneceği veya kaldırılacağı açıklanmaktadır. Testleri çalıştırma veya belirli bir testi çalıştırma hakkında daha fazla bilgi için bkz . Test parametreleri.

Araç seti, PowerShell veya CLI'daki bir komuttan çalıştırılabilen bir Dizi PowerShell betiğidir. Bu testler önerilerdir ancak gereksinimler değildir. Hedeflerinize uygun testlere karar verebilir ve çalıştırılacak testleri özelleştirebilirsiniz.

Araç seti dört test kümesi içerir:

Not

Test araç seti yalnızca ARM şablonları için kullanılabilir. Bicep dosyalarını doğrulamak için Bicep linterini kullanın.

Eğitim kaynakları

ARM şablonu test araç seti hakkında daha fazla bilgi edinmek ve uygulamalı yönergeler için bkz. ARM Şablonu Test Araç Seti'ni kullanarak Azure kaynaklarını doğrulama.

Windows’ta yükleme

  1. PowerShell'iniz yoksa Windows'a PowerShell'i yükleyin.

  2. Test araç seti için en son .zip dosyasını indirin ve ayıklayın.

  3. PowerShell'i başlatın.

  4. Test araç setini ayıkladığınız klasöre gidin. Bu klasörün içinde arm-ttk klasörüne gidin.

  5. Yürütme ilkeniz internetten betikleri engelliyorsa, betik dosyalarının engellemesini kaldırmanız gerekir. arm-ttk klasöründe olduğunuzdan emin olun.

    Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
    
  6. Modülü içeri aktarın.

    Import-Module .\arm-ttk.psd1
    
  7. Testleri çalıştırmak için aşağıdaki komutu kullanın:

    Test-AzTemplate -TemplatePath \path\to\template
    

Linux'ta yükleme

  1. PowerShell'iniz yoksa PowerShell'i Linux'a yükleyin.

  2. Test araç seti için en son .zip dosyasını indirin ve ayıklayın.

  3. PowerShell'i başlatın.

    pwsh
    
  4. Test araç setini ayıkladığınız klasöre gidin. Bu klasörün içinde arm-ttk klasörüne gidin.

  5. Yürütme ilkeniz internetten betikleri engelliyorsa, betik dosyalarının engellemesini kaldırmanız gerekir. arm-ttk klasöründe olduğunuzdan emin olun.

    Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
    
  6. Modülü içeri aktarın.

    Import-Module ./arm-ttk.psd1
    
  7. Testleri çalıştırmak için aşağıdaki komutu kullanın:

    Test-AzTemplate -TemplatePath /path/to/template
    

macOS’ta yükleme

  1. PowerShell'iniz yoksa macOS'a PowerShell'i yükleyin.

  2. coreutils yükleme:

    brew install coreutils
    
  3. Test araç seti için en son .zip dosyasını indirin ve ayıklayın.

  4. PowerShell'i başlatın.

    pwsh
    
  5. Test araç setini ayıkladığınız klasöre gidin. Bu klasörün içinde arm-ttk klasörüne gidin.

  6. Yürütme ilkeniz internetten betikleri engelliyorsa, betik dosyalarının engellemesini kaldırmanız gerekir. arm-ttk klasöründe olduğunuzdan emin olun.

    Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
    
  7. Modülü içeri aktarın.

    Import-Module ./arm-ttk.psd1
    
  8. Testleri çalıştırmak için aşağıdaki komutu kullanın:

    Test-AzTemplate -TemplatePath /path/to/template
    

Sonuç biçimi

Geçen testler yeşil renkte görüntülenir ve ile [+]önüne eklenir.

Başarısız olan testler kırmızıyla görüntülenir ve ile [-]başlanır.

Uyarı içeren testler sarı renkte görüntülenir ve ile [?]birlikte önüne eklenir.

Başarılı, başarısız ve uyarı için farklı renklerde test sonuçlarının ekran görüntüsü.

Metin sonuçları şunlardır:

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.

Test parametreleri

parametresini -TemplatePath sağladığınızda araç seti bu klasörde azuredeploy.json veya maintemplate.json adlı bir şablon arar. Önce bu şablonu test eder, ardından klasördeki ve alt klasörlerindeki diğer tüm şablonları test eder. Diğer şablonlar bağlantılı şablonlar olarak test edilir. Yolunuz createUiDefinition.json adlı bir dosya içeriyorsa, ui tanımıyla ilgili testler çalıştırır. Testler ayrıca parametre dosyaları ve klasördeki tüm JSON dosyaları için de çalıştırılır.

Test-AzTemplate -TemplatePath $TemplateFolder

Bu klasördeki bir dosyayı test etmek için parametresini -File ekleyin. Ancak klasörün yine de azuredeploy.json veya maintemplate.json adlı bir ana şablonu olmalıdır.

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

Varsayılan olarak, tüm testler çalıştırılır. Çalıştırılacak tek tek testleri belirtmek için parametresini -Test kullanın ve test adını belirtin. Test adları için bkz. ARM şablonları, parametre dosyaları, createUiDefinition.json ve tüm dosyalar.

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

Testleri özelleştirme

Varsayılan testleri özelleştirebilir veya kendi testlerinizi oluşturabilirsiniz. Testi kalıcı olarak kaldırmak istiyorsanız klasörden .test.ps1 dosyasını silin.

Araç setinde, belirli dosya türleri için çalıştırılacak varsayılan testleri içeren dört klasör vardır:

  • ARM şablonları: \arm-ttk\testcases\deploymentTemplate
  • Parametre dosyaları: \arm-ttk\testcases\deploymentParameters
  • createUiDefinition.json: \arm-ttk\testcases\CreateUIDefinition
  • Tüm dosyalar: \arm-ttk\testcases\AllFiles

Özel test ekleme

Kendi testinizi eklemek için adlandırma kuralına sahip bir dosya oluşturun: Your-Custom-Test-Name.test.ps1.

Test, şablonu nesne parametresi veya dize parametresi olarak alabilir. Genellikle birini veya diğerini kullanırsınız, ancak her ikisini de kullanabilirsiniz.

Şablonun bir bölümünü almanız ve özelliklerini yinelemeniz gerektiğinde object parametresini kullanın. nesne parametresini kullanan bir test aşağıdaki biçime sahiptir:

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

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

Şablon nesnesi aşağıdaki özelliklere sahiptir:

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

Örneğin, ile $TemplateObject.parametersparametre koleksiyonunu alabilirsiniz.

Şablonun tamamı üzerinde bir dize işlemi yapmanız gerektiğinde dize parametresini kullanın. Dize parametresini kullanan bir test aşağıdaki biçime sahiptir:

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

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

Örneğin, belirli bir söz diziminin kullanılıp kullanılmadiğini görmek için dize parametresinin normal bir ifadesini çalıştırabilirsiniz.

Testi uygulama hakkında daha fazla bilgi edinmek için bu klasördeki diğer testlere bakın.

Azure Market için şablonları doğrulama

Bir teklifi Azure Market yayımlamak için test araç setini kullanarak şablonları doğrulayın. Şablonlarınız doğrulama testlerini geçtiğinde Azure Market teklifinizi daha hızlı onaylar. Testlerde başarısız olursa teklif sertifikasyonu başarısız olur.

Önemli

Market testleri Temmuz 2022'de eklendi. Önceki bir sürüme sahipseniz modülünüzü güncelleştirin.

Testleri ortamınızda çalıştırma

Araç setini yükleyip modülü içeri aktardıktan sonra paketinizi test etmek için aşağıdaki cmdlet'i çalıştırın:

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

Sonuçları yorumlama

Testler sonuçları iki bölümde döndürür. İlk bölüm zorunlu olan testleri içerir. Bu testlerin sonuçları özet bölümünde görüntülenir.

Önemli

Market teklifi kabul etmeden önce kırmızıyla sonuçlanan sonuçları düzeltmeniz gerekir. Sarı renkle döndürülen tüm sonuçları düzeltmenizi öneririz.

Metin sonuçları şunlardır:

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

Özet bölümünün altındaki bölüm, uyarı olarak yorumlanabilir test hatalarını içerir. Hataları düzeltmek isteğe bağlıdır ancak kesinlikle önerilir. Hatalar genellikle müşteri teklifinizi yüklerken hatalara neden olan yaygın sorunlara işaret eder.

Testlerinizi düzeltmek için sizin için geçerli olan test çalışmalarını izleyin:

Teklifi gönderme

Gerekli düzeltmeleri yaptıktan sonra test araç setini yeniden çalıştırın. Teklifinizi Azure Market göndermeden önce sıfır hata olduğundan emin olun.

Azure Pipelines ile tümleştirme

Test araç setini Azure Pipeline'ınıza ekleyebilirsiniz. İşlem hattıyla, şablon her güncelleştirildiğinde testi çalıştırabilir veya dağıtım işleminizin bir parçası olarak çalıştırabilirsiniz.

Test araç setini işlem hattınıza eklemenin en kolay yolu üçüncü taraf uzantıları kullanmaktır. Aşağıdaki iki uzantı kullanılabilir:

İsterseniz kendi görevlerinizi de uygulayabilirsiniz. Aşağıdaki örnekte test araç setinin nasıl indirilmesi gösterilmektedir.

Yayın İşlem Hattı için:

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

İşlem Hattı YAML tanımı için:

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

Sonraki örnekte, testlerin nasıl çalıştırılacakları gösterilmektedir.

Yayın İşlem Hattı için:

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

İşlem Hattı YAML tanımı için:

- 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

Sonraki adımlar