Comença en 5 minuts

Com fas arribar un secret d'AWS SSM Parameter Store o Azure Key Vault a una app en marxa? Instal·la la CLI d'Envilder, associa el secret a un nom de variable a l'envilder.json i arrenca l'app amb envilder exec, que passa el valor al procés sense escriure cap fitxer .env. Tot plegat porta uns cinc minuts quan les teves credencials del núvol ja funcionen.

Què faràs

  1. Instal·lar la CLI d'envilder.
  2. Pujar un secret de prova a AWS SSM Parameter Store o a Azure Key Vault amb envilder, que també escriu l'envilder.json.
  3. Revisar l'envilder.json que ha creat: associa un nom de variable al secret, mai al valor.
  4. Arrencar una petita app de Node.js amb envilder exec i comprovar que rep el valor.

Requisits previs

  • Node.js 22.12 o posterior.
  • AWS SSM: l'AWS CLI amb credencials que funcionin (aws configure, o aws sso login per a perfils SSO) i una identitat amb permís per cridar ssm:GetParameter sobre els paràmetres que mapegis. Si un paràmetre SecureString està xifrat amb una clau KMS gestionada pel client, la identitat també necessita kms:Decrypt sobre aquesta clau. Configuració d'AWS SSM
  • Azure Key Vault: un Key Vault existent, l'Azure CLI amb la sessió iniciada amb az login i el rol Key Vault Secrets User sobre el vault (o una política d'accés amb Get sobre secrets). Envilder s'autentica amb DefaultAzureCredential, de manera que una identitat administrada o credencials en variables d'entorn també funcionen. Configuració d'Azure Key Vault

El pas 2 crea un secret, cosa que requereix permís d'escriptura (ssm:PutParameter, o Key Vault Secrets Officer). Si el secret ja existeix, salta'l i escriu l'envilder.json a mà tal com es mostra al pas 3.

1. Instal·la la CLI

Instal·la envilder de manera global. Si prefereixes no instal·lar-lo, posa npx davant de cada ordre d'aquesta guia.

npm install -g envilder
pnpm add -g envilder
npx envilder --version

Comprova que l'ordre és al PATH. Mostra la versió:

envilder --version
0.20.0

2. Puja un secret de prova

Tria el teu proveïdor. Una sola ordre d'envilder desa el secret al vault i registra l'associació a l'envilder.json, així que aquest pas no necessita ni l'AWS CLI ni l'Azure CLI. La guia fa servir un sol secret: la contrasenya de la base de dades d'un entorn de desenvolupament. El valor queda a l'historial de la terminal; per a secrets reals, fes el push des d'un fitxer .env amb el mode push.

envilder --push --provider=aws --profile=default \
  --key=DB_PASSWORD --value=local-dev-password \
  --secret-path=/my-app/dev/db-password

A AWS, --provider=aws i --profile són opcionals: aws és el proveïdor per defecte i, sense --profile, Envilder fa servir la cadena de credencials per defecte d'AWS. El perfil és una elecció local i no s'escriu a l'envilder.json.

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

Els noms de Key Vault només admeten lletres, dígits i guions. Envilder converteix les barres en guions i elimina la barra inicial abans de cridar Azure, així que "/my-app/dev/db-password" resoldria el mateix secret. Tota la resta s'envia tal com està escrit.

3. Revisa l'envilder.json

El push ha creat l'envilder.json al directori actual, o hi ha afegit l'entrada si el fitxer ja existia. Cada clau és el nom de variable que llegeix la teva app i cada valor és l'identificador del secret al teu vault. Per a Azure també hi ha escrit $config amb provider i vaultUrl; AWS no necessita $config.

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

El fitxer conté camins de secrets, mai valors, així que desa'l al repositori amb el codi. Els editors validen l'envilder.json a través de SchemaStore sense línia $schema. Per pujar un secret sense tocar el fitxer de mapatge, afegeix --no-map-update.

4. Executa la teva app amb envilder exec

Crea un petit script que llegeixi la variable i arrenca'l a través d'Envilder. Tot el que va després de -- és la teva ordre, que es passa tal qual, sense shell.

app.jstypescript
const password = process.env.DB_PASSWORD;
console.log(
  password
    ? `DB_PASSWORD loaded (${password.length} characters)`
    : 'DB_PASSWORD missing',
);
envilder exec -- node app.js

Sortida esperada. La primera línia és Envilder a stderr; la segona, la teva app a stdout:

envilder: 1 secret resolved (aws) → node …
DB_PASSWORD loaded (18 characters)
envilder: 1 secret resolved (azure, vault=my-vault.vault.azure.net) → node …
DB_PASSWORD loaded (18 characters)

Envilder resol tots els secrets mapejats i després arrenca l'ordre amb aquests valors afegits al seu entorn. No escriu res al disc. Si algun secret falta, és buit o no es pot llegir, l'ordre no arrenca i envilder acaba amb el codi 125; si no, acaba amb el codi de la teva ordre.

Perquè aquesta sigui la manera habitual d'arrencar el projecte, posa-ho en un script del package.json i continua fent servir npm run dev:

package.jsonjson
{
  "scripts": {
    "dev": "envilder exec -- node app.js"
  }
}

Alternativa: escriure un fitxer .env

Algunes eines només llegeixen un fitxer, com l'env_file de Docker Compose o una configuració d'execució de l'IDE. En aquests casos, baixa els secrets a un fitxer .env. Sense opcions, envilder llegeix l'envilder.json i escriu .env al directori actual:

envilder

Sortida esperada amb AWS, seguida del fitxer que escriu:

☁ AWS identity · account=123456789012 · region=eu-west-1 · profile=default

🪙  RESOLVING SECRETS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✓ DB_PASSWORD         → ***************ord

⭐ LEVEL CLEARED  —  1/1 secrets loaded · .env written
.envdotenv
DB_PASSWORD=local-dev-password
⚠️
El fitxer .env conté els valors reals dels secrets: afegeix-lo al .gitignore i esborra'l quan ja no el necessitis. A diferència d'exec, pull omet amb un avís un secret que no existeix i escriu igualment els altres.

Errors habituals en la primera execució

Cada bloc mostra el text que imprimeix envilder. Amb exec, tots acaben amb el codi 125 i la teva ordre no arriba a arrencar.

No es troba el fitxer de mapatge

No map file found. Provide --map or create envilder.json in the current directory.

envilder busca l'envilder.json al directori actual. Executa'l des de l'arrel del projecte o passa --map=camí/a/envilder.json.

Sense credencials d'AWS

💥 GAME OVER — some secrets could not be fetched
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✗ DB_PASSWORD         → ********************ord

  ⮕ WHY?
     Could not load credentials from any providers

L'SDK d'AWS no ha trobat credencials. Executa aws configure, o aws sso login per a un perfil SSO. Per fer servir un perfil amb nom, passa --profile=nom o defineix "profile" a $config.

Accés denegat per AWS

User: arn:aws:sts::123456789012:assumed-role/<role>/<session> is not authorized to perform: ssm:GetParameter on resource: arn:aws:ssm:eu-west-1:123456789012:parameter/my-app/dev/db-password …

Les credencials funcionen, però la identitat no pot llegir aquest paràmetre. Permet ssm:GetParameter sobre l'ARN del paràmetre, i kms:Decrypt si el paràmetre fa servir una clau gestionada pel client.

Secret no trobat

  ✗ DB_PASSWORD         → ********************ord

  ⮕ WHY?
     not found

L'identificador o la regió no són correctes. A AWS, Envilder pren la regió d'AWS_REGION, després d'AWS_DEFAULT_REGION, després del perfil, i com a últim recurs fa servir us-east-1. Compara-ho amb aws ssm get-parameter --name /my-app/dev/db-password amb el mateix perfil. A Azure, revisa el nom del secret al vault.

Azure sense URL del vault

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, o passa --vault-url.

Opcions abans d'exec

error: Put envilder options after "exec": envilder exec --map=envilder.json -- node …

Les opcions escrites abans d'exec es rebutgen en lloc d'ignorar-se. Mou-les darrere d'exec, com indica el missatge.

--envfile amb exec

error: --envfile cannot be used with exec: exec mode never reads or writes a .env file.

exec mai escriu cap fitxer. Treu --envfile, o fes servir pull (envilder --envfile=.env) quan necessitis el fitxer.

Següents passos