Skip to content

Commit 8746024

Browse files
alexwolfmsftalexwolfmsft
committed
New environment variables overview and working doc
1 parent d1d8ce4 commit 8746024

File tree

3 files changed

+176
-58
lines changed

3 files changed

+176
-58
lines changed

‎articles/azure-developer-cli/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,8 @@
101101
href: ade-integration.md
102102
- name: Environments
103103
items:
104+
- name: Overview
105+
href: environments-overview.md
104106
- name: Work with environments
105107
href: work-with-environments.md
106108
- name: Manage environment variables

‎articles/azure-developer-cli/environments-overview.md

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
---
2+
title: Azure Developer CLI environments overview
3+
description: Learn essential concenpts about environments using Azure Developer CLI (azd).
4+
author: alexwolfmsft
5+
ms.author: alexwolf
6+
ms.date: 08/04/2025
7+
ms.service: azure-dev-cli
8+
ms.topic: how-to
9+
ms.custom: devx-track-azdevcli, build-2023
10+
---
11+
12+
# Azure Developer CLI environments overview
13+
14+
The Azure Developer CLI (`azd`) lets you manage multiple deployment environments for your projects, to keep configurations separate for development, testing, and production. This article explains essential concepts about how you can use environments to manage your development and deployment process.
15+
16+
## What are environments?
17+
18+
An environment in the Azure Developer CLI (`azd`) context represents a named collection of configuration settings, environment variables, and infrastructure parameters associated with a specific deployment of your application. Environments serve several important purposes:
19+
20+
- **Isolation**: Keep development, testing, staging, and production deployments separate.
21+
- **Configuration management**: Maintain different settings for each environment.
22+
- **Collaboration**: Enable team members to work with their own environments.
23+
- **Resource organization**: Group and provision Azure resources by environment, such as using lower tier services for dev environments.
24+
- **Reproducibility**: Ensure consistent deployments across different stages.
25+
26+
Each environment has its own Azure resource group and configuration settings. The environment name typically follows the pattern `rg-<environment-name>`, but this is not enforced by `azd` and is configurable by the user. This environment isolation helps prevent changes in one environment from affecting others.
27+
28+
## Environment structure and configuration files
29+
30+
Azure Developer CLI (`azd`) environments live in a directory structure within your project:
31+
32+
```txt
33+
├── .azure [Created when you run azd init or azd up]
34+
│ ├── <environment-name-1> [Directory for environment-specific configurations]
35+
│ │ ├── .env [Environment variables for this environment]
36+
│ │ └── main.parameters.json [Infrastructure parameters for this environment]
37+
│ ├── <environment-name-2> [Another environment]
38+
│ │ ├── .env
39+
│ │ └── main.parameters.json
40+
│ └── config.json [Global azd configuration]
41+
```
42+
43+
The key components of this structure are:
44+
45+
1. **`.azure` directory**: The root directory for all environment configurations. Excluded from source control by the `.gitignore` file by default.
46+
2. **Environment-specific directories**: Directories named after your environments, such as `dev`, `test`, `prod`.
47+
3. **`.env` file**: Contains environment-specific variables used by your application and during deployment.
48+
4. **`main.parameters.json`**: Contains parameters commonly used during infrastructure provisioning with Bicep or Terraform, but can be used for any per-environment `azd` configuration. This file is not intended to be used directly by end users.
49+
50+
## Environment variables
51+
52+
Azure Developer CLI [Environment variables](manage-environment-variables.md) provide a way to store configuration settings that influence and might vary between environments. When you run Azure Developer CLI commands, these variables are used to:
53+
54+
- Configure your application's settings
55+
- Define infrastructure parameters
56+
- Store connection strings, endpoints, and secrets
57+
58+
The `.env` file contains these variables in a standard format:
59+
60+
```output
61+
AZURE_ENV_NAME=dev
62+
AZURE_LOCATION=eastus
63+
AZURE_SUBSCRIPTION_ID=00000000-0000-0000-0000-000000000000
64+
RESOURCE_TOKEN=12345
65+
AZURE_RESOURCE_GROUP=rg-dev-12345
66+
SERVICE_WEB_HOSTNAME=web-dev-12345.azurewebsites.net
67+
SERVICE_API_HOSTNAME=api-dev-12345.azurewebsites.net
68+
```
69+
70+
Common environment variables include:
71+
72+
| Variable | Description |
73+
|----------|-------------|
74+
| `AZURE_ENV_NAME` | Name of the current environment |
75+
| `AZURE_LOCATION` | Azure region where resources are deployed |
76+
| `AZURE_SUBSCRIPTION_ID` | ID of the Azure subscription used for this environment |
77+
| `AZURE_RESOURCE_GROUP` | Name of the resource group for this environment |
78+
79+
> [!TIP]
80+
> For other common environment variables and service-specific examples, visit the [Environment variables](manage-environment-variables.md) documentation.
81+
82+
When working with environment variables:
83+
84+
- Avoid committing `.env` files to source control. If environment configuration needs to be persisted or shared, users should leverage [Remote environments](remote-environments-support.md).
85+
- Use consistent naming across environments.
86+
- Use the `azd env set` command to update variables safely.
87+
88+
> [!WARNING]
89+
> Never store secrets in an Azure Developer CLI `.env` file. These files can easily be shared or copied into unauthorized locations, or checked into source control. Use services such as Azure Key Vault or Azure Role Based Access Control (RBAC) for protected or secretless solutions.
90+
91+
## Compare other framework environments
92+
93+
Many programming frameworks and tools such as Node.js, Django, or React use `.env` files for configuration. While Azure Developer CLI (`azd`) also uses `.env` files, there are important differences:
94+
95+
| Concept | Azure Developer CLI `.env` | Framework `.env` Files |
96+
|--------|---------------------------|------------------------|
97+
| **Location** | Stored in `.azure/<environment-name>/.env` | Typically stored in project root directory |
98+
| **Environment Support** | Support for multiple user-defined environments (dev, test, prod) | Often require manual file switching or naming conventions (`.env.development`, `.env.production`) |
99+
| **Loading Mechanism** | Automatically loaded by `azd` commands | Usually require explicit loading in application code or build scripts |
100+
| **Integration** | Deeply integrated with Azure services and resource provisioning | General purpose configuration, not Azure-specific |
101+
| **Variable Management** | Managed via `azd env` commands | Typically edited manually or via custom scripts |
102+
103+
While both serve similar purposes, Azure Developer CLI's `.env` approach adds structure and tooling designed for managing multiple deployment environments and Azure resources.
104+
105+
> [!NOTE]
106+
> If your project already uses framework-specific `.env` files, you can keep both configuration systems without conflicts.
107+
>
108+
> `azd` environment variables override system environment variables of the same name for some operations.
109+
110+
## Next steps
111+
112+
> [!div class="nextstepaction"]
113+
> [Work with environments](work-with-environments.md)
114+
115+
> [!div class="nextstepaction"]
116+
> [Manage environment variables in Azure Developer CLI](manage-environment-variables.md)

‎articles/azure-developer-cli/work-with-environments.md

Lines changed: 58 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -88,59 +88,6 @@ When working with environment variables:
8888
> [!WARNING]
8989
> Never store secrets in an Azure Developer CLI `.env` file. These files can easily be shared or copied into unauthorized locations, or checked into source control. Use services such as Azure Key Vault or Azure Role Based Access Control (RBAC) for protected or secretless solutions.
9090
91-
### Use the environment name in infrastructure files
92-
93-
You can use the `AZURE_ENV_NAME` variable from your environment's `.env` file to customize your infrastructure deployments in Bicep. This is useful for naming, tagging, or configuring resources based on the current environment.
94-
95-
1. The `AZURE_ENV_NAME` environment variable is set by `azd` when you initialize a project.
96-
97-
```output
98-
AZURE_ENV_NAME=dev
99-
```
100-
101-
1. In your `main.parameters.json` file, reference the environment variable so `azd` will substitute its value:
102-
103-
```json
104-
{
105-
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
106-
"contentVersion": "1.0.0.0",
107-
"parameters": {
108-
"environmentName": {
109-
"value": "${AZURE_ENV_NAME}"
110-
}
111-
}
112-
}
113-
```
114-
115-
When you deploy with `azd`, the value from `.env` will be passed to your Bicep file from `main.parameters.json`.
116-
117-
1. In your Bicep template, define a parameter for the environment name:
118-
119-
```bicep
120-
param environmentName string
121-
```
122-
123-
1. You can use the `environmentName` parameter to tag resources, making it easy to identify which environment a resource belongs to:
124-
125-
```bicep
126-
param environmentName string
127-
128-
resource storageAccount 'Microsoft.Storage/storageAccounts@2022-09-01' = {
129-
name: 'mystorage${uniqueString(resourceGroup().id)}'
130-
location: resourceGroup().location
131-
sku: {
132-
name: 'Standard_LRS'
133-
}
134-
kind: 'StorageV2'
135-
tags: {
136-
Environment: environmentName
137-
Project: 'myproject'
138-
}
139-
}
140-
```
141-
142-
This approach helps with resource management, cost tracking, and automation by associating each resource with its deployment environment.
143-
14491
## Compare other framework environments
14592

14693
Many programming frameworks and tools such as Node.js, Django, or React use `.env` files for configuration. While Azure Developer CLI (`azd`) also uses `.env` files, there are important differences:
@@ -279,13 +226,66 @@ azd down <environment-name>
279226
> - Run `azd env new <new-name>` to create the new environment.
280227
> - Manually delete the old `.env` folder from `.azure`.
281228
282-
## Next steps
229+
## Use the environment name in infrastructure files
283230

284-
> [!div class="nextstepaction"]
285-
> [Customize your Azure Developer CLI workflows using hooks](azd-extensibility.md)
231+
You can use the `AZURE_ENV_NAME` variable from your environment's `.env` file to customize your infrastructure deployments in Bicep. This is useful for naming, tagging, or configuring resources based on the current environment.
286232

287-
> [!div class="nextstepaction"]
288-
> [Configure CI/CD pipelines with Azure Developer CLI](pipeline-github-actions.md)
233+
> [!NOTE]
234+
> Visit the [Work with environment variables](manage-environment-variables.md) to learn more about how to use environment variables to configure your Azure Developer CLI projects.
235+
236+
1. The `AZURE_ENV_NAME` environment variable is set by `azd` when you initialize a project.
237+
238+
```output
239+
AZURE_ENV_NAME=dev
240+
```
241+
242+
1. In your `main.parameters.json` file, reference the environment variable so `azd` will substitute its value:
243+
244+
```json
245+
{
246+
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
247+
"contentVersion": "1.0.0.0",
248+
"parameters": {
249+
"environmentName": {
250+
"value": "${AZURE_ENV_NAME}"
251+
}
252+
}
253+
}
254+
```
255+
256+
When you deploy with `azd`, the value from `.env` will be passed to your Bicep file from `main.parameters.json`.
257+
258+
1. In your Bicep template, define a parameter for the environment name:
259+
260+
```bicep
261+
param environmentName string
262+
```
263+
264+
1. You can use the `environmentName` parameter to tag resources, making it easy to identify which environment a resource belongs to:
265+
266+
```bicep
267+
param environmentName string
268+
269+
resource storageAccount 'Microsoft.Storage/storageAccounts@2022-09-01' = {
270+
name: 'mystorage${uniqueString(resourceGroup().id)}'
271+
location: resourceGroup().location
272+
sku: {
273+
name: 'Standard_LRS'
274+
}
275+
kind: 'StorageV2'
276+
tags: {
277+
Environment: environmentName
278+
Project: 'myproject'
279+
}
280+
}
281+
```
282+
283+
This approach helps with resource management, cost tracking, and automation by associating each resource with its deployment environment.
284+
285+
## Next steps
289286
290287
> [!div class="nextstepaction"]
291288
> [Manage environment variables in Azure Developer CLI](manage-environment-variables.md)
289+
290+
> [!div class="nextstepaction"]
291+
> [Customize your Azure Developer CLI workflows using hooks](azd-extensibility.md)

0 commit comments

Comments
 (0)