Referència del fitxer de mapatge

Requisits previs

Aquesta pàgina descriu el fitxer de mapatge tal com el llegeixen la CLI d'envilder (0.16) i la GitHub Action. Els SDK de runtime llegeixen el mateix fitxer. Si encara no has resolt cap secret, comença per la guia d'inici.

Estructura

Un fitxer de mapatge és un únic objecte JSON. Les claus que comencen per $ estan reservades; qualsevol altra clau declara una variable d'entorn i el seu valor és l'identificador del secret que l'omple.

{
  "$schema": "https://envilder.com/schema/map-file.v1.json",
  "$config": {
    "provider": "aws",
    "profile": "dev-account"
  },
  "DB_PASSWORD": "/my-app/dev/db-password",
  "STRIPE_API_KEY": "/my-app/dev/stripe/api-key"
}

Camps de $config

Tots els camps són opcionals. Un fitxer sense $config fa servir AWS SSM amb la cadena de credencials per defecte d'AWS.

Els SDK de runtime llegeixen els mateixos camps, però poden rebutjar combinacions de les quals la CLI només avisa, com profile amb azure. Cada pàgina d'SDK llista els seus propis errors.

Identificadors de secrets per proveïdor

AWS SSM Parameter Store

El valor és el nom del paràmetre tal com està desat a SSM, normalment un camí jeràrquic. Envilder crida GetParameter amb desxifratge, així que funcionen tant els paràmetres String com els SecureString. La regió surt d'AWS_REGION, després d'AWS_DEFAULT_REGION, després del perfil, amb us-east-1 com a últim recurs.

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

Azure Key Vault

El valor és el nom del secret. Envilder converteix les barres en guions abans de cridar Key Vault, així que pots compartir el mateix estil de camins amb un fitxer d'AWS:

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

• S'eliminen les barres inicials i la resta de barres passen a ser guions: "/my-app/prod/stripe-api-key" llegeix my-app-prod-stripe-api-key. El CLI, la GitHub Action i tots els SDKs apliquen la mateixa regla.
• Tota la resta s'envia tal com està escrit. Un nom que Key Vault rebutgi (per exemple amb _ o .) falla amb l'error del mateix Key Vault.
• Al CLI i a la GitHub Action, dos valors diferents que resolen al mateix nom dins un fitxer són un error.
• Envilder sempre llegeix la versió més recent del secret.

Precedència entre $config i les opcions

Cada paràmetre es resol per separat, a partir de la primera font que el defineix:

Una opció només substitueix el camp que anomena; la resta de camps de $config continuen aplicant-se. Les mateixes regles valen per a pull, push i exec. Si s'omet --map, envilder fa servir l'envilder.json del directori actual; pull i push també fan servir .env com a valor per defecte de --envfile.

envilder exec -- npm start
envilder exec --profile=staging-account -- npm start
envilder exec --provider=azure \
  --vault-url=https://other-vault.vault.azure.net -- npm start

La GitHub Action accepta els inputs provider i vault-url, però no té input de perfil: a CI les credencials venen del workflow (per exemple, OIDC), no d'un perfil amb nom.

Regles de validació

envilder comprova el fitxer abans de contactar cap proveïdor, de manera que un fitxer no vàlid mai resol només una part dels seus secrets:

• El fitxer ha de ser JSON vàlid. No s'hi permeten comentaris ni comes finals.
• Els noms de variable han de complir ^[A-Za-z0-9_./-]+$: lletres, dígits, guió baix, punt, guió i barra. Són els noms que un fitxer .env pot desar i tornar a llegir sense canvis. Es rebutgen espais, =, #, lletres accentuades i salts de línia.
• Un nom amb / (Database/Password) funciona a tot arreu: els SDKs i exec el passen tal qual, i el SDK de .NET el converteix en una secció de configuració. En escriure un fitxer .env, el CLI el manté i avisa, perquè python-dotenv carrega aquesta línia però dotenv per a Node.js, Docker Compose i bash no; fes servir exec o un nom amb __ (Database__Password) si la teva aplicació llegeix el fitxer amb un d’aquests.
• Es rebutja un nom buit.
• __proto__ no es pot fer servir com a nom de variable: l'schema el rebutja i envilder mai el resol, perquè els parsers de .env no el poden tornar a llegir.
• La regla de noms s'aplica a totes les claus, encara que el valor no sigui un string. Una clau amb un valor que no és string (número, objecte, null) s'omet i no es resol.
• Amb exec a Windows es rebutgen dos noms que només es diferencien en majúscules i minúscules, perquè Windows els tracta com una única variable.
• L'schema recomana noms POSIX (^[a-zA-Z_][a-zA-Z0-9_]*$). Els noms amb punts i guions s'accepten, però algunes shells i eines no els poden llegir com a variables.

Contingut dels secrets (els valors resolts)

Envilder no reescriu mai el valor d’un secret: el que retorna el proveïdor és el que rep la teva aplicació. Els límits depenen d’on es desa el valor:

Les APIs dels SDKs que només resolen (resolve, ResolveFile, IConfiguration) mantenen els valors en memòria i només estan subjectes als límits del proveïdor.

El CLI escriu cada valor de manera que dotenv en llegeixi exactament el string original. Les cometes s’escullen automàticament i es comproven analitzant el resultat abans d’escriure el fitxer. La comprovació fa servir la gramàtica de dotenv ampliada a claus amb /, així que per a aquestes claus demostra que el valor es llegeix igual, no que dotenv per a Node.js les carregui (ignora aquestes línies):

PLAIN=plain
QUOTES=she said "hi"
HASH='alpha#beta'
PADDED='  padded  '
MULTILINE="first\nsecond"

#, espais al principi i al final, cometes, barres inverses, un \n literal, salts de línia LF/CRLF reals i Unicode es conserven tots. Si el fitxer ja existeix, cada assignació es substitueix al seu lloc (una multilínia, sencera), i es mantenen els comentaris, l’ordre i els finals de línia.

Exemple amb diversos entorns

Mantén un fitxer per entorn amb les mateixes claus, així el codi de l'aplicació no canvia mai. Només canvien els camins i el perfil:

{
  "$schema": "https://envilder.com/schema/map-file.v1.json",
  "$config": { "provider": "aws", "profile": "dev-account" },
  "DB_PASSWORD": "/my-app/dev/db-password",
  "STRIPE_API_KEY": "/my-app/dev/stripe/api-key"
}

{
  "$schema": "https://envilder.com/schema/map-file.v1.json",
  "$config": { "provider": "aws", "profile": "prod-account" },
  "DB_PASSWORD": "/my-app/prod/db-password",
  "STRIPE_API_KEY": "/my-app/prod/stripe/api-key"
}

Tria el fitxer amb --map. En local, executa l'app amb el fitxer de desenvolupament; per a un artefacte de producció, genera un .env a partir del fitxer de producció:

envilder exec --map=envilder.dev.json -- npm run dev
envilder --map=envilder.prod.json --envfile=.env.prod

En un workflow, apunta l'action al fitxer d'aquell entorn:

- uses: macalbert/envilder/github-action@v0
  with:
    map-file: envilder.prod.json
    env-file: .env

SchemaStore reconeix els noms envilder.json i envilder.*.json, així que la majoria d'editors els validen fins i tot sense la línia $schema.

Errors habituals

Guies relacionades

• Primers passos: d'un secret a una app en marxa
• Referència d'envilder exec
• Configuració d'Azure Key Vault