Praca ze zmiennymi środowiskowymi interfejsu wiersza polecenia dla deweloperów platformy Azure

Interfejs wiersza polecenia dla deweloperów platformy Azure (azd) używa zmiennych środowiskowych do przechowywania ustawień konfiguracji dla środowisk wdrażania i zarządzania nimi. Te zmienne kontrolują sposób aprowizowania, wdrażania i uruchamiania aplikacji na platformie Azure. W tym artykule wyjaśniono, jak zmienne środowiskowe działają w azd środowiskach i zawierają wskazówki dotyczące efektywnego zarządzania nimi.

Omówienie zmiennych środowiskowych

W kontekście interfejsu wiersza polecenia dla deweloperów platformy Azure zmienne środowiskowe to pary klucz-wartość, które są powiązane z określonymi nazwanymi środowiskami, takimi jak tworzenie, testowanie lub prod. Każde azd środowisko zachowuje własny zestaw zmiennych środowiskowych, co umożliwia skonfigurowanie różnych ustawień dla różnych celów wdrożenia.

Zmienne środowiskowe w programie azd są przechowywane w plikach .env znajdujących się w folderach środowiskowych w folderze .azure. Służą one jako dane wejściowe do:

• Przepływy pracy wdrażania aplikacji
• Konfiguracje usług i połączeń platformy Azure
• Aprowizowanie infrastruktury za pośrednictwem narzędzi Bicep i Terraform

W przeciwieństwie do tradycyjnych zmiennych środowiskowych, które istnieją na poziomie systemu operacyjnego, azd zmienne środowiskowe są ograniczone do określonych środowisk w projekcie, zapewniając izolację między różnymi celami wdrożenia.

Zmienne środowiskowe zapewniają kilka kluczowych korzyści podczas pracy z usługą azd:

• Izolacja środowiskowa: zachowaj konfiguracje na potrzeby programowania, testowania i produkcji oddzielne i odrębne.
• Spójność konfiguracji: Upewnij się, że wszyscy członkowie zespołu używają tych samych ustawień dla określonego środowiska.
• Infrastruktura jako kod: zdefiniuj parametryzację infrastruktury za pomocą zmiennych zamiast zakodowanych wartości.
• Automatyzacja wdrażania: umożliwienie potokom CI/CD wdrażania do różnych środowisk przy użyciu tej samej bazy kodu, ale różnych konfiguracji.
• Uproszczone zarządzanie: łatwe aktualizowanie ustawień we wszystkich usługach w środowisku z centralnej lokalizacji.

Każde azd środowisko ma własny zestaw zmiennych, umożliwiając konfiguracje specyficzne dla środowiska podczas korzystania z tego samego kodu aplikacji i szablonów infrastruktury.

Zmienne środowiskowe i pliki env

azd Zmienne środowiskowe są przechowywane w plikach w .env katalogach specyficznych dla środowiska projektu. Podczas tworzenia środowiska przy użyciu programu azd env new <name>tworzona jest struktura katalogów:

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

Plik .env używa standardowego formatu, w którym każdy wiersz reprezentuje parę klucz-wartość:

KEY1=value1
KEY2=value2

Wskazówka

Więcej informacji na temat środowisk można znaleźć w artykule azd.

Po uruchomieniu poleceń, takich jak azd up, azd automatycznie ładuje zmienne z pliku wybranego .env środowiska.

Te zmienne mają wpływ na:

• Zapewnianie infrastruktury: zmienne, takie jak AZURE_LOCATION i AZURE_SUBSCRIPTION_ID określają, gdzie i w jaki sposób są tworzone zasoby.
• Wdrożenie: zmienne, takie jak punkty końcowe usługi, kontrolują sposób łączenia aplikacji z usługami platformy Azure.
• Konfiguracja aplikacji: zmienne można przekazać do konfiguracji aplikacji, aby kontrolować jej zachowanie.
• Nazewnictwo zasobów: zmienne, takie jak AZURE_RESOURCE_GROUP wpływ na wzorce nazewnictwa zasobów.

Plik .env jest również automatycznie aktualizowany przez azd podczas operacji takich jak azd init, azd provision i azd deploy, przechwytuje dane wyjściowe z szablonów infrastruktury i przechowuje je do użytku w przyszłości.

Ustawianie zmiennych środowiskowych

W zależności od scenariusza można użyć różnych metod ustawiania azd zmiennych środowiskowych.

Używanie poleceń CLI

Zalecanym sposobem ustawienia zmiennej środowiskowej jest użycie azd env set polecenia , które obejmuje kontrole w celu zapewnienia prawidłowych wartości:

azd env set <key> <value>

Aby na przykład ustawić wartość konfiguracji dla aplikacji:

azd env set API_TIMEOUT 5000

Polecenie dodaje lub aktualizuje zmienną w .env pliku aktualnie wybranego środowiska. Możesz również kierować do określonego środowiska przy użyciu flagi --environment :

azd env set API_TIMEOUT 5000 --environment prod

Aby sprawdzić, czy zmienna środowiskowa została prawidłowo ustawiona:

azd env get-value API_TIMEOUT

Dane wyjściowe z Bicep

Zaawansowaną funkcją azd jest możliwość automatycznego przechwytywania parametrów wyjściowych z szablonów infrastruktury Bicep jako zmiennych środowiskowych. Na przykład podczas definiowania parametru wyjściowego w main.bicep pliku:

output API_ENDPOINT string = apiService.outputs.SERVICE_ENDPOINT_URL

Po uruchomieniu azd provisionnastępujące dane wyjściowe są automatycznie zapisywane w pliku środowiska .env :

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

Takie podejście zapewnia, że aplikacja zawsze ma dostęp do najbardziej aktualnych informacji o zasobach, takich jak:

• Punkty końcowe i adresy URL usługi
• Nazwy zasobów i identyfikatory

Pobieranie zmiennych środowiskowych i korzystanie z nich

Po ustawieniu można uzyskać dostęp do zmiennych środowiskowych w kilku kontekstach.

Polecenia CLI

Aby wyświetlić wszystkie zmienne środowiskowe dla bieżącego środowiska:

azd env get-values

Aby wyświetlić wartość określonej zmiennej:

azd env get-value API_ENDPOINT

W przypadku danych wyjściowych z możliwością odczytu maszyny (przydatne w skryptach):

azd env get-values --output json

Używanie zmiennych środowiskowych w plikach infrastruktury

Zmienne środowiskowe umożliwiają dostosowywanie szablonów infrastruktury. Jest to przydatne w przypadku nazewnictwa, tagowania lub konfigurowania zasobów na podstawie bieżącego środowiska. azd Używa również tagów do lokalizowania zasobów na platformie Azure na potrzeby wdrażania i innych zadań.

Rozważmy następujący typowy przepływ:

1. Podczas azd initazd ustawia te zmienne środowiskowe na podstawie odpowiedzi użytkownika na monity:

   AZURE_ENV_NAME=myapp-dev
   AZURE_LOCATION=eastus2
   

2. Odwołaj się do tych zmiennych w main.parameters.json folderze infra. azd zastępuje wartości podczas aprowizacji i przekazuje rozpoznane parametry do 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. Zdefiniuj pasujące parametry w szablonie Bicep:

   @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 dostarcza te parametry Bicep z zastąpionymi wartościami w pliku main.parameters.json.

4. Użyj parametrów nazewnictwa zasobów i tagów, aby później zidentyfikować środowisko, do którego należy zasób:

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

Ten wzorzec zapewnia elastyczność szablonów, umożliwia dostosowywanie poszczególnych środowisk bez zmian kodu i poprawia ład zasobów (nazewnictwo, tagowanie i odnajdywanie).

Uwaga / Notatka

azd ponadto polega na tagowaniu w celu zlokalizowania zasobów platformy Azure na etapie wdrażania.

Punkty zaczepienia

azd zmienne środowiskowe są automatycznie wstępnie załadowane i dostępne w hookach i skryptach niestandardowych zdefiniowanych w azure.yaml pliku. Można uzyskać dostęp do zmiennych środowiskowych przy użyciu następującej składni:

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"

Możesz zdefiniować hooki w pliku azure.yaml aby uruchamiać te skrypty w specyficznych punktach cyklu życia azd.

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

Wskazówka

Aby uzyskać więcej informacji na temat korzystania z punktów zaczepienia, zobacz artykuł Dostosowywanie przepływów pracy przy użyciu punktów zaczepienia .

Usuwanie lub aktualizowanie zmiennych

Aby usunąć zmienną ze środowiska:

azd env unset VARIABLE_NAME

Aby zaktualizować istniejącą zmienną:

azd env set VARIABLE_NAME "new-value"

Aby odświeżyć lokalne zmienne środowiskowe na podstawie bieżącego stanu zasobów platformy Azure:

azd env refresh

Odświeżanie środowiska jest przydatne w następujących przypadkach:

• Chcesz mieć pewność, że plik lokalny .env odzwierciedla najnowsze dane wyjściowe z infrastruktury (takie jak parametry połączenia, punkty końcowe itp.).
• Należy zsynchronizować zmienne środowiskowe po zaktualizowaniu środowiska przez kolegę z zespołu.

Porównanie zmiennych środowiskowych AZD i OS

azd zmienne środowiskowe i zmienne środowiskowe systemu operacyjnego służą różnym celom i działają na różne sposoby:

Pojęcie	Azure Developer CLI	System operacyjny
Lokalizacja	Przechowywane w .azure/<env-name>/.env plikach	Ustaw w środowisku swojego systemu operacyjnego
Scope	Zakres określony nazwanego środowiska w projekcie	Globalne dla sesji użytkownika lub dla systemu
Zarządzanie	Zarządzane przy użyciu azd env poleceń	Zarządzane przy użyciu poleceń specyficznych dla systemu operacyjnego (export, setitp.)
Access	Ładowane automatycznie przez azd komendy	Zazwyczaj ładowane jawnie w skryptach lub aplikacjach
Target	Powiązane z zasobami i wdrożeniami platformy Azure	Konfiguracja systemu ogólnego przeznaczenia
Cykl życia	Zachowanie między sesjami terminalu	Może być tymczasowe lub trwałe w zależności od sposobu ich ustawiania

azd nie odczytuje ani nie zapisuje zmiennych środowiskowych systemu operacyjnego. Można jednak wchodzić w interakcje z obydwoma typami zmiennych przy użyciu skryptów niestandardowych.

Odczyt azd zmiennych środowiskowych i zmiennych środowiskowych systemu operacyjnego:

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)"

Zapisz azd zmienne środowiskowe w zmienne środowiskowe systemu operacyjnego lub środowiska uruchomieniowego:

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

Standardowe zmienne środowiskowe

azd ustawia i używa kilku typowych zmiennych środowiska we wszystkich środowiskach.

Variable	opis	Example	Po ustawieniu
AZURE_ENV_NAME	Nazwa bieżącego środowiska	dev	Po utworzeniu środowiska
AZURE_LOCATION	Region świadczenia usługi Azure, w którym wdrażane są zasoby	eastus	Podczas pierwszej konfiguracji
AZURE_SUBSCRIPTION_ID	Identyfikator użytej subskrypcji platformy Azure	00000000-0000-0000-0000-000000000000	Podczas pierwszej konfiguracji
AZURE_RESOURCE_GROUP	Nazwa grupy zasobów	rg-myapp-dev	Podczas konfiguracji
AZURE_PRINCIPAL_ID	Identyfikator uruchamianego użytkownika/głównego identyfikatora usługi	00000000-0000-0000-0000-000000000000	Podczas konfiguracji
AZURE_PRINCIPAL_TYPE	Typ podmiotu w środowisku.	1a2b3c	Podczas konfiguracji
AZURE_TENANT_ID	Identyfikator dzierżawy platformy Azure używany.	00000000-0000-0000-0000-000000000000	Podczas konfiguracji

Zagadnienia dotyczące tajemnic i poufnych danych

Zmienne środowiskowe są wygodne w konfiguracji, ale wymagają specjalnej obsługi poufnych danych:

Unikaj przechowywania wpisów tajnych w plikach env

.env pliki są zwykle przechowywane w postaci zwykłego tekstu, co ułatwia ich edycję lub modyfikację.

• Przypadkowo zatwierdzone do systemu kontroli wersji
• Udostępnione lub skopiowane bez odpowiednich zabezpieczeń
• Wyświetlane przez wszystkich użytkowników z dostępem do plików projektu
• Uwzględnione w dziennikach lub raportach o błędach

Ostrzeżenie

Nigdy nie przechowuj sekretów w pliku Azure Developer CLI .env. Te pliki można łatwo udostępnić lub skopiować do nieautoryzowanych lokalizacji lub zaewidencjonować w kontroli źródła. Używaj usług, takich jak Azure Key Vault lub Azure Role Based Access Control (RBAC) dla rozwiązań chronionych lub bez tajemnicy.

Alternatywy dla obsługi tajemnic

W przypadku danych poufnych należy wziąć pod uwagę następujące bezpieczniejsze podejścia:

• Odwołania do usługi Azure Key Vault: Przechowywanie wpisów tajnych w usłudze Azure Key Vault i odwołanie się do nich w .env pliku:

  azd env set-secret <secret-value>
  

  To polecenie tworzy tajemnicę usługi Key Vault i przechowuje odwołanie do niej zamiast rzeczywistej wartości w pliku .env.

• Tożsamości zarządzane: skonfiguruj usługi platformy Azure tak, aby używały tożsamości zarządzanych zamiast parametrów połączenia lub kluczy dostępu.

• Zabezpieczenia specyficzne dla środowiska: stosowanie bardziej rygorystycznych mechanizmów kontroli zabezpieczeń do środowisk produkcyjnych niż środowiska programistyczne.

• Wpisy tajne just in time: generowanie poświadczeń krótkotrwałych podczas wdrażania zamiast przechowywania trwałych wpisów tajnych.

Dalsze kroki

Praca ze środowiskami w interfejsie wiersza polecenia dewelopera platformy AzureDostosowywanie przepływów pracy interfejsu wiersza polecenia dla deweloperów platformy Azure przy użyciu punktów zaczepienia