# Unidades que controla tu código :::note Todo lo de esta página está disponible en la API: crear, arrancar, parar y destruir por clave, allocate, despliegues, eventos, webhooks y cuentas de servicio. Las peticiones paso a paso están en la [guía de la API de Units](/es/guides/units-api/overview). ::: 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=&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=`, 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](/es/units/limits) y el tope de gasto. - Las llamadas de una cuenta de servicio tienen límite de ritmo (50 por segundo por cuenta).