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 wird die Vorlage "hello-azd " als standardisiertes Beispiel verwendet, sodass 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. Um mitzumachen, initialisieren Sie die Vorlage in einem leeren Verzeichnis:

azd init --template hello-azd

Die hello-azd Vorlage stellt eine containerisierte C#-App für Azure Container Apps bereit und stellt die unterstützenden Azure Ressourcen über Bicep bereit. Es verwendet eine Ordnerstruktur wie die folgende, wobei jede primäre Ressource 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
│   ├── 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

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, checken Sie eine bekanntermaßen funktionierende Version der Vorlage ein oder speichern Sie sie anderweitig. Ü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.

Die hello-azd Vorlage definiert einen einzelnen Dienst mit dem Namen aca:

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

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

• aca ist der Dienstname. azd verwendet dies, um den Dienst der Azure-Ressource zuzuordnen, die ihn hostet. Weitere Informationen finden Sie unter Konfigurieren der Dienstermittlung.
• project: ./src verweist auf den Anwendungsquellcode, den azd paketiert und bereitstellt.
• language: csharp identifiziert die Anwendungssprache.
• host: containerappweist azd an, den Dienst für Azure Container Apps bereitzustellen.
• docker erstellt das Container-Image aus dem Dockerfile im Verzeichnis src.
• 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. So beschreiben Sie beispielsweise ein neues API-Projekt:

services:
  api:
    project: ./src/api
    language: csharp
    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 hello-azd, der aca Dienst legt project: ./srcfest, sodass azd die C#-App im src Verzeichnis verpackt und auf Azure Container Apps bereitgestellt wird. Da der Dienst auch eine docker Konfiguration festlegt, erstellt azd vor der Bereitstellung das Container-Image 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 hello-azd App z. B. von "src/appinsrc" verschieben, aktualisieren Sie den project Wert des aca Diensts:

services:
  aca:
    project: ./src/app
    language: csharp
    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. Im hello-azd verwendet das infra-Verzeichnis Bicep und enthält die folgenden wichtigen Ressourcen:

• main.bicep ist der standardmäßige Einstiegspunkt für die Bereitstellung, den azd ausführt, um Ressourcen bereitzustellen.
• main.parameters.json liefert die Parameterwerte für main.bicep.
• app enthält Module, die für die Anwendung spezifisch sind.
• core enthält wiederverwendbare Module für allgemeine Ressourcen, z. B. Speicher und Hosting.

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

Wenn Sie azd up ausführen, wird in der Bereitstellungsphase infra/main.bicep bereitgestellt. In main.bicep zielt hello-azd auf den Abonnementbereich ab, erstellt eine Ressourcengruppe und ruft dann Module auf, um die Ressourcen bereitzustellen, die die App benötigt:

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

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 hello-azd, viele Vorlagen gruppieren 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 Schritt-für-Schritt-Anleitung zum Hinzufügen einer neuen Ressource zu hello-azd finden Sie unter Eine Vorlage erweitern.

Die Datei main.parameters.json ordnet die Werte, die azd verwaltet, den Bicep-Parametern zu. Die hello-azd Vorlage verwendet 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.

Beispielsweise stimmt in hello-azd der Dienstname aca mit dem Tag azd-service-name der Container-App-Ressource überein. Die azure.yaml Dienstdefinition legt den Namen fest:

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

Im Container-App-Modul in infra/app/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. Beispielsweise gibt hello-azd die Details zur Containerregistrierung 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.

Verwandte Inhalte

• Übersicht über die Vorlagenentwicklung
• Beginnen mit einer neuen Vorlage
• Beginnen mit einer vorhandenen Vorlage
• Erweitern einer Vorlage
• Erkunden des azd up Workflows

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.