Exploración y edición de archivos de plantilla de la CLI para desarrolladores de Azure

Una plantilla de la CLI para desarrolladores (azd) de Azure es un repositorio estándar con recursos de configuración e infraestructura que permiten azd aprovisionar e implementar un proyecto. Tanto si crea una nueva plantilla como si empieza a partir de una existente, es responsable de revisar y mantener sus archivos a medida que evoluciona el proyecto.

En este artículo se explica cómo inspeccionar y editar los archivos de plantilla principales. Para obtener una descripción conceptual de la estructura completa, consulte Azure plantillas de la CLI para desarrolladores.

En este artículo se usa la plantilla hello-azd como ejemplo estandarizado para que pueda ver lo que hace cada archivo en un proyecto real. Los mismos conceptos se aplican a las plantillas que genera para sus propias aplicaciones. Para continuar, inicialice la plantilla en un directorio vacío:

azd init --template hello-azd

La hello-azd plantilla implementa una aplicación de C# en contenedor para Azure Container Apps y aprovisiona los recursos de Azure auxiliares a través de Bicep. Usa una estructura de carpetas como la siguiente, donde cada recurso principal se asigna a una sección de este artículo:

.
├── azure.yaml                # Project configuration (Explore azure.yaml)
├── infra/                    # Infrastructure as code (Infrastructure files)
│   ├── main.bicep            # Deployment entry point
│   ├── main.parameters.json  # Parameter values that azd supplies
│   ├── abbreviations.json    # Resource name abbreviations
│   ├── app/                  # Application-specific modules
│   └── core/                 # Reusable resource modules
├── src/                      # Application source code (Source code)
│   └── Dockerfile            # Container image build for the app
├── .azure/                   # Environment configuration
└── README.md

La estructura exacta varía según el proyecto e azure.yaml identifica las rutas de acceso que azd usa. En las secciones siguientes se describe cómo editar cada recurso.

Antes de realizar cambios sustanciales, confirme o guarde una versión correcta conocida de la plantilla. Revise todos los cambios de credenciales incrustadas, recursos innecesarios, permisos excesivos, exposición de red, niveles de servicio y valores específicos del entorno.

Explorar azure.yaml

El azure.yaml archivo define el proyecto e indica azd cómo aprovisionar la infraestructura, el código de aplicación de paquete e implementar cada servicio. Puede definir servicios, configuraciones de infraestructura, enlaces, flujos de trabajo y otro comportamiento del proyecto.

La hello-azd plantilla define un único servicio denominado aca:

name: azd-starter
metadata:
  template: hello-azd-dotnet
services:
  aca:
    project: ./src
    language: csharp
    host: containerapp
    docker:
      path: ./Dockerfile
      remoteBuild: true

Cada propiedad indica azd cómo controlar el servicio:

• aca es el nombre del servicio. azdlo usa para hacer coincidir el servicio con el recurso Azure que lo hospeda. Para más información, consulte Configuración de la detección de servicios.
• project: ./src apunta al código fuente de la aplicación que azd empaqueta e implementa.
• language: csharp identifica el idioma de la aplicación.
• host: containerapp le indica a azd que implemente el servicio en Azure Container Apps.
• docker construye la imagen de contenedor a partir de Dockerfile en el directorio src.
• remoteBuildindica azd que use Azure Container Registry (ACR) para compilar la imagen de contenedor.

Adición de una definición de servicio

Agregue una entrada debajo de services para cada aplicación adicional que azd debe desplegar. Una definición de servicio especifica su directorio de origen, idioma y Azure destino de hospedaje. Por ejemplo, para describir un nuevo proyecto de API:

services:
  api:
    project: ./src/api
    language: csharp
    host: appservice

Cuando muevas el código de la aplicación, actualiza la project ruta correspondiente. Al cambiar la arquitectura de hospedaje, actualice la definición del servicio y la infraestructura que aprovisiona el host.

Para ver todas las propiedades disponibles y los valores admitidos, consulte el azure.yaml esquema.

Código fuente

El origen de la aplicación es opcional. Las plantillas con aplicaciones que se pueden implementar suelen organizar el código fuente en el src directorio, pero no es necesario usar un nombre o un diseño de carpeta específicos. La project propiedad de cada servicio de azure.yaml indica azd dónde reside su código fuente.

En hello-azd, el aca servicio establece project: ./src, por lo que azd empaqueta la aplicación de C# en el src directorio e la implementa en Azure Container Apps. Dado que el servicio también establece una configuración docker, azd crea la imagen del contenedor a partir de Dockerfile en el directorio src antes de la implementación.

azdadmite Node.js, Python, .NET, Java y Go en hosts de Azure compatibles. Una plantilla también puede implementar contenedores. Para conocer las combinaciones de lenguaje, marco y host actuales, consulte Idiomas y entornos admitidos.

Edite el código fuente como lo haría en cualquier repositorio de aplicaciones. Si agrega un servicio o mueve su directorio de origen, actualice su azure.yaml definición de servicio. Si la aplicación necesita un nuevo recurso de Azure, actualice la infraestructura y pase el nombre de recurso o punto de conexión necesario a la aplicación a través de la configuración.

Cambio de un directorio de origen de servicio

Por ejemplo, si mueve la hello-azd aplicación de src a src/app, actualice el project valor del aca servicio:

services:
  aca:
    project: ./src/app
    language: csharp
    host: containerapp
    docker:
      path: ./Dockerfile
      remoteBuild: true

Archivos de infraestructura

El infra directorio contiene los archivos Bicep o Terraform que definen los recursos de Azure para la plantilla. En hello-azd, el infra directorio usa Bicep e incluye los siguientes recursos clave:

• main.bicep es el punto de entrada estándar del despliegue que azd ejecuta para aprovisionar recursos.
• main.parameters.json proporciona los valores de parámetro para main.bicep.
• app contiene módulos específicos de la aplicación.
• core contiene módulos reutilizables para recursos comunes, como almacenamiento y hospedaje.

Cómo main.bicep se ejecuta durante azd up

Al ejecutar azd up, la fase de aprovisionamiento implementa infra/main.bicep. En hello-azd, main.bicep tiene como destino el ámbito de la suscripción, crea un grupo de recursos y, a continuación, llama a los módulos para aprovisionar los recursos que necesita la aplicación:

targetScope = 'subscription'

// Create a storage account
module storage './core/storage/storage-account.bicep' = {
  name: 'storage'
  scope: rg
  params: {
    name: !empty(storageAccountName) ? storageAccountName : '${abbrs.storageStorageAccounts}${resourceToken}'
    location: location
    tags: tags
    allowSharedKeyAccess: false
    containers: [ { name: 'attachments' } ]
    tables: [ { name: 'tickets' } ]
  }
}

// Container app for the 'aca' service
module web 'app/app.bicep' = {
  name: serviceName
  scope: rg
  params: {
    // ...
    serviceName: serviceName
  }
}

El main.bicep archivo aprovisiona una identidad administrada asignada por el usuario, una cuenta de Azure Storage, un entorno y un registro de Azure Container Apps, y la aplicación contenedora que hospeda el aca servicio. También asigna los roles que permiten que la identidad administrada acceda al almacenamiento. Los módulos mantienen cada recurso en su propio archivo, por lo que main.bicep permanece legible.

Agregar un recurso a main.bicep

Agregue declaraciones de recursos directamente a infra/main.bicep para recursos simples o únicos. Separe los recursos en módulos de Bicep independientes cuando vaya a reutilizarlos, cuando un recurso requiera varios recursos relacionados o cuando desee mantener la legibilidad de main.bicep. Al igual que hello-azd, muchas plantillas agrupan módulos reutilizables en infra/core.

Para los recursos de Azure comunes, prefiera un módulo comprobado Azure sobre la creación de un módulo desde cero. Los módulos validados reciben mantenimiento de Microsoft, siguen las prácticas recomendadas de seguridad y fiabilidad, y reducen la cantidad de código de infraestructura que debe mantener en la plantilla.

Para ver un tutorial completo que agrega un nuevo recurso a hello-azd, consulte Extensión de una plantilla.

El archivo main.parameters.json asigna a los parámetros de Bicep los valores que mantiene azd. La hello-azd plantilla usa los parámetros siguientes:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "environmentName": { "value": "${AZURE_ENV_NAME}" },
    "location": { "value": "${AZURE_LOCATION}" },
    "principalId": { "value": "${AZURE_PRINCIPAL_ID}" },
    "principalType": { "value": "${AZURE_PRINCIPAL_TYPE=User}" }
  }
}

Cada entrada vincula un parámetro de Bicep a un valor que azd mantiene en el entorno, como el nombre del entorno, la ubicación y la identidad que realiza la implementación. Use main.parameters.json para los valores que varían según el entorno o la implementación, como el nombre del entorno, la ubicación o los nombres de recursos que azd genera. Mantenga los valores estables que no cambien entre entornos como valores predeterminados de parámetros o literales en main.bicep. Este enfoque permite reutilizar la misma plantilla de Bicep en distintos entornos sin tener que editarla para cada despliegue.

Al agregar o editar la infraestructura:

• Mantenga el entorno de configuración de recursos independiente. Use parámetros y azd valores de entorno en lugar de insertar identificadores de suscripción, nombres de recursos, ubicaciones o credenciales.
• Use salidas seguras para valores sensibles y no exponga secretos como salidas de implementación en texto sin formato.
• Aplique asignaciones de roles con privilegios mínimos a identidades administradas.
• Mantenga las definiciones de servicio azure.yaml alineadas con los recursos a los que se dirigen.
• Revise los efectos de los niveles de servicio, los límites de escalado, la redundancia y la configuración de retención sobre el costo.

Para obtener orientación sobre el lenguaje Bicep y los módulos, consulte la documentación de Bicep. Para obtener plantillas basadas en Terraform, consulte Uso de Terraform con Azure CLI para desarrolladores.

Configurar detección de servicios

De forma predeterminada, azd detecta el recurso de Azure para un servicio mediante la búsqueda del recurso cuya azd-service-name etiqueta coincide con el nombre del servicio en azure.yaml. Si cambia el nombre de un servicio, actualice la etiqueta de recurso correspondiente o configure explícitamente el nombre del recurso en azure.yaml.

Por ejemplo, en hello-azd el nombre del aca servicio coincide con la azd-service-name etiqueta en el recurso de la aplicación contenedora. La azure.yaml definición de servicio establece el nombre:

services:
  aca:
    project: ./src
    language: csharp
    host: containerapp

El módulo de la aplicación contenedora de infra/app/app.bicep aplica la etiqueta coincidente:

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

Configure una ruta de infraestructura no estándar

La sección infra de azure.yaml identifica el proveedor de infraestructura y el punto de entrada. Estos valores son opcionales cuando se usa el diseño de Bicep predeterminado, pero declararlos pueden facilitar la comprensión de un diseño no estándar:

infra:
  provider: bicep
  path: infra
  module: main

Configuración de entorno

El .azure directorio contiene el estado del entorno local y los valores que azd crea, como la suscripción seleccionada, la ubicación, los nombres de recursos y las salidas de implementación. 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.

Adición de salidas de infraestructura

Al ejecutar azd provision para desplegar Bicep, se recogen los valores de salida del punto de entrada de la infraestructura como valores de entorno de azd. Agregue salidas para los puntos de conexión de recursos, los nombres de recursos y los identificadores de cliente de identidad administrada que necesitan los servicios de aplicación o los enlaces. Por ejemplo, hello-azd genera los detalles del registro de contenedor y la identidad administrada de main.bicep:

output AZURE_CONTAINER_REGISTRY_ENDPOINT string = containerAppsEnv.outputs.registryLoginServer
output AZURE_CONTAINER_REGISTRY_NAME string = containerAppsEnv.outputs.registryName
output AZURE_USER_ASSIGNED_IDENTITY_NAME string = identity.outputs.name

No genera secretos cuando una identidad administrada o una referencia de Key Vault pueden proporcionar acceso en su lugar. Después del aprovisionamiento, inspeccione los valores capturados ejecutando azd env get-values.

Para obtener más información, consulte Administración de variables de entorno.

Pruebe sus cambios

Ejecute azd up para aprovisionar la infraestructura e implementar cualquier servicio de aplicación:

azd up

Si piensa compartir la plantilla, inicialícela en un directorio limpio e impleméntela con un nuevo entorno. Esta prueba ayuda a identificar archivos locales, valores almacenados en caché o suposiciones específicas del entorno que no forman parte de la plantilla.

Contenido relacionado

• Información general sobre el desarrollo de plantillas
• Empezar con una nueva plantilla
• Inicio desde una plantilla existente
• Extensión de una plantilla
• Explore el azd up flujo de trabajo

Solicitar ayuda

Para obtener información sobre cómo archivar un error, solicitar ayuda o proponer una nueva característica para la CLI para desarrolladores de Azure, visite la página troubleshooting and support.