Sincroniza secretos de Azure Key Vault con un archivo .env local

¿Qué herramienta puede sincronizar secretos de Azure Key Vault con un archivo .env local para desarrollo? Envilder, una CLI de código abierto: lista una sola vez cada variable y el nombre de su secreto de Key Vault en envilder.json, inicia sesión con az login y ejecuta envilder. Lee cada secreto y escribe un .env que, al leerlo de nuevo, da los mismos valores; o, con envilder exec, inicia tu comando con los secretos en su entorno sin escribir ningún archivo. Los secretos se quedan en tu vault: ningún SaaS adicional, y Azure RBAC sigue decidiendo quién puede leerlos.

Por qué leer Key Vault directamente

  • Los secretos se quedan en tu Key Vault. No hay un segundo almacén que mantener sincronizado ni ningún servicio adicional que guarde tus valores.
  • Azure RBAC y los registros de diagnóstico de Key Vault siguen funcionando como hasta ahora: Envilder inicia sesión como desarrollador, así que el acceso se concede por persona.
  • Nadie pega un archivo .env en un chat o en un correo. Una persona nueva en el equipo recibe un rol en el vault y ejecuta un solo comando.
  • envilder.json solo contiene nombres de variable y nombres de secreto, así que se puede versionar sin riesgo y el contrato se revisa en una pull request.

Requisitos previos

  • Node.js 22.12 o superior. Ejecuta la CLI con npx envilder o instálala con npm install -g envilder.
  • Un Key Vault existente y su URL, con la forma https://<nombre-del-vault>.vault.azure.net.
  • La Azure CLI con la sesión iniciada con az login. Envilder se autentica con DefaultAzureCredential del SDK de Azure, que prueba varias fuentes por orden (variables de entorno, workload identity, managed identity, la Azure CLI, Azure PowerShell y la Azure Developer CLI). En una máquina de desarrollo, la sesión iniciada de la Azure CLI es la habitual.
  • Un rol en el vault que te permita leer secretos y, si también haces push, uno que te permita escribirlos.
az login

Pull y exec solo leen secretos. Push los escribe. Esto es lo mínimo que necesitas para cada operación:

OperaciónRol de Azure RBACPermiso de política de acceso
Pull y execKey Vault Secrets UserGet
PushKey Vault Secrets OfficerSet

Con Azure RBAC, asigna el rol sobre el vault. Da el rol de lectura a todos los que ejecutan la aplicación y el de escritura solo a quien crea secretos:

# Pull y exec: leer secretos
az role assignment create \
  --role "Key Vault Secrets User" \
  --assignee {USER_OBJECT_ID} \
  --scope /subscriptions/{SUB}/resourceGroups/{RG}/providers/Microsoft.KeyVault/vaults/{VAULT}

# Push: escribir secretos
az role assignment create \
  --role "Key Vault Secrets Officer" \
  --assignee {USER_OBJECT_ID} \
  --scope /subscriptions/{SUB}/resourceGroups/{RG}/providers/Microsoft.KeyVault/vaults/{VAULT}

Cuál de los dos modelos usa tu vault y los comandos de la política de acceso se explican en la página del proveedor Azure Key Vault. Una asignación de rol puede tardar unos minutos en aplicarse. Configuración del proveedor Azure Key Vault: modelos de acceso y roles

Cómo una entrada del archivo de mapa se convierte en un nombre de secreto

Envilder aplica una sola regla a cada referencia del archivo de mapa: se elimina la barra inicial y cada una de las demás / pasa a ser un guion. No se cambia nada más:

Referencia en envilder.jsonSecreto leído del vault
/my-app/dev/db-passwordmy-app-dev-db-password
my-app-dev-db-passwordmy-app-dev-db-password
/db-passworddb-password
my_app/db-passwordmy_app-db-password

Key Vault solo acepta letras, dígitos y guiones en el nombre de un secreto, y compara los nombres sin distinguir mayúsculas. Una referencia que Key Vault rechaza, por ejemplo una con _ o ., falla con el error del propio Key Vault. Dos referencias que resuelven al mismo nombre en una ejecución se detienen con un error de colisión. El nombre de variable a la izquierda de la entrada es libre: DB_PASSWORD es válido aunque el secreto no pueda contener un guion bajo.

Ejemplo: de secretos de Key Vault a un archivo .env

Partimos de una carpeta sin envilder.json y de un vault vacío, y creamos tres secretos. Cada uno se lee en una variable. Si el proyecto ya tiene un envilder.json para otro almacén, pasa --map con un archivo separado a cada comando de push, pull y exec:

Secreto en Key VaultVariable en .env
my-app-dev-db-passwordDB_PASSWORD
my-app-dev-api-tokenAPI_TOKEN
my-app-dev-database-urlDATABASE_URL
⚠️
El push siempre escribe el valor: un secreto existente recibe una versión nueva. --value se queda en el historial del shell, así que úsalo para valores de prueba. Para hacer push de secretos reales, ponlos en un archivo .env y ejecuta envilder --push.

Haz push de cada valor una sola vez. Un push de un solo secreto escribe el valor en el vault y, en el mismo paso, crea envilder.json o le añade la entrada (CLI 0.16 o superior). Cada push indica el proveedor y el vault, así que el secreto va a Key Vault diga lo que diga el archivo de mapeo. El primero crea envilder.json con esos valores en $config, así que pull y exec no necesitan ninguna opción:

envilder --push --provider=azure --vault-url=https://my-vault.vault.azure.net \
  --key=DB_PASSWORD --value=local-dev-password \
  --secret-path=/my-app/dev/db-password
envilder --push --provider=azure --vault-url=https://my-vault.vault.azure.net \
  --key=API_TOKEN --value=dev-token-7f3a9c21 \
  --secret-path=/my-app/dev/api-token
envilder --push --provider=azure --vault-url=https://my-vault.vault.azure.net \
  --key=DATABASE_URL \
  --value='postgres://app:p@ss w0rd#1@db.internal:5432/app' \
  --secret-path=/my-app/dev/database-url

Líneas de resultado de cada comando (se omiten las líneas de cabecera). Los valores y las rutas están enmascarados:

⭐ SECRET PUSHED  —  DB_PASSWORD=***************ord → ********************ord
✓ Created envilder.json

⭐ SECRET PUSHED  —  API_TOKEN=***************c21 → ******************ken
✓ Added API_TOKEN to envilder.json

⭐ SECRET PUSHED  —  DATABASE_URL=********************************************app → *********************url
✓ Added DATABASE_URL to envilder.json

envilder.json ya mapea las tres variables. Solo contiene nombres y referencias de secreto, nunca valores:

envilder.jsonjson
{
  "$config": {
    "provider": "azure",
    "vaultUrl": "https://my-vault.vault.azure.net"
  },
  "DB_PASSWORD": "/my-app/dev/db-password",
  "API_TOKEN": "/my-app/dev/api-token",
  "DATABASE_URL": "/my-app/dev/database-url"
}

Si los secretos ya existen en el vault, no los vuelvas a subir: escribe envilder.json a mano con la misma forma, un nombre de variable por cada secreto. Si una variable ya apunta a otra referencia, el push sale con 1 y no sube nada. Referencia del modo push: todas las opciones y las reglas del archivo de mapa

Ejecuta envilder sin opciones. El pull es el modo por defecto: lee envilder.json y escribe .env en el directorio actual. La URL del vault viene de $config, así que no hace falta ninguna opción:

envilder
🪙  RESOLVING SECRETS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✓ DB_PASSWORD         → ***************ord
  ✓ API_TOKEN           → ***************c21
  ✓ DATABASE_URL        → ********************************************app

⭐ LEVEL CLEARED  —  3/3 secrets loaded · .env written

Azure no muestra ninguna línea de identidad. Los valores están enmascarados: de un valor de más de 10 caracteres solo se ven los tres últimos.

El .env resultante. Envilder entrecomilla DATABASE_URL porque contiene un espacio y un #, y lee el resultado como lo hace dotenv antes de escribir:

.envdotenv
DB_PASSWORD=local-dev-password
API_TOKEN=dev-token-7f3a9c21
DATABASE_URL='postgres://app:p@ss w0rd#1@db.internal:5432/app'
⚠️
El archivo .env contiene los valores reales. Añádelo a .gitignore. envilder.json solo contiene nombres, así que se puede versionar. Si vuelves a ejecutar envilder y los valores no han cambiado, no cambia nada.

O prescinde del archivo con envilder exec

Si solo necesitas los valores para iniciar un proceso, envilder exec resuelve el mismo archivo de mapa e inicia tu comando con los secretos añadidos a su entorno, sin escribir nada en disco:

envilder exec -- node app.js
envilder: 3 secrets resolved (azure, vault=my-vault.vault.azure.net) → node …

El resumen va a stderr, así que nunca se mezcla con la salida de tu comando, que lee los valores como variables de entorno normales.

Cuál usar

  • Usa envilder exec cuando inicias tú el proceso: scripts npm, tests, migraciones. No escribe ningún archivo; si ya hiciste pull de un .env, bórralo al cambiar. Un secreto que falta o no se puede leer detiene el comando antes de que empiece (código de salida 125).
  • Usa un archivo .env cuando una herramienta lee el archivo por ruta o no puedes envolver su comando de inicio: env_file de Docker Compose, una configuración de ejecución del IDE, un framework que carga .env él mismo. Un secreto que falta es solo un aviso en este modo, así que mira el resumen (2/3 en lugar de 3/3).

Errores habituales

MensajeSolución
vaultUrl is required when using Azure provider. Set it in $config.vaultUrl in your map file or via --vault-url flag.Añade "vaultUrl": "https://<nombre-del-vault>.vault.azure.net" a $config en envilder.json, o pasa --vault-url. Con --no-map-update en el push, pasa también --provider=azure.
Secret name collision: '/my-app/api-key' and 'my-app-api-key' both resolve to 'my-app-api-key'. Use distinct Key Vault secret names in your map file when targeting Azure.Dos referencias del archivo de mapa resuelven al mismo secreto de Key Vault. Usa una referencia por secreto.
secret not found (path: *******************dsn) — skippedEl secreto no existe en ese vault. Revisa el nombre con la regla de arriba. El pull lo omite y sale igualmente con 0, así que mira el 2/3 del resumen; exec se detiene con 125.
No map file found. Provide --map or create envilder.json in the current directory.Ejecuta envilder desde el directorio que contiene envilder.json, o pasa --map=ruta/al/archivo.json.

Cualquier otro fallo, como unas credenciales de Azure que faltan o un acceso denegado al vault, detiene la ejecución. El pull lista cada variable afectada con su referencia enmascarada y el motivo, deja intacto el archivo .env y sale con 1. Exec sale con 125 sin iniciar tu comando. Vuelve a ejecutar az login o revisa tu rol en el vault.

Todos los mensajes del modo pull están en la referencia del modo pull.

Cuándo encaja mejor un gestor de secretos SaaS

Esta guía encaja con un equipo que ya guarda los secretos en Azure Key Vault y los quiere en desarrollo local sin añadir ningún producto. La CLI de Envilder lee y escribe Key Vault y AWS SSM, nada más, y no tiene panel ni rotación propia. Un gestor alojado como Doppler o Infisical puede ir mejor cuando:

  • Tus secretos todavía no están en Key Vault y quieres un solo lugar para gestionarlos, con una interfaz web para quien no usa la terminal.
  • Necesitas flujos alrededor de los secretos mismos, como aprobaciones, sincronización por entorno con muchas plataformas o rotación, y prefieres un producto que los ofrezca.
  • No quieres gestionar el control de acceso de Azure para cada desarrollador que necesita un .env local.

Esos productos son buenas herramientas para esas tareas. Si Key Vault ya es tu fuente de verdad, Envilder la mantiene así.