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 loginPull y exec solo leen secretos. Push los escribe. Esto es lo mínimo que necesitas para cada operación:
| Operación | Rol de Azure RBAC | Permiso de política de acceso |
|---|---|---|
| Pull y exec | Key Vault Secrets User | Get |
| Push | Key Vault Secrets Officer | Set |
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.json | Secreto leído del vault |
|---|---|
/my-app/dev/db-password | my-app-dev-db-password |
my-app-dev-db-password | my-app-dev-db-password |
/db-password | db-password |
my_app/db-password | my_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 Vault | Variable en .env |
|---|---|
my-app-dev-db-password | DB_PASSWORD |
my-app-dev-api-token | API_TOKEN |
my-app-dev-database-url | DATABASE_URL |
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-urlLí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.jsonenvilder.json ya mapea las tres variables. Solo contiene nombres y referencias de secreto, nunca valores:
{
"$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 writtenAzure 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:
DB_PASSWORD=local-dev-password
API_TOKEN=dev-token-7f3a9c21
DATABASE_URL='postgres://app:p@ss w0rd#1@db.internal:5432/app'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.jsenvilder: 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
| Mensaje | Solució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) — skipped | El 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í.