Esplorare e modificare i file di modello di Azure Developer CLI

Un modello di Azure Developer CLI (azd) è un repository standard con risorse di configurazione e infrastruttura che consentono a azd di effettuare il provisioning e distribuire un progetto. Indipendentemente dal fatto che si crei un nuovo modello o si inizi da uno esistente, si rimane responsabili della revisione e della gestione dei relativi file man mano che il progetto si evolve.

Questo articolo illustra come esaminare e modificare i file di modello primari. Per una descrizione concettuale della struttura completa, vedi modelli di Azure Developer CLI.

Questo articolo usa il modello hello-azd come esempio standardizzato in modo da visualizzare le operazioni di ogni file in un progetto reale. Gli stessi concetti si applicano ai modelli generati per le proprie app. Per procedere, inizializzare il modello in una directory vuota:

azd init --template hello-azd

Il hello-azd modello distribuisce un'app C# in contenitori in App contenitore di Azure ed esegue il provisioning delle risorse di supporto Azure tramite Bicep. Usa una struttura di cartelle simile alla seguente, in cui ogni asset primario è mappato a una sezione di questo articolo:

.
├── 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 struttura esatta varia in base al progetto e azure.yaml identifica i percorsi utilizzati azd . Le sezioni seguenti descrivono come modificare ogni asset.

Prima di apportare modifiche sostanziali, eseguire il commit o salvare in altro modo una versione valida nota del modello. Esaminare tutte le modifiche per le credenziali incorporate, le risorse non necessarie, autorizzazioni eccessive, esposizione di rete, livelli di servizio e valori specifici dell'ambiente.

Esplorazione di azure.yaml

Il file azure.yaml definisce il progetto e indica a azd come effettuare il provisioning dell'infrastruttura, impacchettare il codice dell'applicazione e distribuire ciascun servizio. Può definire servizi, impostazioni dell'infrastruttura, hook, flussi di lavoro e altro comportamento del progetto.

Il hello-azd modello definisce un singolo servizio denominato aca:

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

Ogni proprietà indica azd come gestire il servizio:

• aca è il nome del servizio. azdlo usa per associare il servizio alla risorsa Azure che lo ospita. Per altre informazioni, vedere Configurare l'individuazione dei servizi.
• project: ./src punta al codice sorgente dell'applicazione che viene compilato in pacchetti e distribuito da azd.
• language: csharp identifica la lingua dell'applicazione.
• host: containerappindica azd di distribuire il servizio in App contenitore di Azure.
• docker compila l'immagine del contenitore da Dockerfile nella src directory .
• remoteBuildindica azd di usare Registro Azure Container (ACR) per compilare l'immagine del contenitore.

Aggiungere una definizione di servizio

Aggiungere una voce sotto services per ogni applicazione aggiuntiva che azd deve distribuire. Una definizione del servizio specifica la directory di origine, la lingua e Azure destinazione di hosting. Ad esempio, per descrivere un nuovo progetto API:

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

Quando si sposta il codice dell'applicazione, aggiornare il percorso corrispondente project . Quando si modifica l'architettura di hosting, aggiornare sia la definizione del servizio che l'infrastruttura che effettua il provisioning dell'host.

Per tutte le proprietà disponibili e i valori supportati, vedere lo azure.yaml schema.

Codice sorgente

L'origine dell'applicazione è facoltativa. I modelli con applicazioni distribuibili spesso organizzano il codice sorgente nella src directory, ma non è necessario usare un nome o un layout di cartella specifici. La project proprietà per ogni servizio in azure.yaml indica azd dove risiede il codice sorgente.

In hello-azdil aca servizio imposta project: ./src, quindi azd crea un pacchetto dell'app C# nella src directory e la distribuisce in App contenitore di Azure. Poiché il servizio imposta anche una configurazione docker, azd crea l'immagine del contenitore dal Dockerfile nella directory src prima della distribuzione.

azdsupporta Node.js, Python, .NET, Java e Go in host di Azure supportati. Un modello può anche distribuire contenitori. Per le combinazioni correnti di linguaggio, framework e host, vedere Lingue e ambienti supportati.

Modificare il codice sorgente come si farebbe in qualsiasi repository di applicazioni. Se si aggiunge un servizio o si sposta la relativa directory di origine, aggiornarne la azure.yaml definizione. Se l'applicazione richiede una nuova risorsa Azure, aggiornare l'infrastruttura e passare l'endpoint o il nome della risorsa richiesto all'applicazione tramite la configurazione.

Modificare una directory di origine del servizio

Ad esempio, se si sposta l'app hello-azd da src a src/app, aggiornare il valore project del servizio aca:

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

File di infrastruttura

La infra directory contiene i file Bicep o Terraform che definiscono le risorse Azure per il modello. In hello-azd, la directory infra utilizza Bicep e include le seguenti risorse chiave:

• main.bicep è il punto di ingresso standard per la distribuzione che azd esegue per effettuare il provisioning delle risorse.
• main.parameters.json fornisce i valori dei parametri per main.bicep.
• app contiene moduli specifici dell'applicazione.
• core contiene moduli riutilizzabili per risorse comuni, ad esempio archiviazione e hosting.

Modalità main.bicep di esecuzione durante azd up

Quando si esegue azd up, la fase di provisioning distribuisce infra/main.bicep. In hello-azd, main.bicep ha come destinazione l'ambito della sottoscrizione, crea un gruppo di risorse e quindi richiama i moduli per effettuare il provisioning delle risorse necessarie all'app:

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
  }
}

Il file main.bicep esegue il provisioning di un'identità gestita assegnata dall'utente, un account di archiviazione di Azure, un ambiente e un registro di App contenitore di Azure e l'app contenitore che ospita il servizio aca. Assegna anche i ruoli che consentono all'identità gestita di accedere all'archiviazione. I moduli mantengono ogni risorsa nel proprio file in modo che main.bicep rimanga leggibile.

Aggiungere una risorsa a main.bicep

Aggiungere le dichiarazioni di risorse direttamente a infra/main.bicep per risorse semplici o occasionali. Suddividi le risorse in moduli Bicep separati quando vengono riutilizzate, quando una risorsa richiede più risorse correlate o quando vuoi mantenere main.bicep leggibile. Come hello-azd, molti modelli raggruppano moduli riutilizzabili in infra/core.

Per le risorse Azure comuni, preferire un modulo verificato Azure rispetto alla creazione di un modulo da zero. I moduli verificati vengono gestiti Microsoft, seguono le procedure consigliate per la sicurezza e l'affidabilità e riducono la quantità di codice dell'infrastruttura gestita nel modello.

Per una procedura dettagliata completa che aggiunge una nuova risorsa a hello-azd, vedere Estendere un modello.

Il main.parameters.json file esegue il mapping dei valori che azd mantiene nei parametri Bicep. Il hello-azd modello usa i parametri seguenti:

{
  "$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}" }
  }
}

Ogni voce associa un parametro Bicep a un valore gestito azd nell'ambiente, ad esempio il nome dell'ambiente, il percorso e l'entità che esegue la distribuzione. Usare main.parameters.json per i valori che variano in base all'ambiente o alla distribuzione, ad esempio il nome dell'ambiente, la posizione o i nomi delle risorse generati azd . Mantenere valori stabili che non cambiano tra gli ambienti come valori predefiniti dei parametri o valori letterali in main.bicep. Questo approccio mantiene lo stesso Bicep riutilizzabile in ambienti senza modificarlo per ogni distribuzione.

Quando si aggiunge o si modifica l'infrastruttura:

• Mantenere indipendente l'ambiente di configurazione delle risorse. Usare i parametri e le variabili di ambiente azd invece di incorporare ID di sottoscrizione, nomi di risorse, località o credenziali.
• Usare output sicuri per i valori sensibili e non esporre segreti come output di distribuzione di testo normale.
• Applicare assegnazioni di ruolo con privilegi minimi alle identità gestite.
• Mantenere le definizioni del servizio in azure.yaml linea con le risorse di destinazione.
• Esaminare gli effetti dei livelli di servizio, dei limiti di ridimensionamento, della ridondanza e delle impostazioni di conservazione sui costi.

Per linee guida sul linguaggio Bicep e sui moduli, vedere la documentazione di Bicep. Per i modelli basati su Terraform, vedere Usare Terraform con l'interfaccia della riga di comando per sviluppatori Azure.

Configurare l'individuazione dei servizi

Per impostazione predefinita, azd individua la risorsa Azure per un servizio individuando la risorsa il cui azd-service-name tag corrisponde al nome del servizio in azure.yaml. Se si rinomina un servizio, aggiornare il tag di risorsa corrispondente o configurare in modo esplicito il nome della risorsa in azure.yaml.

Ad esempio, in hello-azd, il nome del servizio aca corrisponde al tag azd-service-name nella risorsa dell'app contenitore. La definizione del azure.yaml servizio imposta il nome:

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

Il modulo app contenitore in infra/app/app.bicep applica il tag corrispondente:

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

Configurare un percorso di infrastruttura non standard

La infra sezione di azure.yaml identifica il provider di infrastruttura e il punto di ingresso. Questi valori sono facoltativi quando si usa il layout di Bicep predefinito, ma dichiarandoli possono semplificare la comprensione di un layout non standard:

infra:
  provider: bicep
  path: infra
  module: main

Configurazione dell'ambiente

La .azure directory contiene lo stato dell'ambiente locale e i valori che azd creano, ad esempio la sottoscrizione, il percorso, i nomi delle risorse e gli output della distribuzione selezionati. Considerare questa directory come stato locale anziché come asset modello riutilizzabile. Non eseguire il commit dei file di ambiente che contengono segreti o valori specifici dell'ambiente.

Aggiungi output dell'infrastruttura

Quando si esegue azd provision per distribuire Bicep, recupera gli output dal punto di ingresso dell'infrastruttura come valori di ambiente azd. Aggiungi output per gli endpoint di risorsa, i nomi delle risorse e gli ID client dell'identità gestita necessari per i servizi dell'applicazione o per gli hook. Ad esempio, hello-azd restituisce il registro contenitori e i dettagli dell'identità gestita da 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

Non visualizzare i segreti quando un'identità gestita o un riferimento a Key Vault può invece fornire l'accesso. Dopo il provisioning, esaminare i valori acquisiti eseguendo azd env get-values.

Per altre informazioni, vedere Gestire le variabili di ambiente.

Testare tutte le modifiche.

Eseguire azd up per effettuare il provisioning dell'infrastruttura e distribuire tutti i servizi dell'applicazione:

azd up

Se si intende condividere il modello, inizializzarlo in una directory pulita e distribuirlo con un nuovo ambiente. Questo test consente di identificare file locali, valori memorizzati nella cache o presupposti specifici dell'ambiente che non fanno parte del modello.

Contenuti correlati

• Panoramica dello sviluppo di modelli
• Iniziare con un nuovo modello
• Iniziare da un modello esistente
• Estendere un modello
• Esplorare il azd up flusso di lavoro

Richiedere assistenza

Per informazioni su come inviare un bug, richiedere assistenza o proporre una nuova funzionalità per l'interfaccia della riga di comando per sviluppatori di Azure, visitare la pagina troubleshooting e supporto.