Creación de artefactos personalizados para DevTest Labs

Artículo
09/30/2023

En este artículo se describe cómo crear archivos de artefacto personalizados para máquinas virtuales (VM) de Azure DevTest Labs. Los artefactos de DevTest Labs especifican las acciones que se deben realizar para aprovisionar una máquina virtual. Un artefacto consta de un archivo de definición de artefacto y de otros archivos de script que ha almacenado en una carpeta de un repositorio de Git.

Para obtener información sobre cómo agregar los repositorios de artefactos a laboratorios, consulte Incorporación de un repositorio de artefactos al laboratorio.
Para obtener más información sobre cómo agregar artefactos a las máquinas virtuales, consulte el apartado Adición de artefactos a máquinas virtuales de DevTest Labs.
Para obtener información sobre cómo especificar los artefactos obligatorios que se van a agregar a todas las máquinas virtuales de laboratorio, consulte Especificación de artefactos obligatorios para máquinas virtuales de DevTest Labs.

Archivos de definición de artefacto

Los archivos de definición de artefacto son expresiones JSON que especifican lo que desea instalar en una máquina virtual. Los archivos definen el nombre de un artefacto, un comando que se va a ejecutar y los parámetros disponibles para el comando. Puede hacer referencia a otros archivos de script en el archivo de definición de artefacto por nombre.

En el ejemplo siguiente se muestran las secciones que componen la estructura básica de un archivo de definición de artefacto artifactfile.json:

  {
    "$schema": "https://raw.githubusercontent.com/Azure/azure-devtestlab/master/schemas/2016-11-28/dtlArtifacts.json",
    "title": "",
    "description": "",
    "iconUri": "",
    "targetOsType": "",
    "parameters": {
      "<parameterName>": {
        "type": "",
        "displayName": "",
        "description": ""
      }
    },
    "runCommand": {
      "commandToExecute": ""
    }
  }

Nombre del elemento	Descripción
`$schema`	Ubicación del archivo de esquema JSON. El archivo de esquema JSON puede ayudarle a probar la validez del archivo de definición.
`title`	Nombre del artefacto que se muestra en el laboratorio. Obligatorio.
`description`	Descripción del artefacto que se muestra en el laboratorio. Obligatorio.
`iconUri`	URI del artefacto que se muestra en el laboratorio.
`targetOsType`	Sistema operativo de la máquina virtual en la que instalar el artefacto. Valores admitidos: `Windows`, `Linux`. Obligatorio.
`parameters`	Valores para personalizar el artefacto al instalar en la máquina virtual.
`runCommand`	El comando de instalación del artefacto que se ejecutará en la máquina virtual. Obligatorio.

Parámetros de artefacto

En la sección de parámetros del archivo de definición, especifique los valores que un usuario puede indicar al instalar un artefacto. Puede hacer referencia a estos valores en el comando de instalación del artefacto.

Para definir los parámetros, use la estructura siguiente:

  "parameters": {
    "<parameterName>": {
      "type": "<type-of-parameter-value>",
      "displayName": "<display-name-of-parameter>",
      "description": "<description-of-parameter>"
    }
  }

Nombre del elemento	Descripción
`type`	Tipo del valor de parámetro. Obligatorio.
`displayName`	Nombre del parámetro que se mostrará al usuario del laboratorio. Obligatorio.
`description`	Descripción del parámetro que se mostrará al usuario del laboratorio. Obligatorio.

Los tipos de valor de parámetro permitidos son:

Tipo	Descripción
`string`	Cualquier cadena JSON válida
`int`	Cualquier entero JSON válido
`bool`	Cualquier booleano JSON válido
`array`	Cualquier matriz JSON válida

Secretos como cadenas seguras

Para declarar secretos como parámetros de cadena segura con caracteres enmascarados en la interfaz de usuario, use la sintaxis siguiente en la sección parameters del archivo artifacfile.json:


    "securestringParam": {
      "type": "securestring",
      "displayName": "Secure String Parameter",
      "description": "Any text string is allowed, including spaces, and will be presented in UI as masked characters.",
      "allowEmpty": false
    },

El comando de instalación del artefacto para ejecutar el script de PowerShell toma la cadena segura creada mediante el comando ConvertTo-SecureString.

  "runCommand": {
    "commandToExecute": "[concat('powershell.exe -ExecutionPolicy bypass \"& ./artifact.ps1 -StringParam ''', parameters('stringParam'), ''' -SecureStringParam (ConvertTo-SecureString ''', parameters('securestringParam'), ''' -AsPlainText -Force) -IntParam ', parameters('intParam'), ' -BoolParam:$', parameters('boolParam'), ' -FileContentsParam ''', parameters('fileContentsParam'), ''' -ExtraLogLines ', parameters('extraLogLines'), ' -ForceFail:$', parameters('forceFail'), '\"')]"
  }

No registre secretos en la consola, ya que el script captura la salida para la depuración del usuario.

Expresiones y funciones de artefacto

Puede utilizar expresiones y funciones para construir el comando de instalación del artefacto. Las expresiones se evalúan cuando se instala el artefacto. Pueden aparecer expresiones en cualquier lugar de un valor de cadena JSON y devolver siempre otro valor JSON. Incluya las expresiones entre corchetes, [ ]. Si necesita usar una cadena literal que comienza por un corchete [, use dos corchetes [[.

Normalmente se utilizan expresiones con funciones para construir un valor. Las llamadas de función tienen el formato functionName(arg1, arg2, arg3).

Las funciones más comunes incluyen:

Función	Descripción
`parameters(parameterName)`	Devuelve un valor de parámetro que proporcionar cuando se ejecute el comando de artefacto.
`concat(arg1, arg2, arg3, ...)`	combina varios valores de cadena. Esta función puede adoptar varios argumentos.

En el ejemplo siguiente se muestra cómo utilizar expresiones y funciones para construir un valor:

  runCommand": {
      "commandToExecute": "[concat('powershell.exe -ExecutionPolicy bypass \"& ./startChocolatey.ps1'
  , ' -RawPackagesList ', parameters('packages')
  , ' -Username ', parameters('installUsername')
  , ' -Password ', parameters('installPassword'))]"
  }

Creación de un artefacto personalizado

Para crear un artefacto personalizado:

Instale un editor de JSON para trabajar con los archivos de definición del artefacto. Visual Studio Code está disponible para Windows, Linux y macOS.
Obtenga un archivo de definición artifactfile.json de ejemplo.

El repositorio de artefactos público de DevTest Labs público tiene una amplia biblioteca de artefactos que puede usar. Puede descargar un archivo de definición de artefacto y personalizarlo para crear sus propios artefactos.

En este artículo se usa el archivo de definición artifactfile.json y el script de PowerShell artifact.ps1 en https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes.
Use IntelliSense para ver los elementos válidos y las opciones de valor que se pueden utilizar para construir un archivo de definición de artefacto. Por ejemplo, al editar el elemento targetOsType, IntelliSense muestra las opciones Windows o Linux.
Almacene los artefactos en repositorios de artefactos de Git públicos o privados.
- Almacene cada archivo de definición de artefacto artifactfile.json en un directorio independiente denominado igual que el nombre del artefacto.
- Almacene los scripts a los que hace referencia el comando de instalación en el mismo directorio que el archivo de definición de artefacto.
La siguiente captura de pantalla muestra una carpeta de artefacto:
Para almacenar los artefactos personalizados en el repositorio de artefactos de DevTest Labs público, abra una solicitud de incorporación de cambios en el repositorio.
Para agregar el repositorio de artefactos privado a un laboratorio, consulte Agregar un repositorio de artefactos al laboratorio en DevTest Labs.