Referencia del archivo de mapeo

Requisitos previos

Esta página describe el archivo de mapeo tal como lo leen la CLI de envilder (0.16) y la GitHub Action. Los SDK de runtime leen el mismo archivo. Si todavía no has resuelto ningún secreto, empieza por la guía de inicio.

Estructura

Un archivo de mapeo es un único objeto JSON. Las claves que empiezan por $ están reservadas; cualquier otra clave declara una variable de entorno y su valor es el identificador del secreto que la rellena.

{
  "$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"
}

Campos de $config

Todos los campos son opcionales. Un archivo sin $config usa AWS SSM con la cadena de credenciales por defecto de AWS.

Los SDK de runtime leen los mismos campos, pero pueden rechazar combinaciones que la CLI solo avisa, como profile con azure. Cada página de SDK lista sus propios errores.

Identificadores de secretos por proveedor

AWS SSM Parameter Store

El valor es el nombre del parámetro tal como está guardado en SSM, normalmente una ruta jerárquica. Envilder llama a GetParameter con descifrado, así que funcionan tanto los parámetros String como los SecureString. La región sale de AWS_REGION, después de AWS_DEFAULT_REGION, después del perfil, con us-east-1 como último recurso.

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

Azure Key Vault

El valor es el nombre del secreto. Envilder convierte las barras en guiones antes de llamar a Key Vault, así que puedes compartir el mismo estilo de rutas con un archivo de 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"
}

• Se eliminan las barras iniciales y el resto de barras pasan a ser guiones: "/my-app/prod/stripe-api-key" lee my-app-prod-stripe-api-key. El CLI, la GitHub Action y todos los SDKs aplican la misma regla.
• Todo lo demás se envía tal como está escrito. Un nombre que Key Vault rechace (por ejemplo con _ o .) falla con el error del propio Key Vault.
• En el CLI y la GitHub Action, dos valores distintos que resuelven al mismo nombre dentro de un archivo son un error.
• Envilder siempre lee la versión más reciente del secreto.

Precedencia entre $config y las opciones

Cada ajuste se resuelve por separado, a partir de la primera fuente que lo define:

Una opción solo sustituye el campo que nombra; los demás campos de $config siguen aplicándose. Las mismas reglas valen para pull, push y exec. Si se omite --map, envilder usa envilder.json en el directorio actual; pull y push también usan .env como valor por defecto 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 acepta los inputs provider y vault-url, pero no tiene input de perfil: en CI las credenciales vienen del workflow (por ejemplo, OIDC), no de un perfil con nombre.

Reglas de validación

envilder comprueba el archivo antes de contactar con ningún proveedor, así que un archivo no válido nunca resuelve solo una parte de sus secretos:

• El archivo debe ser JSON válido. No se permiten comentarios ni comas finales.
• Los nombres de variable deben cumplir ^[A-Za-z0-9_./-]+$: letras, dígitos, guion bajo, punto, guion y barra. Son los nombres que un archivo .env puede guardar y volver a leer sin cambios. Se rechazan espacios, =, #, letras acentuadas y saltos de línea.
• Un nombre con / (Database/Password) funciona en todas partes: los SDKs y exec lo pasan tal cual, y el SDK de .NET lo convierte en una sección de configuración. Al escribir un archivo .env, el CLI lo mantiene y avisa, porque python-dotenv carga esa línea pero dotenv para Node.js, Docker Compose y bash no; usa exec o un nombre con __ (Database__Password) si tu aplicación lee el archivo con uno de ellos.
• Se rechaza un nombre vacío.
• __proto__ no se puede usar como nombre de variable: el schema lo rechaza y envilder nunca lo resuelve, porque los parsers de .env no pueden volver a leerlo.
• La regla de nombres se aplica a todas las claves, aunque el valor no sea un string. Una clave con un valor que no es string (número, objeto, null) se omite y no se resuelve.
• Con exec en Windows se rechazan dos nombres que solo se diferencian en mayúsculas y minúsculas, porque Windows los trata como una única variable.
• El schema recomienda nombres POSIX (^[a-zA-Z_][a-zA-Z0-9_]*$). Los nombres con puntos y guiones se aceptan, pero algunas shells y herramientas no pueden leerlos como variables.

Contenido de los secretos (los valores resueltos)

Envilder nunca reescribe el valor de un secreto: lo que devuelve el proveedor es lo que recibe tu aplicación. Los límites dependen de dónde se guarda el valor:

Las APIs de los SDKs que solo resuelven (resolve, ResolveFile, IConfiguration) mantienen los valores en memoria y solo están sujetas a los límites del proveedor.

El CLI escribe cada valor de forma que dotenv lea exactamente el string original. Las comillas se eligen automáticamente y se comprueban analizando el resultado antes de escribir el archivo. La comprobación usa la gramática de dotenv ampliada a claves con /, así que para esas claves demuestra que el valor se lee igual, no que dotenv para Node.js las cargue (ignora esas líneas):

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

#, espacios al principio y al final, comillas, barras invertidas, un \n literal, saltos de línea LF/CRLF reales y Unicode se conservan todos. Si el archivo ya existe, cada asignación se sustituye en su sitio (una multilínea, entera), y se mantienen los comentarios, el orden y los finales de línea.

Ejemplo con varios entornos

Mantén un archivo por entorno con las mismas claves, así el código de la aplicación no cambia nunca. Solo cambian las rutas y 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"
}

Elige el archivo con --map. En local, ejecuta la app con el archivo de desarrollo; para un artefacto de producción, genera un .env a partir del archivo de producción:

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

En un workflow, apunta la action al archivo de ese entorno:

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

SchemaStore reconoce los nombres envilder.json y envilder.*.json, así que la mayoría de editores los validan incluso sin la línea $schema.

Errores habituales

Guías relacionadas

• Primeros pasos: de un secreto a una app en marcha
• Referencia de envilder exec
• Configuración de Azure Key Vault