Secrets y variables de entorno

¿Tenés un .env? Empezá acá (la forma simple)

Si en tu máquina guardás la config en un archivo .env, no tenés que aprender nada nuevo: en el form de deploy hay una caja Environment variables — pegá tu .env tal cual (KEY=value, uno por línea). Esos valores se guardan cifrados y se inyectan al contenedor igual que un .env local. En una app multi-servicio, cada servicio tiene su propia caja para pegar.

Eso alcanza para la mayoría de las apps. Usá Secrets nombrados (abajo) solo cuando querés:

• reusar los mismos valores en varias apps,
• compartir valores sensibles sin re-escribirlos, o
• montarlos como archivos en vez de variables de entorno.

---

Secrets nombrados

Los secrets son objetos nombrados y cifrados con pares clave/valor (AES-256-GCM at-rest) que las apps referencian por nombre. La API nunca devuelve los valores — solo los nombres de las claves.

Tip: en el panel de Secrets podés pegar un .env y hacer click en Fill keys from .env para crear un secret de una sola vez.

Dos formas de consumir un secret

Modo	Campo	Resultado en el contenedor
Variables de entorno	envFrom	cada clave se vuelve una variable de entorno
Archivos	secretFiles	cada clave se monta read-only en /run/secrets/<KEY> (en RAM, nunca en disco)

Podés usar una, la otra o ambas, a nivel app (aplica a todos los servicios) o por servicio.

Compartido vs scopeado a una app

• Compartido (org-wide): disponible para todas las apps de tu org.
• Scopeado a una app: atado a una app por nombre. Si un secret compartido y uno scopeado tienen el mismo nombre, gana el scopeado para esa app.

---

Crear un secret

Dashboard

Panel Secrets → nombre + pares clave/valor → elegí Scope (Compartido o una app específica) → Save secret. Los valores se muestran como campos de password y nunca se vuelven a mostrar.

API

# compartido (org-wide)
curl -s -X POST $API/secrets \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"name":"db-creds","data":{"DATABASE_URL":"postgres://u:p@host/db"}}'

# scopeado a una app específica (por nombre de app)
curl -s -X POST $API/secrets \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"name":"db-creds","data":{"DATABASE_URL":"postgres://…/app1"},"appId":"app1"}'

POST /secrets crea o reemplaza el secret de ese nombre+scope.

Usarlo en un deploy

# inyectar como env vars + montar una clave como archivo
curl -s -X POST $API/deploy \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{
    "name":"api", "image":"acme/api:1.0", "port":3000,
    "envFrom":["db-creds"],
    "secretFiles":["tls-bundle"]
  }'

• envFrom inyecta cada clave de db-creds como variable de entorno.
• secretFiles monta cada clave de tls-bundle en /run/secrets/<KEY> (read-only, RAM).

En el dashboard, el form de deploy tiene selectores de checkbox Inject as env vars y Mount as files con tus secrets.

Referenciar un secret que no existe falla rápido con 400 unknown_secret y la lista de nombres faltantes.

Precedencia (cuando las claves chocan)

Se mergean en este orden, gana el último (semántica envFrom de K8s):

1. secrets envFrom a nivel app
2. secrets envFrom por servicio
3. env inline (siempre gana)

Y para cualquier nombre, un secret scopeado le gana a uno compartido.

Listar / borrar

curl -s $API/secrets -H "authorization: Bearer $TOKEN"           # nombres + claves solamente
curl -s -X DELETE "$API/secrets/db-creds" -H "authorization: Bearer $TOKEN"          # compartido
curl -s -X DELETE "$API/secrets/db-creds?appId=app1" -H "authorization: Bearer $TOKEN" # scopeado

Si los deploys devuelven 503 sealed

La plataforma puede correr con su llave maestra solo en memoria (“sealed”). Cuando está sealed, /deploy y /secrets devuelven 503. Un operador la abre con POST /admin/unseal (ver Solución de problemas). En la config por defecto esto es automático y nunca lo vas a ver.

→ Usalos al desplegar: Desplegar una imagen Docker, Apps multi-servicio