Archivo de mapeo

Define los mapeos de variables de entorno y la configuración del proveedor en envilder.json.

Archivo de mapeo

El archivo de mapeo (envilder.json) es el núcleo de Envilder. Es un archivo JSON que mapea nombres de variables de entorno (claves) a rutas de secretos (valores) en tu proveedor en la nube.

📄

Estructura: Cada clave se convierte en un nombre de variable de entorno en tu archivo .env.Cada valor es la ruta donde vive el secreto en tu proveedor en la nube.

Formato básico (AWS SSM, por defecto)

Cuando no hay sección $config, Envilder usa AWS SSM Parameter Store por defecto. Los valores deben ser rutas de parámetros SSM válidas (normalmente comenzando con /):

envilder.jsonjson

{
  "API_KEY": "/myapp/prod/api-key",
  "DB_PASSWORD": "/myapp/prod/db-password",
  "SECRET_TOKEN": "/myapp/prod/secret-token"
}

Esto genera:

.envdotenv

API_KEY={value from /myapp/prod/api-key}
DB_PASSWORD={value from /myapp/prod/db-password}
SECRET_TOKEN={value from /myapp/prod/secret-token}

La sección $config

Añade una clave $config a tu archivo de mapeo para declarar qué proveedor en la nube usar y su configuración. Envilder lee $config para la configuración y trata todas las demás claves como mapeos de secretos.

Opciones de $config

Clave	Tipo	Por defecto	Descripción
`provider`	`"aws"` \| `"azure"`	`"aws"`	Proveedor en la nube a usar
`vaultUrl`	`string`	-	URL de Azure Key Vault (requerido cuando el proveedor es "azure")
`profile`	`string`	-	Perfil AWS CLI para configuraciones multi-cuenta (solo AWS)

AWS SSM con perfil

Para usar un perfil AWS CLI específico (útil para configuraciones multi-cuenta), añade profile a $config:

envilder.jsonjson

{
  "$config": {
    "provider": "aws",
    "profile": "prod-account"
  },
  "API_KEY": "/myapp/prod/api-key",
  "DB_PASSWORD": "/myapp/prod/db-password"
}

Esto indica a Envilder que use el perfil prod-account de tu archivo ~/.aws/credentials en lugar del perfil por defecto.

Azure Key Vault

Para Azure Key Vault, establece provider a "azure" y proporciona el vaultUrl:

envilder.jsonjson

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

⚠️

Convención de nombres Azure: Los nombres de secretos de Key Vault solo permiten caracteres alfanuméricos y guiones. Envilder normaliza automáticamente los nombres: barras y guiones bajos se convierten en guiones (ej., /myapp/db/password → myapp-db-password).

Diferencias clave por proveedor

	AWS SSM	Azure Key Vault
Formato de ruta de secreto	Rutas de parámetros con barras `/myapp/prod/api-key`	Nombres con guiones `myapp-prod-api-key`
$config requerido	Ninguno (AWS es por defecto)	`provider + vaultUrl`
$config opcional	`profile`	-
Autenticación	Credenciales AWS CLI	Azure Default Credentials

Múltiples entornos

Un patrón común es tener un archivo de mapeo por entorno. La estructura es la misma, solo cambian las rutas de los secretos:

config/dev/envilder.jsonjson

{
  "$config": {
    "provider": "aws",
    "profile": "dev-account"
  },
  "API_KEY": "/myapp/dev/api-key",
  "DB_PASSWORD": "/myapp/dev/db-password"
}

config/prod/envilder.jsonjson

{
  "$config": {
    "provider": "aws",
    "profile": "prod-account"
  },
  "API_KEY": "/myapp/prod/api-key",
  "DB_PASSWORD": "/myapp/prod/db-password"
}

Luego obtén el correcto:

# Development
envilder --map=config/dev/envilder.json --envfile=.env.dev

# Production
envilder --map=config/prod/envilder.json --envfile=.env.prod

Sobreescribir $config con flags CLI

Los flags CLI siempre tienen prioridad sobre los valores de $config. Esto te permite establecer valores por defecto en el archivo y sobreescribirlos por invocación:

# Uses $config from the map file as-is
envilder --map=envilder.json --envfile=.env

# Overrides provider and vault URL, ignoring $config
envilder --provider=azure \
  --vault-url=https://other-vault.vault.azure.net \
  --map=envilder.json --envfile=.env

# Overrides just the AWS profile
envilder --map=envilder.json --envfile=.env --profile=staging-account

Orden de prioridad: flags CLI / inputs GHA → $config en archivo de mapeo → por defecto (AWS).

Prioridad de configuración

Cuando hay múltiples fuentes de configuración, Envilder las resuelve en este orden (el más alto gana):

1. Flags CLI / inputs GHA

2. $config en el archivo de mapeo

3. Por defecto (AWS)

Esto significa que --provider=azure en la CLI sobreescribirá "provider": "aws" en $config.