Creación de artefactos personalizados para máquinas virtuales de DevTest Labs

Los artefactos son herramientas, acciones o software que puede agregar a máquinas virtuales de Azure DevTest Labs. Por ejemplo, los artefactos pueden ejecutar scripts, instalar herramientas o realizar acciones como unir un dominio. Los usuarios de DevTest Labs pueden agregar artefactos a sus máquinas virtuales y los administradores de laboratorio pueden especificar artefactos obligatorios que se van a agregar a todas las máquinas virtuales de laboratorio.

En este artículo se describe cómo crear artefactos que aprovisionan máquinas virtuales de laboratorio. Un artefacto consta de un archivo JSON de definición de artefacto y otros archivos de script almacenados en una carpeta del repositorio de Git. Puede almacenar artefactos en un repositorio git privado o público. Los administradores de laboratorio pueden agregar repositorios de artefactos a laboratorios para que todos los usuarios del laboratorio puedan acceder a ellos.

Prerrequisitos

• Para crear y trabajar con archivos de definición de artefactos, necesita un editor JSON. Visual Studio Code está disponible para Windows, Linux y macOS.
• Para almacenar la definición del artefacto y los archivos de script, necesita una cuenta de GitHub.

Comprende los archivos de definición de artefactos

Un archivo de definición de artefacto consta de una expresión JSON que especifica la acción que se va a realizar en una máquina virtual. El archivo define un nombre de artefacto, un comando que se va a ejecutar y parámetros disponibles para el comando. Si el artefacto contiene otros archivos de script, puede hacer referencia a los archivos por su nombre en el archivo de definición de artefacto.

En el ejemplo siguiente se muestra 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": "<title>",
    "description": "<description>",
    "iconUri": "",
    "targetOsType": "<os>",
    "parameters": {
      "<paramName>": {
        "type": "<type>",
        "displayName": "<display name>",
        "description": "<description>"
      }
    },
    "runCommand": {
      "commandToExecute": "<command>"
    }
  }

La definición tiene los siguientes elementos obligatorios y opcionales:

Parámetros de artefacto

La parameters sección del archivo de definición define las opciones y los valores que los usuarios pueden especificar al instalar el artefacto. Puede hacer referencia a estos parámetros en el runCommand.

La estructura siguiente define un parámetro:

  "parameters": {
    "<name>": {
      "type": "<type>",
      "displayName": "<display name>",
      "description": "<description>"
    }
  }

Cada parámetro requiere un nombre y la definición de parámetro requiere los siguientes elementos:

Parámetros de cadena seguros

Para incluir secretos en una definición de artefacto, declare los secretos como cadenas seguras mediante la secureStringParam sintaxis de la parameters sección del archivo de definición. El description elemento permite cualquier cadena de texto, incluidos los espacios, y presenta la cadena en la interfaz de usuario como caracteres enmascarados.

    "securestringParam": {
      "type": "securestring",
      "displayName": "Secure String Parameter",
      "description": "<any text string>",
      "allowEmpty": false
    },

El siguiente runCommand usa un script de PowerShell que toma la cadena segura creada mediante el comando ConvertTo-SecureString. El script captura la salida para depuración, así que, por motivos de seguridad, no registres la salida en la consola.

  "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'), '\"')]"
  }

Expresiones y funciones de artefacto

Puede usar expresiones y funciones para construir el comando artifact install. Las expresiones se evalúan cuando se instala el artefacto.

Las expresiones pueden aparecer en cualquier lugar de un valor de cadena JSON y siempre devolver otro valor JSON. Incluya expresiones con corchetes, [ ]. Si necesita usar una cadena literal que empiece por un corchete, use dos corchetes [[.

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

Entre las funciones comunes se incluyen las siguientes:

En el ejemplo siguiente se usan expresiones con la concat función 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

Puede crear un artefacto personalizado a partir de un archivo de definición de ejemplo artifactfile.json. El repositorio de artefactos de DevTest Labs público tiene una biblioteca de artefactos. Puede descargar un archivo de definición de artefacto y personalizarlo para crear sus propios artefactos.

1. Descargue el archivo de definición artifactfile.json y artifact.ps1, un script de PowerShell, desde https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes.

2. Edite el archivo de definición de artefacto para realizar algunos cambios válidos en elementos y valores. En Visual Studio Code, puede usar IntelliSense para ver elementos y opciones de valor válidos. Por ejemplo, al editar el targetOsType elemento, IntelliSense muestra las Windows opciones o Linux .

3. Almacene el artefacto en un repositorio de artefactos de Git público o privado.

   • Almacene cada archivo de definición de artefacto artifactfile.json en un directorio independiente nombrado como el 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.

   En la captura de pantalla siguiente se muestra una carpeta de artefactos de ejemplo:

   

   Nota:

   Para añadir los artefactos personalizados en el repositorio de artefactos de DevTest Labs público, abra una solicitud de incorporación de cambios en el repositorio.

Pasos siguientes

• Adición de artefactos a máquinas virtuales de DevTest Labs
• Especificación de artefactos obligatorios que se van a agregar a todas las máquinas virtuales de laboratorio
• Adición de un repositorio de artefactos a un laboratorio

Contenido relacionado

• Diagnosticar fallos en los artefactos del laboratorio
• Solución de problemas al aplicar artefactos