Écrire un fichier de personnalisation pour une dev box
Dans cet article, vous allez découvrir comment créer et tester un fichier de personnalisation pour votre dev box en utilisant Visual Studio Code (VS Code) et Dev Home.
Il existe deux façons d’utiliser un fichier de personnalisation dans Microsoft Dev Box. Les personnalisations d’équipe sont appliquées automatiquement quand les développeurs les configurent sur un pool. Les personnalisations individuelles sont appliquées quand un utilisateur crée une dev box.
Cet article vous aide à définir de nouvelles tâches dans votre fichier de personnalisation, à les appliquer à vos dev box et à tester ces personnalisations directement dans VS Code.
Important
La fonctionnalité de personnalisations d’équipe Dev Box est actuellement en préversion. Pour plus d’informations sur l’état de préversion, consultez Conditions d’utilisation supplémentaires pour les préversions de Microsoft Azure. Le document définit les conditions juridiques qui s’appliquent aux fonctionnalités Azure en version bêta, en préversion ou qui ne sont pas encore en disponibilité générale.
Prérequis
Pour effectuer les étapes décrites dans cet article, vous devez :
- Disposer d’un centre de développement configuré avec une définition de dev box, un pool de dev box et un projet de dev box pour pouvoir créer une dev box.
- Être membre de du groupe de sécurité Utilisateurs Dev Box pour au moins un projet.
- Disposer d’un catalogue attaché au Centre de développement avec des tâches que vous pouvez utiliser dans votre fichier de personnalisation. Si vous n’avez pas de catalogue, consultez Ajouter et configurer un catalogue depuis GitHub ou Azure Repos.
Autorisations requises pour configurer des personnalisations
Pour effectuer les actions requises pour créer et appliquer des personnalisations à une dev box, vous avez besoin des autorisations suivantes :
| Action | Autorisation/rôle |
|---|---|
| Activer les catalogues de niveau projet pour un centre de développement. | Ingénieur de plateforme disposant d’un accès en écriture sur l’abonnement. |
| Activer les paramètres de synchronisation de catalogue pour un projet. | Ingénieur de plateforme disposant d’un accès en écriture sur l’abonnement. |
| Attacher un catalogue à un projet. | Autorisations Administrateur de projet ou Contributeur sur le projet. |
| Créer un fichier de personnalisation. | Aucune spécification. Tout le monde peut créer un fichier de personnalisation. |
| Utiliser le portail des développeurs pour charger et appliquer un fichier YAML pendant la création d’une dev box. | Utilisateur Dev Box. |
| Ajouter des tâches à un catalogue. | Autorisation d’ajouter au référentiel qui héberge le catalogue. |
Qu’est-ce qu’un fichier de personnalisation ?
Les personnalisations Dev Box utilisent un fichier au format YAML pour spécifier une liste de tâches lorsqu’un développeur crée une dev box. Ces tâches peuvent être simples, comme l’installation d’un package, ou plus sophistiquées, comme l’exécution d’un ensemble complexe de scripts pour configurer une codebase. Les tâches identifient le catalogue et fournissent des paramètres tels que le nom du logiciel à installer. Le fichier de personnalisation est ensuite mis à la disposition des développeurs qui créent des dev box.
L’exemple suivant utilise une tâche winget pour installer VS Code et une tâche git-clone pour cloner un référentiel :
# From https://github.com/microsoft/devcenter-examples
$schema: 1.0
tasks:
- name: winget
parameters:
package: Microsoft.VisualStudioCode
runAsUser: true
- name: git-clone
description: Clone this repository into C:\Workspaces
parameters:
repositoryUrl: https://github.com/OrchardCMS/OrchardCore.git
directory: C:\Workspaces
Il existe deux façons d’utiliser un fichier de personnalisation : les personnalisations individuelles, qui s’appliquent à une seule dev box, et les personnalisations d’équipe, qui s’appliquent à une équipe entière.
Fichiers de personnalisations individuelles
- Contiennent des tâches qui sont appliquées quand un développeur crée une dev box.
- Sont chargés par le développeur pendant la création d’une dev box.
Fichiers de personnalisations d’équipe
- Contiennent des tâches qui sont appliquées quand un développeur crée une dev box.
- Sont partagés par une équipe ou un projet.
- Incluent un champ qui spécifie l’image de base.
- Sont nommés imagedefinition.yaml.
- Sont chargés dans le référentiel qui héberge un catalogue.
- Sont automatiquement utilisés quand un développeur crée une dev box à partir d’un pool configuré.
Important
Les définitions d’images peuvent uniquement utiliser des images de la Place de marché Dev Box comme images de base. Pour obtenir la liste des images auxquelles votre centre de développement peut accéder, utilisez cette commande Azure CLI :
az devcenter admin image list --dev-center-name CustomizationsImagingHQ --resource-group TeamCustomizationsImagingRG --query "[].name"
Créer un fichier de personnalisation
Vous pouvez créer et gérer des fichiers de personnalisation avec VS Code. Vous pouvez utiliser l’extension Microsoft Dev Box dans VS Code pour découvrir les tâches du catalogue attaché et tester le fichier de personnalisation.
Créez une dev box (ou utilisez une dev box existante) à des fins de test.
Sur la dev box de test, installez VS Code, puis installez l’extension Dev Box.
Téléchargez un fichier de personnalisation YAML d’exemple à partir du référentiel d’exemples et ouvrez-le dans VS Code.
Découvrez les tâches disponibles dans le catalogue en utilisant la palette de commandes. Sélectionnez Afficher>Palette de commandes>Dev Box : Lister les tâches disponibles pour cette dev box.
Testez la personnalisation dans VS Code à l’aide de la palette de commandes. Sélectionnez Afficher>Palette de commandes>Dev Box : Appliquer des tâches de personnalisation.
Le fichier de personnalisation s’exécute immédiatement et applique les tâches spécifiées à votre dev box de test. Inspectez les changements et vérifiez si le terminal VS Code contient des erreurs ou des avertissements générés pendant l’exécution des tâches.
Quand le fichier de personnalisation s’exécute correctement, chargez-le dans votre catalogue.
Cloner un référentiel privé en utilisant un fichier de personnalisation
Vous pouvez utiliser des secrets de votre coffre de clés Azure dans vos personnalisations YAML pour cloner des référentiels privés, ou avec n’importe quelle tâche personnalisée que vous créez et qui nécessite un jeton d’accès. Dans un fichier de personnalisation d’équipe, vous pouvez utiliser un jeton d’accès personnel (PAT) stocké dans un coffre de clés pour accéder à un référentiel privé.
Utiliser des secrets du coffre de clés dans des fichiers de personnalisation d’équipe
Pour cloner un référentiel privé, stockez votre jeton d’accès personnel en tant que secret de coffre de clés et utilisez-le lorsque vous appelez la tâche git-clone dans votre personnalisation.
Pour configurer les secrets de votre coffre de clés à utiliser dans vos personnalisations YAML :
- Assurez-vous que l’identité managée de votre projet de centre de développement dispose du rôle Lecteur Key Vault et du rôle Utilisateur des secrets Key Vault sur votre coffre de clés.
- Accordez le rôle Utilisateur des secrets Key Vault pour le secret de coffre de clés à chaque utilisateur ou groupe d’utilisateurs qui doit pouvoir consommer le secret pendant la personnalisation d’une dev box. L’utilisateur ou le groupe auquel le rôle est accordé doit inclure l’identité managée du centre de développement, votre propre compte d’utilisateur et tout utilisateur ou groupe ayant besoin du secret pendant la personnalisation d’une dev box.
Pour plus d’informations, consultez l’article suivant :
- Configurer une identité managée pour un centre de développement
- Accorder à l’identité managée l’accès au secret du coffre de clés
Vous pouvez référencer le secret dans votre personnalisation YAML au format suivant, qui utilise la tâche git-clone comme exemple :
$schema: "1.0"
tasks:
name: git-clone
description: Clone this repository into C:\Workspaces
parameters:
repositoryUrl: https://myazdo.visualstudio.com/MyProject/_git/myrepo
directory: C:\Workspaces
pat: '{{KEY_VAULT_SECRET_URI}}'
Utiliser des secrets de coffre de clés dans des fichiers de personnalisations individuelles
Si vous souhaitez cloner un référentiel Azure Repos privé à partir d’un fichier de personnalisations individuelles, il n’est pas nécessaire de configurer un secret dans Azure Key Vault. Au lieu de cela, vous pouvez utiliser {{ado}} ou {{ado://your-ado-organization-name}} comme paramètre. Ce paramètre extrait un jeton d’accès en votre nom quand vous créez une dev box. Le jeton d’accès dispose d’une autorisation en lecture seule sur votre référentiel.
La tâche git-clone du catalogue de démarrage rapide utilise le jeton d’accès pour cloner votre référentiel. Voici un exemple :
tasks:
name: git-clone
description: Clone this repository into C:\Workspaces
parameters:
repositoryUrl: https://myazdo.visualstudio.com/MyProject/_git/myrepo
directory: C:\Workspaces
pat: '{{ado://YOUR_ADO_ORG}}'
Votre Centre de développement a besoin d’accéder à votre coffre de clés. Les centres de développement ne prennent pas en charge les étiquettes de service. Par conséquent, si votre coffre de clés reste privé, vous devez autoriser les services Microsoft approuvés à contourner le pare-feu.
Pour savoir comment autoriser les services Microsoft approuvés à contourner le pare-feu, consultez Configurer les paramètres de mise en réseau Azure Key Vault.
Personnaliser votre dev box à l’aide de fichiers WinGet Configuration existants
WinGet Configuration adopte une approche de configuration en tant que code pour définir les ensembles uniques de logiciels et de paramètres de configuration nécessaires pour que votre environnement Windows soit dans un état « prêt à coder ». Vous pouvez également utiliser ces fichiers config pour configurer une dev box à l’aide d’une tâche WinGet incluse dans le catalogue de démarrage rapide fourni par Microsoft.
L’exemple suivant montre un fichier de personnalisation de dev box qui appelle un fichier DSC (Desired State Configuration) WinGet existant :
tasks:
- name: winget
parameters:
configure: "projectConfiguration.dsc.yaml"
Pour en savoir plus, consultez Configuration WinGet.
Partager un fichier de personnalisation depuis un référentiel de code
Mettez votre fichier de personnalisation à disposition des pools de dev box en le nommant imagedefinition.yaml et en le chargeant dans le référentiel qui héberge votre catalogue. Quand vous créez un pool de dev box, vous pouvez sélectionner dans le catalogue le fichier de personnalisation à appliquer aux dev box du pool.