Scale sets

A ScaleSet registers one runner class on one Sylphx Runners installation. It is the whole of the setup: once the registration is Ready, jobs that ask for that class are answered without anyone creating a runner by hand.

#The spec

Four fields decide what is registered, and two of them are required:

runner_class is the half a workflow sees: it is the label a workflow asks for, so two scale sets on one installation are told apart by the class they register and the group they register it in. max_runners is the cap on how many of that class run at once, and zero leaves the cap to the plan.

#The session between the installation and Runners

The registration is not a queue. Runners holds the message session with the installation with one fenced holder, and the forge matches jobs to its runners; there is no list of pending jobs on our side, so nothing can be delivered twice by being on two lists at once.

Two status fields are about that session rather than about runners:

registration is the proof the scale set exists at the installation: it is the forge's own id for it, so a registration that never landed has none. session_region names the region holding the session, and it moves when the holder does — which is what keeps a lost holder from taking the session with it.

#Reading its health

The two counters are the live answer to whether the registration is doing anything: busy is work in flight, idle is machines waiting for a job. A condition that is false carries a reason and a severity, so a scale set that is reconciling reads differently from one that is stalled.

#Steering it

update writes the spec fields a registration is steered with — the runner group, the concurrency cap and the caller-writable metadata:

sylphx runners scale-sets update orgs/acme/scale_sets/scale-set

curl -X PATCH "https://api.sylphx.com/v1/orgs/acme/scale_sets/scale-set" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"orgs/acme/scale_sets/scale-set","spec":{"connection":"…","runner_class":"…"}}'

update_mask names the fields to write, and an unset mask writes every populated field. allow_missing turns the call into a declarative upsert: the Resource is created when it does not exist. validate_only runs every check and writes nothing.

#Deleting it

delete is destructive, so the CLI asks before it runs and takes --yes:

sylphx runners scale-sets delete orgs/acme/scale_sets/scale-set --yes

Without force, a scale set that still has children fails with FAILED_PRECONDITION; force also deletes every child Resource. etag deletes only if the current etag matches, and allow_missing succeeds when the scale set is already gone.

Reading a scale set needs runners:read; create, update and delete need runners:write. The whole collection, method by method, is in the scale_sets reference.