Fitxer de mapatge

Defineix els mapatges de variables d'entorn i la configuració del proveïdor a envilder.json.

Fitxer de mapeig

El fitxer de mapeig (envilder.json) és el nucli d'Envilder. És un fitxer JSON que mapeja noms de variables d'entorn (claus) a rutes de secrets (valors) al teu proveïdor al núvol.

📄

Estructura: Cada clau es converteix en un nom de variable d'entorn al teu fitxer .env.Cada valor és la ruta on viu el secret al teu proveïdor al núvol.

Format bàsic (AWS SSM, per defecte)

Quan no hi ha secció $config, Envilder utilitza AWS SSM Parameter Store per defecte. Els valors han de ser rutes de paràmetres SSM vàlides (normalment començant amb /):

envilder.jsonjson

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

Això 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ó $config

Afegeix una clau $config al teu fitxer de mapeig per declarar quin proveïdor al núvol utilitzar i la seva configuració. Envilder llegeix $config per la configuració i tracta totes les altres claus com a mapeigs de secrets.

Opcions de $config

Clau	Tipus	Per defecte	Descripció
`provider`	`"aws"` \| `"azure"`	`"aws"`	Proveïdor al núvol a utilitzar
`vaultUrl`	`string`	-	URL d'Azure Key Vault (requerit quan el proveïdor és "azure")
`profile`	`string`	-	Perfil AWS CLI per a configuracions multi-compte (només AWS)

AWS SSM amb perfil

Per utilitzar un perfil AWS CLI específic (útil per a configuracions multi-compte), afegeix profile a $config:

envilder.jsonjson

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

Això indica a Envilder que utilitzi el perfil prod-account del teu fitxer ~/.aws/credentials en lloc del perfil per defecte.

Azure Key Vault

Per Azure Key Vault, estableix provider a "azure" i 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ó de noms Azure: Els noms de secrets de Key Vault només permeten caràcters alfanumèrics i guions. Envilder normalitza automàticament els noms: barres i guions baixos es converteixen en guions (p. ex., /myapp/db/password → myapp-db-password).

Diferències clau per proveïdor

	AWS SSM	Azure Key Vault
Format de ruta de secret	Rutes de paràmetres amb barres `/myapp/prod/api-key`	Noms amb guions `myapp-prod-api-key`
$config requerit	Cap (AWS és per defecte)	`provider + vaultUrl`
$config opcional	`profile`	-
Autenticació	Credencials AWS CLI	Azure Default Credentials

Múltiples entorns

Un patró comú és tenir un fitxer de mapeig per entorn. L'estructura és la mateixa, només canvien les rutes dels secrets:

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

Després obté el correcte:

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

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

Sobreescriure $config amb flags CLI

Els flags CLI sempre tenen prioritat sobre els valors de $config. Això et permet establir valors per defecte al fitxer i sobreescriure'ls per invocació:

# 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

Ordre de prioritat: flags CLI / inputs GHA → $config al fitxer de mapeig → per defecte (AWS).

Prioritat de configuració

Quan hi ha múltiples fonts de configuració, Envilder les resol en aquest ordre (el més alt guanya):

1. Flags CLI / inputs GHA

2. $config al fitxer de mapeig

3. Per defecte (AWS)

Això vol dir que --provider=azure a la CLI sobreescriurà "provider": "aws" a $config.