Introducción a las plantillas de la CLI para desarrolladores de Azure

Una plantilla de Azure Developer CLI (azd) es un repositorio de código que sigue las convenciones de azd. Combina la configuración del proyecto, la infraestructura como código y el origen de la aplicación opcional para que pueda crear entornos e implementaciones repetibles Azure.

Las plantillas pueden admitir diferentes tipos de proyecto, entre los que se incluyen:

• Una aplicación completa con uno o varios servicios implementables.
• Una solución solo de infraestructura sin código de aplicación.
• Un punto de partida reutilizable que otro desarrollador puede inicializar y extender.
• Un proyecto existente que se prepara para el aprovisionamiento y la implementación con azd.

En este artículo se explica la estructura de una plantilla y cómo azd los comandos usan sus archivos.

¿Por qué usar una plantilla?

Una plantilla captura las decisiones necesarias para ejecutar un proyecto en Azure. En función del proyecto, puede definir:

• Azure recursos y su configuración.
• Servicios de aplicación desplegables e instrucciones de empaquetado.
• Conexiones entre los servicios de aplicación y los recursos de Azure.
• Parámetros y salidas específicos del entorno.
• Desarrollo local, integración continua y configuración de entrega continua.

Dado que la configuración se almacena con el proyecto, los equipos pueden revisar los cambios en el control de código fuente y crear entornos de desarrollo, pruebas y producción coherentes.

Cómo azd usa una plantilla

Los archivos de una plantilla admiten diferentes fases del azd flujo de trabajo:

• azd init inicializa el proyecto y crea un azd entorno. También puede usar GitHub Copilot para generar una plantilla inicial o copiar una plantilla existente.
• azd provisionevalúa las definiciones de infraestructura y crea o actualiza Azure recursos.
• azd package prepara los servicios de aplicación que se pueden implementar según azure.yaml.
• azd deployasocia cada servicio con su host de Azure e implementa el paquete de aplicación.
• azd up ejecuta las fases de aprovisionamiento, empaquetado e implementación como un flujo de trabajo combinado.

Los archivos de plantilla siguen siendo archivos de origen normales a lo largo de este proceso. Puede revisarlos, editarlos y controlar sus versiones con el resto del proyecto.

Exploración de la estructura de plantillas de la CLI para desarrolladores de Azure

azd las plantillas son repositorios de código estándar con recursos adicionales de configuración e infraestructura. La mayoría de las plantillas usan la estructura siguiente:

• azure.yaml archivo - Define el proyecto y asocia los directorios de código fuente desplegables a recursos de Azure.
• infra folder - Contiene los archivos de infraestructura como código de Bicep o Terraform con los que se crean los recursos de Azure.
• src folder : normalmente contiene código fuente de la aplicación que se puede implementar. Las plantillas solo de infraestructura pueden omitir el origen de la aplicación y las plantillas de aplicación pueden usar otros nombres de directorio de origen.
• .azure folder : contiene entornos locales y valores creados por azd. Esta carpeta es el estado del proyecto local y normalmente no se comparte como parte de una plantilla reutilizable.

Por ejemplo, una plantilla común azd podría coincidir con la siguiente estructura de carpetas:

contoso-project/
├── azure.yaml                 # azd project and service configuration
├── infra/
│   ├── main.bicep            # Infrastructure entry point
│   └── main.parameters.json  # Maps azd values to Bicep parameters
├── src/                      # Optional application source
│   ├── api/
│   └── web/
├── .github/workflows/        # Optional GitHub Actions pipelines
└── .azure/                   # Local environment state; don't distribute

azd Las plantillas también incluyen opcionalmente una o varias de las siguientes carpetas:

• .github carpeta: contiene archivos de flujo de trabajo de CI/CD para Acciones de GitHub.
• .azdo folder : si decide usar Azure Pipelines para CI/CD, defina los archivos de configuración de flujo de trabajo de esta carpeta.
• .devcontainer folder : define un entorno de contenedor de desarrollo para el proyecto.

En el diagrama siguiente se muestra cómo funcionan juntos los recursos de plantilla principal:

flowchart LR
AZ[azure.yaml] -->|Defines services| SRC[Application source]
AZ -->|Selects provider and path| INFRA[Infrastructure as code]
INFRA -->|Provisions| RES[Azure resources]
INFRA -->|Exports values| ENV[azd environment]
ENV -->|Configures| SRC
AZ -->|Maps services to| RES

Recursos obligatorios y opcionales

La estructura exacta varía según el proyecto, pero la mayoría de las plantillas usan los siguientes recursos.

azure.yaml

El azure.yaml archivo es el archivo de configuración del proyecto principal. Define el nombre del proyecto y puede definir servicios implementables, proveedores de infraestructura, enlaces, flujos de trabajo y otro azd comportamiento.

Para un servicio de aplicación, azure.yaml normalmente identifica:

• Ruta de acceso al origen de la aplicación.
• El lenguaje de programación o la estrategia de empaquetado.
• El servicio Azure que hospeda la aplicación.
• Compilación, implementación, contenedor o configuración de Kubernetes.

Las plantillas solo de infraestructura pueden omitir los servicios de aplicación. Para obtener el modelo de configuración completo, consulte el azure.yaml esquema.

En el ejemplo siguiente se definen dos servicios de aplicación. Los nombres de servicio, las rutas de acceso de origen, los idiomas y los destinos de hospedaje indican azd qué empaquetar y dónde implementarlo:

name: store
services:
  api:
    project: ./src/api
    language: js
    host: containerapp
  web:
    project: ./src/web
    language: js
    host: staticwebapp

Infraestructura como código

La mayoría de las plantillas contienen un infra directorio con archivos Bicep o Terraform. Estos archivos definen los recursos de Azure, las asignaciones de roles, las redes, la configuración de la aplicación y las salidas de implementación necesarias para el proyecto.

Para el proveedor de Bicep predeterminado, azd normalmente usa infra/main.bicep como punto de entrada para la implementación y infra/main.parameters.json para asignar los valores de entorno de azd a parámetros de Bicep. Las plantillas de Terraform suelen usar infra/main.tf y los archivos de Terraform relacionados.

Por ejemplo, un archivo de parámetros de Bicep puede pasar valores seleccionados por azd en la implementación de la infraestructura:

{
  "parameters": {
    "environmentName": { "value": "${AZURE_ENV_NAME}" },
    "location": { "value": "${AZURE_LOCATION}" }
  }
}

Cuando finaliza el aprovisionamiento de Bicep, azd almacena las salidas del punto de entrada como valores de entorno. Los servicios de aplicación y los enlaces pueden usar estos valores para los puntos de conexión de recursos, los nombres y otra configuración en tiempo de ejecución.

output API_ENDPOINT string = api.outputs.uri

Origen de la aplicación

El origen de la aplicación es opcional. Cuando una plantilla contiene servicios desplegables, cada definición de servicio de azure.yaml apunta al directorio de origen correspondiente. Una plantilla puede organizar los servicios en src, usar directorios en otro lugar del repositorio o apuntar un servicio en la raíz del repositorio.

El propio nombre de carpeta no es significativo. El valor de project en azure.yaml determina dónde azd encuentra cada servicio.

Configuración de entorno

El .azure directorio contiene el estado del entorno local y los valores creados por azd. Puede contener valores de salida de suscripción, ubicación, nombre de recurso, punto de conexión e implementación para varios entornos.

Trate este directorio como estado local en lugar de un recurso de plantilla reutilizable. No confirme los archivos de entorno que contienen secretos o valores específicos del entorno.

Recursos auxiliares

Las plantillas también pueden contener:

• definiciones de Acciones de GitHub o Azure Pipelines.
• Dockerfiles y configuración del contenedor.
• Configuración del contenedor de desarrollo.
• Enlaces de comando y servicio.
• Pruebas, scripts y documentación del proyecto.

Estos recursos son opcionales y solo deben incluirse cuando admiten la experiencia de plantilla prevista.

Asociación de servicios y recursos

Para implementar un servicio de aplicación, azd debe asociar su definición a azure.yaml un recurso Azure aprovisionado. De forma predeterminada, azd busca un recurso cuya azd-service-name etiqueta coincide con el nombre del servicio.

Por ejemplo, un servicio denominado api se corresponde con un recurso etiquetado con azd-service-name: api. En su lugar, puede usar la resourceName propiedad de servicio para identificar explícitamente el destino de implementación.

La siguiente expresión Bicep agrega la etiqueta de detección a las etiquetas existentes de un recurso:

tags: union(tags, {
  'azd-service-name': 'api'
})

Mantenga alineados los nombres de servicio, la configuración de detección de recursos, las salidas de infraestructura y las variables de entorno de aplicación al editar una plantilla.

Compilación o adaptación de una plantilla

La experiencia de creación recomendada es ejecutar azd init y seleccionar Configurar con GitHub Copilot (versión preliminar). La sesión de agente de Copilot dedicada puede analizar los archivos existentes, ayudar a planear un nuevo proyecto, generar recursos de plantilla y validar el resultado. Para este flujo de trabajo y otros métodos de creación, consulte Inicio con una nueva plantilla.

Los archivos generados no están vinculados a Copilot. Puede explorar y editar los archivos de plantilla directamente después de la inicialización. También puede crear los mismos archivos manualmente o con otro agente de codificación de IA.

Si una plantilla de Microsoft, su organización o la comunidad de desarrolladores ya proporcionan una arquitectura útil, empiece por la plantilla existente y adáptelo para el proyecto. Examine las plantillas disponibles en las galerías de plantillas.

Directrices de uso de plantillas

Cada plantilla tiene licencia de su propietario bajo el contrato que acompaña a la plantilla. Determine qué licencia se aplica antes de usar o distribuir una plantilla.

Microsoft no se hace responsable de las plantillas ajenas a Microsoft y no las examina para detectar problemas de seguridad, privacidad, compatibilidad o rendimiento. Las plantillas, incluidas las plantillas proporcionadas por Microsoft, no son compatibles con un programa o servicio de soporte técnico de Microsoft y se proporcionan tal cual sin garantía.

Revise todos los archivos de plantilla antes del aprovisionamiento. En concreto, evalúe las asignaciones de roles, la exposición de red, los métodos de autenticación, los niveles de servicio, las ubicaciones de recursos y los costos esperados.

Pasos siguientes