docs: comprehensive environment variables documentation #7039
+239
−15
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,21 +1,235 @@ | ||
| # Environment Variables | ||
|
|
||
| Comprehensive reference of environment variables used by `azd`. | ||
|
|
||
| For environment variables that accept a boolean, the values `1, t, T, TRUE, true, True` are accepted | ||
| as "true"; the values `0, f, F, FALSE, false, False` are all accepted as "false". | ||
|
|
||
| ## Core Azure Variables | ||
|
|
||
| These variables are typically set by infrastructure provisioning outputs and stored in the `.env` file | ||
| for each environment. | ||
|
|
||
| | Variable | Description | | ||
| | --- | --- | | ||
| | `AZURE_ENV_NAME` | The name of the active azd environment. | | ||
| | `AZURE_LOCATION` | The default Azure region for resource deployment. | | ||
| | `AZURE_SUBSCRIPTION_ID` | The Azure subscription ID used for deployment. | | ||
| | `AZURE_TENANT_ID` | The Microsoft Entra tenant ID. | | ||
| | `AZURE_PRINCIPAL_ID` | The object ID of the signed-in principal. | | ||
| | `AZURE_PRINCIPAL_TYPE` | The type of the signed-in principal (e.g., `User`, `ServicePrincipal`). | | ||
| | `AZURE_RESOURCE_GROUP` | The default resource group name. | | ||
| | `AZURE_CONTAINER_REGISTRY_ENDPOINT` | The endpoint of the Azure Container Registry. | | ||
| | `AZURE_CONTAINER_APPS_ENVIRONMENT_DEFAULT_DOMAIN` | The default domain of the Container Apps environment. | | ||
| | `AZURE_APP_SERVICE_DASHBOARD_URI` | The URI for the Azure App Service dashboard. | | ||
| | `AZURE_AKS_CLUSTER_NAME` | The name of the Azure Kubernetes Service cluster. | | ||
|
|
||
| ## Dev Center Variables | ||
|
|
||
| Variables for [Azure Dev Center](https://learn.microsoft.com/azure/dev-box/overview-what-is-microsoft-dev-box) | ||
| integration. | ||
|
|
||
| | Variable | Description | | ||
| | --- | --- | | ||
| | `AZURE_DEVCENTER_NAME` | The name of the Dev Center instance. | | ||
| | `AZURE_DEVCENTER_PROJECT` | The Dev Center project name. | | ||
| | `AZURE_DEVCENTER_CATALOG` | The catalog name within Dev Center. | | ||
| | `AZURE_DEVCENTER_ENVIRONMENT_TYPE` | The environment type in Dev Center (e.g., `Dev`, `Test`, `Prod`). | | ||
| | `AZURE_DEVCENTER_ENVIRONMENT_DEFINITION` | The environment definition name. | | ||
| | `AZURE_DEVCENTER_ENVIRONMENT_USER` | The user identity for the Dev Center environment. | | ||
|
|
||
| ## General Configuration | ||
|
|
||
| | Variable | Description | | ||
| | --- | --- | | ||
| | `AZD_CONFIG_DIR` | The file path of the user-level configuration directory. | | ||
| | `AZD_DEMO_MODE` | If true, enables demo mode. This hides personal output, such as subscription IDs, from being displayed in output. | | ||
| | `AZD_FORCE_TTY` | If true, forces `azd` to write terminal-style output. | | ||
| | `AZD_IN_CLOUDSHELL` | If true, `azd` runs with Azure Cloud Shell specific behavior. | | ||
| | `AZD_SKIP_UPDATE_CHECK` | If true, skips the out-of-date update check output that is typically printed at the end of the command. | | ||
| | `AZD_CONTAINER_RUNTIME` | The container runtime to use (e.g., `docker`, `podman`). | | ||
| | `AZD_ALLOW_NON_EMPTY_FOLDER` | If set, allows `azd init` to run in a non-empty directory without prompting. | | ||
| | `AZD_BUILDER_IMAGE` | The builder docker image used to perform Dockerfile-less builds. | | ||
|
|
||
| ## Extension Variables | ||
|
|
||
| These variables are set and consumed by azd extension hosts (for example, IDE/editor integrations) | ||
| and the azd extension framework. They are not intended to be configured as general CLI settings. | ||
|
|
||
| | Variable | Description | | ||
| | --- | --- | | ||
| | `AZD_NO_PROMPT` | If true, disables interactive prompts. Typically set by extension hosts for non-interactive behavior. | | ||
| | `AZD_ENVIRONMENT` | The azd environment name provided by the extension host when invoking azd. | | ||
| | `AZD_CWD` | The working directory path used by the extension host when invoking azd. | | ||
| | `AZD_SERVER` | The address (e.g., `localhost:12345`) of the azd extension server for gRPC communication. Injected and consumed by the extension framework; not typically set by users directly. | | ||
| | `AZD_ACCESS_TOKEN` | A JWT used to authenticate gRPC calls to the azd extension server. Injected and consumed by the extension framework; not typically set by users directly. | | ||
|
|
||
| ## Alpha Features | ||
|
|
||
| | Variable | Description | | ||
| | --- | --- | | ||
| | `AZD_ALPHA_ENABLE_ALL` | Enables all alpha features at once. | | ||
| | `AZD_ALPHA_ENABLE_<name>` | Enables or disables an alpha feature. `<name>` is the upper-cased name of the feature, with dot `.` characters replaced by underscore `_` characters. | | ||
|
Contributor
There was a problem hiding this comment. Can we also call out the special
Member
Author
There was a problem hiding this comment. Good call — will add |
||
|
|
||
| ## External Authentication | ||
|
|
||
| Variables for [External Authentication](./external-authentication.md) integration. | ||
|
|
||
| | Variable | Description | | ||
| | --- | --- | | ||
| | `AZD_AUTH_ENDPOINT` | The [External Authentication](./external-authentication.md) endpoint. | | ||
| | `AZD_AUTH_KEY` | The [External Authentication](./external-authentication.md) shared key. | | ||
| | `AZD_AUTH_CERT` | The [External Authentication](./external-authentication.md) client certificate, provided as a base64-encoded DER certificate string. When set, `AZD_AUTH_ENDPOINT` must use HTTPS. | | ||
|
|
||
| ## Tool Configuration | ||
|
|
||
| For tools that are auto-acquired by `azd`, the following environment variables configure the path to a | ||
| specific version of the tool installed on the machine. | ||
|
|
||
| | Variable | Description | | ||
| | --- | --- | | ||
| | `AZD_BICEP_TOOL_PATH` | The Bicep tool override path. The direct path to `bicep` or `bicep.exe`. | | ||
| | `AZD_GH_TOOL_PATH` | The `gh` tool override path. The direct path to `gh` or `gh.exe`. | | ||
| | `AZD_PACK_TOOL_PATH` | The `pack` tool override path. The direct path to `pack` or `pack.exe`. | | ||
|
|
||
| ## Extension Configuration | ||
|
|
||
| | Variable | Description | | ||
| | --- | --- | | ||
| | `AZD_EXT_TIMEOUT` | Timeout for extension operations, parsed as an integer number of seconds (for example, `10`). Defaults to `5` seconds; this is not a duration string, so values like `10m` are not valid. | | ||
| | `AZD_EXT_DEBUG` | If true, enables debug output for extensions. | | ||
| | `AZD_EXTENSION_CACHE_TTL` | Time-to-live for extension cache entries, parsed with Go's `time.ParseDuration` format (for example, `30m`, `4h`). Defaults to `4h`. | | ||
|
|
||
| ## Extension-Specific Variables | ||
|
Contributor
There was a problem hiding this comment. [Low] Extension-specific section organization Building on @JeffreyCA's earlier comment — it might be worth considering whether extension-specific env vars should live here or in the extension's own documentation, especially as more extensions are added. Either approach works; just worth establishing the pattern now. |
||
|
|
||
| ### azure.ai.agents | ||
|
|
||
| | Variable | Description | | ||
| | --- | --- | | ||
| | `AZURE_AI_PROJECT_ID` | The Microsoft Foundry project resource ID used by the `azure.ai.agents` extension. | | ||
| | `AZURE_AI_PROJECT_ENDPOINT` | The Microsoft Foundry project endpoint used by the `azure.ai.agents` extension. | | ||
| | `AZURE_AI_PROJECT_PRINCIPAL_ID` | The principal ID associated with the Microsoft Foundry project identity. | | ||
| | `AZURE_AI_ACCOUNT_NAME` | The Microsoft Foundry account name associated with the project. | | ||
| | `AZURE_AI_PROJECT_NAME` | The Microsoft Foundry project name. | | ||
| | `AZURE_AI_MODEL_DEPLOYMENT_NAME` | The default model deployment name used for generated agent code and templates. | | ||
| | `AZURE_AI_PROJECT_ACR_CONNECTION_NAME` | The Azure Container Registry connection name used by the extension for hosted agents. | | ||
| | `AI_PROJECT_DEPLOYMENTS` | JSON-encoded deployment metadata populated by the extension for agent workflows. | | ||
| | `AI_PROJECT_DEPENDENT_RESOURCES` | JSON-encoded dependent resource metadata populated by the extension for agent workflows. | | ||
| | `ENABLE_HOSTED_AGENTS` | If set, indicates that hosted agents are enabled for the current azd environment. | | ||
| | `ENABLE_CONTAINER_AGENTS` | If set, indicates that container agents are enabled for the current azd environment. | | ||
|
|
||
| ## UI Prompt Integration | ||
|
|
||
| | Variable | Description | | ||
| | --- | --- | | ||
| | `AZD_UI_PROMPT_ENDPOINT` | The endpoint for external UI prompt service integration. | | ||
| | `AZD_UI_PROMPT_KEY` | The authentication key for the external UI prompt service. | | ||
| | `AZD_UI_NO_PROMPT_DIALOG` | If true, disables prompt dialog UI. | | ||
|
|
||
| ## Telemetry & Tracing | ||
|
|
||
| | Variable | Description | | ||
| | --- | --- | | ||
| | `AZURE_DEV_COLLECT_TELEMETRY` | If false, disables telemetry collection. Telemetry is enabled by default. | | ||
| | `AZURE_DEV_USER_AGENT` | Appends a custom string to the `User-Agent` header sent with Azure requests. | | ||
| | `TRACEPARENT` | The W3C Trace Context `traceparent` header for distributed tracing. Automatically set by azd on extension processes for trace propagation. Not typically set by users. | | ||
| | `TRACESTATE` | The W3C Trace Context `tracestate` header for vendor-specific trace data. Automatically set by azd alongside `TRACEPARENT`. Not typically set by users. | | ||
|
|
||
| ## CI/CD Variables | ||
|
|
||
| These variables are read by `azd` to detect and integrate with CI/CD systems. | ||
|
|
||
| ### Azure Pipelines | ||
|
|
||
| | Variable | Description | | ||
| | --- | --- | | ||
| | `TF_BUILD` | Set to `True` when running in Azure Pipelines. | | ||
| | `BUILD_BUILDID` | The build ID in Azure Pipelines. | | ||
| | `BUILD_BUILDNUMBER` | The build number in Azure Pipelines. | | ||
| | `SYSTEM_ACCESSTOKEN` | The access token for Azure Pipelines service connections. | | ||
| | `SYSTEM_TEAMPROJECTID` | The Team Project ID in Azure DevOps. | | ||
| | `SYSTEM_OIDCREQUESTURI` | The OIDC request URI for federated identity in Azure Pipelines. | | ||
| | `AZURESUBSCRIPTION_CLIENT_ID` | The client ID from the Azure service connection. | | ||
| | `AZURESUBSCRIPTION_TENANT_ID` | The tenant ID from the Azure service connection. | | ||
| | `AZURESUBSCRIPTION_SERVICE_CONNECTION_ID` | The service connection ID in Azure DevOps. | | ||
| | `AZURESUBSCRIPTION_SUBSCRIPTION_ID` | The subscription ID from the Azure service connection. | | ||
|
|
||
| ### GitHub Actions | ||
|
|
||
| | Variable | Description | | ||
| | --- | --- | | ||
| | `GITHUB_ACTIONS` | Set to `true` when running in GitHub Actions. | | ||
| | `GITHUB_RUN_ID` | The unique ID of the current GitHub Actions workflow run. | | ||
| | `AZURE_OIDC_TOKEN` | An OIDC token for Azure federated credential authentication. | | ||
| | `AZURE_OIDC_REQUEST_TOKEN` | The request token for Azure OIDC in GitHub Actions. | | ||
| | `AZURE_OIDC_REQUEST_URL` | The request URL for Azure OIDC in GitHub Actions. | | ||
| | `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | The GitHub Actions OIDC request token. | | ||
| | `ACTIONS_ID_TOKEN_REQUEST_URL` | The GitHub Actions OIDC request URL. | | ||
|
Contributor
There was a problem hiding this comment. [Medium] Missing The Consider adding it to this section: |
||
|
|
||
| ### General CI | ||
|
|
||
| | Variable | Description | | ||
| | --- | --- | | ||
| | `CI` | Set to `true` when running in a generic CI environment. | | ||
|
|
||
| ## Terraform Provider Variables | ||
|
|
||
| These variables are used by the Terraform provider integration to authenticate with Azure. | ||
|
|
||
| | Variable | Description | | ||
| | --- | --- | | ||
| | `ARM_TENANT_ID` | The Azure tenant ID for Terraform Azure provider. | | ||
| | `ARM_CLIENT_ID` | The Azure client ID for Terraform Azure provider. | | ||
| | `ARM_CLIENT_SECRET` | The Azure client secret for Terraform Azure provider. | | ||
| | `ARM_SUBSCRIPTION_ID` | The Azure subscription ID for Terraform Azure provider. | | ||
|
|
||
| ## Console & Terminal | ||
|
|
||
| | Variable | Description | | ||
| | --- | --- | | ||
| | `NO_COLOR` | If set, disables color output. See [no-color.org](https://no-color.org). | | ||
| | `FORCE_COLOR` | If set, forces color output regardless of terminal detection. | | ||
| | `COLUMNS` | Overrides the detected terminal width (in columns). | | ||
| | `TERM` | The terminal type. Used to detect terminal capabilities. | | ||
| | `BROWSER` | The browser command to use for opening URLs (e.g., during `azd auth login`). | | ||
|
|
||
| ## Debug Variables | ||
|
|
||
| > **Warning**: Debug variables are unsupported and may change or be removed without notice. | ||
|
|
||
| | Variable | Description | | ||
| | --- | --- | | ||
| | `AZD_DEBUG` | If true, enables debug mode. | | ||
| | `AZD_DEBUG_LOG` | If true, enables debug-level logging. | | ||
| | `AZD_DEBUG_TELEMETRY` | If true, enables debug-level telemetry output. | | ||
| | `AZD_DEBUG_LOGIN_FORCE_SUBSCRIPTION_REFRESH` | If true, forces a refresh of the subscription list on login. | | ||
| | `AZD_DEBUG_SYNTHETIC_SUBSCRIPTION` | If set, provides a synthetic subscription for testing. | | ||
| | `AZD_DEBUG_NO_ALPHA_WARNINGS` | If true, suppresses alpha feature warnings. | | ||
| | `AZD_DEBUG_PROVISION_PROGRESS_DISABLE` | If true, disables provision progress display. | | ||
|
Contributor
There was a problem hiding this comment. [Low] Minor description precision This variable is read by both the Bicep provider ( |
||
| | `AZD_DEBUG_DOTNET_APPHOST_USE_FIXED_MANIFEST` | If true, uses a fixed manifest for .NET Aspire app host. | | ||
| | `AZD_DEBUG_DOTNET_APPHOST_IGNORE_UNSUPPORTED_RESOURCES` | If true, ignores unsupported resources in .NET Aspire app host. | | ||
| | `AZD_DEBUG_SERVER_DEBUG_ENDPOINTS` | If true, enables debug endpoints in server mode. | | ||
| | `AZD_DEBUG_EXPERIMENTATION_TAS_ENDPOINT` | Overrides the experimentation TAS endpoint URL. | | ||
| | `AZD_SUBSCRIPTIONS_FETCH_MAX_CONCURRENCY` | Limits the maximum concurrency when fetching subscriptions. | | ||
| | `DEPLOYMENT_STACKS_BYPASS_STACK_OUT_OF_SYNC_ERROR` | If true, bypasses Deployment Stacks out-of-sync errors. | | ||
| | `AGENT_DEFINITION_PATH` | Path to an agent definition file for AI agent workflows. | | ||
|
Contributor
There was a problem hiding this comment. This is specific to the azure.ai.agents extension - we may want to remove this or keep it in a separate section?
Member
Author
There was a problem hiding this comment. Agreed — will move the agents extension-specific vars to a separate section to keep the core doc focused. |
||
|
|
||
| ## Test Variables | ||
|
Contributor
There was a problem hiding this comment. There's also
Member
Author
There was a problem hiding this comment. Will add |
||
|
|
||
| > **Warning**: Test variables are used by the `azd` test suite only and are not intended for end users. | ||
|
|
||
| | Variable | Description | | ||
| | --- | --- | | ||
| | `AZD_TEST_CLIENT_ID` | The client ID for test authentication. | | ||
| | `AZD_TEST_TENANT_ID` | The tenant ID for test authentication. | | ||
| | `AZD_TEST_AZURE_SUBSCRIPTION_ID` | The Azure subscription ID for tests. | | ||
| | `AZD_TEST_AZURE_LOCATION` | The Azure location for tests. | | ||
| | `AZD_TEST_CLI_VERSION` | Overrides the CLI version reported during tests. | | ||
| | `AZD_TEST_FIXED_CLOCK_UNIX_TIME` | Sets a fixed clock time (Unix epoch) for deterministic tests. | | ||
| | `AZD_TEST_HTTPS_PROXY` | The HTTPS proxy URL for tests. | | ||
| | `AZD_TEST_DOCKER_E2E` | If true, enables Docker-based end-to-end tests. | | ||
| | `AZD_FUNC_TEST` | If true, indicates functional test mode. | | ||
| | `UPDATE_SNAPSHOTS` | If set, updates test snapshots when running snapshot-based tests. | | ||
| | `AZURE_RECORD_MODE` | Sets the record mode for Azure SDK test recordings. Valid values: `live`, `playback`, `record`. | | ||
| | `CLI_TEST_AZD_PATH` | Overrides the `azd` binary path used in CLI tests. | | ||
| | `CLI_TEST_SKIP_BUILD` | If true, skips building `azd` before running tests. | | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[Medium] Description is slightly misleading
The internal constant for this variable is
AppServiceAspireDashboardUrlEnvVarName, indicating it's specifically for the .NET Aspire dashboard URL on App Service, not a generic App Service dashboard.Consider updating the description to be more precise: