Use o do Kit de ferramenta de teste do modelo do ARM

Artigo
03/20/2024

OKit de ferramentas de teste do modelo do Azure Resource Manager (modelo ARM) verifica se o modelo usa práticas recomendadas. Quando o modelo não estiver em conformidade com as práticas recomendadas, ele retorna uma lista de avisos com as alterações sugeridas. Usando o kit de ferramentas de teste, você pode aprender a problemas comuns no desenvolvimento de modelos. Este artigo descreve como executar o kit de ferramentas de teste e adicionar ou remover testes. Para obter mais informações sobre como executar testes ou como executar um teste específico, confira Parâmetros de teste.

O kit de ferramentas de teste é um conjunto de scripts do PowerShell que pode ser executado a partir de um comando no PowerShell ou na CLI. Estes testes são recomendações, mas não requisitos. Você pode decidir quais testes são relevantes para suas metas e personalizar quais testes serão executados.

O kit de ferramentas contém quatro conjuntos de testes:

Observação

O kit de ferramentas de teste só está disponível para os modelos do ARM. Para validar arquivos Bicep, use o linter Bicep.

Recursos de treinamento

Para saber mais sobre o kit de ferramentas de teste de modelo do ARM e para obter diretrizes práticas, confira Validar recursos do Azure usando o kit de ferramentas de teste do modelo do ARM.

Instalar no Windows

Se você não tiver o PowerShell, Instale o PowerShell no Windows.
Baixe o arquivo. zip mais recente do kit de ferramentas de teste e extraia-o.
Inicie o PowerShell.
Navegue até a pasta onde você extraiu o kit de ferramentas de teste. Dentro dessa pasta, navegue até a pasta arm-ttk.
Se a política de execução bloquear os scripts da Internet, você precisará desbloquear os arquivos de script. Certifica-se de que você está na pasta arm-ttk.
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importe o módulo.
```
Import-Module .\arm-ttk.psd1
```

Para executar os testes, use comando a seguir:

Test-AzTemplate -TemplatePath \path\to\template

Instalar no Linux

Se você não tiver o PowerShell, Instale o PowerShell no Linux.
Baixe o arquivo. zip mais recente do kit de ferramentas de teste e extraia-o.
Inicie o PowerShell.
```
pwsh
```
Navegue até a pasta onde você extraiu o kit de ferramentas de teste. Dentro dessa pasta, navegue até a pasta arm-ttk.
Se a política de execução bloquear os scripts da Internet, você precisará desbloquear os arquivos de script. Certifica-se de que você está na pasta arm-ttk.
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importe o módulo.
```
Import-Module ./arm-ttk.psd1
```

Para executar os testes, use comando a seguir:

Test-AzTemplate -TemplatePath /path/to/template

Instalar no macOS

Se você não tiver o PowerShell, Instale o PowerShell no macOS.
Instale coreutils:
```
brew install coreutils
```
Baixe o arquivo. zip mais recente do kit de ferramentas de teste e extraia-o.
Inicie o PowerShell.
```
pwsh
```
Navegue até a pasta onde você extraiu o kit de ferramentas de teste. Dentro dessa pasta, navegue até a pasta arm-ttk.
Se a política de execução bloquear os scripts da Internet, você precisará desbloquear os arquivos de script. Certifica-se de que você está na pasta arm-ttk.
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importe o módulo.
```
Import-Module ./arm-ttk.psd1
```

Para executar os testes, use comando a seguir:

Test-AzTemplate -TemplatePath /path/to/template

Formato de resultado

Os testes aprovados são exibidos em verde e precedido com [+] .

Os testes que falham são exibidos em vermelho e precedido de [-] .

Os testes com um aviso são exibidos em amarelo e precedidos por [?].

Captura de tela dos resultados do teste em cores diferentes para aprovação, reprovação e aviso.

Os resultados do texto serão:

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.

Parâmetros de teste

Quando você fornece o parâmetro -TemplatePath, o kit de ferramentas examina esta pasta em busca de um modelo chamado azuredeploy.json ou maintemplate.json. Ele testa primeiro este modelo e, em seguida, testa todos os outros modelos na pasta e suas subpastas. Os outros modelos serão testados como modelos vinculados. Se o caminho incluir um arquivo chamado createUiDefinition.json, ele executará os testes que são relevantes para a definição da interface do usuário. Os testes também são executados em arquivos de parâmetro e todos os arquivos JSON na pasta.

Test-AzTemplate -TemplatePath $TemplateFolder

Para testar um arquivo nessa pasta, adicione o parâmetro -File. No entanto, a pasta deve ter um modelo principal chamado azuredeploy.json ou maintemplate.json.

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

Por padrão, todos os testes serão executados. Para especificar os testes individuais a serem executados, use o parâmetro -Test e forneça o nome do teste. Para os nomes de teste, consulte Modelos do ARM, arquivos de parâmetros, createUiDefinition.json e todos os arquivos.

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

Personalizar testes

Você pode personalizar os testes padrão ou criar seus próprios testes. Se você quiser remover um teste permanentemente, exclua o arquivo .test.ps1 da pasta.

O kit de ferramentas tem quatro pastas que contêm os testes padrão que são executados para tipos de arquivo específicos:

Modelos do ARM: \arm-ttk\testcases\deploymentTemplate
Arquivos de parâmetros: \arm-ttk\testcases\deploymentParameters
createUiDefinition.json: \arm-ttk\testcases\CreateUIDefinition
Todos os arquivos: \arm-ttk\testcases\AllFiles

Adicionar um teste personalizado

Para adicionar seu próprio teste, crie um arquivo com a Convenção de nomeação: Your-Custom-Test-Name.test.ps1.

O teste poderá obter o modelo como um parâmetro de objeto ou um parâmetro de cadeia de caracteres. Normalmente, você usa um ou outro, mas poderá usar ambos.

Use o parâmetro de objeto quando precisar obter uma seção do modelo e iterar por meio de suas propriedades. Um teste que usa o parâmetro de objeto tem o seguinte formato:

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

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

O modelo do objeto tem as seguintes propriedades:

$schema
contentVersion
parameters
variables
resources
outputs

Por exemplo, você poderá obter a coleção de parâmetros$TemplateObject.parameters.

Use o parâmetro de cadeia de caracteres quando precisar fazer uma operação de cadeia de caracteres em todo o modelo. Um teste que usa o parâmetro de cadeia de caracteres tem o formato seguinte:

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

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

Por exemplo, você pode executar uma expressão regular do parâmetro de cadeia de caracteres para verificar se uma sintaxe específica é usada.

Para saber mais sobre como implementar o teste, considere os outros testes nessa pasta.

Validar modelos para Azure Marketplace

Para publicar uma oferta no Azure Marketplace, use o kit de ferramentas de teste para validar os modelos. Quando seus modelos passarem nos testes de validação,o Azure Marketplace aprovará sua oferta mais rapidamente. Se eles falharem nos testes, a oferta falhará na certificação.

Importante

Os testes do Marketplace foram adicionados em julho de 2022. Atualize seu módulo se você tiver uma versão anterior.

Executar os testes em seu ambiente

Depois de instalar o kit de ferramentas e importar o módulo, execute o seguinte cmdlet para testar seu pacote:

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

Interpretar os resultados

Os testes retornam resultados em duas seções. A primeira seção inclui os testes obrigatórios. Os resultados desses testes são exibidos na seção resumo.

Importante

Você deve corrigir os resultados em vermelho antes que a oferta do Marketplace seja aceita. Recomendamos corrigir os resultados que retornem em amarelo.

Os resultados do texto serão:

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

A seção abaixo da seção resumo inclui falhas de teste que podem ser interpretadas como avisos. Corrigir as falhas é opcional, mas altamente recomendado. As falhas geralmente apontam para problemas comuns que causam falhas quando um cliente instala sua oferta.

Para corrigir seus testes, siga o caso de teste aplicável a você:

Enviar a oferta

Depois de fazer as correções necessárias, execute novamente o kit de ferramentas de teste. Antes de enviar sua oferta para o Azure Marketplace, certifique-se de não ter nenhuma falha.

Incorporar o Azure Pipelines

Você pode adicionar o kit de ferramentas de teste ao seu Azure Pipeline. Com um pipeline, você pode executar o teste cada vez que o modelo for atualizado ou executá-lo como parte do processo de implantação.

A forma mais fácil de adicionar o kit de ferramentas de teste ao seu pipeline é com extensões de terceiros. As duas extensões a seguir estão disponíveis:

Ou, você pode implementar suas próprias tarefas. O seguinte exemplo mostra como baixar o kit de ferramentas de teste.

Para adicionar o pipeline de lançamento:

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

Para a definição de YAML do pipeline:

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

O próximo exemplo mostra como executar os testes.

Para adicionar o pipeline de lançamento:

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

Para a definição de YAML do pipeline:

- 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

Próximas etapas

Para saber mais sobre os testes de modelo, consulte Casos de teste para modelos do ARM.
Para testar arquivos de parâmetros, consulte Casos de teste para arquivos de parâmetros.
Para testes createUiDefinition, confira Casos de teste para createUiDefinition.json.
Para saber mais sobre testes para todos os arquivos, consulte Casos de teste para todos os arquivos.
Para conferir um módulo do Learn que abrange o uso do kit de ferramentas de teste, consulte Validar recursos do Azure usando o kit de ferramentas de teste do modelo do ARM.

Use o do Kit de ferramenta de teste do modelo do ARM

Recursos de treinamento

Instalar no Windows

Instalar no Linux

Instalar no macOS

Formato de resultado

Parâmetros de teste

Personalizar testes

Adicionar um teste personalizado

Validar modelos para Azure Marketplace

Executar os testes em seu ambiente

Interpretar os resultados

Enviar a oferta

Incorporar o Azure Pipelines

Próximas etapas

Recursos adicionais