Elastic pool and prewarm

Plan where Spaces go and what it costs, add and remove cloud hosts, set the budget, and keep Spaces ready.

With clouds linked, on auto (or a cloud) places Spaces by one solve over your devices, your hosts and new cloud machines, under the budget. Spaces.cloud_plan shows that decision without doing it; Spaces.cloud_hosts, cloud_add_host and cloud_remove_host manage the hosts; cloud_budget sets the caps; Spaces.prewarm keeps Spaces of one shape ready so the next creates of it start at once.

Elastic pool methods#

Methods of Spaces.

`Spaces.cloud_plan`#

What the elastic pool would do for some Spaces: where each goes (your devices first, then hosts with room, then new cloud machines at the least cost) and what that costs. With apply, it adds the machines (create the Spaces with on auto).

async def cloud_plan(self, request: ElasticPlanRequest) -> ElasticPlan

Parameter	Type	Default
`request`	`ElasticPlanRequest`	required

Returns ElasticPlan · Async · Raises CuaError

`Spaces.cloud_hosts`#

The hosts the elastic pool added in your clouds, with their cost.

async def cloud_hosts(self) -> List[ElasticHost]

Returns Vec<ElasticHost> · Async · Raises CuaError

`Spaces.cloud_add_host`#

Adds count hosts of instance_type in a linked cloud by hand (the scaler never removes them); each ends at its TTL.

async def cloud_add_host(self, provider: str, instance_type: str, region: Optional[str], count: Optional[int], ttl_hours: Optional[int]) -> List[ElasticHost]

Parameter	Type	Default
`provider`	`String`	required
`instance_type`	`String`	required
`region`	`Option<String>`	required
`count`	`Option<u32>`	required
`ttl_hours`	`Option<u32>`	required

Returns Vec<ElasticHost> · Async · Raises CuaError

`Spaces.cloud_remove_host`#

Removes hosts this home added to the pool.

async def cloud_remove_host(self, names: List[str]) -> ElasticRemoved

Parameter	Type	Default
`names`	`Vec<String>`	required

Returns ElasticRemoved · Async · Raises CuaError

`Spaces.cloud_budget`#

The elastic pool's budget and autoscale switch, after setting the fields update gives.

async def cloud_budget(self, update: ElasticBudgetUpdate) -> ElasticBudget

Parameter	Type	Default
`update`	`ElasticBudgetUpdate`	required

Returns ElasticBudget · Async · Raises CuaError

`Spaces.cloud_reconcile`#

One scale-in pass now: idle hosts go at the end of their paid time, the least-used one is cordoned when the others have room.

async def cloud_reconcile(self) -> List[ElasticDecision]

Returns Vec<ElasticDecision> · Async · Raises CuaError

`Spaces.prewarm`#

Keeps Spaces of image ready where the elastic pool puts them (the same solve as on auto, under the budget and pins), so the next creates of that shape start in a fraction of a second. Refused, and nothing bought, when the budget or pins cannot fit it.

async def prewarm(self, image: str, options: PrewarmOptions) -> Prewarm

Parameter	Type	Default
`image`	`String`	required
`options`	`PrewarmOptions`	required

Returns Prewarm · Async · Raises CuaError

`Spaces.prewarms`#

The prewarms, with how many each keeps ready now.

async def prewarms(self) -> List[Prewarm]

Returns Vec<Prewarm> · Async · Raises CuaError

`Spaces.remove_prewarm`#

Ends prewarm id (its ready Spaces go). false: no such prewarm.

async def remove_prewarm(self, id: str) -> bool

Parameter	Type	Default
`id`	`String`	required

Returns bool · Async · Raises CuaError

`ElasticAssignment` record#

Some Spaces of one group on one machine.

Field	Type	Description
`group`	`String`	The group (`request-0`).
`host`	`String`	A machine in the pool by name, or empty when it is a new one.
`new_index` / `newIndex`	`Option<u32>`	The index into `new_hosts` (when `host` is empty).
`count`	`u32`	How many Spaces.
`sync`	`bool`	The checkpoint is copied there first.

`ElasticBudget` record#

The budget, and what the clouds cost now.

Returned by Spaces.cloud_budget.

Field	Type	Description
`autoscale`	`bool`
`max_usd_per_hour` / `maxUsdPerHour`	`f64`
`monthly_usd` / `monthlyUsd`	`f64`
`max_new_hosts` / `maxNewHosts`	`u32`
`warm`	`bool`
`allow_metal` / `allowMetal`	`bool`
`month_usd` / `monthUsd`	`f64`	USD spent on elastic hosts this month.
`running_usd_per_hour` / `runningUsdPerHour`	`f64`	USD per hour of the hosts running now.
`hosts`	`u32`	Hosts running.

`ElasticBudgetUpdate` record#

The elastic pool's caps and switches (cloud_budget): set those given.

Field	Type	Default
`max_usd_per_hour` / `maxUsdPerHour`	`Option<f64>`	`None`
`monthly_usd` / `monthlyUsd`	`Option<f64>`	`None`
`autoscale`	`Option<bool>`	`None`
`max_new_hosts` / `maxNewHosts`	`Option<u32>`	`None`
`warm`	`Option<bool>`	`None`
`allow_metal` / `allowMetal`	`Option<bool>`	`None`

`ElasticDecision` record#

One scale-in decision.

Returned by Spaces.cloud_reconcile.

Field	Type	Description
`host`	`String`
`action`	`String`	`keep`, `cordon` or `remove`.
`reason`	`String`
`until`	`u64`	`keep`: unix seconds it is looked at again.
`saves_usd` / `savesUsd`	`f64`	`remove`: USD saved against keeping it a billing step longer.

`ElasticHost` record#

A host the elastic pool added in one of your clouds.

Returned by Spaces.cloud_add_host, Spaces.cloud_hosts.

Field	Type	Description
`name`	`String`	Its pool name (`hetzner-1`).
`provider`	`String`
`type_name` / `typeName`	`String`
`region`	`String`
`id`	`String`	The cloud's id.
`machine`	`String`	Its relay machine once joined.
`state`	`String`	`creating`, `booting`, `joined`, `cordoned`, `offline`, `gone`.
`started`	`u64`	Unix seconds.
`expires`	`u64`	Unix seconds it ends on its own.
`usd_per_hour` / `usdPerHour`	`f64`
`billing_step_secs` / `billingStepSecs`	`u64`
`billing_min_secs` / `billingMinSecs`	`u64`
`pinned`	`bool`	Added by hand: never removed by the scaler.

`ElasticNewHost` record#

A machine the plan adds.

Field	Type	Description
`provider`	`String`
`type_name` / `typeName`	`String`
`region`	`String`
`usd_per_hour` / `usdPerHour`	`f64`
`boot_secs` / `bootSecs`	`u32`
`billed_secs` / `billedSecs`	`u64`	Seconds billed for the work it gets.
`one_space` / `oneSpace`	`bool`	A Spaces supplier's Space (Modal), not a host.
`rtt_ms` / `rttMs`	`u32`	Estimated round trip from the requester, ms (0: unknown).

`ElasticPlan` record#

The elastic pool's decision (cloud_plan).

Returned by Spaces.cloud_plan.

Field	Type	Description
`assignments`	`Vec<ElasticAssignment>`
`new_hosts` / `newHosts`	`Vec<ElasticNewHost>`
`unplaced`	`Vec<ElasticUnplaced>`
`added_usd_per_hour` / `addedUsdPerHour`	`f64`	USD per hour the new machines add.
`projected_usd` / `projectedUsd`	`f64`	USD the new machines cost for the work, billed.
`lower_bound_usd` / `lowerBoundUsd`	`f64`	A lower bound for any plan of the same work.
`solver`	`String`	`exact`, `exact-incumbent` or `greedy`.
`ready_in_secs` / `readyInSecs`	`u32`	Seconds until the last Space can start.
`explain`	`Vec<String>`	One line per decision.
`added`	`Vec<ElasticHost>`	The hosts added (with `apply`).
`json`	`String`	The whole answer as JSON (the demand it detected, the pool it saw): what an agent inspects or edits.

`ElasticPlanRequest` record#

What to plan for (cloud_plan). Pins are constraints of the same solve: leave them unset to let the pool decide.

Field	Type	Default	Description
`count`	`Option<u32>`	`None`	How many Spaces (default 1).
`image`	`Option<String>`	`None`	Image (default linux).
`kind`	`Option<String>`	`None`	`container`, `vm` or `microvm` (default: from the image).
`cpus`	`Option<u32>`	`None`	vCPUs each (default: learned from earlier Spaces of the image).
`memory_mb` / `memoryMb`	`Option<u64>`	`None`	MiB each.
`together`	`Option<bool>`	`None`	Keep them on one machine (forks of one checkpoint).
`caller`	`Option<String>`	`None`	`interactive`, `batch`, `compat` or `persistent_agent`.
`duration_secs` / `durationSecs`	`Option<u64>`	`None`	Expected lifetime, seconds.
`provider`	`Option<String>`	`None`	Only this cloud.
`region`	`Option<String>`	`None`	Only this region.
`instance_type` / `instanceType`	`Option<String>`	`None`	Only this machine type.
`hosts`	`Option<u32>`	`None`	Exactly this many new machines.
`no_scale` / `noScale`	`Option<bool>`	`None`	Add no machines.
`devices_only` / `devicesOnly`	`Option<bool>`	`None`	Only your own devices.
`max_usd_per_hour` / `maxUsdPerHour`	`Option<f64>`	`None`	A $/hour cap for this plan.
`apply`	`bool`	`false`	Add the machines the plan needs.

`ElasticRemoved` record#

What cloud_remove_host did.

Returned by Spaces.cloud_remove_host.

Field	Type	Default	Description
`removed`	`Vec<String>`
`failed`	`Vec<String>`		`name: error` per host not removed.

`ElasticUnplaced` record#

Spaces with no place, and why.

Field	Type	Default	Description
`group`	`String`
`count`	`u32`
`reason`	`String`

`Prewarm` record#

Spaces of one shape the elastic pool keeps ready: the next creates of that shape claim them in a fraction of a second.

Returned by Spaces.prewarm, Spaces.prewarms.

Field	Type	Description
`id`	`String`	`pw-xxxxxx`.
`image`	`String`
`kind`	`String`
`cpus`	`u32`
`memory_mb` / `memoryMb`	`u64`
`count`	`u32`	Asked.
`ready`	`u32`	Ready now.
`placements`	`Vec<PrewarmPlacement>`
`expires_at` / `expiresAt`	`u64`	Unix seconds.
`new_hosts` / `newHosts`	`Vec<String>`	Hosts added for it.

`PrewarmOptions` record#

What to keep ready (Spaces::prewarm).

Field	Type	Default	Description
`count`	`Option<u32>`	`None`	How many, 1 to 256 (default 1).
`on`	`Option<String>`	`None`	`auto` (default), `local`, a linked cloud or `host:<machine>`.
`kind`	`Option<String>`	`None`	`container`, `vm` or `microvm` (default: the image's).
`cpus`	`Option<u32>`	`None`
`memory_mb` / `memoryMb`	`Option<u64>`	`None`
`ttl_secs` / `ttlSecs`	`Option<u64>`	`None`	Seconds to keep them (default 3600).
`instance_type` / `instanceType`	`Option<String>`	`None`	Only this cloud machine type.
`region`	`Option<String>`	`None`	Only this cloud region.

`PrewarmPlacement` record#

Where a prewarm keeps Spaces ready.

Field	Type	Description
`host`	`String`	The machine's name.
`machine`	`String`	`local` or its relay machine id.
`count`	`u32`
`ready`	`u32`

Elastic pool and prewarm

Elastic pool methods#

Spaces.cloud_plan#

Spaces.cloud_hosts#

Spaces.cloud_add_host#

Spaces.cloud_remove_host#

Spaces.cloud_budget#

Spaces.cloud_reconcile#

Spaces.prewarm#

Spaces.prewarms#

Spaces.remove_prewarm#

ElasticAssignment record#

ElasticBudget record#

ElasticBudgetUpdate record#

ElasticDecision record#

ElasticHost record#

ElasticNewHost record#

ElasticPlan record#

ElasticPlanRequest record#

ElasticRemoved record#

ElasticUnplaced record#

Prewarm record#

PrewarmOptions record#

PrewarmPlacement record#