El contrato de unidad v1
El contrato es la superficie estable entre la plataforma y tu proceso. Se publica como JSON Schemas (borrador 2020-12) y se versiona con un entero mayor.
Entorno
| Variable | Valor |
|---|---|
ZAROZ_CONTRACT_VERSION | 1 |
ZAROZ_DIR | /zaroz |
ZAROZ_UNIT_ID, ZAROZ_UNIT_KEY | el id y la clave de la unidad |
ZAROZ_WORKLOAD | el slug del Workload |
ZAROZ_PRIVATE_NAME | <clave>.<workload>, cómo llegan a esta unidad sola otros Workloads del proyecto |
ZAROZ_PROJECT_ID, ZAROZ_REGION, ZAROZ_SERVICE_INSTANCE_ID | dónde corre |
MEMORY_LIMIT_MIB | el límite de memoria de la unidad |
ZAROZ_API_URL | solo cuando el Workload tiene un principal de servicio |
Los valores por unidad se fijan al crear el pod, porque la clave de una unidad nunca cambia. Solo los pods que llevan el agente o un principal reciben las variables nuevas: un Workload que no usa estas funciones se ejecuta igual que antes.
Archivos en /zaroz
| Ruta | Esquema | Notas |
|---|---|---|
contract.json | contract.schema.json | {version: 1, agent_version} |
unit.json | unit.schema.json | identidad; labels se actualiza en vivo |
user-data.json | user-data.schema.json | el valor JSON o null |
allocation.json | allocation.schema.json | null o {id, allocated_at, generation} |
state.json | state.schema.json | {draining: false} o {draining: true, reason} |
signals/ | solo escritura: ready, accepting, idle, busy, shutdown | |
signal.sock | signal-response.schema.json, accepting-request.schema.json, error.schema.json | HTTP/1.1 sobre un socket Unix |
credentials/token | solo con un principal; rotado, léelo en cada petición |
Cada archivo se escribe de forma atómica. Mira Señales para saber cómo usarlos.
Eventos
El sobre de GET .../units/events y de las entregas de webhooks es event.schema.json. Mira Eventos. data está tipado por tipo de evento.
La regla de versionado
- Dentro de una versión mayor los cambios son solo aditivos: campos opcionales nuevos, archivos nuevos, señales nuevas, tipos de evento nuevos. Quien consume debe ignorar lo que no conoce.
- Quitar o renombrar un campo, o cambiar un tipo o un significado, es una versión mayor nueva, que se elige por Workload con
contract_versionen la política (por defecto, la más reciente). - La versión mayor anterior se sigue sirviendo al menos 12 meses después de que salga la siguiente.
- El agente incluye los esquemas de cada versión mayor admitida y valida contra ellos cada archivo que escribe y cada evento. El emisor de eventos del kernel se prueba con los mismos archivos.
Garantías
Las garantías del ciclo de vida (ready significa ready, allocate es atómico, drenar antes de matar, detenida no cuesta nada, rechazo rápido, fuera del balanceo en aproximadamente un segundo, los eventos nunca se saltan) están en Unidades que controla tu código. Cada una la comprueba la suite de conformidad abierta.