Escritura de un archivo de personalización para un equipo de desarrollo
En este artículo, aprenderá a crear y probar un archivo de personalización para el equipo de desarrollo mediante Visual Studio Code (VS Code) y Dev Home.
Hay dos maneras de usar un archivo de personalización en Microsoft Dev Box. Las personalizaciones de equipo se aplican automáticamente cuando los desarrolladores los configuran en un grupo. Las personalizaciones individuales 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 VS Code.
Importante
La característica de personalizaciones de equipo de Dev Box está 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. En el documento se definen los términos legales que se aplican a las características de Azure que están en versión beta, en versión preliminar o que aún no se han publicado con disponibilidad general.
Requisitos previos
Para completar los pasos de este artículo, debe:
- Tener un centro de desarrollo configurado con una definición de equipo de desarrollo, un grupo de equipo de desarrollo y un proyecto de equipo de desarrollo 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
A fin de realizar las acciones necesarias para crear y aplicar personalizaciones a un equipo de desarrollo, necesita los permisos siguientes:
| Action | Permiso / Rol |
|---|---|
| Habilitación de catálogos de nivel de proyecto para un centro de desarrollo. | Ingeniero de plataforma con acceso de escritura en la suscripción. |
| Habilitación de la configuración de sincronización de catálogos 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. |
| Creación de un archivo de personalización. | No se ha especificado ninguno. Cualquier persona puede crear un archivo de personalización. |
| Use el portal para desarrolladores a fin de cargar y aplicar un archivo YAML durante la creación del equipo de desarrollo. | Usuario de Dev Box. |
| Agregue 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 cuando un desarrollador crea un 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 el 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 equipos de desarrollo.
En el ejemplo siguiente se usa una winget tarea para instalar VS Code y una git-clone tarea 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 maneras de usar un archivo de personalización: las personalizaciones individuales se aplican a un único cuadro de desarrollo y las personalizaciones de equipo se aplican a todo el equipo.
Archivos de personalización individuales
- Contienen tareas que se aplican cuando un desarrollador crea un cuadro de desarrollo.
- El desarrollador lo carga durante la creación de un cuadro de desarrollo.
Archivos de personalización de equipo
- Contienen tareas que se aplican cuando un desarrollador crea un cuadro 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 un catálogo.
- Se usan automáticamente cuando un desarrollador crea 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 imágenes a las que puede acceder el centro de desarrollo, use este comando de la CLI de Azure:
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 mediante VS Code. Puede usar la extensión Microsoft Dev Box en VS Code para detectar las tareas del catálogo adjunto y probar el archivo de personalización.
Cree una instancia de Dev Box (o use una instancia de Dev Box existente) para realizar pruebas.
En el cuadro de desarrollo de prueba, instale VS Code e instale la extensión Dev Box.
Descargue un archivo de personalización de YAML de ejemplo del repositorio de ejemplos y ábralo en VS Code.
Descubra las tareas disponibles en el catálogo mediante la paleta de comandos. Seleccione Ver> Paleta de comandos>Dev Box: enumerar tareas disponibles para este Dev Box.
Pruebe la personalización en VS Code mediante la paleta de comandos. En Ver>Paleta de comandos, seleccione >Dev Box: aplicar tareas de personalización.
El archivo de personalización se ejecuta inmediatamente y aplica las tareas especificadas al cuadro de desarrollo de prueba. Inspeccione los cambios y compruebe el terminal de VS 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.
Clonación de un repositorio privado mediante 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.
Utilizar secretos de Key Vault en los archivos de personalización del equipo
Para clonar un repositorio privado, almacene el PAT como un secreto del almacén de claves y úselo al invocar la git-clonetarea en la 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 secretos de Key Vault para el secreto del almacén de claves a cada usuario o grupo de usuarios que pueda consumir el secreto durante la personalización de un cuadro de desarrollo. El usuario o grupo al que se concede 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 cuadro de desarrollo.
Para más información, vea:
- Configuración de una identidad administrada para un centro de desarrollo
- 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 en el formato siguiente, que usa la git-clone tarea 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 quiere clonar un repositorio privado de Azure Repos desde un archivo de personalización individual, no es necesario configurar un secreto en Azure Key Vault. En su lugar, puede usar {{ado}} o {{ado://your-ado-organization-name}} como parámetro. Este parámetro captura un token de acceso en su nombre al crear un cuadro de desarrollo. El token de acceso 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. Los centros de desarrollo no admiten 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. También puede usar estos archivos de configuración para configurar un cuadro de desarrollo mediante una tarea WinGet incluida en el catálogo de inicio rápido proporcionado por Microsoft.
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 más información, consulte Configuración de WinGet.
Uso compartido de un archivo de personalización desde un repositorio de código
Para que el archivo de personalización esté disponible para los grupos de cuadros de desarrollo, asígnele el nombre imagedefinition.yaml y cárguelo 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.