Erkunden und Bearbeiten Azure Entwickler-CLI-Vorlagendateien

Eine Azure Developer CLI (azd)-Vorlage ist ein Standardrepository mit Konfigurations- und Infrastrukturressourcen, die es azd ermöglichen, ein Projekt zu provisionieren und bereitzustellen. Unabhängig davon, ob Sie eine neue Vorlage erstellen oder mit einer vorhandenen Vorlage beginnen, sind Sie für das Überprüfen und Verwalten der Dateien verantwortlich, während sich das Projekt weiterentwickelt.

In diesem Artikel wird erläutert, wie Sie die primären Vorlagendateien überprüfen und bearbeiten. Eine konzeptionelle Beschreibung der vollständigen Struktur finden Sie unter Azure Developer CLI-Vorlagen.

In diesem Artikel werden die hello-azd Beispielvorlagen verwendet, damit Sie sehen können, was jede Datei in einem echten Projekt tut. Die gleichen Konzepte gelten für Vorlagen, die Sie für Ihre eigenen Apps generieren.

Initialisieren einer Beispielvorlage

Führen Sie die Voraussetzungen für den Schnellstart aus, wählen Sie eine Sprache aus, und initialisieren Sie die Vorlage in einem leeren Verzeichnis. Der .-Parameter behält das Projekt im aktuellen Verzeichnis bei:

Diese Option verwendet das hello-azd-python Beispiel-Repository.

azd init --template hello-azd-python .

Beide Vorlagen stellen eine containerisierte App für Azure Container Apps bereit und stellen die unterstützenden Azure Ressourcen über Bicep bereit. Sie verwenden die folgende Ordnerstruktur, wobei jedes primäre Objekt einem Abschnitt in diesem Artikel zugeordnet ist:

.
├── 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
│   └── core/                 # Reusable resource modules
├── src/                      # Application source code (Source code)
│   └── Dockerfile            # Container image build for the app
├── .azure/                   # Environment configuration
└── README.md

Die genaue Struktur variiert je nach Projekt, und azure.yaml identifiziert die Pfade, die azd verwendet. In den folgenden Abschnitten wird beschrieben, wie Sie die einzelnen Ressourcen bearbeiten.

Bevor Sie wesentliche Änderungen vornehmen, sollten Sie eine nachweislich funktionierende Version der Vorlage committen oder anderweitig speichern. Überprüfen Sie alle Änderungen für eingebettete Anmeldeinformationen, unnötige Ressourcen, übermäßige Berechtigungen, Netzwerkexposition, Dienstebenen und umgebungsspezifische Werte.

azure.yaml erkunden

Die azure.yaml Datei definiert das Projekt und teilt azd mit, wie Infrastruktur, Paketanwendungscode bereitgestellt und jeder Dienst bereitgestellt wird. Sie kann Dienste, Infrastruktureinstellungen, Hooks, Workflows und anderes Projektverhalten definieren.

Beide Vorlagen definieren einen einzelnen Dienst mit dem Namen aca. Wählen Sie eine Sprache aus, um die Dienstdefinition anzuzeigen:

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

Jede Eigenschaft teilt azd mit, wie der Dienst behandelt werden soll:

  • aca ist der Dienstname. azd verwendet ihn, um den Dienst mit der Azure-Ressource abzugleichen, die ihn hostet. Weitere Informationen finden Sie unter Konfigurieren der Dienstermittlung.
  • project: ./src verweist auf den Anwendungsquellcode, den azd paketiert und bereitstellt.
  • language identifiziert die Anwendungssprache als python oder csharp.
  • host: containerappweist azd an, den Dienst für Azure Container Apps bereitzustellen.
  • docker erstellt das Containerimage aus dem Dockerfile im src-Verzeichnis.
  • remoteBuildweist azd an, Azure Container Registry (ACR) zum Erstellen des Containerimages zu verwenden.

Hinzufügen einer Dienstdefinition

Fügen Sie unter services für jede zusätzliche Anwendung, die azd bereitstellen soll, einen Eintrag hinzu. Eine Dienstdefinition gibt das Quellverzeichnis, die Sprache und Azure Hostingziel an. Wählen Sie beispielsweise eine Sprache aus, um ein neues API-Projekt zu beschreiben:

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

Aktualisieren Sie beim Verschieben des Anwendungscodes den entsprechenden project Pfad. Wenn Sie die Hostingarchitektur ändern, aktualisieren Sie sowohl die Dienstdefinition als auch die Infrastruktur, die den Host bereitstellt.

Alle verfügbaren Eigenschaften und unterstützten Werte finden Sie im azure.yaml Schema.

Quellcode

Die Anwendungsquelle ist optional. Vorlagen mit bereitstellungsfähigen Anwendungen organisieren häufig Quellcode im src Verzeichnis, aber Sie müssen keinen bestimmten Ordnernamen oder ein bestimmtes Layout verwenden. Die Eigenschaft project für jeden Dienst in azd teilt azure.yaml mit, wo sich der Quellcode befindet.

In beiden Beispielvorlagen setzt der Dienst acaproject: ./src, sodass azd die App im Verzeichnis src verpackt und in Azure Container Apps bereitstellt. Die .NET Quelle enthält eine Blazor-App unter src/Components, und die Python Quelle enthält eine FastAPI-App unter src/app. Da jeder Dienst auch eine docker-Konfiguration festlegt, erstellt azd das Containerimage vor der Bereitstellung aus dem Dockerfile im Verzeichnis src.

azd unterstützt Node.js, Python, .NET, Java und Go auf unterstützten Azure-Hosts. Eine Vorlage kann auch Container bereitstellen. Aktuelle Sprach-, Framework- und Hostkombinationen finden Sie unter "Unterstützte Sprachen und Umgebungen".

Bearbeiten Sie Den Quellcode wie in jedem Anwendungs-Repository. Wenn Sie einen Dienst hinzufügen oder das Quellverzeichnis verschieben, aktualisieren Sie die azure.yaml Dienstdefinition. Wenn die Anwendung eine neue Azure Ressource benötigt, aktualisieren Sie die Infrastruktur, und übergeben Sie den erforderlichen Endpunkt oder Ressourcennamen über die Konfiguration an die Anwendung.

Ändern eines Dienstquellverzeichnisses

Wenn Sie die App z. B. von src/web in src verschieben, aktualisieren Sie den project Wert des aca Diensts:

services:
  aca:
    project: ./src/web
    language: python
    host: containerapp
    docker:
      path: ./Dockerfile
      remoteBuild: true

Infrastrukturdateien

Das infra Verzeichnis enthält die dateien Bicep oder Terraform, die die Azure Ressourcen für die Vorlage definieren. Beide Beispielvorlagen verwenden Bicep und enthalten die folgenden wichtigen Ressourcen:

  • main.bicep ist der standardmäßige Einstiegspunkt, den azd ausführt, um Ressourcen bereitzustellen.
  • main.parameters.json stellt die Parameterwerte für main.bicep.
  • coreenthält fokussierte Module für Ressourcen wie Speicher, Identität, Azure Container Registry und Azure Container Apps.

Wie main.bicep während azd up ausgeführt wird

Wenn Sie azd up ausführen, wird in der Bereitstellungsphase infra/main.bicep bereitgestellt. Die Datei zielt auf den Abonnementbereich ab, erstellt eine Ressourcengruppe und ruft dann Module auf, um die Ressourcen bereitzustellen, die die App benötigt. Wählen Sie eine Sprache aus, um die relevanten Bezeichner in jeder Vorlage anzuzeigen:

targetScope = 'subscription'

var abbreviations = loadJsonContent('./abbreviations.json')

resource resourceGroup 'Microsoft.Resources/resourceGroups@2021-04-01' = {
  name: !empty(resourceGroupName) ? resourceGroupName : '${abbreviations.resourcesResourceGroups}${environmentName}'
  location: location
  tags: tags
}

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

module web './core/host/container-app.bicep' = {
  name: serviceName
  scope: resourceGroup
  // ...
}

Die main.bicep Datei stellt eine vom Benutzer zugewiesene verwaltete Identität, ein Azure Storage Konto, eine Azure Container Apps Umgebung und Registrierung sowie die Container-App bereit, die den aca Dienst hosten soll. Außerdem werden die Rollen zugewiesen, die der verwalteten Identität den Zugriff auf den Speicher ermöglichen. Module behalten jede Ressource in einer eigenen Datei bei, sodass main.bicep sie lesbar bleibt.

Hinzufügen einer Ressource zu main.bicep

Fügen Sie Ressourcendeklarationen direkt zu infra/main.bicep für einfache oder einzelne Ressourcen hinzu. Gliedern Sie Ressourcen in separate Bicep-Module aus, wenn Sie sie wiederverwenden, wenn eine Ressource mehrere zusammengehörige Ressourcen benötigt oder wenn Sie main.bicep lesbar halten möchten. Wie in den Beispielen gruppieren viele Vorlagen wiederverwendbare Module unter infra/core.

Für gängige Azure-Ressourcen verwenden Sie vorzugsweise ein Azure Verified Module, anstatt ein Modul von Grund auf zu erstellen. Überprüfte Module werden von Microsoft gepflegt, entsprechen bewährten Verfahren für Sicherheit und Zuverlässigkeit und verringern den Umfang des Infrastrukturcodes, den Sie in der Vorlage verwalten.

Eine vollständige exemplarische Vorgehensweise, mit der Sie einer von beiden Beispielvorlagen eine neue Ressource hinzufügen, finden Sie unter Erweitern einer Vorlage.

Die Datei main.parameters.json ordnet die Werte, die azd verwaltet, den Bicep-Parametern zu. Beide Beispielvorlagen verwenden die folgenden Parameter:

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

Jeder Eintrag verknüpft einen Bicep-Parameter mit einem Wert, den azd in der Umgebung verwaltet, z. B. den Umgebungsnamen, die Region und den Prinzipal, der die Bereitstellung ausführt. Verwenden Sie main.parameters.json für Werte, die je nach Umgebung oder Bereitstellung variieren, z. B. den Namen der Umgebung, den Standort oder die Ressourcennamen, die von azd generiert werden. Halten Sie stabile Werte, die sich nicht zwischen Umgebungen ändern, als Parameterstandardwerte oder Literale in main.bicep. Dieser Ansatz sorgt dafür, dass dieselbe Bicep-Vorlage in verschiedenen Umgebungen wiederverwendbar bleibt, ohne sie für jede Bereitstellung bearbeiten zu müssen.

Beim Hinzufügen oder Bearbeiten der Infrastruktur:

  • Halten Sie die Ressourcenkonfigurationsumgebung unabhängig. Verwenden Sie Parameter und azd Umgebungswerte, anstatt Abonnement-IDs, Ressourcennamen, Speicherorte oder Anmeldeinformationen einzubetten.
  • Verwenden Sie geschützte Ausgaben für sensible Werte, und geben Sie Geheimnisse nicht als Bereitstellungsausgaben im Klartext aus.
  • Wenden Sie Rollenzuweisungen mit geringsten Berechtigungen auf verwaltete Identitäten an.
  • Halten Sie die Dienstdefinitionen in azure.yaml auf die Ressourcen abgestimmt, auf die sie gerichtet sind.
  • Überprüfen Sie die Auswirkungen von Dienstebenen, Skalierungsgrenzwerten, Redundanz und Aufbewahrungseinstellungen auf Kosten.

Hinweise zur Bicep-Sprache und zu Modulen finden Sie in der Bicep-Dokumentation. Informationen zu Terraform-basierten Vorlagen finden Sie unter Verwenden von Terraform mit Azure Developer CLI.

Dienst­erkennung konfigurieren

Standardmäßig ermittelt azd die Azure-Ressource für einen Dienst, indem nach der Ressource gesucht wird, deren azd-service-name-Tag mit dem Dienstnamen in azure.yaml übereinstimmt. Wenn Sie einen Dienst umbenennen, aktualisieren Sie das entsprechende Ressourcentag, oder konfigurieren Sie den Ressourcennamen explizit in azure.yaml.

In beiden Beispielvorlagen entspricht der aca Dienstname beispielsweise dem azd-service-name Tag in der Container-App-Ressource. Die azure.yaml Dienstdefinition legt den Namen fest. Wählen Sie eine Sprache aus, um ihre Definition anzuzeigen:

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

Im Container-App-Modul in infra/core/host/container-app.bicep wird das passende Tag angewendet:

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

Konfigurieren eines nicht standardmäßigen Infrastrukturpfads

Der Abschnitt infra von azure.yaml identifiziert den Infrastrukturanbieter und den Einstiegspunkt. Diese Werte sind optional, wenn Sie das Standardlayout Bicep verwenden, aber durch das Deklarieren können Sie ein nicht standardmäßiges Layout einfacher verstehen:

infra:
  provider: bicep
  path: infra
  module: main

Umgebungskonfiguration

Das .azure-Verzeichnis enthält den Status der lokalen Umgebung und Werte, die azd erstellt, z. B. das ausgewählte Abonnement, den Standort, die Ressourcennamen und die Ausgaben der Bereitstellung. Behandeln Sie dieses Verzeichnis als lokalen Zustand und nicht als wiederverwendbare Vorlagenressource. Committen Sie keine Umgebungsdateien, die Geheimnisse oder umgebungsspezifische Werte enthalten.

Hinzufügen von Infrastrukturausgaben

Wenn Sie azd provision zum Bereitstellen von Bicep ausführen, werden die Ausgabewerte des Einstiegspunkts der Infrastruktur als Umgebungswerte für azd erfasst. Fügen Sie Ausgabewerte für Ressourcenendpunkte, Ressourcennamen und Client-IDs verwalteter Identitäten hinzu, die von Anwendungsdiensten oder Hooks benötigt werden. Beide Beispielvorlagen geben beispielsweise die Details zur Container Registry und zur verwalteten Identität aus main.bicep aus:

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

Geben Sie keine geheimen Schlüssel aus, wenn stattdessen eine verwaltete Identität oder Key Vault Referenz Zugriff gewähren kann. Überprüfen Sie nach der Bereitstellung die erfassten Werte, indem Sie azd env get-values ausführen.

Weitere Informationen finden Sie unter Verwalten von Umgebungsvariablen.

Testen der Änderungen

Führen Sie die Ausführung azd up aus, um die Infrastruktur bereitzustellen und alle Anwendungsdienste bereitzustellen:

azd up

Wenn Sie die Vorlage freigeben möchten, initialisieren Sie sie in einem sauberen Verzeichnis, und stellen Sie sie mit einer neuen Umgebung bereit. Dieser Test hilft bei der Identifizierung lokaler Dateien, zwischengespeicherter Werte oder umgebungsspezifischer Annahmen, die nicht Teil der Vorlage sind.

Hilfe anfordern

Informationen zum Melden eines Fehlers, Anfordern von Hilfe oder Vorschlagen einer neuen Funktion für die Azure Developer CLI finden Sie auf der Seite Fehlerbehebung und Support.