Referència del mode push

Requisits previs

• La CLI d'envilder. El push d'un sol secret registra el mapatge des de la 0.16.
• Accés d'escriptura al destí: ssm:PutParameter a AWS, o el permís Set de secrets a Azure Key Vault, per exemple amb el rol Key Vault Secrets Officer.
• Per a --push, un fitxer de mapatge i un fitxer .env amb els valors. El push d'un sol secret no necessita cap dels dos: crea el fitxer de mapatge si no existeix.

Sinopsi

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

envilder [--push] --key=<NAME> --value=<value> --secret-path=<path> \
  [--map=<file>] [--no-map-update] \
  [--provider=aws|azure] [--vault-url=<url>] [--profile=<name>]

Push té dues formes. --push puja valors d'un fitxer .env. --key, --value i --secret-path junts pugen un sol secret; amb ells, --push és opcional (amb les tres opcions n'hi ha prou), i la documentació l'escriu per claredat. No hi ha cap subcomanda push. --ssm-path és un àlies obsolet de --secret-path i mostra un avís.

Pujar un fitxer .env

Per a cada variable que declara el fitxer de mapatge, Envilder llegeix el seu valor del fitxer .env i l'escriu a la ruta mapada. Les variables del fitxer .env que el fitxer de mapatge no declara s'ignoren.

Amb aquest fitxer de mapatge i aquest .env, envilder --push escriu dos secrets i ignora LOG_LEVEL. Sortida esperada amb AWS (Azure mostra les mateixes línies sense la d'identitat):

{
  "DB_PASSWORD": "/my-app/dev/db-password",
  "API_TOKEN": "/my-app/dev/api-token"
}

DB_PASSWORD=rotated-password-2026
API_TOKEN=prod-token-91c2e4
LOG_LEVEL=debug

envilder --push

☁ AWS identity · account=123456789012 · region=eu-west-1 · profile=default
Starting push operation from '.env' using map 'envilder.json'
Loading parameter map from 'envilder.json'
Loading environment variables from '.env'
Found 2 parameter mappings in map file
Found 3 environment variables in env file
Validated 2 environment variables mapping to 2 unique secrets
Processing 2 unique secrets
Pushed DB_PASSWORD=******************026 to secret store at path ********************ord
Pushed API_TOKEN=**************2e4 to secret store at path ******************ken
Successfully pushed environment variables from '.env' to secret store.

• Una variable mapada que no és al fitxer .env s'omet amb un avís. Que el fitxer .env no existeixi tampoc és un error: s'ometen totes les variables i l'execució surt amb 0.
• Diverses variables poden apuntar a la mateixa ruta només si tenen el mateix valor. Si no, Envilder s'atura abans d'escriure res.
• Els secrets s'escriuen en paral·lel. Els errors de limitació (throttling) es reintenten fins a 5 vegades amb espera creixent. Qualsevol altre error atura l'execució amb codi 1, i els secrets ja escrits es queden escrits.

Pujar un sol secret

Passa el nom de la variable, el valor i la ruta del secret. Envilder escriu el secret i registra "NOM": "<ruta>" al fitxer de mapatge, perquè el següent envilder o envilder exec el resolgui. El valor no s'escriu mai al fitxer de mapatge.

En un directori sense fitxer de mapatge, puja un secret. La comanda, la sortida esperada i el fitxer de mapatge que crea:

envilder --push --key=API_KEY --value=dev-api-key-4821 --secret-path=/my-app/dev/api-key

envilder --push --provider=azure --vault-url=https://my-vault.vault.azure.net \
  --key=API_KEY --value=dev-api-key-4821 --secret-path=/my-app/dev/api-key

Using configuration: provider=aws

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

📤 PUSHING SECRET
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  → API_KEY → ****************key

⭐ SECRET PUSHED  —  API_KEY=*************821 → ****************key

✓ Created envilder.json

Using configuration: provider=azure, vault=https://my-vault.vault.azure.net

📤 PUSHING SECRET
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  → API_KEY → ****************key

⭐ SECRET PUSHED  —  API_KEY=*************821 → ****************key

✓ Created envilder.json

{
  "API_KEY": "/my-app/dev/api-key"
}

{
  "$config": {
    "provider": "azure",
    "vaultUrl": "https://my-vault.vault.azure.net"
  },
  "API_KEY": "/my-app/dev/api-key"
}

Com s'actualitza el fitxer de mapatge

• Sense fitxer: Envilder el crea. Un fitxer anomenat envilder.json o envilder.*.json no rep la línia $schema, perquè els editors ja el reconeixen via SchemaStore; qualsevol altre nom la rep.
• La variable no és al fitxer: s'hi afegeix l'entrada, mantenint el sagnat i els salts de línia del fitxer (✓ Added API_KEY to envilder.json).
• La variable ja apunta a la mateixa ruta: el fitxer no es toca (✓ API_KEY already mapped in envilder.json, no changes).
• La variable apunta a una altra ruta: no es puja res i Envilder surt amb 1.
• El fitxer apunta a un altre proveïdor o vault que el push: el secret es puja, el fitxer es queda com està i un avís anomena els dos destins.
• El fitxer de mapatge s'escriu abans que el secret. Si el push falla, Envilder restaura el fitxer anterior, o esborra el que ha creat, de manera que el fitxer mai llista un secret que no s'ha pujat.

Com es desen els valors

AWS SSM. Cada valor s'escriu amb PutParameter com a SecureString, amb la sobreescriptura activada: es crea un paràmetre nou o l'existent rep una versió nova. Envilder no passa cap clau KMS, així que SSM fa servir la clau per defecte del compte.

Azure Key Vault. Cada valor s'escriu amb Set Secret, que crea el secret o hi afegeix una versió nova. El nom del secret és la ruta sense les barres inicials i amb la resta de barres convertides en guions: /my-app/dev/api-key passa a ser my-app-dev-api-key. No canvia res més, així que un nom que Key Vault no accepta, per exemple un amb _ o ., falla amb l'error propi de Key Vault. Dues referències que donen el mateix nom en una mateixa execució són un error.

Errors habituals

Pàgines relacionades

• Referència del fitxer de mapatge: camps de $config i regles de validació
• Mode pull: escriu els secrets pujats a un fitxer .env
• Configuració d'Azure Key Vault: rols i polítiques d'accés per llegir i escriure secrets