Bekerja dengan variabel lingkungan Azure Developer CLI

Azure Developer CLI (azd) menggunakan variabel lingkungan untuk menyimpan dan mengelola pengaturan konfigurasi untuk lingkungan penyebaran. Variabel ini mengontrol bagaimana aplikasi Anda disediakan, disebarkan, dan berjalan di Azure. Artikel ini menjelaskan cara kerja variabel lingkungan dalam azd lingkungan dan memberikan panduan tentang mengelolanya secara efektif.

Memahami variabel lingkungan

Dalam konteks Azure Developer CLI, variabel lingkungan adalah pasangan kunci-nilai yang terkait dengan lingkungan bernama tertentu seperti dev, test, atau prod. Setiap azd lingkungan mempertahankan serangkaian variabel lingkungannya sendiri, memungkinkan Anda mengonfigurasi pengaturan yang berbeda untuk target penyebaran yang berbeda.

Variabel lingkungan di azd disimpan dalam file dalam .env folder lingkungan Anda di .azure folder . Mereka berfungsi sebagai input untuk:

• Alur kerja penyebaran aplikasi
• Konfigurasi untuk layanan dan koneksi Azure
• Provisi infrastruktur melalui Bicep dan Terraform

Tidak seperti variabel lingkungan tradisional yang ada di tingkat sistem operasi, azd variabel lingkungan dilingkupkan ke lingkungan tertentu dalam proyek Anda, memberikan isolasi antara target penyebaran yang berbeda.

Variabel lingkungan memberikan beberapa manfaat utama saat bekerja dengan azd:

• Isolasi lingkungan: Menjaga konfigurasi untuk pengembangan, pengujian, dan produksi terpisah dan berbeda.
• Konsistensi konfigurasi: Pastikan semua anggota tim menggunakan pengaturan yang sama untuk lingkungan tertentu.
• Infrastruktur sebagai Kode: Tentukan parameterisasi infrastruktur melalui variabel alih-alih nilai yang dikodekan secara permanen.
• Otomatisasi penyebaran: Aktifkan alur CI/CD untuk disebarkan ke lingkungan yang berbeda menggunakan basis kode yang sama tetapi konfigurasi yang berbeda.
• Manajemen yang disederhanakan: Memperbarui pengaturan dengan mudah di semua layanan di lingkungan dari lokasi pusat.

Setiap azd lingkungan memiliki serangkaian variabelnya sendiri, memungkinkan konfigurasi khusus lingkungan saat menggunakan kode aplikasi dan templat infrastruktur yang sama.

Variabel lingkungan dan file .env

Variabel azd lingkungan disimpan dalam file dalam .env direktori khusus lingkungan proyek Anda. Saat Anda membuat lingkungan menggunakan azd env new <name>, struktur direktori dibuat:

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

File .env menggunakan format standar di mana setiap baris mewakili pasangan kunci-nilai:

KEY1=value1
KEY2=value2

Petunjuk / Saran

Kunjungi artikel Bekerja dengan lingkungan untuk informasi selengkapnya tentang azd lingkungan.

Saat Anda menjalankan perintah seperti azd up, azd secara otomatis memuat variabel dari file lingkungan .env tertentu.

Variabel ini memengaruhi:

• Provisi infrastruktur: Variabel menyukai AZURE_LOCATION dan AZURE_SUBSCRIPTION_ID menentukan di mana dan bagaimana sumber daya dibuat.
• Penyebaran: Variabel seperti titik akhir layanan mengontrol cara aplikasi Anda terhubung ke layanan Azure.
• Konfigurasi aplikasi: Variabel dapat diteruskan ke konfigurasi aplikasi Anda untuk mengontrol perilakunya.
• Penamaan sumber daya: Variabel seperti AZURE_RESOURCE_GROUP memengaruhi pola penamaan sumber daya.

File .env juga diperbarui secara otomatis oleh azd selama operasi seperti azd init, azd provision, dan azd deploy, menangkap output dari templat infrastruktur Anda dan menyimpannya untuk digunakan di masa mendatang.

Atur variabel lingkungan

Anda dapat menggunakan metode yang berbeda untuk mengatur azd variabel lingkungan, tergantung pada skenarionya.

Menggunakan perintah CLI

Cara yang disarankan untuk mengatur variabel lingkungan adalah menggunakan azd env set perintah , yang mencakup pemeriksaan untuk memastikan nilai yang valid:

azd env set <key> <value>

Misalnya, untuk menetapkan nilai konfigurasi untuk aplikasi Anda:

azd env set API_TIMEOUT 5000

Perintah menambahkan atau memperbarui variabel dalam .env file lingkungan yang saat ini dipilih. Anda juga dapat menargetkan lingkungan tertentu menggunakan --environment bendera :

azd env set API_TIMEOUT 5000 --environment prod

Untuk memverifikasi bahwa variabel lingkungan Anda diatur dengan benar:

azd env get-value API_TIMEOUT

Output dari Bicep

Fitur azd yang kuat adalah kemampuannya untuk menangkap parameter output secara otomatis dari templat infrastruktur Bicep Anda sebagai variabel lingkungan. Misalnya, saat Anda menentukan parameter output dalam file Anda main.bicep :

output API_ENDPOINT string = apiService.outputs.SERVICE_ENDPOINT_URL

Setelah menjalankan azd provision, output ini secara otomatis disimpan ke file lingkungan .env :

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

Pendekatan ini memastikan bahwa aplikasi Anda selalu memiliki akses ke informasi sumber daya terbaru, seperti:

• Titik akhir dan URL layanan
• Nama dan pengidentifikasi sumber daya

Mendapatkan dan menggunakan variabel lingkungan

Setelah diatur, Anda dapat mengakses variabel lingkungan dalam beberapa konteks.

Perintah CLI

Untuk melihat semua variabel lingkungan untuk lingkungan saat ini:

azd env get-values

Untuk melihat nilai variabel tertentu:

azd env get-value API_ENDPOINT

Untuk output yang dapat dibaca mesin (berguna dalam skrip):

azd env get-values --output json

Menggunakan variabel lingkungan dalam file infrastruktur

Anda dapat menggunakan variabel lingkungan untuk menyesuaikan templat infrastruktur Anda. Ini berguna untuk penamaan, pemberian tag, atau konfigurasi sumber daya berdasarkan lingkungan saat ini. azd juga menggunakan tag untuk menemukan sumber daya di Azure untuk penyebaran dan tugas lainnya.

Pertimbangkan alur umum berikut:

1. Selama azd init, azd mengatur variabel lingkungan ini berdasarkan respons pengguna terhadap perintah:

   AZURE_ENV_NAME=myapp-dev
   AZURE_LOCATION=eastus2
   

2. Referensikan variabel tersebut main.parameters.json dalam infra folder . azd menggantikan nilai selama provisi dan meneruskan parameter yang diselesaikan ke 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. Tentukan parameter yang cocok di templat Bicep Anda:

   @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 memasok parameter Bicep ini dengan nilai pengganti dalam main.parameters.json.

4. Gunakan parameter untuk penamaan sumber daya dan tag untuk mengidentifikasi lingkungan mana yang dimiliki sumber daya:

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

Pola ini menjaga templat Anda tetap fleksibel, memungkinkan penyesuaian per lingkungan tanpa perubahan kode, dan meningkatkan tata kelola sumber daya (penamaan, pemberian tag, dan penemuan).

Nota

azd juga bergantung pada pemberian tag untuk menemukan sumber daya Azure selama tahap penyebaran.

Hook

azd variabel lingkungan secara otomatis dimuat sebelumnya dan tersedia dalam kait dan skrip kustom yang ditentukan dalam file Anda azure.yaml , Anda dapat mengakses variabel lingkungan menggunakan sintaks berikut:

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"

Anda dapat menentukan kait dalam file Anda azure.yaml untuk menjalankan skrip ini pada titik tertentu dalam azd siklus hidup:

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

Petunjuk / Saran

Kunjungi artikel Kustomisasi alur kerja menggunakan hook untuk informasi selengkapnya tentang menggunakan kait.

Menghapus atau memperbarui variabel

Untuk menghapus variabel dari lingkungan Anda:

azd env unset VARIABLE_NAME

Untuk memperbarui variabel yang ada:

azd env set VARIABLE_NAME "new-value"

Untuk merefresh variabel lingkungan lokal Anda dari status sumber daya Azure Anda saat ini:

azd env refresh

Merefresh lingkungan Anda berguna saat:

• Anda ingin memastikan file lokal .env Anda mencerminkan output terbaru dari infrastruktur Anda (seperti string koneksi, titik akhir, dll.).
• Anda perlu menyinkronkan variabel lingkungan setelah rekan satu tim memperbarui lingkungan.

Variabel lingkungan AZD vs OS

azd variabel lingkungan dan variabel lingkungan sistem operasi melayani tujuan yang berbeda dan bekerja dengan cara yang berbeda:

Konsep	Azure Developer CLI	Sistem operasi
Lokasi	Disimpan dalam .azure/<env-name>/.env file	Diatur di lingkungan sistem operasi Anda
Ruang lingkup	Dilingkup ke lingkungan bernama tertentu dalam proyek	Global ke sesi atau sistem pengguna Anda
Direksi	Dikelola menggunakan azd env perintah	Dikelola menggunakan perintah khusus OS (export, , setdll.)
Access	Dimuat secara otomatis menurut azd perintah	Biasanya dimuat secara eksplisit dalam skrip atau aplikasi
Target	Terkait dengan sumber daya dan penyebaran Azure	Konfigurasi sistem tujuan umum
Siklus hidup	Bertahan di antara sesi terminal	Mungkin bersifat sementara atau persisten tergantung pada bagaimana mereka diatur

azd tidak secara otomatis membaca atau menulis variabel lingkungan OS. Namun, Anda dapat berinteraksi dengan kedua jenis variabel menggunakan skrip kustom.

Membaca azd variabel lingkungan dan variabel lingkungan OS:

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

Tulis azd variabel lingkungan ke OS atau variabel lingkungan kerangka kerja:

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

Variabel lingkungan standar

azd mengatur dan menggunakan beberapa variabel lingkungan umum di semua lingkungan:

Variable	Deskripsi	Example	Saat Diatur
AZURE_ENV_NAME	Nama lingkungan saat ini	dev	Saat lingkungan dibuat
AZURE_LOCATION	Wilayah Azure tempat sumber daya disebarkan	eastus	Selama provisi pertama
AZURE_SUBSCRIPTION_ID	ID langganan Azure yang digunakan	00000000-0000-0000-0000-000000000000	Selama provisi pertama
AZURE_RESOURCE_GROUP	Nama grup sumber daya	rg-myapp-dev	Selama provisi
AZURE_PRINCIPAL_ID	ID perwakilan pengguna/layanan yang sedang berjalan	00000000-0000-0000-0000-000000000000	Selama provisi
AZURE_PRINCIPAL_TYPE	Jenis prinsipal di lingkungan.	1a2b3c	Selama provisi
AZURE_TENANT_ID	ID penyewa Azure yang digunakan.	00000000-0000-0000-0000-000000000000	Selama provisi

Rahasia dan pertimbangan data sensitif

Meskipun variabel lingkungan nyaman untuk konfigurasi, variabel tersebut memerlukan penanganan khusus untuk data sensitif:

Hindari menyimpan rahasia dalam file .env

.env file biasanya disimpan dalam teks biasa dan dapat dengan mudah:

• Tidak sengaja berkomitmen pada kontrol sumber
• Dibagikan atau disalin tanpa perlindungan yang tepat
• Dilihat oleh siapa saja yang memiliki akses ke file proyek
• Disertakan dalam log atau laporan kesalahan

Peringatan

Jangan pernah menyimpan rahasia dalam file Azure Developer CLI .env . File-file ini dapat dengan mudah dibagikan atau disalin ke lokasi yang tidak sah, atau diperiksa ke kontrol sumber. Gunakan layanan seperti Azure Key Vault atau Azure Role Based Access Control (RBAC) untuk solusi yang dilindungi atau tanpa rahasia.

Alternatif untuk menangani rahasia

Untuk data sensitif, pertimbangkan pendekatan yang lebih aman ini:

• Referensi Azure Key Vault: Simpan rahasia di Azure Key Vault dan referensikan di file Anda .env :

  azd env set-secret <secret-value>
  

  Perintah ini membuat rahasia Key Vault dan menyimpan referensi ke dalam file Anda .env daripada nilai aktual.

• Identitas terkelola: Konfigurasikan layanan Azure Anda untuk menggunakan identitas terkelola alih-alih string koneksi atau kunci akses.

• Keamanan khusus lingkungan: Terapkan kontrol keamanan yang lebih ketat ke lingkungan produksi daripada yang dikembangkan.

• Rahasia just-in-time: Menghasilkan kredensial berumur pendek selama penyebaran daripada menyimpan rahasia persisten.

Langkah selanjutnya

Bekerja dengan lingkungan di Azure Developer CLISesuaikan alur kerja Azure Developer CLI Anda menggunakan kait