Load Balancer

Agregar un destino a un listener

POST /v1/load-balancers/{id}/backends · scope lb:write · reversible · idempotente

Atajo sobre PUT /listeners para el caso frecuente de sumar una máquina. Revalida y aplica la configuración completa, así que hereda la misma garantía: o el destino queda recibiendo tráfico, o no cambió nada.

curl https://api.truo.cloud/v1/load-balancers/svc_10432/backends \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"listener":"<listener>","ip":"<ip>","port":1}'

truo lb backend add svc_10432

await truo.lb.backends.create("svc_10432", {"listener":"<listener>","ip":"<ip>","port":1});

truo_lb({
  "action": "backend_create",
  "id": "svc_10432"
})

operationId: lb.backends.create

Quitar un destino de un listener

DELETE /v1/load-balancers/{id}/backends/{listener}/{ip}/{port} · scope lb:write · destructiva — no tiene vuelta atras · idempotente

Los tres valores que identifican al destino van en la ruta. El backend los espera en el cuerpo de un DELETE, cosa que proxies y CDNs descartan y que varios clientes HTTP no mandan; el cuerpo se arma de este lado.

Un listener no puede quedarse sin destinos. Quitar el último devuelve 400 validation_failed: para eliminar el listener entero usá PUT /listeners sin él.

curl https://api.truo.cloud/v1/load-balancers/svc_10432/backends/web/10.0.0.5/8080 \
  -X DELETE \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo lb backend remove svc_10432 web 10.0.0.5 8080

await truo.lb.backends.delete("svc_10432", "web", "10.0.0.5", "8080");

truo_lb({
  "action": "backend_delete",
  "id": "svc_10432",
  "listener": "web",
  "ip": "10.0.0.5",
  "port": "8080"
})

operationId: lb.backends.delete

Listar los destinos

GET /v1/load-balancers/{id}/backends · scope lb:read

Los destinos de todos los listeners, aplanados, cada uno con el listener al que pertenece. Es una vista sobre la misma configuración que devuelve GET /listeners.

curl https://api.truo.cloud/v1/load-balancers/svc_10432/backends \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo lb backend list svc_10432

await truo.lb.backends.list("svc_10432");

truo_lb({
  "action": "backend_list",
  "id": "svc_10432"
})

operationId: lb.backends.list

Obtener un load balancer con su estado real

GET /v1/load-balancers/{id} · scope lb:read

Consulta el control plane, que a su vez sondea el balanceador. Si no responde, los campos de estado vuelven en null en vez de fallar.

curl https://api.truo.cloud/v1/load-balancers/svc_10432 \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo lb get svc_10432

await truo.lb.instances.get("svc_10432");

truo_lb({
  "action": "get",
  "id": "svc_10432"
})

operationId: lb.instances.get

Listar los load balancers de la cuenta

GET /v1/load-balancers · scope lb:read

Sale de la base, sin consultar el control plane: provisioning_state, healthy y listener_count vienen en null. Traerlos costaría una llamada por elemento de la página.

Una página puede venir con menos elementos que el limit aunque haya más: todos los productos del control plane comparten un mismo módulo de aprovisionamiento, así que el filtro por familia solo puede aplicarse después de leer la página. has_more sigue siendo la señal correcta de si queda algo por traer.

curl https://api.truo.cloud/v1/load-balancers \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo lb list

await truo.lb.instances.list();

truo_lb({
  "action": "list"
})

operationId: lb.instances.list

Listar los listeners

GET /v1/load-balancers/{id}/listeners · scope lb:read

La configuración completa del balanceador, incluidos los destinos de cada listener. Es lo que hay que leer, modificar y volver a mandar en PUT.

curl https://api.truo.cloud/v1/load-balancers/svc_10432/listeners \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo lb listener list svc_10432

await truo.lb.listeners.list("svc_10432");

truo_lb({
  "action": "listener_list",
  "id": "svc_10432"
})

operationId: lb.listeners.list

Reemplazar la configuración de listeners

PUT /v1/load-balancers/{id}/listeners · scope lb:write · destructiva — no tiene vuelta atras · idempotente

Reemplaza el conjunto entero: los listeners que no vengan en listeners se borran, con sus destinos. Mandar [] deja el balanceador sin nada escuchando y corta el tráfico. Leé GET /listeners, modificá y mandá todo de vuelta.

El cambio se aplica dentro de la llamada: cuando esto devuelve, la configuración nueva ya está sirviendo tráfico. Si la configuración resultante es inválida no se aplica nada y la respuesta es 400 validation_failed — el servicio nunca queda a medias.

curl https://api.truo.cloud/v1/load-balancers/svc_10432/listeners \
  -X PUT \
  -H "Authorization: Bearer $TRUO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"listeners":[]}'

truo lb listener apply svc_10432

await truo.lb.listeners.replace("svc_10432", {"listeners":[]});

truo_lb({
  "action": "listener_replace",
  "id": "svc_10432"
})

operationId: lb.listeners.replace

Estado y tráfico por listener

GET /v1/load-balancers/{id}/stats · scope lb:read

Una foto del momento: conexiones en curso y bytes acumulados desde el último arranque del balanceador, más la salud de cada destino según el último sondeo. No hay serie histórica.

Si el balanceador no contesta el sondeo, los listeners igual aparecen —salen de la configuración guardada— con state: unknown y los contadores en cero. Un listener que existe y no responde y uno que existe sin tráfico no se distinguen por los contadores: miralos por state.

curl https://api.truo.cloud/v1/load-balancers/svc_10432/stats \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo lb stats svc_10432

await truo.lb.stats.get("svc_10432");

truo_lb({
  "action": "stats",
  "id": "svc_10432"
})

operationId: lb.stats.get