Arbeta med Azure Developer CLI-miljövariabler

Azure Developer CLI (azd) använder miljövariabler för att lagra och hantera konfigurationsinställningar för distributionsmiljöer. Dessa variabler styr hur ditt program etableras, distribueras och körs i Azure. Den här artikeln beskriver hur miljövariabler fungerar i azd miljöer och ger vägledning om hur du hanterar dem effektivt.

Förstå miljövariabler

I kontexten för Azure Developer CLI är miljövariabler nyckel/värde-par som är knutna till specifika namngivna miljöer som dev, test eller prod. Varje azd miljö har en egen uppsättning miljövariabler så att du kan konfigurera olika inställningar för olika distributionsmål.

Miljövariabler i azd lagras i filer i .env dina miljömappar i .azure mappen. De fungerar som indata för att:

• Arbetsflöden för programdistribution
• Konfigurationer för Azure-tjänster och -anslutningar
• Infrastrukturetablering via Bicep och Terraform

Till skillnad från traditionella miljövariabler som finns på operativsystemnivå azd begränsas miljövariabler till specifika miljöer i projektet, vilket ger isolering mellan olika distributionsmål.

Miljövariabler ger flera viktiga fördelar när du arbetar med azd:

• Miljöisolering: Håll konfigurationerna för utveckling, testning och produktion åtskilda och distinkta.
• Konfigurationskonsekvens: Se till att alla teammedlemmar använder samma inställningar för en specifik miljö.
• Infrastruktur som kod: Definiera infrastrukturparameterisering via variabler i stället för hårdkodade värden.
• Distributionsautomatisering: Aktivera CI/CD-pipelines för att distribuera till olika miljöer med samma kodbas men olika konfigurationer.
• Förenklad hantering: Uppdatera enkelt inställningarna för alla tjänster i en miljö från en central plats.

Varje azd miljö har en egen uppsättning variabler, vilket möjliggör miljöspecifika konfigurationer samtidigt som samma programkod och infrastrukturmallar används.

Miljövariabler och .env-filer

Miljövariablerna azd lagras i .env filer i de miljöspecifika katalogerna i projektet. När du skapar en miljö med azd env new <name> skapas en katalogstruktur:

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

Filen .env använder ett standardformat där varje rad representerar ett nyckel/värde-par:

KEY1=value1
KEY2=value2

När du kör kommandon som azd upläser automatiskt azd in variabler från select-miljöns .env fil.

Dessa variabler påverkar:

• Infrastrukturetablering: Variabler som AZURE_LOCATION och AZURE_SUBSCRIPTION_ID avgör var och hur resurser skapas.
• Distribution: Variabler som tjänstslutpunkter styr hur ditt program ansluter till Azure-tjänster.
• Programkonfiguration: Variabler kan skickas till programkonfigurationen för att styra dess beteende.
• Resursnamngivning: Variabler som AZURE_RESOURCE_GROUP påverkar resursnamngivningsmönster.

Filen .env uppdateras också automatiskt genom azd att under åtgärder som azd init, azd provisionoch azd deploy, samla in utdata från dina infrastrukturmallar och lagra dem för framtida användning.

Ange miljövariabler

Du kan använda olika metoder för att ange azd miljövariabler, beroende på scenariot.

Använda CLI-kommandon

Det rekommenderade sättet att ange en miljövariabel är att använda azd env set kommandot, som innehåller kontroller för att säkerställa giltiga värden:

azd env set <key> <value>

Om du till exempel vill ange ett konfigurationsvärde för ditt program:

azd env set API_TIMEOUT 5000

Kommandot lägger till eller uppdaterar variabeln .env i filen i den aktuella miljön. Du kan också rikta in dig på en specifik miljö med hjälp av --environment flaggan:

azd env set API_TIMEOUT 5000 --environment prod

Så här kontrollerar du att miljövariabeln har angetts korrekt:

azd env get-value API_TIMEOUT

Utdata från Bicep

En kraftfull funktion hos azd är dess förmåga att automatiskt fånga upp utdataparametrar från dina Bicep-infrastrukturmallar som miljövariabler. När du till exempel definierar en utdataparameter i main.bicep filen:

output API_ENDPOINT string = apiService.outputs.SERVICE_ENDPOINT_URL

När du har kört azd provisionsparas dessa utdata automatiskt i miljöns .env fil:

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

Den här metoden säkerställer att ditt program alltid har åtkomst till den senaste resursinformationen, till exempel:

• Tjänstslutpunkter och URL:er
• Resursnamn och identifierare

Hämta och använda miljövariabler

När de väl är angivna kan du komma åt miljövariabler i olika sammanhang.

CLI-kommandon

Så här visar du alla miljövariabler för den aktuella miljön:

azd env get-values

Så här visar du värdet för en specifik variabel:

azd env get-value API_ENDPOINT

För maskinläsbara utdata (användbara i skript):

azd env get-values --output json

Använda miljövariabler i infrastrukturfiler

Du kan använda miljövariabler för att anpassa dina infrastrukturmallar. Detta är användbart för att namnge, tagga eller konfigurera resurser baserat på den aktuella miljön. azd använder också taggar för att hitta resurser i Azure för distribution och andra uppgifter.

Tänk på följande vanliga flöde:

1. Under tiden azd init definierar azd dessa miljövariabler baserat på användarens svar på uppmaningar:

   AZURE_ENV_NAME=myapp-dev
   AZURE_LOCATION=eastus2
   

2. Referera till variablerna i main.parameters.jsoninfra mappen. azd ersätter värdena under provisioneringen och skickar de lösade parametrarna till 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. Definiera matchande parametrar i Bicep-mallen:

   @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 försörjer dessa Bicep-parametrar med de ersatta värdena i main.parameters.json.

4. Använd parametrarna för namngivning av resurser och taggar för att senare identifiera vilken miljö en resurs tillhör:

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

Det här mönstret håller dina mallar flexibla, möjliggör anpassning per miljö utan kodändringar och förbättrar resursstyrningen (namngivning, taggning och identifiering).

Hookar

azd miljövariabler förinstalleras automatiskt och är tillgängliga i krokar och anpassade skript som definieras i azure.yaml filen. Du kan komma åt miljövariabler med hjälp av följande syntax:

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

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

Du kan definiera krokar i azure.yaml filen för att köra dessa skript vid specifika tidpunkter i azd livscykeln:

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

Ta bort eller uppdatera variabler

Så här tar du bort en variabel från din miljö:

azd env unset VARIABLE_NAME

Så här uppdaterar du en befintlig variabel:

azd env set VARIABLE_NAME "new-value"

Så här uppdaterar du dina lokala miljövariabler från det aktuella tillståndet för dina Azure-resurser:

azd env refresh

Det är användbart att uppdatera din miljö när:

• Du vill se till att den lokala .env filen återspeglar de senaste utdata från infrastrukturen (t.ex. anslutningssträngar, slutpunkter osv.).
• Du måste synkronisera miljövariabler när en lagkamrat har uppdaterat miljön.

AZD- och OS-miljövariabler

azd miljövariabler och miljövariabler för operativsystem har olika syften och fungerar på olika sätt:

azd läser eller skriver inte os-miljövariabler automatiskt. Du kan dock interagera med båda typerna av variabler med hjälp av anpassade skript.

Läsa azd miljövariabler och OS-miljövariabler:

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

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

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

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

Skriva azd miljövariabler till os- eller ramverksmiljövariabler:

# 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

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

Standardmiljövariabler

azd anger och använder flera vanliga miljövariabler i alla miljöer:

Överväganden för hemligheter och känsliga data

Miljövariabler är praktiska för konfiguration, men de kräver särskild hantering av känsliga data:

Undvik att lagra hemligheter i .env-filer

.env filer lagras vanligtvis i oformaterad text och kan enkelt vara:

• Av misstag checkas in på källkontroll
• Delat eller kopierat utan rätt skydd
• Visad av alla som har åtkomst till projektfilerna
• Ingår i loggar eller felrapporter

Alternativ för hantering av hemligheter

För känsliga data bör du överväga följande säkrare metoder:

• Azure Key Vault-referenser: Lagra hemligheter i Azure Key Vault och referera till dem i filen .env :

  azd env set-secret <secret-value>
  

  Det här kommandot skapar en Key Vault hemlighet och lagrar en referens till den i .env-filen istället för det faktiska värdet.

• Hanterade identiteter: Konfigurera dina Azure-tjänster så att de använder hanterade identiteter i stället för anslutningssträngar eller åtkomstnycklar.

• Miljöspecifik säkerhet: Tillämpa striktare säkerhetskontroller på produktionsmiljöer än utvecklingsmiljöer.

• Just-in-time-hemligheter: Generera kortlivade autentiseringsuppgifter under distributionen i stället för att lagra beständiga hemligheter.

Nästa steg