Sincronitza secrets d'Azure Key Vault amb un fitxer .env local

Quina eina pot sincronitzar secrets d'Azure Key Vault amb un fitxer .env local per a desenvolupament? Envilder, una CLI de codi obert: llista una sola vegada cada variable i el nom del seu secret de Key Vault a envilder.json, inicia sessió amb az login i executa envilder. Llegeix cada secret i escriu un .env que, un cop llegit de nou, dona els mateixos valors; o, amb envilder exec, inicia la teva ordre amb els secrets al seu entorn sense escriure cap fitxer. Els secrets es queden al teu vault: cap SaaS addicional, i Azure RBAC continua decidint qui els pot llegir.

Per què llegir Key Vault directament

  • Els secrets es queden al teu Key Vault. No hi ha un segon magatzem per mantenir sincronitzat ni cap servei addicional que guardi els teus valors.
  • Azure RBAC i els registres de diagnòstic de Key Vault continuen funcionant com ara: Envilder inicia sessió com a desenvolupador, així que l'accés es concedeix per persona.
  • Ningú enganxa un fitxer .env en un xat o en un correu. Una persona nova a l'equip rep un rol al vault i executa una sola ordre.
  • envilder.json només conté noms de variable i noms de secret, així que es pot versionar sense risc i el contracte es revisa en una pull request.

Requisits previs

  • Node.js 22.12 o superior. Executa la CLI amb npx envilder o instal·la-la amb npm install -g envilder.
  • Un Key Vault existent i la seva URL, amb la forma https://<nom-del-vault>.vault.azure.net.
  • L'Azure CLI amb la sessió iniciada amb az login. Envilder s'autentica amb DefaultAzureCredential de l'SDK d'Azure, que prova diverses fonts per ordre (variables d'entorn, workload identity, managed identity, l'Azure CLI, Azure PowerShell i l'Azure Developer CLI). En una màquina de desenvolupament, la sessió iniciada de l'Azure CLI és l'habitual.
  • Un rol al vault que et permeti llegir secrets i, si també fas push, un que et permeti escriure'ls.
az login

Pull i exec només llegeixen secrets. Push els escriu. Això és el mínim que necessites per a cada operació:

OperacióRol d'Azure RBACPermís de política d'accés
Pull i execKey Vault Secrets UserGet
PushKey Vault Secrets OfficerSet

Amb Azure RBAC, assigna el rol sobre el vault. Dona el rol de lectura a tothom qui executa l'aplicació i el d'escriptura només a qui crea secrets:

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

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

Quin dels dos models fa servir el teu vault i les ordres de la política d'accés s'expliquen a la pàgina del proveïdor Azure Key Vault. Una assignació de rol pot trigar uns minuts a aplicar-se. Configuració del proveïdor Azure Key Vault: models d'accés i rols

Com una entrada del fitxer de mapa esdevé un nom de secret

Envilder aplica una sola regla a cada referència del fitxer de mapa: se suprimeix la barra inicial i cada una de les altres / passa a ser un guionet. No es canvia res més:

Referència a envilder.jsonSecret llegit 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 només accepta lletres, dígits i guionets en el nom d'un secret, i compara els noms sense distingir majúscules. Una referència que Key Vault rebutja, per exemple una amb _ o ., falla amb l'error del mateix Key Vault. Dues referències que resolen al mateix nom en una execució s'aturen amb un error de col·lisió. El nom de variable de l'esquerra de l'entrada és lliure: DB_PASSWORD és correcte tot i que el secret no pot contenir un guió baix.

Exemple: de secrets de Key Vault a un fitxer .env

Partim d'una carpeta sense envilder.json i d'un vault buit, i creem tres secrets. Cadascun es llegeix en una variable. Si el projecte ja té un envilder.json per a un altre magatzem, passa --map amb un fitxer separat a cada ordre de push, pull i exec:

Secret a Key VaultVariable al .env
my-app-dev-db-passwordDB_PASSWORD
my-app-dev-api-tokenAPI_TOKEN
my-app-dev-database-urlDATABASE_URL
⚠️
El push sempre escriu el valor: un secret existent en rep una versió nova. --value es queda a l'historial del shell, així que fes-lo servir per a valors de prova. Per fer push de secrets reals, posa'ls en un fitxer .env i executa envilder --push.

Fes push de cada valor una sola vegada. Un push d'un sol secret escriu el valor al vault i, en el mateix pas, crea envilder.json o hi afegeix l'entrada (CLI 0.16 o superior). Cada push indica el proveïdor i el vault, així que el secret va a Key Vault digui el que digui el fitxer de mapatge. El primer crea envilder.json amb aquests valors a $config, així que pull i exec no necessiten cap opció:

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ínies de resultat de cada ordre (s'ometen les línies de capçalera). Els valors i les rutes estan emmascarats:

⭐ 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 ja mapeja les tres variables. Només conté noms i referències de secret, mai valors:

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 els secrets ja existeixen al vault, no els tornis a pujar: escriu envilder.json a mà amb la mateixa forma, un nom de variable per cada secret. Si una variable ja apunta a una altra referència, el push surt amb 1 i no puja res. Referència del mode push: totes les opcions i les regles del fitxer de mapa

Executa envilder sense opcions. El pull és el mode per defecte: llegeix envilder.json i escriu .env al directori actual. La URL del vault ve de $config, així que no cal cap opció:

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

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

Azure no mostra cap línia d'identitat. Els valors estan emmascarats: d'un valor de més de 10 caràcters només es veuen els tres últims.

El .env resultant. Envilder posa DATABASE_URL entre cometes perquè conté un espai i un #, i llegeix el resultat com ho fa dotenv abans d'escriure:

.envdotenv
DB_PASSWORD=local-dev-password
API_TOKEN=dev-token-7f3a9c21
DATABASE_URL='postgres://app:p@ss w0rd#1@db.internal:5432/app'
⚠️
El fitxer .env conté els valors reals. Afegeix-lo a .gitignore. envilder.json només conté noms, així que es pot versionar. Si tornes a executar envilder i els valors no han canviat, no canvia res.

O prescindeix del fitxer amb envilder exec

Si només necessites els valors per iniciar un procés, envilder exec resol el mateix fitxer de mapa i inicia la teva ordre amb els secrets afegits al seu entorn, sense escriure res al disc:

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

El resum va a stderr, així que mai es barreja amb la sortida de la teva ordre, que llegeix els valors com a variables d'entorn normals.

Quin fer servir

  • Fes servir envilder exec quan inicies tu el procés: scripts npm, tests, migracions. No escriu cap fitxer; si ja havies fet pull d'un .env, esborra'l quan canviïs. Un secret que falta o no es pot llegir atura l'ordre abans que comenci (codi de sortida 125).
  • Fes servir un fitxer .env quan una eina llegeix el fitxer per ruta o no pots embolcallar-ne l'ordre d'inici: env_file de Docker Compose, una configuració d'execució de l'IDE, un framework que carrega .env ell mateix. Un secret que falta només és un avís en aquest mode, així que mira el resum (2/3 en comptes de 3/3).

Errors habituals

MissatgeSolució
vaultUrl is required when using Azure provider. Set it in $config.vaultUrl in your map file or via --vault-url flag.Afegeix "vaultUrl": "https://<nom-del-vault>.vault.azure.net" a $config d'envilder.json, o passa --vault-url. Amb --no-map-update al push, passa també --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.Dues referències del fitxer de mapa resolen al mateix secret de Key Vault. Fes servir una referència per secret.
secret not found (path: *******************dsn) — skippedEl secret no existeix en aquell vault. Revisa el nom amb la regla de dalt. El pull l'omet i surt igualment amb 0, així que mira el 2/3 del resum; exec s'atura amb 125.
No map file found. Provide --map or create envilder.json in the current directory.Executa envilder des del directori que conté envilder.json, o passa --map=ruta/al/fitxer.json.

Qualsevol altre error, com unes credencials d'Azure que falten o un accés denegat al vault, atura l'execució. El pull llista cada variable afectada amb la seva referència emmascarada i el motiu, deixa intacte el fitxer .env i surt amb 1. Exec surt amb 125 sense iniciar la teva ordre. Torna a executar az login o revisa el teu rol al vault.

Tots els missatges del mode pull són a la referència del mode pull.

Quan un gestor de secrets SaaS encaixa millor

Aquesta guia encaixa amb un equip que ja guarda els secrets a Azure Key Vault i els vol en desenvolupament local sense afegir cap producte. La CLI d'Envilder llegeix i escriu Key Vault i AWS SSM, res més, i no té panell ni rotació pròpia. Un gestor allotjat com Doppler o Infisical pot anar millor quan:

  • Els teus secrets encara no són a Key Vault i vols un sol lloc per gestionar-los, amb una interfície web per a qui no fa servir el terminal.
  • Necessites fluxos al voltant dels secrets mateixos, com aprovacions, sincronització per entorn amb moltes plataformes o rotació, i prefereixes un producte que els ofereixi.
  • No vols gestionar el control d'accés d'Azure per a cada desenvolupador que necessita un .env local.

Aquests productes són bones eines per a aquestes tasques. Si Key Vault ja és la teva font de veritat, Envilder la manté així.