progress

Author: alexwolfmsft

articles/azure-developer-cli/manage-environment-variables.md

@@ -17,14 +17,11 @@ The Azure Developer CLI (`azd`) uses environment variables to store and manage c
 
 In the context of the Azure Developer CLI, environment variables are key-value pairs that are tied to specific named environments like *dev*, *test*, or *prod*. Each `azd` environment maintains its own set of environment variables, allowing you to configure different settings for different deployment targets.
 
-### What are environment variables
+Environment variables in `azd` are configuration settings stored in `.env` files within your environment folders in the `.azure` folder. They serve as inputs to:
 
-Environment variables in `azd` are configuration settings stored in `.env` files within your environment folders. They serve as inputs to:
-
-- Infrastructure provisioning processes
 - Application deployment workflows
-- Runtime configurations for Azure services
-- Feature flags and connection parameters
+- Configurations for Azure services and connections
+- Infrastructure provisioning processes
 
 Unlike traditional environment variables that exist at the operating system level, `azd` environment variables are scoped to specific environments within your project, providing isolation between different deployment targets.
 
@@ -42,105 +39,40 @@ Each `azd` environment has its own set of variables, allowing for environment-sp
 
 The `azd` environment variables are stored in `.env` files within the environment-specific directories of your project. When you create an environment using `azd env new <name>`, a directory structure is created:
 
-```text
+```txt
 .azure/
 ├── <environment-name>/
 │   ├── .env                   # Environment variables for this environment
-│   └── main.parameters.json   # Infrastructure parameters
 ```
 
 The `.env` file uses a standard format where each line represents a key-value pair:
 
-```text
+```txt
 KEY1=value1
 KEY2=value2
 ```
 
 > [!TIP]
 > Visit the [Working with environments](work-with-environments.md) article for more information about `azd` environments.
 
-When you run `azd` commands targeting a specific environment, the CLI automatically loads variables from that environment's `.env` file.
+When you run `azd` commands such as `azd up`, the CLI automatically loads variables from the select environment's `.env` file.
 
 These variables influence:
 
 - **Infrastructure provisioning**: Variables like `AZURE_LOCATION` and `AZURE_SUBSCRIPTION_ID` determine where and how resources are created.
-- **Deployment**: Variables like service endpoints and connection strings control how your application connects to Azure services.
-- **Application configuration**: Variables can be passed to your application to control its behavior.
-- **Resource naming**: Variables like `RESOURCE_TOKEN` ensure consistent resource naming patterns.
-
-The `.env` file is also updated automatically during operations like `azd init`, `azd provision`, and `azd deploy`, capturing outputs from your infrastructure templates and storing them for future use.
-
-## AZD vs OS environment variables
-
-`azd` environment variables and operating system environment variables serve different purposes and work in different ways:
-
-| Concept | Azure Developer CLI | Operating system |
-|---------|------------------------------------------|--------------------------|
-| Location | Stored in `.azure/<env-name>/.env` files | Set in your operating system environment |
-| Scope | Scoped to a specific named environment within a project | Global to your user session or system |
-| Management | Managed using `azd env` commands | Managed using OS-specific commands (`export`, `set`, etc.) |
-| Access | Loaded automatically by `azd` commands | Typically loaded explicitly in scripts or applications |
-| Target | Tied to Azure resources and deployments | General purpose system configuration |
-| Lifecycle | Persist between terminal sessions | May be temporary or persistent depending on how they're set |
-
-`azd` doesn't automatically read or write OS environment variables. However, you can interact with both types of variables using custom scripts:
-
-**Reading OS environment variables in scripts:**
-
-**Bash:**
-
-```bash
-# Access OS environment variable
-echo "OS variable: $PATH"
+- **Deployment**: Variables like service endpoints control how your application connects to Azure services.
+- **Application configuration**: Variables can be passed to your application configuration to control its behavior.
+- **Resource naming**: Variables like `AZURE_RESOURCE_GROUP` influence resource naming patterns.
 
-# Access azd environment variable
-echo "AZD variable: $(azd env get-value MY_VARIABLE)"
-```
-
-**PowerShell:**
-
-```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)"
-```
-
-**Convert azd environment variables to OS environment variables:**
-
-**Bash:**
-
-```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:**
-
-```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
-    }
-}
-```
+The `.env` file is also updated automatically by `azd` during operations like `azd init`, `azd provision`, and `azd deploy`, capturing outputs from your infrastructure templates and storing them for future use.
 
 ## Set Environment Variables
 
 You can use different methods to set `azd` environment variables, depending on the scenario.
 
 ### CLI commands
 
-The most direct way to set an environment variable is using the `azd env set` command:
+The recommended way to set an environment variable is using the `azd env set` command, which includes checks to ensure valid values:
 
 ```azdeveloper
 azd env set <key> <value>
@@ -228,7 +160,7 @@ For machine-readable output (useful in scripts):
 azd env get-values --output json
 ```
 
-### Bicep files
+### Pass environment variables to Bicep files
 
 Environment variables can be referenced in Bicep parameter files (`main.parameters.json`) using a special substitution syntax:
 
@@ -253,7 +185,7 @@ When `azd` processes this file during provisioning, it automatically substitutes
 
 In custom scripts and [hooks](azd-extensibility.md) defined in your `azure.yaml` file, you can access environment variables using the `azd env get-values` command:
 
-**Bash:**
+### [Bash](#tab/bash)
 
 ```bash
 #!/bin/bash
@@ -270,7 +202,7 @@ EOF
 echo "API endpoint: $API_ENDPOINT"
 ```
 
-**PowerShell:**
+### [PowerShell](#tab/powershell)
 
 ```powershell
 Write-Host "Loading azd .env file from current environment"
@@ -286,6 +218,8 @@ foreach ($line in (& azd env get-values)) {
 Write-Host "API endpoint: $env:API_ENDPOINT"
 ```
 
+---
+
 You can define hooks in your `azure.yaml` file to run these scripts at specific points in the `azd` lifecycle:
 
 ```yaml
@@ -324,75 +258,93 @@ To refresh your local environment variables from the current state of your Azure
 azd env refresh
 ```
 
-The `azd env refresh` command is particularly useful when:
+Refreshing your environment is useful when:
 
-- Resources have been modified outside of `azd` (through the Azure portal or other tools)
-- Team members have updated the environment
-- You've switched to a different machine or workspace
-- You need to ensure your local configuration matches the deployed state
+- You want to ensure your local `.env` file reflects the latest outputs from your infrastructure (like connection strings, endpoints, etc.).
+- You need to sync environment variables after a teammate updated the environment.
 
-## Common environment variables
+## AZD vs OS environment variables
 
-`azd` sets and uses several common environment variables across all environments:
+`azd` environment variables and operating system environment variables serve different purposes and work in different ways:
 
-| Variable | Description | Example | When Set |
-|----------|-------------|---------|---------|
-| `AZURE_ENV_NAME` | Name of the current environment | `dev` | When environment is created |
-| `AZURE_LOCATION` | Azure region where resources are deployed | `eastus` | During first provisioning |
-| `AZURE_SUBSCRIPTION_ID` | ID of the Azure subscription used | `00000000-0000-0000-0000-000000000000` | During first provisioning |
-| `AZURE_RESOURCE_GROUP` | Name of the resource group | `rg-myapp-dev` | During provisioning |
-| `AZURE_PRINCIPAL_ID` | The running user/service principal ID | `00000000-0000-0000-0000-000000000000` | During provisioning |
-| `RESOURCE_TOKEN` | Unique token used to generate resource names | `1a2b3c` | During provisioning |
+| Concept | Azure Developer CLI | Operating system |
+|---------|------------------------------------------|--------------------------|
+| Location | Stored in `.azure/<env-name>/.env` files | Set in your operating system environment |
+| Scope | Scoped to a specific named environment within a project | Global to your user session or system |
+| Management | Managed using `azd env` commands | Managed using OS-specific commands (`export`, `set`, etc.) |
+| Access | Loaded automatically by `azd` commands | Typically loaded explicitly in scripts or applications |
+| Target | Tied to Azure resources and deployments | General purpose system configuration |
+| Lifecycle | Persist between terminal sessions | May be temporary or persistent depending on how they're set |
 
-Additionally, `azd` automatically sets service-specific variables based on the services defined in your `azure.yaml` file:
+`azd` doesn't automatically read or write OS environment variables. However, you can interact with both types of variables using custom scripts.
 
-### App Service
+**Read `azd` environment variables and OS environment variables**:
 
-```output
-SERVICE_WEB_IDENTITY_PRINCIPAL_ID=00000000-0000-0000-0000-000000000000
-SERVICE_WEB_NAME=app-web-dev-1a2b3c
-SERVICE_WEB_ENDPOINT=https://app-web-dev-1a2b3c.azurewebsites.net
-```
+### [Bash](#tab/bash)
 
-### Container Apps
+```bash
+# Access OS environment variable
+echo "OS variable: $PATH"
 
-```output
-SERVICE_API_IDENTITY_PRINCIPAL_ID=00000000-0000-0000-0000-000000000000
-SERVICE_API_NAME=ca-api-dev-1a2b3c
-SERVICE_API_ENDPOINT=https://ca-api-dev-1a2b3c.azurecontainerapps.io
-SERVICE_API_IMAGE_NAME=cr-dev-1a2b3c.azurecr.io/api:latest
+# Access azd environment variable
+echo "AZD variable: $(azd env get-value MY_VARIABLE)"
 ```
 
-### Azure OpenAI
+### [PowerShell](#tab/powershell)
+
+```powershell
+# Access OS environment variable
+Write-Host "OS variable: $env:PATH"
 
-```output
-AZURE_OPENAI_SERVICE=oai-dev-1a2b3c
-AZURE_OPENAI_DEPLOYMENT=gpt-35-turbo
-AZURE_OPENAI_ENDPOINT=https://oai-dev-1a2b3c.openai.azure.com/
+# Access azd environment variable
+Write-Host "AZD variable: $(azd env get-value MY_VARIABLE)"
 ```
 
-### Cosmos DB
+---
 
-```output
-AZURE_COSMOS_ENDPOINT=https://cosmos-dev-1a2b3c.documents.azure.com:443/
-AZURE_COSMOS_DATABASE_NAME=mydb
-AZURE_COSMOS_CONTAINER_NAME=items
-```
+**Convert `azd` environment variables to OS environment variables:**
 
-### Key Vault
+### [Bash](#tab/bash)
 
-```output
-AZURE_KEY_VAULT_NAME=kv-dev-1a2b3c
-AZURE_KEY_VAULT_ENDPOINT=https://kv-dev-1a2b3c.vault.azure.net/
+```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
 ```
 
-### Storage Account
+### [PowerShell](#tab/powershell)
 
-```output
-AZURE_STORAGE_ACCOUNT=stdev1a2b3c
-AZURE_STORAGE_ENDPOINT=https://stdev1a2b3c.blob.core.windows.net/
+```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
+    }
+}
 ```
 
+---
+
+## Common environment variables
+
+`azd` sets and uses several common environment variables across all environments:
+
+| Variable | Description | Example | When Set |
+|----------|-------------|---------|---------|
+| `AZURE_ENV_NAME` | Name of the current environment | `dev` | When environment is created |
+| `AZURE_LOCATION` | Azure region where resources are deployed | `eastus` | During first provisioning |
+| `AZURE_SUBSCRIPTION_ID` | ID of the Azure subscription used | `00000000-0000-0000-0000-000000000000` | During first provisioning |
+| `AZURE_RESOURCE_GROUP` | Name of the resource group | `rg-myapp-dev` | During provisioning |
+| `AZURE_PRINCIPAL_ID` | The running user/service principal ID | `00000000-0000-0000-0000-000000000000` | During provisioning |
+| `AZURE_PRINCIPAL_TYPE` | The type of a principal in the environment. | `1a2b3c` | During provisioning |
+| `AZURE_TENANT_ID` | The type of a principal in the environment. | `1a2b3c` | During provisioning |
+
 ## Secrets and sensitive data considerations
 
 While environment variables are convenient for configuration, they require special handling for sensitive data:
@@ -413,30 +365,17 @@ While environment variables are convenient for configuration, they require speci
 
 For sensitive data, consider these more secure approaches:
 
-1. **Azure Key Vault references**: Store secrets in Azure Key Vault and reference them in your `.env` file:
+- **Azure Key Vault references**: Store secrets in Azure Key Vault and reference them in your `.env` file:
 
    ```azdeveloper
-   azd env set-secret DB_PASSWORD
+   azd env set-secret <secret-value>
    ```
 
    This command creates a Key Vault secret and stores a reference to it in your `.env` file rather than the actual value.
 
-2. **Managed identities**: Configure your Azure services to use managed identities instead of connection strings or access keys.
-
-3. **Environment-specific security**: Apply stricter security controls to production environments than development ones.
-
-4. **Just-in-time secrets**: Generate short-lived credentials during deployment rather than storing persistent secrets.
-
-### Source control best practices
-
-When working with `.env` files and source control:
-
-- Add `.azure/**/.env` to your `.gitignore` file to prevent accidental commits
-- Consider using template `.env.example` files with placeholder values for documentation
-- Document required environment variables in your README file
-- Use CI/CD pipelines to inject secrets during deployment rather than storing them in repositories
-- Regularly rotate sensitive credentials
-- Consider using tools like pre-commit hooks to prevent secret leaks
+- **Managed identities**: Configure your Azure services to use managed identities instead of connection strings or access keys.
+- **Environment-specific security**: Apply stricter security controls to production environments than development ones.
+- **Just-in-time secrets**: Generate short-lived credentials during deployment rather than storing persistent secrets.
 
 ## Next steps