Escribir un archivo de personalización para Dev Box
En este artículo, aprenderá a crear y probar un archivo de personalización para el equipo de desarrollo mediante Visual Studio Code y Dev Home.
Hay dos maneras de usar un archivo de personalización: personalizaciones de equipo que se aplican automáticamente una vez configuradas en un grupo y personalizaciones individuales que se aplican cuando un usuario crea un equipo de desarrollo.
Este artículo le ayuda a definir nuevas tareas en el archivo de personalización, aplicarlas a los equipo de desarrollo y probar estas personalizaciones directamente en Visual Studio Code.
Importante
Las personalizaciones del equipo de Dev Box se encuentran actualmente en VERSIÓN PRELIMINAR. Para obtener más información sobre el estado de la versión preliminar, vea los Términos de uso complementarios para las versiones preliminares de Microsoft Azure. El documento define los términos legales que se aplican a las características de Azure que se encuentran en versión beta, versión preliminar o aún no se han publicado en disponibilidad general.
Requisitos previos
Para completar los pasos de este artículo, debe:
- Tener un centro de desarrollo configurado con una definición de cuadro de desarrollo, un grupo de cuadros de desarrollo y un proyecto de cuadro de desarrollo configurado para poder crear un cuadro de desarrollo.
- Ser miembro del grupo de seguridad Usuarios de Dev Box para al menos un proyecto.
- Tener un catálogo adjunto al centro de desarrollo con tareas que puede usar en el archivo de personalización.
- Si no tiene un catálogo, consulte Agregar y configurar un catálogo desde GitHub o Azure Repos.
Permisos necesarios para configurar personalizaciones
Para realizar las acciones necesarias para crear y aplicar personalizaciones a un equipo de desarrollo, necesita determinados permisos. En la tabla siguiente, se describen las acciones y los permisos o roles que necesita para configurar las personalizaciones.
| Action | Permiso / Rol |
|---|---|
| Habilitar catálogos a nivel de proyecto para un centro de desarrollo | Ingeniero de plataforma con acceso de escritura en la suscripción. |
| Habilitar la configuración de sincronización del catálogo para un proyecto | Ingeniero de plataforma con acceso de escritura en la suscripción. |
| Adjuntar un catálogo a un proyecto | Permisos de administrador o colaborador del proyecto. |
| Crear un archivo de personalización | Cualquier persona puede crear un archivo de personalización. |
| Uso del portal para desarrolladores para cargar y aplicar un archivo YAML durante la creación del equipo de desarrollo | Usuario de Dev Box |
| Agregar tareas a un catálogo | Permiso para agregar al repositorio que hospeda el catálogo. |
¿Qué es un archivo de personalización?
Las personalizaciones de Dev Box usan un archivo con formato yaml para especificar una lista de tareas que se aplicarán al crear un nuevo equipo de desarrollo. Estas tareas pueden ser tan sencillas como instalar un paquete o tan sofisticadas como ejecutar un complejo conjunto de scripts para configurar una base de código. Las tareas identifican la tarea de catálogo y proporcionan parámetros como el nombre del software que se va a instalar. A continuación, el archivo de personalización está disponible para los desarrolladores que crean nuevos equipos de desarrollo.
El siguiente ejemplo utiliza una tarea winget para instalar Visual Studio Code, y una tarea git clone para clonar un repositorio.
# 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
Hay dos formas de utilizar un archivo de personalización: personalizaciones individuales que se aplican a un único equipo de desarrollo, y personalizaciones de equipo que se aplican a todo un equipo.
Archivos de personalización individuales
- Contienen tareas que se aplican cuando se crea un equipo de desarrollo.
- Cargado por el desarrollador cuando crean un equipo de desarrollo.
Archivos de personalización de equipo
- Contienen tareas que se aplican cuando se crea un equipo de desarrollo.
- Se comparten en un equipo o proyecto.
- Incluya un campo que especifique la imagen base.
- Se denominan imagedefinition.yaml.
- Se cargan en el repositorio que hospeda el catálogo.
- Se usan automáticamente al crear un equipo de desarrollo a partir de un grupo configurado.
Importante
Las definiciones de imágenes solo pueden usar imágenes de marketplace de Dev Box como imágenes base. Para obtener una lista de las imágenes a las que tiene acceso su DevCenter, utilice este comando az cli:
az devcenter admin image list --dev-center-name CustomizationsImagingHQ --resource-group TeamCustomizationsImagingRG --query "[].name"
Crear un archivo de personalización
Puede crear y administrar archivos de personalización con Visual Studio Code. Puede usar la extensión de Visual Studio Code de Microsoft Dev Box para detectar las tareas del catálogo adjunto y probar el archivo de personalización en Visual Studio Code.
Cree una instancia de Dev Box (o use una instancia de Dev Box existente) para realizar pruebas.
En el equipo de desarrollo de prueba, instale Visual Studio Code y luego instale la extensión de VS Code de Dev Box.
Descargue un archivo de personalización yaml de ejemplo del repositorio de muestras y ábralo en Visual Studio Code.
Descubra las tareas disponibles en el catálogo mediante la paleta de comandos. En Ver>Paleta de comandos, seleccione Dev Box: enumerar las tareas disponibles para este equipo de desarrollo.
Pruebe la personalización en Visual Studio Code mediante f5/paleta de comandos. En Ver>Paleta de comandos, seleccione Dev Box: aplicar tareas de personalización.
El archivo de personalización se ejecuta inmediatamente, aplicando las tareas especificadas al cuadro de desarrollo de prueba. Inspeccione los cambios y compruebe el terminal de Visual Studio Code en busca de errores o advertencias generados durante la ejecución de la tarea.
Cuando el archivo de personalización se ejecute correctamente, cárguelo en el catálogo.
Clonar un repositorio privado utilizando un archivo de personalización
Puede usar secretos de Azure Key Vault en las personalizaciones de yaml para clonar repositorios privados o con cualquier tarea personalizada que cree que requiera un token de acceso. En un archivo de personalización de equipo, puede usar un token de acceso personal (PAT) almacenado en un almacén de claves para acceder a un repositorio privado. git
Utilizar secretos de Key Vault en los archivos de personalización del equipo
Para clonar un repositorio privado, almacene su PAT como un secreto de Azure KeyVault, y utilícelo cuando invoque la tarea git-clone en su personalización.
Para configurar los secretos de Key Vault para usarlos en las personalizaciones de yaml:
- Asegúrese de que la identidad administrada del proyecto del centro de desarrollo tenga el rol Lector de Key Vault y el rol de usuario secretos de Key Vault en el almacén de claves.
- Conceda el rol de usuario de Secretos para el secreto de Key Vault a cada usuario o grupo de usuarios que debería poder consumir el secreto durante la personalización de un equipo de desarrollo. El usuario o grupo al que se le ha concedido el rol debe incluir la identidad administrada para el centro de desarrollo, su propia cuenta de usuario y cualquier usuario o grupo que necesite el secreto durante la personalización de un equipo de desarrollo.
Para más información, vea:
- Obtener más información sobre la configuración de una identidad administrada para un centro de desarrollo.
- Obtener más información sobre la Concesión a la identidad administrada de acceso al secreto del almacén de claves.
Puede hacer referencia al secreto en la personalización de yaml con el siguiente formato, mediante la tarea git-clone como ejemplo:
$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}}'
Uso de secretos de Key Vault en archivos de personalización individuales
Si desea clonar un repositorio privado de Azure Repos desde un archivo de personalización individual, no es necesario configurar un secreto en Key Vault. En su lugar, puede usar {{ado}}o {{ado://your-ado-organization-name}} como parámetro. Esto captura un token de acceso en su nombre al crear un equipo de desarrollo, que tiene permiso de solo lectura para el repositorio. La tarea git-clone del catálogo de inicio rápido usa el token de acceso para clonar el repositorio. Este es un ejemplo:
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}}'
El centro de desarrollo necesita acceso al almacén de claves. DevCenter no admite etiquetas de servicio, por lo que si el almacén de claves se mantiene privado, debe permitir que los servicios de Microsoft de confianza omitan el firewall.
Para saber cómo permitir que los servicios de confianza de Microsoft eviten el firewall, consulte Configuración de red de Azure Key Vault.
Personalizar el cuadro de desarrollo mediante archivos de configuración de WinGet existentes
La configuración WinGet adopta un enfoque de configuración como código para definir los conjuntos únicos de software y ajustes de configuración necesarios para obtener su entorno Windows en un estado listo para el código. Estos archivos de configuración también se pueden usar para configurar un Dev Box, mediante una tarea WinGet incluida en el catálogo de inicio rápido proporcionado por Microsoft mencionado anteriormente. En el siguiente ejemplo se muestra un archivo de personalización de equipo de desarrollo que llama a un archivo WinGet Desired State Configuration (DSC) existente.
tasks:
- name: winget
parameters:
configure: "projectConfiguration.dsc.yaml"
Para obtener más información sobre la configuración de WinGet, consulte Configuración de WinGet.
Uso compartido de un archivo de personalización desde un repositorio de código
Haga que el archivo de personalización esté disponible para los grupos de equipo de desarrollo al asignarle el nombre imagedefinition.yaml y cargarlo en el repositorio que hospeda el catálogo. Al crear un grupo de equipo de desarrollo, puede seleccionar el archivo de personalización del catálogo que se aplicará a los equipo de desarrollo del grupo.