HostService

ActivateHost

POST /spin.v1.HostService/ActivateHost

Activate a drained host (set to healthy, admin only)

Request

Field	Type	What it is
id	string

Response

Field	Type	What it is
host	Host

DrainHost

POST /spin.v1.HostService/DrainHost

Set host to draining (admin only)

Request

Field	Type	What it is
id	string
suspend	boolean	Suspend every running workspace off the host: its memory and disk go to the object store, and it is resumed on whichever other host has room, on its own - or, suspended without its memory, on its owner’s next start. Answered once each is suspended or has failed to be; a workspace that failed runs on as it was.
leaveStopped	boolean	leave_stopped is for a drain that shrinks the fleet: the workspaces it suspends stay stopped, and each resumes on another host when its owner starts it. Without it they are resumed elsewhere at once, waiting for a host where the installation is bringing one up.

Response

Field	Type	What it is
host	Host
suspendedWorkspaceIds	list of string
failures	list of WorkspaceSuspendFailure

GetFleet

POST /spin.v1.HostService/GetFleet

The fleet as a whole (admin only): how many hosts there are against how many the installation has asked its cloud for, and what it is waiting for. A fleet that scales from none looks broken without this - no hosts, no explanation, and a workspace that waits minutes for a machine to boot with nothing saying so.

Request

No fields: {}.

Response

Field	Type	What it is
autoscaling	boolean	False when no group is configured: the hosts of this installation are whatever somebody registered by hand, and none of the numbers below mean anything.
group	string	The group the control plane sizes, as its cloud names it.
desired	integer (int32)	What it last asked the group for, and the most it may ask: zero of one is a fleet at rest, which is what an idle installation looks like.
most	integer (int32)
connected	integer (int32)	The hosts that are connected now, which lags desired by a machine’s boot: one desired and none connected is a machine on its way.
waiting	integer (int32)	Workspaces that have nowhere to run yet, and when the first of them started waiting: this is what makes the control plane ask for a machine.
oldestWaiting	Timestamp
busy	integer (int32)	Workspaces that are keeping the fleet up.
idleMinutes	integer (int32)	How long the fleet may be idle before the group is emptied, and the window in which it is emptied at once. Empty quiet_hours is none.
quietHours	string
timeZone	string

GetHost

POST /spin.v1.HostService/GetHost

Get host details (admin only)

Request

Field	Type	What it is
id	string

Response

Field	Type	What it is
host	Host

GetHostPolicy

POST /spin.v1.HostService/GetHostPolicy

What a host may do, as against what it is (admin only). A host reads what it *is* from its own environment, before it can reach this; everything else it is told, on its heartbeat, and it reports back the revision it is running under.

Request

Field	Type	What it is
hostId	string

Response

Field	Type	What it is
policy	HostPolicy
writebackPresets	list of WritebackPreset	The writeback thresholds an operator chooses from without testing them on the host, each with what it measured. The first is unset: what the host booted with.
writebackTest	WritebackTest	The last writeback test of this host, while SetHostPolicy still takes its thresholds.

ListHosts

POST /spin.v1.HostService/ListHosts

List all hosts (admin only)

Request

Field	Type	What it is
page	PageRequest
stateFilter	HostState

Response

Field	Type	What it is
hosts	list of Host
page	PageResponse

SetHostPolicy

POST /spin.v1.HostService/SetHostPolicy

Request

Field	Type	What it is
policy	HostPolicy	Sent whole: what is left unset is unset, so a write is the policy and not a patch.

Response

Field	Type	What it is
policy	HostPolicy

TestHostWriteback

POST /spin.v1.HostService/TestHostWriteback

Measures a host’s disk under writeback thresholds no preset names, against the ones it holds (admin only). SetHostPolicy refuses such thresholds for a host until it has been tested with them; the test loads that host’s disk for about forty seconds.

Request

Field	Type	What it is
hostId	string
limitBytes	string (int64)	The candidates, as HostPolicy holds them.
backgroundBytes	string (int64)

Response

Field	Type	What it is
test	WritebackTest