Provisioning a più livelli

L'interfaccia della riga di comando per sviluppatori di Azure (azd) supporta il provisioning a più livelli, che è possibile usare per definire più livelli di provisioning nel azure.yaml file. Ogni livello punta al proprio set di modelli IaC (Infrastructure as Code). La CLI esegue il provisioning dei livelli uno alla volta, seguendo l'ordine determinato dalle dipendenze tra di essi. È anche possibile configurare o rimuovere singoli livelli in modo indipendente.

Questa funzionalità risolve scenari di dipendenza complessi in cui le risorse in un livello dipendono dalle risorse di un altro livello. Invece di combinare IaC con script hook imperativi, il provisioning a più livelli mantiene tutto dichiarativo.

Annotazioni

Il provisioning a più livelli è attualmente una funzionalità beta. Altre informazioni sulla strategia di controllo delle versioni.

Quando usare il provisioning a più livelli

Utilizza il provisioning a più livelli quando una singola azd provision distribuzione non può soddisfare tutte le esigenze dell'infrastruttura in un unico passaggio. È consigliabile usare il provisioning a più livelli quando:

  • Dipendenze circolari: alcune risorse devono fare riferimento ad altre risorse che devono essere create per prime, ad esempio una rete virtuale che deve esistere prima di poter configurare un endpoint privato.
  • L'infrastruttura di base è diversa dall'infrastruttura dell'applicazione: è possibile gestire le risorse di rete, sicurezza o identità condivise separatamente dalle risorse per ogni applicazione.
  • È necessaria la gestione indipendente del ciclo di vita: si aggiornano e si eliminano componenti dell'infrastruttura diversi in momenti diversi. Ad esempio, un livello di rete potrebbe essere di lunga durata, mentre un livello applicazione viene ridistribuito di frequente.
  • Progetti Monorepo con gruppi di infrastruttura distinti: un singolo repository contiene più servizi indipendenti (ad esempio un hub eventi, un'app contenitore e un'app per le funzioni), ognuno con i propri modelli di infrastruttura.

Configurare i livelli in azure.yaml

Definire i livelli nella infra sezione del azure.yaml file. Ogni livello richiede un name e un path puntatore alla directory che contiene i modelli IaC per tale livello.

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

Ordine di elaborazione dei livelli:azd provision elabora i livelli in base alle relative dipendenze. Per i layer Bicep e i provider personalizzati o di estensione, azd deduce automaticamente le dipendenze analizzando i file di parametri (*.bicepparam e *.parameters.json) alla ricerca di riferimenti a variabili di ambiente e output dei layer, e li ordina di conseguenza invece di seguire rigorosamente l'ordine indicato in azure.yaml. I livelli che non hanno dipendenze inferite o dichiarate vengono eseguiti nell'ordine in cui sono elencati. azd down segue l'ordine inverso corrispondente, quindi i livelli dipendenti vengono rimossi prima che i livelli da cui dipendono. Usare la dependsOn proprietà per dichiarare l'ordinamento che azd non può dedurre.

Proprietà livello

Ogni livello supporta le proprietà seguenti:

Proprietà Obbligatorio Descrzione
name Sì Nome univoco per il livello. Usare questo nome quando si prende di mira un livello specifico con i comandi.
path Sì Il percorso relativo alla directory contenente i template IaC per questo livello.
module NO Il nome del modulo nella directory del livello. Il valore predefinito è main.
provider NO Provider IaC per questo livello (bicep o terraform). Eredita dalla radice infra.provider se non viene specificata.
dependsOn NO Nomi di altri livelli da cui dipende questo livello. Usare questa proprietà quando l'ordinamento è importante, ma azd non può dedurre la dipendenza dai riferimenti ai parametri.

Importante

Quando si definisce infra.layers, non è possibile dichiarare altre proprietà nella infra sezione (path, module, deploymentStacks) a livello radice. È necessario specificare tutte le configurazioni dell'infrastruttura all'interno di ogni livello.

Struttura di directory

Un progetto tipico che usa il provisioning a più livelli potrebbe avere la struttura di directory seguente:

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

Ogni directory di livello contiene il proprio set completo di modelli IaC, proprio come farebbe la directory di azd un progetto standardinfra.

Eseguire la configurazione e gestire i livelli

È possibile effettuare il provisioning di tutti i livelli contemporaneamente o specificare un livello specifico in base al nome. Le sezioni seguenti descrivono i comandi comuni per il provisioning, la disinstallazione e l'aggiornamento dello stato del livello.

Effettuare il provisioning di tutti i livelli

Eseguire azd provision senza argomenti per effettuare il provisioning di tutti i livelli:

azd provision

azd elabora ogni livello uno alla volta, assicurandosi che un livello venga completato prima dell'inizio di qualsiasi livello che dipende da esso. Per i layer Bicep e i provider personalizzati o di estensione, azd deduce automaticamente le dipendenze dai riferimenti alle variabili di ambiente e all'output dei layer nei file *.bicepparam e *.parameters.json, pertanto l'ordine di esecuzione può differire dall'ordine elencato in azure.yaml. I livelli senza dipendenze inferite o dichiarate vengono elaborati nell'ordine elencato. Questo processo garantisce che le risorse dipendenti esistano prima che i livelli che vi facciano riferimento vengano distribuiti.

Eseguire il provisioning di un livello specifico

Per effettuare il provisioning solo di un livello specifico, passare il nome del livello come argomento:

azd provision networking

Questo comando distribuisce solo le risorse definite nel networking livello. La configurazione di un livello specifico è utile quando:

  • Stai iterando su un singolo layer durante lo sviluppo.
  • È necessario aggiornare un livello senza ridistribuire altri.
  • Si sta configurando un nuovo livello sopra l'infrastruttura esistente.

Smontare tutti i livelli

Eseguire azd down senza argomenti per eliminare le risorse da tutti i livelli. Quando esistono più livelli, azd li elabora inverso dell'ordine di provisioning, quindi le risorse dipendenti vengono rimosse prima delle risorse di base da cui dipendono:

azd down

Smontare un livello specifico

Per rimuovere solo un livello specifico, passare il nome del livello come argomento:

azd down application

Questo comando rimuove solo le risorse distribuite dal application livello, lasciando intatti gli altri livelli.

Aggiornare lo stato dell'ambiente

È possibile aggiornare lo stato dell'ambiente da un livello specifico usando il --layer flag con azd env refresh:

azd env refresh --layer networking

Questo comando aggiorna le variabili di ambiente e gli output in base alla distribuzione più recente del livello specificato.

Esempio: Monorepo con più servizi

L'esempio seguente illustra il provisioning a più livelli per un monorepo che contiene un hub eventi, un'app contenitore che esegue più contenitori e un'app per le funzioni di 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}

Struttura di directory corrispondente:

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

Con questa configurazione è possibile:

  1. Effettuare il provisioning solo dell'infrastruttura di Hub eventi: azd provision eventhub
  2. Eseguire il provisioning solo dell'infrastruttura dell'applicazione contenitore: azd provision aca
  3. Configurare tutti gli elementi nell'ordine corretto: azd provision
  4. Rimuovere solo il livello Function App: azd down functionapp

Esempio: Livelli di base e applicazione

Un modello comune separa l'infrastruttura condivisa o di base dall'infrastruttura per applicazione:

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

Il base livello crea risorse condivise come rete, identità e monitoraggio. Il app livello crea le risorse specifiche dell'applicazione, ad esempio un ambiente dell'app contenitore e le app contenitore, che fanno riferimento alle risorse di base.

Durante lo sviluppo, è possibile effettuare il provisioning del livello di base una sola volta ed eseguire l'iterazione sul livello dell'applicazione:

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

Esempio: Provider IaC misti

Ogni livello può usare un provider IaC diverso. Ad esempio, è possibile usare Bicep per la rete e Terraform per il livello dell'applicazione:

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

I provider non Bicep predefiniti (Terraform, Pulumi, ARM e il provider di test) non sono trasparenti all'inferenza delle dipendenze, perché azd non può analizzare i relativi input alla ricerca di riferimenti ad altri livelli. Usare una proprietà esplicita dependsOn ogni volta che si ordinano tra tali livelli o tra tali livelli e altri livelli, è importante:

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

Considerazioni e limitazioni

  • Quando si effettua il provisioning di tutti i livelli, azd li elabora uno alla volta in base alle relative dipendenze. Per i layer Bicep e i provider personalizzati o di estensione, azd deduce automaticamente le dipendenze dai riferimenti alle variabili di ambiente e agli output dei layer nei file *.bicepparam e *.parameters.json. I livelli senza dipendenze dedotti o dichiarati vengono eseguiti nell'ordine definito.
  • I provider integrati diversi da Bicep (Terraform, Pulumi, ARM e il provider di test) sono opachi ai fini dell'inferenza delle dipendenze. Usare una proprietà esplicita dependsOn quando si ordinano tali livelli è importante.
  • L'esplicito dependsOn è necessario anche quando l'ordine è importante, ma azd non può desumere la dipendenza dai riferimenti ai parametri. Ad esempio, usare dependsOn quando l'hook di postprovision un livello produce un valore utilizzato da un altro livello, perché i valori prodotti da hook non vengono visualizzati come riferimenti di output in *.bicepparam o *.parameters.json file.
  • Quando si eliminano tutti i livelli, azd li elabora nell'ordine inverso dell'ordine di provisioning.
    • Se più livelli distribuiscono le risorse nello stesso gruppo di risorse di Azure e si usa il comportamento di eliminazione predefinito basato su gruppo di risorse, le risorse condivise possono essere eliminate durante l'esecuzione di azd down.
    • Per consentire il rilevamento indipendente e l'eliminazione dell'infrastruttura a più livelli, abilitare gli stack di distribuzione eseguendo il comando azd config set alpha.deployment.stacks on.
  • Non è possibile usare il flag durante il --preview provisioning di più livelli contemporaneamente. Specificare un <layer> nome per usare la modalità di anteprima.
  • I livelli operano in modo indipendente in termini di IaC. Per fare riferimento agli output di un livello in un altro livello, usare le variabili di ambiente che azd impostano dopo la distribuzione di ogni livello. Fare riferimento a tali variabili di ambiente in un file *.bicepparam o *.parameters.json consente inoltre a azd di determinare l'ordinamento tra i livelli.
  • Tutte le funzionalità di provisioning standard azd (memorizzazione nella cache dello stato della distribuzione, hook, parametri, Bicep o Terraform) funzionano all'interno di ogni singolo livello.
    • Gli hook a livello di comando ( ad esempio preprovision, ) postprovisionvengono richiamati una volta per ogni livello. Quando vengono definiti più livelli, gli hook vengono eseguiti per ciascun livello nell'ordine in cui i livelli vengono elaborati.

Passaggi successivi

Informazioni di riferimento sullo schema azure.yaml

  • Last updated on