Trabajar con variables de entorno de la CLI para desarrolladores de Azure

La CLI para desarrolladores de Azure (azd) usa variables de entorno para almacenar y administrar opciones de configuración para entornos de implementación. Estas variables controlan cómo se aprovisiona, implementa y ejecuta la aplicación en Azure. En este artículo se explica cómo funcionan las variables de entorno dentro azd de los entornos y se proporcionan instrucciones sobre cómo administrarlas de forma eficaz.

Descripción de las variables de entorno

En el contexto de la CLI para desarrolladores de Azure, las variables de entorno son pares clave-valor que están vinculados a entornos con nombre específicos, como desarrollo, prueba o prod. Cada azd entorno mantiene su propio conjunto de variables de entorno, lo que le permite configurar diferentes opciones para distintos destinos de implementación.

Las variables de entorno de azd se almacenan en .env archivos dentro de las carpetas de entorno de la .azure carpeta . Sirven como entradas para:

Flujos de trabajo de implementación de aplicaciones
Configuraciones para servicios y conexiones de Azure
Aprovisionamiento de infraestructura a través de Bicep y Terraform

A diferencia de las variables de entorno tradicionales que existen en el nivel de sistema operativo, azd las variables de entorno se limitan a entornos específicos dentro del proyecto, lo que proporciona aislamiento entre distintos destinos de implementación.

Las variables de entorno proporcionan varias ventajas clave al trabajar con azd:

Aislamiento del entorno: mantenga las configuraciones de desarrollo, pruebas y producción independientes y distintas.
Coherencia de la configuración: asegúrese de que todos los miembros del equipo usan la misma configuración para un entorno específico.
Infraestructura como código: defina la parametrización de infraestructura mediante variables en lugar de valores codificados de forma rígida.
Automatización de la implementación: habilite las canalizaciones de CI/CD para implementar en entornos diferentes mediante el mismo código base, pero configuraciones diferentes.
Administración simplificada: actualice fácilmente la configuración en todos los servicios de un entorno desde una ubicación central.

Cada azd entorno tiene su propio conjunto de variables, lo que permite configuraciones específicas del entorno al usar el mismo código de aplicación y plantillas de infraestructura.

Variables de entorno y archivos .env

Las azd variables de entorno se almacenan en .env archivos dentro de los directorios específicos del entorno del proyecto. Al crear un entorno mediante azd env new <name>, se crea una estructura de directorios:

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

El .env archivo usa un formato estándar en el que cada línea representa un par clave-valor:

KEY1=value1
KEY2=value2

Sugerencia

Visite el artículo Trabajar con entornos para obtener más información sobre azd los entornos.

Al ejecutar comandos como azd up, azd carga automáticamente variables desde el archivo del entorno seleccionado .env .

Estas variables influyen en:

Aprovisionamiento de infraestructura: variables como AZURE_LOCATION y AZURE_SUBSCRIPTION_ID determinan dónde y cómo se crean los recursos.
Implementación: variables como puntos de conexión de servicio controlan cómo se conecta la aplicación a los servicios de Azure.
Configuración de la aplicación: las variables se pueden pasar a la configuración de la aplicación para controlar su comportamiento.
Nomenclatura de recursos: variables como AZURE_RESOURCE_GROUP influyen en los patrones de nomenclatura de recursos.

El .env archivo también se actualiza automáticamente azd durante las operaciones como azd init, azd provisiony azd deploy, capturando salidas de las plantillas de infraestructura y almacenándolas para su uso futuro.

Establecimiento de variables de entorno

Puede usar diferentes métodos para establecer azd variables de entorno, en función del escenario.

Uso de comandos de la CLI

La manera recomendada de establecer una variable de entorno es usar el azd env set comando , que incluye comprobaciones para garantizar valores válidos:

azd env set <key> <value>

Por ejemplo, para establecer un valor de configuración para la aplicación:

azd env set API_TIMEOUT 5000

El comando agrega o actualiza la variable en el .env archivo del entorno seleccionado actualmente. También puede tener como destino un entorno específico mediante la --environment marca :

azd env set API_TIMEOUT 5000 --environment prod

Para comprobar que la variable de entorno se estableció correctamente:

azd env get-value API_TIMEOUT

Salida de Bicep

Una característica eficaz de es su capacidad de capturar automáticamente los parámetros de salida de las plantillas de azd infraestructura de Bicep como variables de entorno. Por ejemplo, al definir un parámetro de salida en el main.bicep archivo:

output API_ENDPOINT string = apiService.outputs.SERVICE_ENDPOINT_URL

Después de ejecutar azd provision, esta salida se guarda automáticamente en el archivo del .env entorno:

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

Este enfoque garantiza que la aplicación siempre tenga acceso a la información de recursos más actual, como:

Puntos de conexión de servicio y direcciones URL
Nombres e identificadores de recursos

Obtención y uso de variables de entorno

Una vez establecido, puede acceder a variables de entorno en varios contextos.

Comandos de la CLI

Para ver todas las variables de entorno del entorno actual:

azd env get-values

Para ver el valor de una variable específica:

azd env get-value API_ENDPOINT

Para la salida legible por máquina (útil en scripts):

azd env get-values --output json

Uso de variables de entorno en archivos de infraestructura

Puede usar variables de entorno para personalizar las plantillas de infraestructura. Esto resulta útil para asignar nombres, etiquetado o configurar recursos en función del entorno actual. azd también usa etiquetas para buscar recursos en Azure para la implementación y otras tareas.

Tenga en cuenta el siguiente flujo común:

Durante azd init, azd establece estas variables de entorno en función de la respuesta del usuario a las solicitudes:
```
AZURE_ENV_NAME=myapp-dev
AZURE_LOCATION=eastus2
```

Haga referencia a esas variables en main.parameters.json la infra carpeta . azd sustituye los valores durante el aprovisionamiento y pasa los parámetros resueltos a 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}"
    }
  }
}

Defina los parámetros coincidentes en la plantilla de Bicep:

@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 proporciona estos parámetros de Bicep con los valores sustituidos en main.parameters.json.

Use los parámetros para la nomenclatura y las etiquetas de recursos para identificar posteriormente a qué entorno pertenece un recurso:

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

Este patrón mantiene las plantillas flexibles, habilita la personalización por entorno sin cambios de código y mejora la gobernanza de recursos (nomenclatura, etiquetado y detección).

Nota:

azd también se basa en el etiquetado para localizar los recursos de Azure durante la fase de implementación.

Enlaces

azd Las variables de entorno se cargan automáticamente y están disponibles en enlaces y scripts personalizados definidos en el azure.yaml archivo, puede acceder a las variables de entorno mediante la sintaxis siguiente:

Bash
PowerShell

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

Puede definir enlaces en el azure.yaml archivo para ejecutar estos scripts en puntos específicos del ciclo de azd vida:

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

Sugerencia

Visite el artículo Personalización de flujos de trabajo mediante enlaces para obtener más información sobre el uso de enlaces.

Quitar o actualizar variables

Para quitar una variable del entorno:

azd env unset VARIABLE_NAME

Para actualizar una variable existente:

azd env set VARIABLE_NAME "new-value"

Para actualizar las variables de entorno locales desde el estado actual de los recursos de Azure:

azd env refresh

Actualizar el entorno es útil cuando:

Quiere asegurarse de que el archivo local .env refleja las salidas más recientes de la infraestructura (como cadenas de conexión, puntos de conexión, etc.).
Debe sincronizar las variables de entorno después de que un compañero de equipo actualice el entorno.

Variables de entorno de AZD frente a OS

azd las variables de entorno y las variables de entorno del sistema operativo sirven para diferentes propósitos y funcionan de maneras diferentes:

Concepto	CLI para desarrolladores de Azure	Sistema operativo
Ubicación	Almacenados en `.azure/<env-name>/.env` archivos	Establecer en el entorno del sistema operativo
Ámbito	Con ámbito a un entorno con nombre específico dentro de un proyecto	Global para la sesión de usuario o el sistema
Administración	Administrado mediante `azd env` comandos	Administrado mediante comandos específicos del sistema operativo (`export`, `set`, etc.)
Access	Cargado automáticamente por `azd` comandos	Normalmente se carga explícitamente en scripts o aplicaciones
Target	Vinculado a los recursos e implementaciones de Azure	Configuración del sistema de uso general
Ciclo de vida	Conservar entre sesiones de terminal	Puede ser temporal o persistente en función de cómo se establezcan.

azd no lee ni escribe automáticamente variables de entorno del sistema operativo. Sin embargo, puede interactuar con ambos tipos de variables mediante scripts personalizados.

Lee azd las variables de entorno y las variables de entorno del sistema operativo:

Bash
PowerShell

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

Escriba azd variables de entorno en variables de entorno del sistema operativo o marco:

Bash
PowerShell

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

Variables de entorno estándar

azd establece y usa varias variables de entorno comunes en todos los entornos:

Variable	Descripción	Example	Cuándo se establece
`AZURE_ENV_NAME`	Nombre del entorno actual	`dev`	Cuando se crea el entorno
`AZURE_LOCATION`	Región de Azure donde se implementan los recursos	`eastus`	Durante el primer aprovisionamiento
`AZURE_SUBSCRIPTION_ID`	Identificador de la suscripción de Azure usada	`00000000-0000-0000-0000-000000000000`	Durante el primer aprovisionamiento
`AZURE_RESOURCE_GROUP`	Nombre del grupo de recursos	`rg-myapp-dev`	Durante el aprovisionamiento
`AZURE_PRINCIPAL_ID`	Identificador de usuario o entidad de servicio en ejecución	`00000000-0000-0000-0000-000000000000`	Durante el aprovisionamiento
`AZURE_PRINCIPAL_TYPE`	Tipo de una entidad de seguridad en el entorno.	`1a2b3c`	Durante el aprovisionamiento
`AZURE_TENANT_ID`	Identificador del tenant de Azure utilizado.	`00000000-0000-0000-0000-000000000000`	Durante el aprovisionamiento

Consideraciones sobre secretos y datos confidenciales

Aunque las variables de entorno son cómodas para la configuración, requieren un control especial para los datos confidenciales:

Evite almacenar secretos en archivos .env.

.env los archivos se almacenan normalmente en texto sin formato y pueden ser fácilmente:

Confirmación accidental en el control de código fuente
Compartido o copiado sin protecciones adecuadas
Visto por cualquier persona con acceso a los archivos del proyecto
Incluidos en registros o informes de errores

Advertencia

Nunca almacene secretos en un archivo de la CLI .env para desarrolladores de Azure. Estos archivos se pueden compartir o copiar fácilmente en ubicaciones no autorizadas o se pueden comprobar en el control de código fuente. Use servicios como Azure Key Vault o Control de acceso basado en rol de Azure (RBAC) para soluciones protegidas o sin secretos.

Alternativas para controlar secretos

En el caso de los datos confidenciales, tenga en cuenta estos enfoques más seguros:

Referencias de Azure Key Vault: almacene secretos en Azure Key Vault y haga referencia a ellos en el .env archivo:
```
azd env set-secret <secret-value>
```
Este comando crea un secreto de Key Vault y almacena una referencia a él en el archivo en .env lugar del valor real.
Identidades administradas: configure los servicios de Azure para que usen identidades administradas en lugar de cadenas de conexión o claves de acceso.
Seguridad específica del entorno: aplique controles de seguridad más estrictos a entornos de producción que los de desarrollo.
Secretos Just-In-Time: genere credenciales de corta duración durante la implementación en lugar de almacenar secretos persistentes.

Pasos siguientes

Trabajar con entornos en la CLI para desarrolladores de Azure Personalización de los flujos de trabajo de la CLI para desarrolladores de Azure mediante enlaces

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-08-16