Créer des artefacts personnalisés pour les machines virtuelles DevTest Labs

Les artefacts sont des outils, des actions ou des logiciels que vous pouvez ajouter aux machines virtuelles Azure DevTest Labs. Par exemple, les artefacts peuvent exécuter des scripts, installer des outils ou effectuer des actions telles que la jonction d’un domaine. Les utilisateurs devTest Labs peuvent ajouter des artefacts à leurs machines virtuelles, et les administrateurs de laboratoire peuvent spécifier des artefacts obligatoires à ajouter à toutes les machines virtuelles de laboratoire.

Cet article explique comment créer des artéfacts qui provisionnent des machines virtuelles de laboratoire. Un artefact se compose d’un fichier JSON de définition d’artefact et d’autres fichiers de script stockés dans un dossier de référentiel Git. Vous pouvez stocker des artefacts dans un dépôt Git privé ou public. Les administrateurs de laboratoire peuvent ajouter des référentiels d’artefacts aux laboratoires afin que tous les utilisateurs du labo puissent y accéder.

Prerequisites

• Pour créer et utiliser des fichiers de définition d’artefact, vous avez besoin d’un éditeur JSON. Visual Studio Code est disponible pour Windows, Linux et macOS.
• Pour stocker les fichiers de définition d’artefact et de script, vous avez besoin d’un compte GitHub.

Comprendre les fichiers de définition d’artefact

Un fichier de définition d’artefact se compose d’une expression JSON qui spécifie l’action à entreprendre sur une machine virtuelle. Le fichier définit un nom d’artefact, une commande à exécuter et des paramètres disponibles pour la commande. Si l’artefact contient d’autres fichiers de script, vous pouvez faire référence aux fichiers par nom dans le fichier de définition d’artefact.

L’exemple suivant montre la structure de base d’un fichier de définition d’artefact 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 définition comporte les éléments obligatoires et facultatifs suivants :

Paramètres d’artefact

La parameters section du fichier de définition définit les options et les valeurs que les utilisateurs peuvent spécifier quand ils installent l’artefact. Vous pouvez faire référence à ces paramètres dans le runCommand.

La structure suivante définit un paramètre :

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

Chaque paramètre nécessite un nom et la définition de paramètre nécessite les éléments suivants :

Paramètres de chaîne sécurisée

Pour inclure des secrets dans une définition d’artefact, déclarez les secrets en tant que chaînes sécurisées à l’aide de la secureStringParam syntaxe dans la parameters section du fichier de définition. L’élément description autorise toute chaîne de texte, y compris les espaces, et présente la chaîne dans l’interface utilisateur sous forme de caractères masqués.

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

L’exemple suivant runCommand utilise un script PowerShell qui prend la chaîne sécurisée créée à l’aide de la ConvertTo-SecureString commande. Le script capture la sortie pour le débogage. Par conséquent, pour la sécurité, ne consignez pas la sortie dans la console.

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

Expressions et fonctions d’artefact

Vous pouvez utiliser des expressions et des fonctions pour construire la commande d’installation d’artefact. Les expressions sont évaluées lors de l’installation de l’artefact.

Les expressions peuvent apparaître n’importe où dans une valeur de chaîne JSON et retourner toujours une autre valeur JSON. Placez les expressions entre crochets, [ ]. Si vous devez utiliser une chaîne littérale qui commence par un crochet, utilisez deux crochets [[.

Vous utilisez généralement des expressions avec des fonctions pour construire une valeur. Les appels de fonction sont mis en forme en tant que functionName(arg1, arg2, arg3).

Les fonctions courantes sont les suivantes :

L’exemple suivant utilise des expressions avec la concat fonction pour construire une valeur.

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

Créer un artefact personnalisé

Vous pouvez créer un artefact personnalisé en commençant à partir d’un exemple de fichier de définitionartifactfile.json . Le référentiel d’artefacts DevTest Labs public a une bibliothèque d’artefacts. Vous pouvez télécharger un fichier de définition d’artefact et le personnaliser pour créer vos propres artefacts.

1. Téléchargez le fichier de définition artifactfile.json et le script PowerShell artifact.ps1 à partir de https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes.

2. Modifiez le fichier de définition d’artefact pour apporter des modifications valides aux éléments et valeurs. Dans Visual Studio Code, vous pouvez utiliser IntelliSense pour afficher des éléments et des options de valeur valides. Par exemple, lorsque vous modifiez l’élément targetOsType, IntelliSense affiche des options Windows ou Linux pour vous.

3. Stockez votre artefact dans un référentiel d’artefacts Git public ou privé.

   • Stockez chaque artifactfile.json fichier de définition d’artefact dans un répertoire distinct nommé identique au nom de l’artefact.
   • Stockez les scripts référencés par la commande Install dans le même répertoire que le fichier de définition d’artefact.

   La capture d’écran suivante montre un exemple de dossier d’artefacts :

   

   Note

   Pour ajouter vos artefacts personnalisés au référentiel d’artefacts DevTest Labs public, ouvrez une pull request sur le dépôt.

Étapes suivantes

• Ajouter des artefacts aux machines virtuelles DevTest Labs
• Spécifier les artefacts obligatoires à ajouter à toutes les machines virtuelles lab
• Ajouter un référentiel d’artefacts à un laboratoire

Contenu connexe

• Diagnostiquer les défaillances d'artefact dans le laboratoire
• Résoudre les problèmes liés à l’application d’artefacts