provisioning: Define mapping between `AZURE_ENV_VAR` to parameter

[weikanglim]

Background

azd users currently define a mapping between environment variables (AZURE_ENV_NAME) and Bicep parameters (envName) inside main.parameters.json and main.bicepparam. While this works, from a UX perspective, it introduces another point of configuration with users. The environment substitution syntax, while powerful and used in many advanced cases, is also a potential source of misconfiguration due to lacking of upfront tooling validation.

Proposal

Define an automatic naming translation rule between environment variables and provisioning parameters. When variables are not mapped explicitly, azd will automatically allow for an environment variable override for parameters.

Some useful background to consider:

• For Terraform, this already exists as TF_VAR_<case sensitive variable name>, described in the Terraform docs.
• For Bicep, this convention does not yet exist. However, we are currently using scaffold.EnvFormat for some Aspire-related work.

Some properties of this proposal:

1. This proposal would not change the current explicit mapping behavior.
2. This proposal would contribute towards a design where pipeline config would set individual key-values rather than a JSON object, such as AZD_INITIAL_ENVIRONMENT_CONFIG. This would help with troubleshooting and debugging for DevOps scenarios.

Risks

For advanced DevOps users that are largely familiar with the Azure Bicep ecosystem, there may be slight hesitation towards adopting environment variables as input parameters (even if they are just overrides). An observation that may reduce assessment of this risk is that we have seen through wide-usage of environment variables over parameter files based on current azd usage in the template ecosystem.

[pamelafox]

With the AZURE_VAR mapping, is that how they would get set, i.e. azd env set AZURE_VAR_OPENAI_ENDPOINT ? Or is this only for picking up globally set env variables?

[weikanglim]

Hi @pamelafox! The current proposal is that we'd use AZURE_ as the mapping prefix. From our early conversation in #4383, there was a concern with AZURE_ having name collisions with other commonly used az environment variables.

The alternative proposal is to adopt something that would avoid naming collisions, such as AZURE_VAR_ as the mapping prefix. If we do such a thing, both system and azd environment variable would be mapped to AZURE_VAR_OPENAI_ENDPOINT -- I think we'd want to keep the consistency between azd and system environment here, but always open to suggestions here.