Referència del mode pull

Requisits previs

• La CLI d'envilder.
• Un fitxer de mapatge, envilder.json per defecte, que associa cada variable a un identificador de secret.
• Accés de lectura a tots els secrets mapats: ssm:GetParameter a AWS (més kms:Decrypt quan un paràmetre fa servir una clau gestionada pel client), o el permís Get de secrets a Azure Key Vault, per exemple amb el rol Key Vault Secrets User.
• Credencials que l'SDK del proveïdor pugui trobar: un perfil AWS, una sessió SSO o variables d'entorn, o un inici de sessió d'Azure com az login o una identitat gestionada.

Sinopsi

envilder [--map=<file>] [--envfile=<file>] \
  [--provider=aws|azure] [--vault-url=<url>] [--profile=<name>]

Pull és el mode per defecte: no hi ha cap subcomanda pull. Executa envilder sense opcions per llegir envilder.json i escriure .env al directori actual. Afegir --push, o --key, --value i --secret-path, canvia al mode push, i envilder exec és una subcomanda a part.

Opcions

Una opció que rep una ruta o un nom no accepta mai un valor que comenci per -. A envilder --map --envfile=.env, --map no té valor, així que l'execució s'atura amb error: option '--map <path>' argument missing en lloc de llegir --envfile=.env com a ruta. envilder --help llista totes les opcions.

Com es combinen $config i les opcions

Cada paràmetre surt de la primera font que el defineix: l'opció, després $config al fitxer de mapatge i després el valor per defecte. Una opció substitueix només el camp que anomena, així que la resta de camps de $config continuen aplicant-se. Pren aquest fitxer de producció:

{
  "$config": { "provider": "aws", "profile": "prod-account" },
  "DB_PASSWORD": "/my-app/prod/db-password"
}

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

La primera comanda fa servir la configuració del fitxer. La segona en substitueix un camp i manté la resta:

envilder --map=envilder.prod.json --envfile=.env.prod
envilder --map=envilder.prod.json --envfile=.env.prod --profile=ci-readonly

envilder --map=envilder.prod.json --envfile=.env.prod
envilder --map=envilder.prod.json --envfile=.env.prod \
  --vault-url=https://my-app-dr.vault.azure.net

Regles de precedència completes a la referència del fitxer de mapatge

Exemple: actualitzar un .env existent

El fitxer de mapatge declara quatre variables. Al vault, SENTRY_DSN no existeix i FEATURE_FLAG és buit. El projecte ja té un fitxer .env:

{
  "DB_PASSWORD": "/my-app/dev/db-password",
  "API_TOKEN": "/my-app/dev/api-token",
  "SENTRY_DSN": "/my-app/dev/sentry-dsn",
  "FEATURE_FLAG": "/my-app/dev/feature-flag"
}

# Local settings
LOG_LEVEL=debug
DB_PASSWORD=old-password
SENTRY_DSN=https://old-dsn.example.com/1

Executa envilder des de l'arrel del projecte. Sortida esperada amb AWS:

envilder

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

🪙  RESOLVING SECRETS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✓ DB_PASSWORD         → ***************ord
  ✓ API_TOKEN           → ***************c21
  ✗ SENTRY_DSN           secret not found (path: *******************dsn) — skipped
  ⚠ FEATURE_FLAG         no value found (path: *********************lag) — skipped

⭐ LEVEL CLEARED  —  2/4 secrets loaded · .env written

Amb Azure no es mostra la línia d'identitat d'AWS; la resta és igual. Els valors van emmascarats: un de més de 10 caràcters mostra els 3 últims, un de més curt s'amaga sencer, i les rutes mostren els 3 últims caràcters. Les línies omeses són avisos a stderr; la resta va a stdout.

El fitxer .env després:

# Local settings
LOG_LEVEL=debug
DB_PASSWORD=local-dev-password
SENTRY_DSN=https://old-dsn.example.com/1
API_TOKEN=dev-token-7f3a9c21

Com s'actualitza un .env existent

• Una variable mapada que ja és al fitxer es substitueix al seu lloc: la mateixa línia, el mateix comentari en línia i les mateixes cometes quan encara representen el valor nou.
• Una línia que ja té el valor correcte no es reescriu, així que una execució sense res de nou deixa el fitxer idèntic byte a byte.
• Es conserven les línies que el fitxer de mapatge no declara (LOG_LEVEL a l'exemple), els comentaris, les línies en blanc, l'ordre i els salts de línia.
• Les variables que encara no són al fitxer s'afegeixen al final. Un fitxer nou acaba amb un salt de línia.
• Un secret omès conserva el valor que el fitxer ja tenia (SENTRY_DSN a l'exemple). Envilder no elimina mai cap línia.
• Abans d'escriure, Envilder torna a llegir el resultat com ho fa dotenv. Si es perdés o canviés algun valor, no escriu res i s'atura amb un error que anomena les variables, mai els valors.

Les cometes, els valors multilínia i l'únic valor que un fitxer .env no pot contenir es descriuen a què pot contenir un secret

Secrets que falten, buits o que fallen

Un secret que no existeix (ParameterNotFound a AWS SSM, 404 a Key Vault) o que té el valor buit s'omet amb un avís. Els altres secrets s'escriuen igualment, el resum compta només els resolts (2/4 a l'exemple) i el codi de sortida és 0.

Qualsevol altra fallada, com un accés denegat, credencials que falten o un error de xarxa, atura l'execució. Envilder llista cada variable afectada amb la ruta emmascarada i el motiu, no toca el fitxer .env i surt amb 1:

💥 GAME OVER — some secrets could not be fetched
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✗ API_TOKEN           → ******************ken

  ⮕ WHY?
     User: arn:aws:sts::123456789012:assumed-role/dev/session is not authorized to perform: ssm:GetParameter on resource: arn:aws:ssm:eu-west-1:123456789012:parameter/my-app/dev/api-token …

Quan una sessió SSO d'AWS ha caducat i stdin i stdout són un terminal, Envilder pregunta Run 'aws sso login --profile dev' now? [y/N]. Si acceptes i l'inici de sessió funciona, ho torna a provar una vegada. A la CI, o si ho rebutges, mostra la comanda que cal executar i surt amb 1. Si un secret que falta també ha d'aturar l'execució, fes servir envilder exec: mai inicia una comanda amb un conjunt de secrets incomplet.

Errors habituals

Pàgines relacionades

• Referència del fitxer de mapatge: camps de $config, regles de validació i precedència de les opcions
• envilder exec: executa una comanda amb els mateixos secrets i sense fitxer .env
• Mode push: puja un fitxer .env o un sol secret
• Guia: carrega paràmetres d'AWS SSM en un fitxer .env, pas a pas