Parcourir et modifier les fichiers de modèle d’Azure Developer CLI

Un modèle AZURE Developer CLI (azd) est un référentiel standard avec des ressources de configuration et d’infrastructure qui permettent azd de provisionner et de déployer un projet. Que vous générez un nouveau modèle ou commencez à partir d’un modèle existant, vous restez responsable de l’examen et de la maintenance de ses fichiers au fur et à mesure que le projet évolue.

Cet article explique comment inspecter et modifier les fichiers de modèle principal. Pour obtenir une description conceptuelle de la structure complète, consultez les modèles de l’interface de ligne de commande Azure Developer.

Cet article utilise le modèle hello-azd comme exemple standardisé afin de voir ce que fait chaque fichier dans un projet réel. Les mêmes concepts s’appliquent aux modèles que vous générez pour vos propres applications. Pour suivre le suivi, initialisez le modèle dans un répertoire vide :

azd init --template hello-azd

Le hello-azd modèle déploie une application C# conteneurisée pour Azure Container Apps et provisionne les ressources de prise en charge Azure via Bicep. Il utilise une structure de dossiers comme suit, où chaque ressource principale est mappée à une section de cet article :

.
├── 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 structure exacte varie selon le projet et azure.yaml identifie les chemins d’accès qui azd utilisent. Les sections suivantes décrivent comment modifier chaque ressource.

Avant d’apporter des modifications importantes, validez ou enregistrez autrement une version fiable du modèle. Passez en revue toutes les modifications pour les informations d’identification incorporées, les ressources inutiles, les autorisations excessives, l’exposition réseau, les niveaux de service et les valeurs propres à l’environnement.

Explorer azure.yaml

Le azure.yaml fichier définit le projet et indique azd comment approvisionner l’infrastructure, le code d’application de package et déployer chaque service. Il peut définir des services, des paramètres d’infrastructure, des hooks, des flux de travail et d’autres comportements de projet.

Le hello-azd modèle définit un seul service nommé aca:

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

Chaque propriété indique azd comment gérer le service :

• aca est le nom du service. azdl’utilise pour faire correspondre le service à la ressource Azure qui l’héberge. Pour plus d’informations, consultez Configurer la découverte de service.
• project: ./src désigne le code source de l’application que azd empaquète et déploie.
• language: csharp identifie la langue de l’application.
• host: containerappindique azd de déployer le service sur Azure Container Apps.
• docker construit l’image du conteneur à partir de Dockerfile dans le répertoire src.
• remoteBuildindique azd d’utiliser Azure Container Registry (ACR) pour générer l’image conteneur.

Ajouter une définition de service

Ajoutez une entrée sous services pour chaque application supplémentaire que azd doit déployer. Une définition de service spécifie son répertoire source, sa langue et sa cible d’hébergement Azure. Par exemple, pour décrire un nouveau projet d’API :

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

Lorsque vous déplacez le code de l’application, mettez à jour le project chemin d’accès correspondant. Lorsque vous modifiez l’architecture d’hébergement, mettez à jour la définition de service et l’infrastructure qui provisionne l’hôte.

Pour toutes les propriétés disponibles et les valeurs prises en charge, consultez le azure.yaml schéma.

Code source

La source de l’application est facultative. Les modèles avec des applications déployables organisent souvent le code source sous le src répertoire, mais vous n’avez pas besoin d’utiliser un nom de dossier ou une disposition spécifique. La project propriété de chaque service indique azure.yamlazd où réside son code source.

Dans hello-azd, le service aca définit project: ./src, de sorte que azd empaquette l’application C# dans le répertoire src et la déploie sur Azure Container Apps. Étant donné que le service définit également une configuration docker, azd construit l’image de conteneur à partir du Dockerfile dans le répertoire src avant le déploiement.

azdprend en charge Node.js, Python, .NET, Java et Go sur les hôtes Azure pris en charge. Un modèle peut également déployer des conteneurs. Pour connaître les combinaisons de langage, d’infrastructure et d’hôte actuelles, consultez les langages et environnements pris en charge.

Modifiez le code source comme vous le feriez dans n’importe quel référentiel d’applications. Si vous ajoutez un service ou déplacez son répertoire source, mettez à jour sa azure.yaml définition de service. Si l’application a besoin d’une nouvelle ressource Azure, mettez à jour l’infrastructure et transmettez le point de terminaison ou le nom de ressource requis à l’application via la configuration.

Modifier un répertoire source de service

Par exemple, si vous déplacez l’application hello-azd de src à src/app, mettez à jour la valeur project du service aca :

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

Fichiers d’infrastructure

Le infra répertoire contient les fichiers Bicep ou Terraform qui définissent les ressources Azure pour le modèle. Dans hello-azd, le infra répertoire utilise Bicep et inclut les ressources clés suivantes :

• main.bicep est le point d’entrée standard du déploiement que azd exécute pour provisionner des ressources.
• main.parameters.json fournit les valeurs de paramètre pour main.bicep.
• app contient des modules spécifiques à l’application.
• core contient des modules réutilisables pour les ressources courantes, telles que le stockage et l’hébergement.

Comment main.bicep s’exécute pendant azd up

Lorsque vous exécutez azd up, la phase de provisionnement déploie infra/main.bicep. Dans hello-azd, main.bicep cible l’étendue de l’abonnement, crée un groupe de ressources, puis appelle des modules pour approvisionner les ressources dont l’application a besoin :

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

Le main.bicep fichier provisionne une identité managée affectée par l’utilisateur, un compte stockage Azure, un environnement et un registre Azure Container Apps et l’application conteneur qui héberge le aca service. Il attribue également les rôles qui permettent à l’identité managée d’accéder au stockage. Les modules conservent chaque ressource dans son propre fichier afin qu’elle main.bicep reste lisible.

Ajouter une ressource à main.bicep

Ajoutez directement à infra/main.bicep des déclarations de ressources pour des ressources simples ou ponctuelles. Regroupez les ressources dans des modules Bicep distincts lorsque vous les réutilisez, lorsqu’une ressource nécessite plusieurs ressources connexes, ou lorsque vous souhaitez que main.bicep reste lisible. Comme hello-azd, de nombreux modèles regroupent des modules réutilisables sous infra/core.

Pour les ressources courantes Azure, préférez un module vérifié Azure par rapport à la création d’un module à partir de zéro. Les modules vérifiés sont gérés Microsoft, suivent les bonnes pratiques de sécurité et de fiabilité et réduisent la quantité de code d’infrastructure que vous gérez dans le modèle.

Pour obtenir une procédure pas à pas complète qui ajoute une nouvelle ressource, hello-azdconsultez Étendre un modèle.

Le fichier main.parameters.json associe aux paramètres Bicep les valeurs que azd conserve. Le hello-azd modèle utilise les paramètres suivants :

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

Chaque entrée associe un paramètre Bicep à une valeur que azd conserve dans l’environnement, comme le nom de l’environnement, la région et l’identité qui exécute le déploiement. Utilisez main.parameters.json pour les valeurs qui varient selon l’environnement ou le déploiement, comme le nom de l’environnement, l’emplacement ou les noms de ressources qui azd génèrent. Conservez les valeurs stables qui ne changent pas entre les environnements en tant que paramètres par défaut ou littéraux dans main.bicep. Cette approche permet de réutiliser le même fichier Bicep d’un environnement à l’autre sans avoir à le modifier pour chaque déploiement.

Lorsque vous ajoutez ou modifiez l’infrastructure :

• Conservez l’environnement de configuration des ressources indépendamment. Utilisez des paramètres et azd des valeurs d’environnement au lieu d’incorporer des ID d’abonnement, des noms de ressources, des emplacements ou des informations d’identification.
• Utilisez des sorties sécurisées pour les valeurs sensibles et n’exposez pas les secrets en tant que sorties de déploiement en texte brut.
• Appliquez des attributions de rôles de privilège minimum aux identités managées.
• Conservez les définitions de services dans azure.yaml alignées sur les ressources qu’elles ciblent.
• Passez en revue les effets des niveaux de service, des limites de mise à l’échelle, de la redondance et des paramètres de rétention sur les coûts.

Pour obtenir des conseils sur le langage Bicep et les modules, consultez la documentation de Bicep. Pour les modèles basés sur Terraform, consultez Utiliser Terraform avec Azure Developer CLI.

Configurer la découverte de services

Par défaut, azd découvre la ressource Azure pour un service en recherchant la ressource dont azd-service-name l’étiquette correspond au nom du service dans azure.yaml. Si vous renommez un service, mettez à jour la balise de ressource correspondante ou configurez explicitement le nom de la ressource dans azure.yaml.

Par exemple, dans hello-azd le nom du aca service correspond à l’étiquette azd-service-name sur la ressource d’application conteneur. La définition de azure.yaml service définit le nom :

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

Le module d’application conteneur dans infra/app/app.bicep applique la balise correspondante :

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

Configurer un chemin d’infrastructure non standard

La section infra de azure.yaml identifie le fournisseur d’infrastructure et le point d’entrée. Ces valeurs sont facultatives lorsque vous utilisez la disposition par défaut Bicep, mais la déclaration de ces valeurs peut faciliter la compréhension d’une disposition non standard :

infra:
  provider: bicep
  path: infra
  module: main

Configuration de l’environnement

Le .azure répertoire contient l’état et les valeurs d’environnement locaux qui azd créent, comme l’abonnement sélectionné, l’emplacement, les noms de ressources et les sorties de déploiement. Traitez ce répertoire comme un état local plutôt qu’une ressource de modèle réutilisable. Ne validez pas les fichiers d’environnement qui contiennent des secrets ou des valeurs propres à l’environnement.

Ajouter des sorties d’infrastructure

Lorsque vous exécutez azd provision pour déployer Bicep, il capture les sorties du point d’entrée de l’infrastructure en tant que azd valeurs d’environnement. Ajoutez des sorties pour les points de terminaison de ressources, les noms de ressources et les ID de client d’identité managée dont ont besoin les services d’application ou les hooks. Par exemple, hello-azd génère le registre de conteneurs et les détails de l’identité managée à partir 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

N’affichez pas de secrets lorsqu’une identité managée ou une référence à Key Vault peut permettre d’y accéder à la place. Après l’approvisionnement, inspectez les valeurs capturées en exécutant azd env get-values.

Pour plus d’informations, consultez Gérer les variables d’environnement.

Tester vos modifications

Exécutez azd up pour provisionner l’infrastructure et déployer tous les services d’application :

azd up

Si vous envisagez de partager le modèle, initialisez-le dans un répertoire propre et déployez-le avec un nouvel environnement. Ce test permet d’identifier les fichiers locaux, les valeurs mises en cache ou les hypothèses propres à l’environnement qui ne font pas partie du modèle.

Contenu connexe

• Vue d’ensemble du développement de modèles
• Commencer avec un nouveau modèle
• Démarrer à partir d’un modèle existant
• Étendre un modèle
• Explorer le azd up flux de travail

Demander de l’aide

Pour plus d’informations sur la façon de déposer un bogue, de demander de l’aide ou de proposer une nouvelle fonctionnalité pour l’interface CLI Azure développeur, visitez la page troubleshooting et support.