Créer des artefacts personnalisés pour DevTest Labs
Cet article explique comment créer des fichiers d’artefacts personnalisés pour des machines virtuelles Azure DevTest Labs. Les artefacts DevTest Labs spécifient les actions à entreprendre pour approvisionner une machine virtuelle. Un artefact se compose d’un fichier de définition d’artefact et d’autres fichiers de script que vous stockez dans un dossier d’un référentiel Git.
- Pour plus d’informations sur l’ajout de vos référentiels d’artefacts aux laboratoires, consultez Ajouter un référentiel d’artefacts à votre laboratoire.
- Pour plus d’informations sur l’ajout des artefacts que vous créez aux machines virtuelles, consultez Ajouter des artefacts à des machines virtuelles DevTest Labs.
- Pour plus d’informations sur la spécification d’artefacts obligatoires à ajouter à toutes les machines virtuelles de laboratoire, consultez Spécifier les artefacts obligatoires pour les machines virtuelles DevTest Labs.
Fichiers de définition d’artefact
Les fichiers de définition d’artefact sont des expressions JSON qui spécifient ce que vous voulez installer sur une machine virtuelle. Les fichiers définissent le nom d’un artefact, une commande à exécuter et les paramètres disponibles pour la commande. Vous pouvez faire référence à d’autres fichiers de script par leur nom dans le fichier de définition d’artefact.
L’exemple suivant indique les sections qui composent 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": "",
"description": "",
"iconUri": "",
"targetOsType": "",
"parameters": {
"<parameterName>": {
"type": "",
"displayName": "",
"description": ""
}
},
"runCommand": {
"commandToExecute": ""
}
}
| Nom de l'élément | Description |
|---|---|
$schema |
Emplacement du fichier de schéma JSON. Le fichier de schéma JSON peut vous aider à tester la validité du fichier de définition. |
title |
Nom de l’artefact à afficher dans le laboratoire. Obligatoire. |
description |
Description de l’artefact à afficher dans le laboratoire. Obligatoire. |
iconUri |
URI de l’icône d’artefact à afficher dans le laboratoire. |
targetOsType |
Système d’exploitation de la machine virtuelle sur laquelle installer l’artefact. Valeurs prises en charge : Windows, Linux.
Obligatoire. |
parameters |
Valeurs pour personnaliser l’artefact lors de l’installation sur la machine virtuelle. |
runCommand |
Commande d’installation de l’artefact à exécuter sur la machine virtuelle. Obligatoire. |
Paramètres d'artefact
Dans la section des paramètres du fichier de définition, spécifiez les valeurs qu’un utilisateur peut entrer lors de l’installation d’un artefact. Vous pouvez faire référence à ces valeurs dans la commande d'installation d'artefact.
Pour définir des paramètres, utilisez la structure suivante :
"parameters": {
"<parameterName>": {
"type": "<type-of-parameter-value>",
"displayName": "<display-name-of-parameter>",
"description": "<description-of-parameter>"
}
}
| Nom de l'élément | Description |
|---|---|
type |
Type de la valeur du paramètre. Obligatoire. |
displayName |
Nom du paramètre à afficher à l’utilisateur du laboratoire. Obligatoire. |
description |
Description du paramètre à afficher à l’utilisateur du laboratoire. Obligatoire. |
Les types de valeurs de paramètres autorisés sont les suivants :
| Type | Description |
|---|---|
string |
N’importe quelle chaîne JSON valide |
int |
N’importe quel entier JSON valide |
bool |
N’importe quelle valeur booléenne JSON valide |
array |
N’importe quel tableau JSON valide |
Secrets sous forme de chaînes sécurisées
Pour déclarer des secrets en tant que paramètres de chaînes sécurisées avec des caractères masqués dans l’interface utilisateur, utilisez la syntaxe suivante dans la section parameters du fichier artifactfile.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
},
La commande d’installation de l’artefact pour exécuter le script PowerShell accepte la chaîne sécurisée créée à l’aide de la commande 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'), '\"')]"
}
N’enregistrez pas de secrets dans la console, car le script capture la sortie pour le débogage utilisateur.
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 retournent toujours une autre valeur JSON. Placez les expressions entre crochets, [ ]. Si vous avez besoin d’utiliser une chaîne littérale qui commence par un crochet, utilisez deux crochets [[.
Vous utilisez généralement les expressions avec des fonctions pour construire une valeur. Les appels de fonction suivent le format functionName(arg1, arg2, arg3).
Les fonctions courantes sont les suivantes :
| Fonction | Description |
|---|---|
parameters(parameterName) |
Renvoie une valeur de paramètre à fournir lors de l’exécution de la commande de l’artefact. |
concat(arg1, arg2, arg3, ...) |
combine plusieurs valeurs de chaîne. Cette fonction peut prendre plusieurs arguments. |
L’exemple suivant utilise des expressions et des fonctions pour construire une valeur :
runCommand": {
"commandToExecute": "[concat('powershell.exe -ExecutionPolicy bypass \"& ./startChocolatey.ps1'
, ' -RawPackagesList ', parameters('packages')
, ' -Username ', parameters('installUsername')
, ' -Password ', parameters('installPassword'))]"
}
Création d'un artefact personnalisé
Pour créer un artefact personnalisé :
Installez un éditeur JSON pour utiliser des fichiers de définition d’artefact. Visual Studio Code est disponible pour Windows, Linux et macOS.
Commencez par un exemple de fichier de définition artifactfile.json.
Le référentiel d’artefacts DevTest Labs public contient une bibliothèque complète d’artefacts que vous pouvez utiliser. Vous pouvez télécharger un fichier de définition d’artefact et le personnaliser pour créer vos propres artefacts.
Cet article utilise le fichier de définition artifactfile.json et le script PowerShell artifact.ps1 accessibles à l’adresse https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes.
Utilisez IntelliSense pour voir les éléments valides et les options de valeur que vous pouvez utiliser pour construire un fichier de définition d’artefact. Par exemple, lorsque vous modifiez l’élément
targetOsType, IntelliSense vous indique les optionsWindowsouLinux.Stockez vos artefacts dans des référentiels d’artefacts Git publics ou privés.
- Stockez chaque fichier de définition d’artefact artifactfile.json dans un répertoire distinct portant le même nom que celui de l’artefact.
- Stockez les scripts auxquels la commande d’installation fait référence 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’artefact :
Pour stocker vos artefacts personnalisés dans le référentiel d’artefacts DevTest Labs public, ouvrez une demande de tirage (pull request) sur le référentiel.
Pour ajouter votre référentiel d’artefacts privé à un laboratoire, consultez Ajouter un référentiel d’artefacts à votre laboratoire dans DevTest Labs.