Arbeiten mit Azure Developer CLI-Umgebungsvariablen

Die Azure Developer CLI (azd) verwendet Umgebungsvariablen zum Speichern und Verwalten von Konfigurationseinstellungen für Bereitstellungsumgebungen. Diese Variablen steuern, wie Ihre Anwendung in Azure bereitgestellt, implementiert und ausgeführt wird. In diesem Artikel wird erläutert, wie Umgebungsvariablen in azd Umgebungen funktionieren und Anleitungen zum effektiven Verwalten dieser Variablen bieten.

Grundlegendes zu Umgebungsvariablen

Im Kontext der Azure Developer CLI sind Umgebungsvariablen Schlüsselwertpaare, die an bestimmte benannte Umgebungen wie Dev, Test oder Prod gebunden sind. Jede azd Umgebung verwaltet einen eigenen Satz von Umgebungsvariablen, sodass Sie unterschiedliche Einstellungen für unterschiedliche Bereitstellungsziele konfigurieren können.

Umgebungsvariablen azd werden in .env Dateien in Ihren Umgebungsordnern im .azure Ordner gespeichert. Sie dienen als Eingaben für:

• Workflows für die Anwendungsbereitstellung
• Konfigurationen für Azure-Dienste und -Verbindungen
• Infrastrukturbereitstellung durch Bicep und Terraform

Im Gegensatz zu herkömmlichen Umgebungsvariablen, die auf Betriebssystemebene vorhanden sind, azd sind Umgebungsvariablen auf bestimmte Umgebungen innerhalb Ihres Projekts ausgerichtet, wodurch eine Isolation zwischen verschiedenen Bereitstellungszielen bereitgestellt wird.

Umgebungsvariablen bieten mehrere wichtige Vorteile beim Arbeiten mit azd.

• Umgebungsisolation: Halten Sie die Konfigurationen für Entwicklung, Test und Produktion getrennt und eindeutig voneinander getrennt.
• Konfigurationskonsistenz: Stellen Sie sicher, dass alle Teammitglieder dieselben Einstellungen für eine bestimmte Umgebung verwenden.
• Infrastruktur als Code: Definieren der Infrastrukturparameterisierung durch Variablen anstelle hartcodierter Werte.
• Bereitstellungsautomatisierung: Ermöglichen Sie CI/CD-Pipelines für die Bereitstellung in verschiedenen Umgebungen mithilfe derselben Codebasis, aber verschiedener Konfigurationen.
• Vereinfachte Verwaltung: Einfaches Aktualisieren von Einstellungen für alle Dienste in einer Umgebung von einem zentralen Standort aus.

Jede azd Umgebung verfügt über einen eigenen Satz von Variablen, der umgebungsspezifische Konfigurationen ermöglicht, während sie denselben Anwendungscode und die gleichen Infrastrukturvorlagen verwenden.

Umgebungsvariablen und env-Dateien

Die azd Umgebungsvariablen werden in .env Dateien in den umgebungsspezifischen Verzeichnissen Ihres Projekts gespeichert. Wenn Sie eine Umgebung mithilfe von azd env new <name> erstellen, wird eine Verzeichnisstruktur erstellt.

.azure/
├── <environment-name>/
│   ├── .env                   # Environment variables for this environment

Die .env Datei verwendet ein Standardformat, in dem jede Zeile ein Schlüssel-Wert-Paar darstellt:

KEY1=value1
KEY2=value2

Tipp

Weitere Informationen zu Umgebungen finden Sie im Artikel "azd".

Wenn Sie Befehle wie azd up ausführen, werden Variablen automatisch aus der azd-Datei der ausgewählten Umgebung geladen.

Diese Variablen beeinflussen:

• Infrastrukturbereitstellung: Variablen wie AZURE_LOCATION und AZURE_SUBSCRIPTION_ID bestimmen, wo und wie Ressourcen erstellt werden.
• Bereitstellung: Variablen wie Dienstendpunkte steuern, wie Ihre Anwendung eine Verbindung mit Azure-Diensten herstellt.
• Anwendungskonfiguration: Variablen können an Ihre Anwendungskonfiguration übergeben werden, um das Verhalten zu steuern.
• Ressourcenbenennung: Variablen wie AZURE_RESOURCE_GROUP haben Einfluss auf Ressourcenbenennungsmuster.

Die .env-Datei wird auch automatisch von azd während Vorgängen wie azd init, azd provision und azd deploy aktualisiert, wobei Ergebnisse aus Ihren Infrastrukturvorlagen erfasst und für die zukünftige Verwendung gespeichert werden.

Festlegen von Umgebungsvariablen

Sie können je nach Szenario unterschiedliche Methoden verwenden, um Umgebungsvariablen festzulegen azd .

Verwenden von CLI-Befehlen

Die empfohlene Methode zum Festlegen einer Umgebungsvariablen ist die Verwendung des azd env set Befehls, der Überprüfungen umfasst, um gültige Werte sicherzustellen:

azd env set <key> <value>

So legen Sie beispielsweise einen Konfigurationswert für Ihre Anwendung fest:

azd env set API_TIMEOUT 5000

Der Befehl fügt die Variable in der .env Datei der aktuell ausgewählten Umgebung hinzu oder aktualisiert sie. Sie können auch eine bestimmte Umgebung mit dem --environment Flag als Ziel festlegen:

azd env set API_TIMEOUT 5000 --environment prod

So überprüfen Sie, ob die Umgebungsvariable korrekt festgelegt wurde:

azd env get-value API_TIMEOUT

Ausgabe von Bicep

Eine leistungsfähige Funktion von azd ist die Fähigkeit, Ausgabeparameter aus Ihren Bicep-Infrastrukturvorlagen automatisch als Umgebungsvariablen zu erfassen. Wenn Sie beispielsweise einen Ausgabeparameter in Ihrer main.bicep Datei definieren:

output API_ENDPOINT string = apiService.outputs.SERVICE_ENDPOINT_URL

Nach dem Ausführen azd provisionwird diese Ausgabe automatisch in der Datei der Umgebung .env gespeichert:

API_ENDPOINT=https://api-dev-123456.azurewebsites.net

Mit diesem Ansatz wird sichergestellt, dass Ihre Anwendung immer Zugriff auf die aktuellsten Ressourceninformationen hat, z. B.:

• Dienstendpunkte und URLs
• Ressourcennamen und -bezeichner

Abrufen und Verwenden von Umgebungsvariablen

Nach der Festlegung können Sie in mehreren Kontexten auf Umgebungsvariablen zugreifen.

CLI-Befehle

So zeigen Sie alle Umgebungsvariablen für die aktuelle Umgebung an:

azd env get-values

So zeigen Sie den Wert einer bestimmten Variablen an:

azd env get-value API_ENDPOINT

Für maschinenlesbare Ausgabe (nützlich in Skripts):

azd env get-values --output json

Verwenden von Umgebungsvariablen in Infrastrukturdateien

Sie können Umgebungsvariablen verwenden, um Ihre Infrastrukturvorlagen anzupassen. Dies ist nützlich, um Ressourcen basierend auf der aktuellen Umgebung zu benennen, zu kategorisieren oder zu konfigurieren. azd verwendet auch Tags zum Auffinden von Ressourcen in Azure für die Bereitstellung und andere Aufgaben.

Berücksichtigen Sie den folgenden allgemeinen Fluss:

1. Während azd init setzt azd diese Umgebungsvariablen basierend auf der Antwort des Benutzers auf die Eingabeaufforderungen fest:

   AZURE_ENV_NAME=myapp-dev
   AZURE_LOCATION=eastus2
   

2. Verweisen Sie auf diese Variablen im main.parameters.json im infra Ordner. azd ersetzt die Werte während der Bereitstellung und übergibt die aufgelösten Parameter an Bicep:

   {
     "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
     "contentVersion": "1.0.0.0",
     "parameters": {
       "name": {
         "value": "${AZURE_ENV_NAME}"
       },
       "location": {
         "value": "${AZURE_LOCATION}"
       }
     }
   }
   

3. Definieren Sie übereinstimmende Parameter in Ihrer Bicep-Vorlage:

   @description('Name of the environment used to derive resource names and tags.')
   param name string
   
   @minLength(1)
   @description('Primary Azure region for all resources.')
   param location string
   

   azd liefert diese Bicep-Parameter mit den ersetzten Werten in main.parameters.json.

4. Verwenden Sie die Parameter für die Ressourcenbenennung und Tags, um später zu identifizieren, zu welcher Umgebung eine Ressource gehört:

   var resourceToken = toLower(uniqueString(resourceGroup().id, name, location))
   
   resource storageAccount 'Microsoft.Storage/storageAccounts@2022-09-01' = {
     name: 'st${resourceToken}'
     location: location
     sku: {
       name: 'Standard_LRS'
     }
     kind: 'StorageV2'
     tags: {
       Environment: name
       Project: 'myproject'
     }
   }
   

Dieses Muster behält Ihre Vorlagen flexibel bei, ermöglicht die Anpassung pro Umgebung ohne Codeänderungen und verbessert die Ressourcengovernance (Benennung, Tagging und Ermittlung).

Hinweis

azd verwendet ebenfalls Tags, um Azure-Ressourcen während der Bereitstellungsphase zu identifizieren.

Hooks

azd Umgebungsvariablen werden automatisch vorinstalliert und in Hooks und benutzerdefinierten Skripts in Ihrer azure.yaml Datei definiert, Sie können mithilfe der folgenden Syntax auf Umgebungsvariablen zugreifen:

Bash

# Use the variables in your script
echo "API endpoint: $API_ENDPOINT"
echo "Deploying to: $AZURE_LOCATION"

PowerShell

# Use the variables in your script
Write-Host "API endpoint: $API_ENDPOINT"
Write-Host "Deploying to: $AZURE_LOCATION"

Sie können Hooks in Ihrer azure.yaml Datei definieren, um diese Skripts an bestimmten Stellen im azd Lebenszyklus auszuführen:

hooks:
  postprovision:
    windows:
      shell: pwsh
      run: ./scripts/load-env-vars.ps1
      interactive: false
    posix:
      shell: sh
      run: ./scripts/load-env-vars.sh
      interactive: false

Tipp

Weitere Informationen zur Verwendung von Hooks finden Sie im Artikel "Workflows anpassen" mit Hooks .

Entfernen oder Aktualisieren von Variablen

So entfernen Sie eine Variable aus Ihrer Umgebung:

azd env unset VARIABLE_NAME

So aktualisieren Sie eine vorhandene Variable:

azd env set VARIABLE_NAME "new-value"

So aktualisieren Sie Ihre lokalen Umgebungsvariablen aus dem aktuellen Status Ihrer Azure-Ressourcen:

azd env refresh

Das Aktualisieren Ihrer Umgebung ist nützlich, wenn:

• Sie möchten sicherstellen, dass Ihre lokale .env Datei die neuesten Ausgaben Ihrer Infrastruktur widerspiegelt (z. B. Verbindungszeichenfolgen, Endpunkte usw.).
• Sie müssen Umgebungsvariablen synchronisieren, nachdem ein Teamkollege die Umgebung aktualisiert hat.

AZD- und Betriebssystemumgebungsvariablen

azd Umgebungsvariablen und Betriebssystemumgebungsvariablen dienen unterschiedlichen Zwecken und funktionieren auf unterschiedliche Weise:

Begriff	Azure Developer CLI (Befehlszeilenschnittstelle für Entwickler)	Betriebssystem
Standort	In .azure/<env-name>/.env Dateien gespeichert	Festlegen in Ihrer Betriebssystemumgebung
Umfang	Eingeschränkt auf eine spezifische benannte Umgebung innerhalb eines Projekts	Global für Ihre Benutzersitzung oder Ihr System
Verwaltung	Verwaltet mithilfe von azd env Befehlen	Verwaltet mit betriebssystemspezifischen Befehlen (export, setusw.)
Zugang	Automatisch von azd Befehlen geladen	In der Regel explizit in Skripts oder Anwendungen geladen
Target	An Azure-Ressourcen und -Bereitstellungen gebunden	Allgemeine Systemkonfiguration
Lebenszyklus	Zwischen Terminalsitzungen beibehalten	Kann temporär oder dauerhaft sein, je nachdem, wie sie festgelegt werden

azd liest oder schreibt keine Betriebssystemumgebungsvariablen automatisch. Sie können jedoch mit beiden Variablentypen mit benutzerdefinierten Skripts interagieren.

Lesen von azd Umgebungsvariablen und Betriebssystemumgebungsvariablen:

Bash

# Access OS environment variable
echo "OS variable: $PATH"

# Access azd environment variable
echo "AZD variable: $(azd env get-value MY_VARIABLE)"

PowerShell

# Access OS environment variable
Write-Host "OS variable: $env:PATH"

# Access azd environment variable
Write-Host "AZD variable: $(azd env get-value MY_VARIABLE)"

Schreiben Sie azd Umgebungsvariablen in die Betriebssystem- oder die Framework-Umgebungsvariablen:

Bash

# Load all azd environment variables into the current shell session
while IFS='=' read -r key value; do
    value=$(echo "$value" | sed 's/^"//' | sed 's/"$//')
    export "$key=$value"
done <<EOF
$(azd env get-values)
EOF

PowerShell

# Load all azd environment variables into the current PowerShell session
foreach ($line in (& azd env get-values)) {
    if ($line -match "([^=]+)=(.*)") {
        $key = $matches[1]
        $value = $matches[2] -replace '^"|"$'
        $env:$key = $value
    }
}

Standardumgebungsvariablen

azd legt mehrere allgemeine Umgebungsvariablen in allen Umgebungen fest und verwendet diese:

Variable	Beschreibung	Example	Wenn festgelegt
AZURE_ENV_NAME	Name der aktuellen Umgebung	dev	Wann eine Umgebung erstellt wird
AZURE_LOCATION	Azure-Region, in der Ressourcen bereitgestellt werden	eastus	Während der ersten Bereitstellung
AZURE_SUBSCRIPTION_ID	ID des verwendeten Azure-Abonnements	00000000-0000-0000-0000-000000000000	Während der ersten Bereitstellung
AZURE_RESOURCE_GROUP	Name der Ressourcengruppe	rg-myapp-dev	Während der Bereitstellung
AZURE_PRINCIPAL_ID	Die laufende Benutzer-/Dienstprinzipal-ID	00000000-0000-0000-0000-000000000000	Während der Bereitstellung
AZURE_PRINCIPAL_TYPE	Der Typ eines Prinzipals in der Umgebung.	1a2b3c	Während der Bereitstellung
AZURE_TENANT_ID	ID des verwendeten Azure-Mandanten.	00000000-0000-0000-0000-000000000000	Während der Bereitstellung

Überlegungen zu geheimen und vertraulichen Daten

Während Umgebungsvariablen für die Konfiguration geeignet sind, benötigen sie eine spezielle Behandlung für vertrauliche Daten:

Vermeiden des Speicherns geheimer Schlüssel in env-Dateien

.env Dateien werden in der Regel als Klartext gespeichert und können leicht verarbeitet werden:

• Versehentlicher Commit zur Quellcodeverwaltung
• Geteilt oder kopiert ohne richtigen Schutz
• Von jedem mit Zugriff auf die Projektdateien angezeigt
• In Protokollen oder Fehlerberichten enthalten

Warnung

Speichern Sie geheime Schlüssel niemals in einer Azure Developer CLI-Datei .env . Diese Dateien können problemlos freigegeben oder an nicht autorisierte Speicherorte kopiert oder in die Quellcodeverwaltung eingecheckt werden. Verwenden Sie Dienste wie Azure Key Vault oder Azure Role Based Access Control (RBAC) für geschützte oder schlüssellose Lösungen.

Alternativen zum Umgang mit Geheimnissen

Berücksichtigen Sie bei vertraulichen Daten die folgenden sichereren Ansätze:

• Verweise auf Azure Key Vault: Speichern Sie geheime Schlüssel in Azure Key Vault, und verweisen Sie in Ihrer .env Datei darauf:

  azd env set-secret <secret-value>
  

  Mit diesem Befehl wird ein Schlüsseltresorgeheimnis erstellt und ein Verweis darauf in Ihrer .env Datei statt auf den tatsächlichen Wert gespeichert.

• Verwaltete Identitäten: Konfigurieren Sie Ihre Azure-Dienste so, dass verwaltete Identitäten anstelle von Verbindungszeichenfolgen oder Zugriffstasten verwendet werden.

• Umgebungsspezifische Sicherheit: Wenden Sie strengere Sicherheitskontrollen auf Produktionsumgebungen an als Entwicklungsumgebungen.

• Just-in-Time-Geheime Schlüssel: Generieren Sie während der Bereitstellung kurzlebige Anmeldeinformationen, anstatt dauerhafte geheime Schlüssel zu speichern.

Nächste Schritte

Arbeiten mit Umgebungen in der Azure Developer CLIPassen Sie Ihre Azure Developer CLI-Workflows mithilfe von Hooks an