Uso del kit de herramientas para pruebas de plantillas de ARM

Article
03/20/2024

El kit de herramientas para pruebas de la plantilla de Resource Manager comprueba si la plantilla usa los procedimientos recomendados. Cuando la plantilla no es compatible con los procedimientos recomendados, devuelve una lista de advertencias con los cambios sugeridos. Con el kit de herramientas para pruebas, puede obtener información sobre cómo evitar los problemas comunes en el desarrollo de plantillas. En este artículo se describe cómo ejecutar el kit de herramientas para pruebas y cómo agregar o eliminar pruebas. Para más información sobre cómo ejecutar pruebas o sobre la ejecución de una prueba específica, consulte Parámetros de prueba.

El kit de herramientas es un conjunto de scripts de PowerShell que se puede ejecutar desde un comando de PowerShell o la CLI. Estas pruebas son recomendaciones, pero no requisitos. Puede decidir qué pruebas son adecuadas para sus objetivos y personalizar qué pruebas se ejecutan.

El kit de herramientas contiene cuatro conjuntos de pruebas:

Nota:

El kit de herramientas de prueba solo está disponible para plantillas de ARM. Para validar los archivos de Bicep, use Bicep linter.

Recursos de aprendizaje

Para obtener más información sobre el kit de herramientas de pruebas de plantillas de ARM y para obtener instrucciones prácticas, consulte Validación de recursos de Azure mediante el kit de herramientas para pruebas de plantillas de ARM.

Instalar en Windows

Si aún no tiene PowerShell, instale PowerShell en Windows.
Descargue el archivo ZIP más reciente para el kit de herramientas de pruebas y extráigalo.
Inicie PowerShell.
Navegue hasta la carpeta en la que extrajo el kit de herramientas de pruebas. Dentro de esa carpeta, vaya a la carpeta arm-ttk.
Si la directiva de ejecución bloquea los scripts de Internet, debe desbloquear los archivos de script. Asegúrese de que se encuentra en la carpeta arm-ttk.
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importe el módulo.
```
Import-Module .\arm-ttk.psd1
```
Para ejecutar las pruebas, use el siguiente comando:
```
Test-AzTemplate -TemplatePath \path\to\template
```

Instalar en Linux

Si aún no tiene PowerShell, instale PowerShell en Linux.
Descargue el archivo ZIP más reciente para el kit de herramientas de pruebas y extráigalo.
Inicie PowerShell.
```
pwsh
```
Navegue hasta la carpeta en la que extrajo el kit de herramientas de pruebas. Dentro de esa carpeta, vaya a la carpeta arm-ttk.
Si la directiva de ejecución bloquea los scripts de Internet, debe desbloquear los archivos de script. Asegúrese de que se encuentra en la carpeta arm-ttk.
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importe el módulo.
```
Import-Module ./arm-ttk.psd1
```
Para ejecutar las pruebas, use el siguiente comando:
```
Test-AzTemplate -TemplatePath /path/to/template
```

Instalación en macOS

Si aún no tiene PowerShell, instale PowerShell en macOS.
Instale coreutils:
```
brew install coreutils
```
Descargue el archivo ZIP más reciente para el kit de herramientas de pruebas y extráigalo.
Inicie PowerShell.
```
pwsh
```
Navegue hasta la carpeta en la que extrajo el kit de herramientas de pruebas. Dentro de esa carpeta, vaya a la carpeta arm-ttk.
Si la directiva de ejecución bloquea los scripts de Internet, debe desbloquear los archivos de script. Asegúrese de que se encuentra en la carpeta arm-ttk.
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importe el módulo.
```
Import-Module ./arm-ttk.psd1
```
Para ejecutar las pruebas, use el siguiente comando:
```
Test-AzTemplate -TemplatePath /path/to/template
```

Formato de resultado

Las pruebas que se superan se muestran en color verde y precedidas de [+] .

Las pruebas con errores se muestran en color rojo y precedidas de [-] .

Las pruebas con una advertencia se muestran en color amarillo y precedidas de [?].

Captura de pantalla de los resultados de las pruebas en diferentes colores para superado, no superado y advertencia.

Los resultados de texto son:

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 prueba

Cuando se proporciona el parámetro -TemplatePath, el kit de herramientas busca en esa carpeta una plantilla con el nombre azuredeploy.json o maintemplate.json. Primero se prueba esta plantilla y, a continuación, se prueban todas las demás plantillas de la carpeta y sus subcarpetas. Las otras plantillas se prueban como plantillas vinculadas. Si la ruta de acceso incluye un archivo llamado createUiDefinition.json, se ejecutan las pruebas que corresponden a la definición de la interfaz de usuario. Las pruebas también se ejecutan para los archivos de parámetros y todos los archivos JSON de la carpeta.

Test-AzTemplate -TemplatePath $TemplateFolder

Para probar un archivo de esa carpeta, agregue el parámetro -File. Sin embargo, la carpeta debe tener una plantilla principal llamada azuredeploy.json o maintemplate.json.

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

De forma predeterminada, se ejecutan todas las pruebas. Para especificar pruebas individuales que se van a ejecutar, use el parámetro -Test y proporcione el nombre de la prueba. Para los nombres de prueba, consulte las plantillas de ARM, los archivos de parámetros, createUiDefinition.json y todos los archivos.

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

Personalización de las pruebas

Puede personalizar las pruebas predeterminadas o crear sus propias pruebas. Si quiere eliminar permanentemente una prueba, elimine el archivo .test.ps1 de la carpeta.

El kit de herramientas tiene cuatro carpetas que contienen las pruebas predeterminadas que se ejecutan para tipos de archivo específicos:

Plantillas de ARM: \arm-ttk\testcases\deploymentTemplate
Archivos de parámetros: \arm-ttk\testcases\deploymentParameters
createUiDefinition.json: \arm-ttk\testcases\CreateUIDefinition
Todos los archivos: \arm-ttk\testcases\AllFiles

Adición de una prueba personalizada

Para agregar su propia prueba, cree un archivo con la convención de nomenclatura: Your-Custom-Test-Name.test.ps1.

La prueba puede obtener la plantilla como un parámetro de objeto o un parámetro de cadena. Normalmente se usa uno u otro, pero se pueden usar ambos.

Use el parámetro de objeto cuando necesite obtener una sección de la plantilla y recorrer en iteración sus propiedades. Una prueba que usa el parámetro de objeto tiene el siguiente formato:

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

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

El objeto de la plantilla tiene las siguientes propiedades:

$schema
contentVersion
parameters
variables
resources
outputs

Por ejemplo, puede obtener la colección de parámetros con $TemplateObject.parameters.

Use el parámetro de cadena cuando necesite realizar una operación de cadena en toda la plantilla. Una prueba que usa el parámetro de cadena tiene el siguiente formato:

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

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

Por ejemplo, puede ejecutar una expresión regular del parámetro de cadena para ver si se utiliza una sintaxis específica.

Para más información sobre la implementación de la prueba, examine las otras pruebas de esa carpeta.

Validación de plantillas para Azure Marketplace

Para publicar una oferta en Azure Marketplace, use el kit de herramientas de pruebas para validar las plantillas. Cuando las plantillas superen las pruebas de validación, Azure Marketplace aprobará la oferta más rápidamente. Si producen un error en las pruebas, la oferta producirá un error en la certificación.

Importante

Las pruebas de Marketplace se agregaron en julio de 2022. Actualice el módulo si tiene una versión anterior.

Ejecute pruebas en el entorno

Después de instalar el kit de herramientas e importar el módulo, ejecute el siguiente cmdlet para probar el paquete:

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

Interpretación de los resultados

Las pruebas devuelven resultados en dos secciones. La primera sección incluye las pruebas que son obligatorias. Los resultados de estas pruebas se muestran en la sección de resumen.

Importante

Debe corregir los resultados en rojo antes de que se acepte la oferta de Marketplace. Se recomienda corregir los resultados que se devuelven en amarillo.

Los resultados de texto son:

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

La sección debajo de la sección de resumen incluye errores de prueba que se pueden interpretar como advertencias. Corregir los errores es opcional, pero muy recomendable. Los errores suelen apuntar a problemas comunes que provocan errores cuando un cliente instala la oferta.

Para corregir las pruebas, siga el caso de prueba aplicable:

Envío de la oferta

Después de realizar las correcciones necesarias, vuelva a ejecutar el kit de herramientas de pruebas. Antes de enviar la oferta a Azure Marketplace, asegúrese de que no contiene errores.

Integración con Azure Pipelines

Puede agregar el kit de herramientas para pruebas a su canalización de Azure. Con una canalización, puede ejecutar la prueba cada vez que se actualiza la plantilla o ejecutarla como parte del proceso de implementación.

La forma más fácil de agregar el kit de herramientas para pruebas a la canalización es con extensiones de terceros. Están disponibles las dos extensiones siguientes:

O bien, puede implementar sus propias tareas. En el ejemplo siguiente se muestra cómo descargar el kit de herramientas para pruebas.

Para la canalización de versión:

{
  "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 la definición de YAML de canalización:

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

En el ejemplo siguiente se muestra cómo ejecutar las pruebas.