Aprovisionamiento en capas

La CLI para desarrolladores de Azure (azd) admite el aprovisionamiento en capas, que puede usar para definir varias capas de aprovisionamiento en el azure.yaml archivo. Cada capa apunta a su propio conjunto de plantillas de infraestructura como código (IaC). La CLI aprovisiona capas una a la vez, ordenadas por las dependencias entre ellas. También puede aprovisionar o desmontar capas individuales de forma independiente.

Esta característica resuelve escenarios de dependencia complejos en los que los recursos de una capa dependen de los recursos de otra capa. En lugar de mezclar IaC con scripts de conexión imperativos, el aprovisionamiento en capas mantiene todo de manera declarativa.

Nota:

El aprovisionamiento en capas es actualmente una característica beta. Obtenga más información sobre la estrategia de control de versiones.

Cuándo usar el aprovisionamiento en capas

Use el aprovisionamiento en capas cuando una sola azd provision implementación no pueda controlar todas las necesidades de infraestructura en un solo paso. Considere la posibilidad de usar el aprovisionamiento por capas cuando:

  • Dependencias circulares: algunos recursos deben hacer referencia a otros recursos que se deben crear primero, como una red virtual que debe existir antes de que se pueda configurar un punto de conexión privado.
  • La infraestructura básica difiere de la infraestructura de la aplicación: se administran los recursos de red, seguridad o identidad compartidos por separado de los recursos por aplicación.
  • Se necesita la administración del ciclo de vida independiente: se actualizan y desmonta distintos componentes de infraestructura en momentos diferentes. Por ejemplo, una capa de red puede ser de larga duración, mientras que una capa de aplicación se vuelve a implementar con frecuencia.
  • Proyectos de Monorepo con distintos grupos de infraestructura: un único repositorio contiene varios servicios independientes (como un centro de eventos, una aplicación de contenedor y una aplicación de funciones), cada uno con sus propias plantillas de infraestructura.

Configuración de capas en azure.yaml

Definir capas en la sección infra de tu archivo azure.yaml. Cada capa requiere un name y un path que apunten al directorio que contiene las plantillas de IaC para esa capa.

name: my-app
infra:
  layers:
    - name: networking
      path: ./infra/networking
    - name: application
      path: ./infra/application
services:
  api:
    project: ./src/api
    language: js
    host: containerapp

Importante

Orden de procesamiento de capas:azd provision procesa las capas en función de sus dependencias. En el caso de las capas de Bicep y de los proveedores personalizados o de extensión, azd infiere las dependencias al examinar los archivos de parámetros (*.bicepparam y *.parameters.json) en busca de referencias a variables de entorno y a salidas de capas, y ordena las capas en consecuencia en lugar de seguir estrictamente el orden que aparece en azure.yaml. Las capas que no tienen dependencias inferidas o declaradas se ejecutan en el orden en que se muestran. azd down sigue el orden inverso correspondiente, por lo que las capas dependientes se quitan antes de las capas de las que dependen. Usa la propiedad dependsOn para declarar el orden que azd no puede inferir.

Propiedades de capa

Cada capa admite las siguientes propiedades:

Propiedad Obligatorio Description
name Sí Un nombre único para la capa. Use este nombre al dirigirse a una capa específica con comandos.
path Sí Ruta de acceso relativa al directorio que contiene las plantillas de IaC para esta capa.
module No Nombre del módulo dentro del directorio de la capa. Tiene como valor predeterminado main.
provider No Proveedor de IaC para esta capa (bicep o terraform). Hereda de la raíz infra.provider si no se especifica.
dependsOn No Los nombres de otras capas de las que depende esta capa. Use esta propiedad cuando el orden sea importante, pero azd no pueda deducir la dependencia a partir de las referencias de parámetros.

Importante

Al definir infra.layers, no puede declarar otras propiedades en la infra sección (path, module, deploymentStacks) en el nivel raíz. Debe especificar toda la configuración de infraestructura dentro de cada capa.

Estructura de directorios

Un proyecto típico que usa el aprovisionamiento por capas podría tener la siguiente estructura de directorios:

my-app/
├── azure.yaml
├── infra/
│   ├── networking/
│   │   └── main.bicep
│   └── application/
│       └── main.bicep
└── src/
    └── api/
        └── ...

Cada directorio de capas contiene su propio conjunto completo de plantillas de IaC, como lo haría el directorio de azd un proyecto estándarinfra.

Aprovisionamiento y administración de capas

Puede aprovisionar todas las capas a la vez o dirigirse a una capa específica por nombre. En las secciones siguientes se describen los comandos comunes para el aprovisionamiento, la desmontaje y la actualización del estado de la capa.

Aprovisionar todas las capas

Ejecute azd provision sin argumentos para aprovisionar todas las capas:

azd provision

azd procesa cada capa una a la vez, asegurándose de que una capa se completa antes de que se inicie cualquier capa que dependa de ella. Para las capas de Bicep y los proveedores personalizados o de extensiones, azd infiere las dependencias a partir de las referencias a variables de entorno y a salidas de capas en los archivos *.bicepparam y *.parameters.json, por lo que el orden de ejecución puede diferir del orden enumerado en azure.yaml. Las capas sin dependencias inferidas o declaradas se ejecutan en el orden indicado. Este proceso garantiza que existen recursos dependientes antes de que se implementen capas que hagan referencia a ellos.

Aprovisionamiento de una capa específica

Para aprovisionar solo una capa específica, pase el nombre de la capa como argumento:

azd provision networking

Este comando implementa solo los recursos definidos en la networking capa. El aprovisionamiento de una capa específica es útil cuando:

  • Usted está iterando en una sola capa durante el desarrollo de software.
  • Debe actualizar una capa sin volver a implementar otras.
  • Va a configurar una nueva capa sobre la infraestructura existente.

Desmontar todas las capas

Ejecute azd down sin argumentos para anular los recursos de todas las capas. Cuando existen varias capas, azd las procesa en la inversa del orden de aprovisionamiento, por lo que los recursos dependientes se quitan antes de los recursos fundamentales de los que dependen:

azd down

Desmontar una capa específica

Para anular solo una capa específica, pase el nombre de la capa como argumento:

azd down application

Este comando quita solo los recursos implementados por la application capa, dejando intactos los demás niveles.

Actualizar el estado del entorno

Puede actualizar el estado del entorno desde una capa específica mediante el flag --layer con azd env refresh:

azd env refresh --layer networking

Este comando actualiza las variables de entorno y las salidas en función de la implementación más reciente de la capa especificada.

Ejemplo: Monorepo con varios servicios

En el ejemplo siguiente se muestra el aprovisionamiento en capas de un monorepo que contiene un centro de eventos, una aplicación contenedora que ejecuta varios contenedores y una aplicación de funciones de Azure:

name: logging-app
infra:
  layers:
    - name: eventhub
      path: ./infra/eventhub
    - name: aca
      path: ./infra/aca
    - name: functionapp
      path: ./infra/functionapp
services:
  functionapp:
    resourceName: ${site_name}
    language: dotnet
    project: ./src/function/functionapp.csproj
    host: appservice
    resourceGroup: ${rg_name}

La estructura de directorios correspondiente:

logging-app/
├── azure.yaml
├── infra/
│   ├── eventhub/
│   │   └── main.bicep
│   ├── aca/
│   │   └── main.bicep
│   └── functionapp/
│       └── main.bicep
└── src/
    └── function/
        └── functionapp.csproj

Con esta configuración, puede:

  1. Aprovisione solo la infraestructura de Event Hub: azd provision eventhub
  2. Aprovisione solo la infraestructura de Container App: azd provision aca
  3. Aprovisione todo en orden: azd provision
  4. Desmontar solo la capa de Function App: azd down functionapp

Ejemplo: Capas base y de aplicación

Un patrón común separa la infraestructura compartida o fundamental de la infraestructura por aplicación:

name: my-app
infra:
  layers:
    - name: base
      path: ./infra/base
    - name: app
      path: ./infra/app
services:
  web:
    project: ./src/web
    language: js
    host: containerapp

La base capa crea recursos compartidos como redes, identidades y supervisión. La app capa crea los recursos específicos de la aplicación (como un entorno de aplicación contenedora y las aplicaciones de contenedor) que hacen referencia a los recursos base.

Durante el desarrollo, podrías aprovisionar la capa base una vez e iterar sobre la capa de aplicación.

azd provision base
azd provision app
azd provision app  # re-provision only the app layer after changes

Ejemplo: Proveedores de IaC mixtos

Cada capa puede usar un proveedor iaC diferente. Por ejemplo, puede usar Bicep para redes y Terraform para la capa de aplicación:

name: my-app
infra:
  layers:
    - name: networking
      path: ./infra/networking
      provider: bicep
    - name: application
      path: ./infra/application
      provider: terraform

Los proveedores integrados que no son de Bicep (Terraform, Pulumi, ARM y el proveedor de pruebas) son opacos para la deducción de dependencias, porque azd no puede analizar sus entradas en busca de referencias a otras capas. Utilice una propiedad explícita de dependsOn siempre que el orden entre esas capas, o entre esas capas y otras capas, sea importante:

name: my-app
infra:
  layers:
    - name: networking
      path: ./infra/networking
      provider: bicep
    - name: application
      path: ./infra/application
      provider: terraform
      dependsOn:
        - networking

Consideraciones y limitaciones

  • Al aprovisionar todas las capas, azd las procesa una a la vez en función de sus dependencias. Para las capas de Bicep y los proveedores personalizados o de extensiones, azd infiere dependencias a partir de las referencias a variables de entorno y a las salidas de capa en los archivos *.bicepparam y *.parameters.json. Las capas sin dependencias inferidas o declaradas se ejecutan en el orden definido.
  • Los proveedores integrados distintos de Bicep (Terraform, Pulumi, ARM y el proveedor de pruebas) son opacos de cara a la inferencia de dependencias. Use una propiedad explícita dependsOn cuando importe el orden de esas capas.
  • También se requiere dependsOn explícito cuando el orden es importante, pero azd no puede inferir la dependencia a partir de las referencias a parámetros. Por ejemplo, use dependsOn cuando el enlace de postprovision una capa genere un valor que consume otra capa, ya que los valores generados por el enlace no aparecen como referencias de salida en *.bicepparam o *.parameters.json archivos.
  • Al desmontar todas las capas, azd las procesa en el orden inverso al de aprovisionamiento.
    • Si varias capas implementan recursos en el mismo grupo de recursos de Azure y usa el comportamiento de eliminación predeterminado basado en grupo de recursos, los recursos compartidos se pueden eliminar al ejecutar azd down.
    • Para permitir el seguimiento independiente y la eliminación de la infraestructura por capas, habilite las pilas de despliegue ejecutando el comando azd config set alpha.deployment.stacks on.
  • No puede usar la --preview marca al aprovisionar varias capas a la vez. Especifique un <layer> nombre para usar el modo de vista previa.
  • Las capas funcionan de forma independiente en términos de IaC. Para hacer referencia a las salidas de una capa en otra capa, use variables de entorno que azd establece tras la implementación de cada capa. Hacer referencia a esas variables de entorno desde un *.bicepparam archivo o *.parameters.json también permite azd deducir la ordenación entre las capas.
  • Todas las características de aprovisionamiento estándar azd (almacenamiento en caché de estado de implementación, enlaces, parámetros, Bicep o Terraform) funcionan dentro de cada capa individual.
    • Los enlaces de nivel de comando (por ejemplo, preprovision, postprovision) se invocan una vez por capa. Cuando se definen varias capas, los ganchos se ejecutan para cada capa en el orden en que se procesan.

Pasos siguientes

Referencia del esquema azure.yaml

  • Se actualizó por última vez el