Ciclo de vida

Un stack evoluciona siempre por el mismo camino: propones un changeset, revisas el diff y lo ejecutas. Esta página describe cada fase y sus garantías.

Estados del stack

Cualquier estado *_IN_PROGRESS (salvo REVIEW_IN_PROGRESS) actúa como mutex: mientras dura, proponer otro changeset, ejecutar o eliminar responde 409 Conflict.

Changesets

Un changeset pasa por: pending → executing → executed | failed | rolled_back. Proponer un changeset nuevo marca superseded al pending anterior (nunca a uno que ya está ejecutándose). El historial completo se conserva en el stack.

El diff clasifica cada recurso en una acción:

• add — no existe (o se adopta uno equivalente por clave natural).
• modify — cambian propiedades declarables, o un valor write-only detectable (p. ej. el valor de un secreto, por huella).
• replace — cambia una propiedad inmutable; el recurso se recrea. Según la propiedad, el motor crea primero el nuevo y luego borra el viejo (create-first, cuando cambia la clave natural) o borra y recrea (delete-first). Los recursos que dependen de uno reemplazado entran como modify para re-apuntar sus referencias.
• remove — salió del template; se elimina al ejecutar.

Re-proponer el mismo template produce un diff con cero entradas: no hay nada que ejecutar.

Ejecución

Ejecutar un changeset es asíncrono (la API responde 202). El motor corre una función durable que aplica un paso por recurso en orden topológico (dependencias primero):

1. Busca el recurso por su clave natural; si existe, lo adopta y actualiza; si no, lo crea.
2. Toma un snapshot previo del recurso (para poder revertir).
3. Materializa los valores noEcho solo en memoria durante la llamada al gestor.
4. Registra el resultado en la traza de eventos del stack.

Al final elimina los remove en orden inverso, limpia los físicos viejos de los replace y resuelve los outputs. Los parámetros sensibles transitorios y los snapshots se purgan al cerrar el changeset.

Rollback automático

Si cualquier recurso falla al aplicarse, el stack entra en ROLLBACK_IN_PROGRESS (o UPDATE_ROLLBACK_IN_PROGRESS) y revierte las operaciones ya aplicadas en orden inverso:

• Un recurso creado (no adoptado) se elimina.
• Un recurso adoptado o modificado se restaura desde su snapshot — incluida la rotación de credenciales y valores de secretos, que vuelven a su valor anterior sin exponerse.
• Un replace revierte el lado que alcanzó a ejecutarse.

El stack termina en ROLLBACK_COMPLETE / UPDATE_ROLLBACK_COMPLETE con el tenant en su estado previo. La traza de eventos registra el motivo del fallo recurso por recurso. Desde ahí puedes corregir el template y proponer un nuevo changeset.

Traza de eventos

Cada paso del despliegue emite un evento append-only con recurso, estado, motivo y actor (el usuario del portal o la API key que ejecutó). En el portal es la pestaña Eventos, que se refresca sola mientras el stack está en progreso; por API es GET /v1/iac/stacks/:id/events.

Drift y export

Con el tiempo, alguien puede modificar a mano un recurso gestionado por el stack. POST /v1/iac/stacks/:id/detect-drift (o el botón del portal) compara lo aplicado con lo que existe y marca cada recurso IN_SYNC, DRIFTED o DELETED, con el diff por propiedad (los valores write-only se comparan por huella, sin exponerse). Además, GET /v1/iac/export genera un template a partir de los recursos existentes del tenant — útil para adoptar como código lo que ya creaste a mano.

Eliminar un stack

Eliminar es asíncrono y también pasa por confirmación explícita:

• Por defecto se eliminan todos los recursos del stack, en orden topológico inverso (primero quienes referencian, luego los referenciados).
• Con retain indicas nombres lógicos que deben sobrevivir: quedan desasociados del stack pero intactos en tu tenant. En el portal, el diálogo de eliminación muestra un checkbox por recurso.

curl -X DELETE "$CORTEX_API_URL/v1/iac/stacks/$STACK_ID" \
  -H "x-api-key: $CORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"retain": ["SkillCalificar"]}'

El stack termina en DELETE_COMPLETE y desaparece de la lista, pero su historial de changesets y eventos se conserva para auditoría.