Merge pull request #7662 from MicrosoftDocs/main

Auto Publish – main to live - 2025-08-08 23:00 UTC

Author: learn-build-service-prod[bot]

articles/azure-developer-cli/TOC.yml

@@ -99,8 +99,12 @@
           href: remote-environments-support.md
         - name: Azure Deployment Environments integration
           href: ade-integration.md
-      - name: Work with environments
+      - name: Environments
         items:
+        - name: Overview
+          href: environments-overview.md
+        - name: Work with environments
+          href: work-with-environments.md
         - name: Manage environment variables
           href: manage-environment-variables.md
         - name: Environment variables FAQ

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

@@ -13,6 +13,9 @@ ms.custom: devx-track-azdevcli
 
 This article answers frequently asked questions about working with environment variables and the Azure Developer CLI (`azd`).
 
+> [!TIP]
+> For a comprehensive guide on creating and managing environments in Azure Developer CLI, see [Work with environments in Azure Developer CLI](work-with-environments.md).
+
 ### What are the differences between `azd` environment variables and system environment variables?
 
 `azd` environment variables are stored in the `.env` file in the `.azure/<environment name>` directory of your project and are separate from your system/OS environment variables. `azd` environment variables configure template provisioning and deployment tasks and are accessible using commands such as [`azd env`](/azure/developer/azure-developer-cli/reference#azd-env) or [`azd env get-values`](/azure/developer/azure-developer-cli/reference#azd-env-get-values).

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

@@ -0,0 +1,121 @@
+---
+title: Azure Developer CLI Environments Overview
+description: Learn essential concepts about environments using Azure Developer CLI (azd).
+author: alexwolfmsft
+ms.author: alexwolf
+ms.date: 08/04/2025
+ms.service: azure-dev-cli
+ms.topic: how-to
+ms.custom: devx-track-azdevcli, build-2023
+---
+
+# Azure Developer CLI environments overview
+
+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.
+
+## What are environments?
+
+An environment in the Azure Developer CLI (`azd`) is a named set of configurations for a deployment of your app, such as dev, test, or prod. Different environments can be configured with different values. Environments serve several important purposes:
+
+- **Isolation**: Keep development, testing, and production deployments separate.
+- **Configuration management**: Maintain different settings for each environment.
+- **Collaboration**: Enable team members to work with their own environments.
+- **Resource organization**: Group and provision Azure resources by environment.
+- **Reproducibility**: Ensure consistent deployments across different stages.
+
+Each environment has its own Azure resource group and configuration settings. This environment isolation helps prevent changes in one environment from affecting others.
+
+## Environment structure and configuration
+
+Azure Developer CLI (`azd`) environments live in a directory structure within your project:
+
+```txt
+├── .azure                          [Created when you run azd init or azd up]
+│   ├── <environment-name-1>        [Directory for environment-specific configurations]
+│   │   ├── .env                    [Environment variables for this environment]
+│   │   └── config.json             [Additional configuration parameters for this environment]
+│   ├── <environment-name-2>        [Another environment]
+│   │   ├── .env                    
+│   │   └── config.json
+│   └── config.json                 [Global azd configuration]
+```
+
+The key components of this structure are:
+
+- **`.azure` directory**: The root directory for all environment configurations. Excluded from source control by the `.gitignore` file by default.
+- **Environment-specific directories**: Directories named after your environments, such as `dev`, `test`, `prod`.
+- **`.env` file**: Contains environment-specific variables used by your application and during deployment.
+- **`config.json`**: Used to drive settings that influence `azd` command behavior and features. This file isn't intended to be used directly by end users.
+
+### Environment names
+
+Environment naming typically follows these patterns:
+
+- Team projects: `<project-name-[dev/int/prod]>`
+- Personal projects: `<personal-unique-alias-[dev/int/prod]>`
+
+These naming conventions aren't enforced by `azd` and are configurable by the user.
+
+## Environment variables
+
+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:
+
+- Configure your application settings, such as endpoints for Azure services.
+- Define infrastructure parameters to influence the provisioning process.
+
+The `.env` file contains these variables in a standard format:
+
+```output
+AZURE_ENV_NAME=dev
+AZURE_LOCATION=eastus
+AZURE_SUBSCRIPTION_ID=00000000-0000-0000-0000-000000000000
+AZURE_RESOURCE_GROUP=rg-dev-12345
+SERVICE_WEB_HOSTNAME=web-dev-12345.azurewebsites.net
+SERVICE_API_HOSTNAME=api-dev-12345.azurewebsites.net
+```
+
+Common environment variables include:
+
+| Variable | Description |
+|----------|-------------|
+| `AZURE_ENV_NAME` | Name of the current environment |
+| `AZURE_LOCATION` | Azure region where resources are deployed |
+| `AZURE_SUBSCRIPTION_ID` | ID of the Azure subscription used for this environment |
+| `AZURE_RESOURCE_GROUP` | Name of the resource group for this environment |
+
+> [!TIP]
+> For other common environment variables and service-specific examples, visit the [Environment variables](manage-environment-variables.md) documentation.
+
+When working with environment variables:
+
+- Avoid committing `.env` files to source control. If environment configuration needs to be persisted or shared, users should use [Remote environments](remote-environments-support.md).
+- Use consistent naming across environments.
+- Use the `azd env set` command to update variables safely.
+
+> [!WARNING]
+> 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.
+
+## Compare other framework environments
+
+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:
+
+| Concept | Azure Developer CLI `.env` | Framework `.env` Files |
+|--------|---------------------------|------------------------|
+| **Location** | Stored in `.azure/<environment-name>/.env` | Typically stored in project root directory |
+| **Environment Support** | Support for multiple user-defined environments (dev, test, prod) | Often require manual file switching or naming conventions (`.env.development`, `.env.production`) |
+| **Loading Mechanism** | Automatically loaded by `azd` commands | Usually require explicit loading in application code or build scripts |
+| **Integration** | Deeply integrated with Azure services and resource provisioning | General purpose configuration, not Azure-specific |
+| **Variable Management** | Managed via `azd env` commands | Typically edited manually or via custom scripts |
+
+While both serve similar purposes, Azure Developer CLI's `.env` approach adds structure and tooling designed for managing multiple deployment environments and Azure resources.
+
+> [!NOTE]
+> If your project already uses framework-specific `.env` files, you can keep both configuration systems without conflicts. `azd` environment variables override system environment variables of the same name for some operations.
+
+## Next steps
+
+> [!div class="nextstepaction"]
+> [Work with environments](work-with-environments.md)
+
+> [!div class="nextstepaction"]
+> [Manage environment variables in Azure Developer CLI](manage-environment-variables.md)

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

@@ -13,6 +13,9 @@ ms.custom: devx-track-azdevcli
 
 Environment variables influence how resources are provisioned and deployed to Azure. This is especially useful when running azd in CI/CD workflow scenarios.
 
+> [!TIP]
+> For a comprehensive guide on creating and managing environments in Azure Developer CLI, see [Work with environments in Azure Developer CLI](work-with-environments.md).
+
 ## Input Parameters Substitution
 
 Environment variables can be referenced in parameter files (`*.parameters.json` for Bicep, `*.tfvars.json` for Terraform) as part of provisioning. When an environment variable substitution syntax is encountered, `azd` automatically substitutes the reference with the actual environment variable value set. Substitution also occurs for certain configuration settings in `azure.yaml` (properties documented with 'Supports environment variable substitution'), and in deployment configuration files, such as deployment manifests for `aks`.

articles/azure-developer-cli/reference.md

@@ -3,7 +3,7 @@ title: Azure Developer CLI reference
 description: This article explains the syntax and parameters for the various Azure Developer CLI commands.
 author: alexwolfmsft
 ms.author: alexwolf
-ms.date: 07/17/2025
+ms.date: 08/07/2025
 ms.service: azure-dev-cli
 ms.topic: conceptual
 ms.custom: devx-track-azdevcli

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

@@ -0,0 +1,193 @@
+---
+title: Work with Environments in Azure Developer CLI
+description: Learn how to create, manage, and switch between different environments using Azure Developer CLI (azd).
+author: alexwolfmsft
+ms.author: alexwolf
+ms.date: 08/04/2025
+ms.service: azure-dev-cli
+ms.topic: how-to
+ms.custom: devx-track-azdevcli, build-2023
+---
+
+# Work with Azure Developer CLI environments
+
+The Azure Developer CLI (`azd`) helps you create and manage [Environments](environments-overview.md) with their own configurations, such as dev, test, and prod. This article shows how to create and manage environments, and how to use them with your Bicep infrastructure files.
+
+## Create environments
+
+Create a new environment using the `azd env new` command:
+
+```azdeveloper
+azd env new <environment-name>
+```
+
+For example, to create a development environment:
+
+```azdeveloper
+azd env new dev
+```
+
+When you run a command such as `azd up` or `azd deploy`, `azd` prompts you to select an Azure subscription and location for the new environment. Prompt settings are stored in the new environment `.env` or `config.json` files.
+
+You can also specify subscription and location directly in the command:
+
+```azdeveloper
+azd env new prod --subscription "My Production Subscription" --location eastus2
+```
+
+## List environments
+
+To see all available environments for your project, use:
+
+```azdeveloper
+azd env list
+```
+
+This command displays all the environments you created, highlighting the current active environment:
+
+```output
+NAME      DEFAULT   LOCAL     REMOTE
+dev       true      true      false
+test      false     true      false
+prod      false     true      false
+```
+
+## Switch between environments
+
+To switch to a different environment, use the `azd env select` command:
+
+```azdeveloper
+azd env select <environment-name>
+```
+
+For example, to switch to a production environment:
+
+```azdeveloper
+azd env select prod
+```
+
+> [!NOTE]
+> This command changes your active environment, which affects subsequent `azd` commands like `provision` or `deploy`.
+
+## Understand the default environment
+
+The global configuration file `.azure/config.json` keeps track of your currently selected environment. When you run `azd init` and no environments exist yet, `azd` automatically creates your first environment and sets it as the default. If you already have one or more environments and run `azd env new <name>`, `azd` prompts you to choose whether to make the new environment the default. If you decline, the new environment is created but your current selection remains unchanged.
+
+You can temporarily override the default environment for a single command by using the `--environment` flag. Using this flag doesn't change the default for future commands.
+
+## Refresh environment settings
+
+You can refresh your local environment variables using the `azd env refresh` command. This command locates the most recent Azure deployment for your app, retrieves the environment variable values by name, and then updates your local `.env` file with those latest values for the select environment. For example, if you provisioned both a `dev` and `prod` version, and you currently have the `dev` environment selected, it retrieves the latest output from that deployment to populate the .env file.
+
+```azdeveloper
+azd env refresh
+```
+
+> [!NOTE]
+> The `azd env refresh` command doesn't redeploy resources. It only updates your local environment configuration to match the current state in Azure.
+
+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.
+
+If other team members made changes to environment configurations, or if you made changes through the Azure portal, you can refresh your local environment settings with:
+
+## Run commands in specific environments
+
+You can run many `azd` commands in a specific environment without changing your active environment by using the `--environment` or `-e` flag:
+
+```azdeveloper
+azd up --environment dev
+```
+
+This command runs the `up` workflow (provision and deploy) in the `dev` environment without changing your active environment.
+
+Alternatively, you can first switch to your intended environment:
+
+```azdeveloper
+azd env select test
+azd up
+```
+
+> [!NOTE]
+> Teams should consider using CICD pipelines via the `azd pipeline config` command, rather than direct deployments using commands such as `azd up` or `azd provision`.
+
+## Delete environment resources
+
+To delete the Azure resources for a specific environment, using the `azd down` command:
+
+```azdeveloper
+azd down <environment-name>
+```
+
+> [!NOTE]
+> It's currently not possible to delete or rename `azd` environments directly using commands. If you need to rename an environment:
+>
+> - Use `azd down` to delete the environment resources.
+> - Run `azd env new <new-name>` to create the new environment.
+> - Manually delete the old `.env` folder from `.azure`.
+
+## Use the environment name in infrastructure files
+
+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.
+
+> [!NOTE]
+> 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.
+
+1. `azd` sets the `AZURE_ENV_NAME` environment variable when you initialize a project.
+
+    ```output
+    AZURE_ENV_NAME=dev
+    ```
+
+1. In your `main.parameters.json` file, reference the environment variable so `azd` substitutes its value:
+
+    ```json
+    {
+      "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
+      "contentVersion": "1.0.0.0",
+      "parameters": {
+        "environmentName": {
+          "value": "${AZURE_ENV_NAME}"
+        }
+      }
+    }
+    ```
+
+    When you deploy with `azd`, the value from `.env` is passed to your Bicep file from `main.parameters.json`.
+
+1. In your Bicep template, define a parameter for the environment name:
+
+    ```bicep
+    param environmentName string
+    ```
+
+1. You can use the `environmentName` parameter to tag resources, making it easy to identify which environment a resource belongs to:
+
+    ```bicep
+    param environmentName string
+    
+    resource storageAccount 'Microsoft.Storage/storageAccounts@2022-09-01' = {
+      name: 'mystorage${uniqueString(resourceGroup().id)}'
+      location: resourceGroup().location
+      sku: {
+        name: 'Standard_LRS'
+      }
+      kind: 'StorageV2'
+      tags: {
+        Environment: environmentName
+        Project: 'myproject'
+      }
+    }
+    ```
+
+This approach helps with resource management, cost tracking, and automation by associating each resource with its deployment environment.
+
+## Next steps
+
+> [!div class="nextstepaction"]
+> [Manage environment variables in Azure Developer CLI](manage-environment-variables.md)
+
+> [!div class="nextstepaction"]
+> [Customize your Azure Developer CLI workflows using hooks](azd-extensibility.md)