Skip to content
Spinbox is experimental: APIs change and data may be lost. Status lists what is built and what proves it.

modules/runners

View Markdown

Source: github.com/spin-stack/spin-terraform-aws//modules/runners?ref=v20261027.02. Generated from its variables and outputs.

VariableTypeDefault
controlplaneobject({ name = string iam_name = string vpc_id = string subnet_ids = list(string) security_group_id = string runner_document_arn = string runner_user_data = string images = map(object({ id = string, root_device = string })) boot_log_policy_arn = string standard_vcpus = number boundary_arn = string })required
instance_typeslist(string)["c8i.*","c8id.*","m8i.*","m8id.*","r8i.*","r8id.*"]
vcpusobject({ min = number, max = number }){"max":48,"min":32}
nested_virtualizationbooltrue
spotbooltrue
request_quotabooltrue
max_hostsnumber1
rolloutstring"idle"
drain_secondsnumber150
data_volume_gbnumber0
root_volume_gbnumber30
tagsmap(string){}

The control plane module’s outputs, as they are: its name, where the runners go, their document, and what a runner’s machine runs at its first boot.

  • Type: object({ name = string iam_name = string vpc_id = string subnet_ids = list(string) security_group_id = string runner_document_arn = string runner_user_data = string images = map(object({ id = string, root_device = string })) boot_log_policy_arn = string standard_vcpus = number boundary_arn = string })
  • Required

The types the group may start, as EC2’s allowed_instance_types takes them: names, or patterns with * (c8id.*). The group starts any type they match that has vcpus and the disk data_volume_gb leaves the data on - a local NVMe while it is 0, so a d variant - and AWS adds the sizes and types it brings out without this list changing.

Keep them one CPU generation: a checkpoint records the processor and its flags as -cpu host showed them (MachineIdentity in spin’s internal/runner/vmm), and resumes only onto a host that shows the same - a workspace suspended at night on one family and brought back on another cold-boots. Nested virtualization is offered on C8i, M8i, R8i (and their d variants), C7i, M7i, R7i and I7i. Not c8i* for c8i.*: that matches the flex types too.

For spot, the more pools a request can draw on the likelier a machine, and one type is one pool per zone. How the types these match score in a region, before installing: aws ec2 get-spot-placement-scores —target-capacity 1 —region-names <region>
—single-availability-zone —instance-requirements-with-metadata
’{“ArchitectureTypes”:[“x86_64”],“InstanceRequirements”:{“VCpuCount”:{“Min”:32,“Max”:48},“MemoryMiB”:{“Min”:65536},“LocalStorage”:“required”,“AllowedInstanceTypes”:[<the types>]}}’

  • Type: list(string)
  • Default: ["c8i.*","c8id.*","m8i.*","m8id.*","r8i.*","r8id.*"]

How many vCPUs a runner may have, at least and at most: each type instance_types matches within it is a pool the group may draw on. max is also what the quota is sized by (quota.tf).

  • Type: object({ min = number, max = number })
  • Default: {"max":48,"min":32}

Enable KVM inside the instance. False for .metal types, which have it by being metal and refuse the option.

  • Type: bool
  • Default: true

Every host a spot instance. The policy a runner joins under (the control plane module’s runner_policy) is what tells each one a stop is a reclaim.

  • Type: bool
  • Default: true

Ask AWS for the vCPU quota max_hosts runners need, when the account’s is lower (quota.tf). A request costs nothing and lowers nothing when it is removed.

  • Type: bool
  • Default: true

The most runners the group may have. How many it has is the control plane’s to decide: none until a workspace waits for a host, and none again once nothing has run for the control plane module’s runner_idle_minutes.

  • Type: number
  • Default: 1

How a new release reaches the runners. idle: when the fleet next empties - no workspace running, starting or being saved - the next host boots it, and no workspace is moved for it; a host keeps the old release until then, which its control plane allows for 90 days. rolling: the hosts are replaced at once, one at a time, each old one’s workspaces suspended to the bucket and resumed on the new one - for a fleet that never empties.

  • Type: string
  • Default: "idle"

How long a host the group is taking away is held while it empties itself: the termination hook’s timeout. At least the pool token’s —shutdown-grace; the hook is left to expire, so this is also how long each scale-in takes.

  • Type: number
  • Default: 150

An EBS volume for the runner’s data, for an instance type with no local NVMe. Zero uses the instance store, which is the right disk for volumes’ cache and costs nothing more. A machine’s boot takes an empty EBS volume where it has one, and the instance store otherwise.

  • Type: number
  • Default: 0

The runner’s root disk: the OS and the machine’s files; its data is on the instance store or data_volume_gb.

  • Type: number
  • Default: 30

Tags on everything this module creates.

  • Type: map(string)
  • Default: {}
OutputWhat it is
autoscaling_groupThe runners’ group, which the control plane sizes: empty until a workspace waits for a host.
security_group_idThe runners’ security group: nothing in, everything out - a workspace’s egress is filtered on the host by spin.

Generated by task reference from spin-terraform-aws/modules/runners/variables.tf at 358445c95.

Installations run Spinbox v20261027.01; the reference is generated from spin v20261114.01 (51f7e0dea). This page as Markdown, for a model or a terminal.