Utilizar o toolkit de testes de modelos do ARM

Artigo
03/20/2024

O toolkit de testes do modelo do Azure Resource Manager (modelo arm) verifica se o seu modelo utiliza práticas recomendadas. Quando o modelo não está em conformidade com as práticas recomendadas, devolve uma lista de avisos com as alterações sugeridas. Ao utilizar o toolkit de testes, pode aprender a evitar problemas comuns no desenvolvimento de modelos. Este artigo descreve como executar o toolkit de testes e como adicionar ou remover testes. Para obter mais informações sobre como executar testes ou como executar um teste específico, veja Parâmetros de teste.

O toolkit é um conjunto de scripts do PowerShell que podem ser executados a partir de um comando no PowerShell ou na CLI. Estes testes são recomendações, mas não requisitos. Pode decidir que testes são relevantes para os seus objetivos e personalizar os testes que são executados.

O toolkit contém quatro conjuntos de testes:

Nota

O toolkit de testes só está disponível para modelos arm. Para validar ficheiros Bicep, utilize o linter Bicep.

Recursos de preparação

Para saber mais sobre o toolkit de testes de modelos do ARM e para obter orientações práticas, veja Validar recursos do Azure com o Toolkit de Testes de Modelos do ARM.

Instalar no Windows

Se ainda não tiver o PowerShell, instale o PowerShell no Windows.
Transfira o ficheiro de .zip mais recente do toolkit de testes e extraia-o.
Inicie o PowerShell.
Navegue para a pasta onde extraiu o toolkit de testes. Nessa pasta, navegue para a pasta arm-ttk .
Se a política de execução bloquear scripts da Internet, terá de desbloquear os ficheiros de script. Certifique-se de que 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, utilize o seguinte comando:
```
Test-AzTemplate -TemplatePath \path\to\template
```

Instalar no Linux

Se ainda não tiver o PowerShell, instale o PowerShell no Linux.
Transfira o ficheiro de .zip mais recente do toolkit de testes e extraia-o.
Inicie o PowerShell.
```
pwsh
```
Navegue para a pasta onde extraiu o toolkit de testes. Nessa pasta, navegue para a pasta arm-ttk .
Se a política de execução bloquear scripts da Internet, terá de desbloquear os ficheiros de script. Certifique-se de que 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, utilize o seguinte comando:
```
Test-AzTemplate -TemplatePath /path/to/template
```

Instalar no macOS

Se ainda não tiver o PowerShell, instale o PowerShell no macOS.
Instalar coreutils:
```
brew install coreutils
```
Transfira o ficheiro de .zip mais recente do toolkit de testes e extraia-o.
Inicie o PowerShell.
```
pwsh
```
Navegue para a pasta onde extraiu o toolkit de testes. Nessa pasta, navegue para a pasta arm-ttk .
Se a política de execução bloquear scripts da Internet, terá de desbloquear os ficheiros de script. Certifique-se de que 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, utilize o seguinte comando:
```
Test-AzTemplate -TemplatePath /path/to/template
```

Formato dos resultados

Os testes transmitidos são apresentados a verde e precedidos de [+].

Os testes que falham são apresentados a vermelho e prefaciados com [-].

Os testes com um aviso são apresentados a amarelo e precedidos de [?].

Captura de ecrã a mostrar resultados de teste com cores diferentes para passar, falhar e avisar.

Os resultados do texto sã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.

Testar parâmetros

Quando fornece o -TemplatePath parâmetro , o toolkit procura nessa pasta um modelo com o nome azuredeploy.json ou maintemplate.json. Testa primeiro este modelo e, em seguida, testa todos os outros modelos na pasta e nas respetivas subpastas. Os outros modelos são testados como modelos ligados. Se o seu caminho incluir um ficheiro com o nome createUiDefinition.json, executa testes que são relevantes para a definição da IU. Os testes também são executados para ficheiros de parâmetros e todos os ficheiros JSON na pasta.

Test-AzTemplate -TemplatePath $TemplateFolder

Para testar um ficheiro nessa pasta, adicione o -File parâmetro . No entanto, a pasta ainda tem de ter um modelo principal com o nome azuredeploy.json ou maintemplate.json.

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

Por predefinição, todos os testes são executados. Para especificar testes individuais a executar, utilize o -Test parâmetro e forneça o nome do teste. Para obter os nomes dos testes, veja Modelos arm, ficheiros de parâmetros, createUiDefinition.json e todos os ficheiros.

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

Personalizar testes

Pode personalizar os testes predefinidos ou criar os seus próprios testes. Se quiser remover permanentemente um teste, elimine o ficheiro .test.ps1 da pasta.

O toolkit tem quatro pastas que contêm os testes predefinidos que são executados para tipos de ficheiro específicos:

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

Adicionar um teste personalizado

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

O teste pode obter o modelo como um parâmetro de objeto ou um parâmetro de cadeia. Normalmente, utiliza um ou outro, mas pode utilizar ambos.

Utilize o parâmetro de objeto quando precisar de obter uma secção do modelo e iterar através das respetivas propriedades. Um teste que utiliza 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 objeto de modelo tem as seguintes propriedades:

$schema
contentVersion
parameters
variables
resources
outputs

Por exemplo, pode obter a coleção de parâmetros com $TemplateObject.parameters.

Utilize o parâmetro de cadeia quando precisar de efetuar uma operação de cadeia de carateres em todo o modelo. Um teste que utiliza o parâmetro de cadeia tem o seguinte formato:

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

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

Por exemplo, pode executar uma expressão regular do parâmetro de cadeia para ver se é utilizada uma sintaxe específica.

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

Validar modelos para Azure Marketplace

Para publicar uma oferta no Azure Marketplace, utilize o toolkit de testes para validar os modelos. Quando os seus modelos passarem nos testes de validação, Azure Marketplace aprovará a oferta mais rapidamente. Se falharem nos testes, a oferta falhará a certificação.

Importante

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

Executar os testes no seu ambiente

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

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

Interpretar os resultados

Os testes devolvem resultados em duas secções. A primeira secção inclui os testes obrigatórios. Os resultados destes testes são apresentados na secção de resumo.

Importante

Tem de corrigir quaisquer resultados a vermelho antes de a oferta do Marketplace ser aceite. Recomendamos que corrija todos os resultados devolvidos a amarelo.

Os resultados do texto sã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 secção abaixo da secção de resumo inclui falhas de teste que podem ser interpretadas como avisos. Corrigir as falhas é opcional, mas altamente recomendado. Muitas vezes, as falhas apontam para problemas comuns que causam falhas quando um cliente instala a oferta.

Para corrigir os testes, siga o caso de teste aplicável:

Submeter a oferta

Depois de efetuar as correções necessárias, execute novamente o toolkit de testes. Antes de submeter a oferta para Azure Marketplace, certifique-se de que não tem nenhuma falha.

Integrar com o Azure Pipelines

Pode adicionar o toolkit de testes ao seu Pipeline do Azure. Com um pipeline, pode executar o teste sempre que o modelo for atualizado ou executá-lo como parte do processo de implementação.

A forma mais fácil de adicionar o toolkit de testes ao pipeline é com extensões de terceiros. Estão disponíveis as duas extensões seguintes:

Em alternativa, pode implementar as suas próprias tarefas. O exemplo seguinte mostra como transferir o toolkit de testes.

Para o Pipeline de Versão:

{
  "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 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 exemplo seguinte mostra como executar os testes.