Copy page

Unidades

Unidades que controla tu código

Las políticas fija y autoescalada dejan que Zaroz decida cuántas unidades se ejecutan. Algunos programas saben más que un porcentaje de CPU: un hub de juego que necesita un servidor nuevo en cuanto dos jugadores emparejan, o una plataforma que ejecuta una unidad por cliente. Para ellos, un Workload puede ponerse en modo código, donde tu programa decide qué unidades existen.

La idea

En modo código no hay un número. En su lugar, cada unidad es algo que tu programa crea, con un nombre:

• Clave (key). Cada unidad tiene un nombre que eliges tú (de 1 a 40 caracteres: minúsculas, dígitos y guiones). Es el nombre privado de la unidad, así que la unidad duel-77 del Workload duels es accesible en duel-77.duels. Una clave nunca cambia.
• Etiquetas (labels). Hasta 16 etiquetas pequeñas que puedes cambiar en cualquier momento, para encontrar unidades después ("region=eu", "mode=ranked").
• Datos de usuario (user_data). Un documento JSON de hasta 64 KiB que se entrega a la unidad al arrancar (los ajustes de la partida, el id del cliente). No es un almacén de secretos; guarda los secretos en el entorno.

Crear, parar, destruir

llamada	qué hace
POST .../units	crea una unidad con una clave y la arranca. Llamarla de nuevo con la misma clave devuelve la misma unidad, así que es seguro reintentar
POST .../units/{key}/stop	la vacía y la para. Se conservan la clave, las etiquetas y los datos de usuario, y una unidad parada no cuesta nada
POST .../units/{key}/start	vuelve a arrancar una unidad parada, opcionalmente con nuevos datos de usuario
DELETE .../units/{key}	la vacía y la destruye. Definitivo; la clave puede reutilizarse
PATCH .../units/{key}	sustituye las etiquetas

El modo código es una decisión de política: en los modos fixed y autoscaled la plataforma decide qué unidades existen, y crear o parar una a mano se rechaza.

Unidades calientes y allocate

Un arranque en frío tarda. Un búfer caliente mantiene un número de unidades listas y sin asignar esperando (warm_units). POST .../units/allocate toma una, de forma atómica, le entrega tus etiquetas y datos de usuario, y el búfer se rellena. Dos llamadas nunca reciben la misma unidad. Con una cabecera Idempotency-Key, un reintento devuelve la misma unidad. Si no hay ninguna lista, la llamada responde 409 no-warm-unit, o, con if_none: create, arranca una en frío por ti. Las unidades calientes se facturan como unidades extra normales.

Señales y despliegues

Una unidad puede decir a la plataforma cuándo está accepting (aceptando jugadores), idle (ociosa) o busy (ocupada), y cuándo se está apagando. Con eso, el autoescalado puede mantener N servidores aceptando (keep_accepting) y quitar solo los ociosos al bajar. Una unidad con jugadores dentro no se quita. El modo código añade los despliegues replace_idle y next_start, que sustituyen las unidades solo cuando están ociosas o la próxima vez que arrancan, en lugar de interrumpir una partida.

Eventos y webhooks

Cada transición es un evento: unit.created, unit.ready, unit.allocated, unit.idle, unit.stopped, unit.exited, unit.failed, unit.destroyed, units.scaled y otros, cada uno con un número de secuencia sin huecos por Workload, conservados 30 días.

• Ruta de eventos. GET .../units/events?after=<seq>&wait=<0..30> lee los eventos posteriores a un cursor y espera hasta 30 segundos si no hay nada nuevo. next_after es el cursor que enviar a continuación. Mira la referencia de la API.
• Webhooks. Hasta 5 por Workload, firmados con Zaroz-Signature: v1=<HMAC-SHA256 de timestamp.cuerpo>, entregados en orden, al menos una vez, con reintentos. Un webhook que falla durante 72 horas se desactiva y se avisa a los propietarios.

Cuentas de servicio: dejar que tu código llame a Zaroz

Un programa dentro de tu Workload necesita permiso para llamar a las rutas de unidades. En lugar de poner la clave de una persona en una variable de entorno, creas una cuenta de servicio para el Workload ("Let code in this service use the Zaroz API" en los ajustes del Workload). La plataforma monta un token de corta duración en cada unidad en /zaroz/credentials/token y lo renueva por ti. Le das permisos por Workload de destino dentro del mismo proyecto: sin acceso, lectura, o arrancar y parar. Los programas ajenos a Zaroz usan una credencial con nombre que creas, ves una sola vez y puedes revocar.

Las rutas de cuentas de servicio (principal, principal/grants, principal/credentials) son solo para personas: un programa puede controlar unidades, pero no puede cambiar sus propios permisos. Que una cuenta de servicio pueda ya llamar a una ruta de unidades concreta depende de que esa ruta esté publicada (mira arriba).

Qué recordar

• El modo código es para programas que crean unidades. Si solo quieres "más copias cuando hay carga", usa una política autoescalada.
• Cada unidad que crees y tenga un pod cuenta contra los mismos límites y el tope de gasto.
• Las llamadas de una cuenta de servicio tienen límite de ritmo (50 por segundo por cuenta).