Copy page

Guía de la API de Units

Crear por clave, iniciar, detener y destruir

Una unidad creada por tu código tiene una clave: su nombre, elegido por ti, que nunca cambia. Un hub que abre un mundo privado por jugador usa plot-<jugador>. Un ejecutor de trabajos usa job-<id>. La clave es también el nombre de red privado de la unidad: <clave>.<slug-del-workload>.

Estas rutas necesitan la política en modo code.

Crear una unidad por clave

POST .../units es idempotente sobre la clave, así que se puede llamar sin miedo cada vez que "un jugador abre su parcela".

curl

Code
curl -sS -X POST "$UNITS" -H "$AUTH" -H "Content-Type: application/json" -d '{
  "key": "plot-ana",
  "labels": {"kind": "plot", "owner": "ana"},
  "user_data": {"world": "s3://my-bucket/plots/ana"},
  "start": true,
  "on_exit": "stop"
}'
# 201 {"created": true,  "unit": {...}}   a new unit
# 200 {"created": false, "unit": {...}}   the live unit with that key already existed

TypeScript

Code
import { call, UNITS } from "./zaroz";

const { status, body } = await call("POST", UNITS, {
  key: "plot-ana",
  labels: { kind: "plot", owner: "ana" },
  user_data: { world: "s3://my-bucket/plots/ana" },
  start: true,
  on_exit: "stop",
});
console.log(status, body.created, body.unit.key, body.unit.state);

Python

Code
from zaroz import call, UNITS

status, body = call("POST", UNITS, {
    "key": "plot-ana",
    "labels": {"kind": "plot", "owner": "ana"},
    "user_data": {"world": "s3://my-bucket/plots/ana"},
    "start": True,
    "on_exit": "stop",
})
print(status, body["created"], body["unit"]["key"], body["unit"]["state"])

Situación	Respuesta
Ninguna unidad viva tiene esta clave	201 {created: true} y la unidad arranca (salvo "start": false)
Una unidad viva tiene esta clave y está en marcha, con entrada igual u omitida	200 {created: false} con la unidad actual
Está detenida y start es true	Arranca. Si envías labels y user_data, reemplazan a los guardados. 200 {created: false}
Está en marcha y envías labels o user_data distintos	409 unit-input-differs. La entrada de una unidad en marcha solo cambia con allocate o con PATCH de etiquetas

Campos: key (obligatorio), labels, user_data, start (por defecto true), on_exit (restart, stop o destroy; por defecto el default_on_exit de la política).

"start": false crea la unidad detenida: no ocupa ranura y no cuesta nada hasta que la inicies.

on_exit es lo que pasa cuando el proceso de la unidad termina: restart conserva el pod y reinicia el proceso en su sitio; stop y destroy terminan la unidad (y liberan la ranura). Usa destroy para una partida o un trabajo y stop para una parcela a la que volverás.

Leer una unidad

curl

Code
curl -sS "$UNITS/plot-ana" -H "$AUTH"

TypeScript

Code
const { body: unit } = await call("GET", `${UNITS}/plot-ana`);
console.log(unit.state, unit.labels, unit.user_data, unit.allocation);

Python

Code
_, unit = call("GET", f"{UNITS}/plot-ana")
print(unit["state"], unit["labels"], unit["user_data"], unit["allocation"])

La respuesta incluye state, desired_state, labels, user_data, origin (policy, code o warm), allocation (nulo hasta que se asigna), private_name, public_endpoints, billing_class (included o extra), el pod actual y el número de reinicios.

Detener, iniciar y destruir

curl

Code
curl -sS -X POST "$UNITS/plot-ana/stop" -H "$AUTH"      # drain, then stop: costs nothing while stopped
curl -sS -X POST "$UNITS/plot-ana/start" -H "$AUTH" -H "Content-Type: application/json" -d '{}'
curl -sS -X DELETE "$UNITS/plot-ana" -H "$AUTH"         # drain, then destroy: final

TypeScript

Code
await call("POST", `${UNITS}/plot-ana/stop`);
await call("POST", `${UNITS}/plot-ana/start`, {});          // {} starts it as it is
await call("DELETE", `${UNITS}/plot-ana`);                   // final; the key may be reused afterwards

Python

Code
call("POST", f"{UNITS}/plot-ana/stop")
call("POST", f"{UNITS}/plot-ana/start", {})   # {} starts it as it is
call("DELETE", f"{UNITS}/plot-ana")           # final; the key may be reused afterwards

• stop vacía la unidad (recibe un aviso de drenaje y deja de aceptar trabajo nuevo) y después la detiene. La clave, las etiquetas y el user_data se conservan, la ranura se libera y no se factura nada mientras está detenida. Detener una unidad detenida es un 200 sin efecto.
• start despierta una unidad detenida. Iniciar una unidad en marcha es un 200 sin efecto. El cuerpo puede llevar labels y user_data, que reemplazan enteros a los guardados. Envía {} para iniciarla tal cual.
• destroy vacía y después elimina la unidad. Es definitivo: después la clave responde 404 y puede reutilizarse. El éxito es 204.

curl

Code
curl -sS -X POST "$UNITS/plot-ana/start" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"labels": {"kind": "plot", "owner": "ana", "tier": "vip"}, "user_data": {"world": "s3://my-bucket/plots/ana-v2"}}'

TypeScript

Code
await call("POST", `${UNITS}/plot-ana/start`, {
  labels: { kind: "plot", owner: "ana", tier: "vip" },
  user_data: { world: "s3://my-bucket/plots/ana-v2" },   // replaces the stored value whole
});

Python

Code
call("POST", f"{UNITS}/plot-ana/start", {
    "labels": {"kind": "plot", "owner": "ana", "tier": "vip"},
    "user_data": {"world": "s3://my-bucket/plots/ana-v2"},  # replaces the stored value whole
})

Toda llamada que arranca un pod (crear con start, start, un relleno, allocate con if_none: create) se comprueba contra tus límites y tu tope de gasto: mira Errores para container-unit-limit, org-unit-limit, start-rate y spend-cap. Un rechazo nunca es un éxito parcial y un límite nunca toca las unidades en marcha.

Las unidades detenidas se acumulan

Un Workload puede guardar 1.000 unidades detenidas (stopped-unit-limit). Las que llevan detenidas más que destroy_stopped_after_days de la política (90 por defecto) se destruyen y un evento unit.destroyed con motivo expired te lo avisa.