Work with Azure Developer CLI environment variables

The Azure Developer CLI (azd) uses environment variables to store and manage configuration settings for deployment environments. These variables control how your application is provisioned, deployed, and runs in Azure. This article explains how environment variables work within azd environments and provides guidance on managing them effectively.

Understand environment variables

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.

Environment variables in azd are stored in .env files within your environment folders in the .azure folder. They serve as inputs to:

• Application deployment workflows
• Configurations for Azure services and connections
• Infrastructure provisioning via Bicep and Terraform

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.

Environment variables provide several key benefits when working with azd:

• Environment isolation: Keep configurations for development, testing, and production separate and distinct.
• Configuration consistency: Ensure all team members use the same settings for a specific environment.
• Infrastructure as Code: Define infrastructure parameterization through variables instead of hard-coded values.
• Deployment automation: Enable CI/CD pipelines to deploy to different environments using the same codebase but different configurations.
• Simplified management: Easily update settings across all services in an environment from a central location.

Each azd environment has its own set of variables, allowing for environment-specific configurations while using the same application code and infrastructure templates.

Environment variables and .env files

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:

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

The .env file uses a standard format where each line represents a key-value pair:

KEY1=value1
KEY2=value2

When you run commands such as azd up, azd 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 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.

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.

Use CLI commands

The recommended way to set an environment variable is using the azd env set command, which includes checks to ensure valid values:

azd env set <key> <value>

For example, to set a configuration value for your application:

azd env set API_TIMEOUT 5000

The command adds or updates the variable in the .env file of the currently selected environment. You can also target a specific environment using the --environment flag:

azd env set API_TIMEOUT 5000 --environment prod

To verify that your environment variable was set correctly:

azd env get-value API_TIMEOUT

Output from Bicep

A powerful feature of azd is its ability to automatically capture output parameters from your Bicep infrastructure templates as environment variables. For example, when you define an output parameter in your main.bicep file:

output API_ENDPOINT string = apiService.outputs.SERVICE_ENDPOINT_URL

After running azd provision, this output is automatically saved to the environment's .env file:

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

This approach ensures that your application always has access to the most current resource information, such as:

• Service endpoints and URLs
• Resource names and identifiers

Get and use environment variables

Once set, you can access environment variables in several contexts.

CLI commands

To view all environment variables for the current environment:

azd env get-values

To view the value of a specific variable:

azd env get-value API_ENDPOINT

For machine-readable output (useful in scripts):

azd env get-values --output json

Use environment variables in infrastructure files

You can use environment variables to customize your infrastructure templates. This is useful for naming, tagging, or configuring resources based on the current environment. azd also uses tags to locate resources in Azure for deployment and other tasks.

Consider the following common flow:

1. During azd init, azd sets these environment variables based on the user's response to prompts:

   AZURE_ENV_NAME=myapp-dev
   AZURE_LOCATION=eastus2
   

2. Reference those variables in main.parameters.json in the infra folder. azd substitutes the values during provisioning and passes the resolved parameters to 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. Define matching parameters in your Bicep template:

   @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 supplies these Bicep parameters with the substituted values in main.parameters.json.

4. Use the parameters for resource naming and tags to later identify which environment a resource belongs to:

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

This pattern keeps your templates flexible, enables per-environment customization without code changes, and improves resource governance (naming, tagging, and discovery).

Hooks

azd environment variables are automatically preloaded and available in hooks and custom scripts defined in your azure.yaml file, you can access environment variables using the following 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"

You can define hooks in your azure.yaml file to run these scripts at specific points in the azd lifecycle:

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

Remove or update variables

To remove a variable from your environment:

azd env unset VARIABLE_NAME

To update an existing variable:

azd env set VARIABLE_NAME "new-value"

To refresh your local environment variables from the current state of your Azure resources:

azd env refresh

Refreshing your environment is useful when:

• 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.

AZD vs OS environment variables

azd environment variables and operating system environment variables serve different purposes and work in different ways:

azd doesn't automatically read or write OS environment variables. However, you can interact with both types of variables using custom scripts.

Read azd environment variables and OS environment variables:

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

Write azd environment variables to OS or framework environment variables:

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

Standard environment variables

azd sets and uses several common environment variables across all environments:

Secrets and sensitive data considerations

While environment variables are convenient for configuration, they require special handling for sensitive data:

Avoid storing secrets in .env files

.env files are typically stored in plain text and can easily be:

• Accidentally committed to source control
• Shared or copied without proper protections
• Viewed by anyone with access to the project files
• Included in logs or error reports

Alternatives for handling secrets

For sensitive data, consider these more secure approaches:

• Azure Key Vault references: Store secrets in Azure Key Vault and reference them in your .env file:

  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.

• 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