The installation module

Source: github.com/spin-stack/spin-terraform-aws?ref=<tag>. Generated from its variables.tf and outputs.tf.

Variables

Variable	Type	Default
spin_version	string	required
domain	string	required
name	string	the module’s own
acme_email	string	the module’s own
admin_email	string	the module’s own
runner_policy	object({ shutdown_grace = optional(string) preemption_source = optional(string) })	the module’s own
proxy_allowed_cidrs	list(string)	the module’s own
instance_type	string	the module’s own
proxy_instance_type	string	the module’s own
collector	object({ metric_interval = optional(string) })	the module’s own
controlplane_volume_gb	number	the module’s own
image_ids	map(string)	the module’s own
image_measurements	map(list(object({ pcr4 = string pcr7 = string pcr12 = string statement = optional(string) bundle = optional(string) revoked = optional(string) })))	the module’s own
installation_config	string	the module’s own
runner_idle_minutes	number	the module’s own
quiet_hours	string	the module’s own
time_zone	string	the module’s own
runner_instance_types	list(string)	the module’s own
runner_spot	bool	the module’s own
runner_data_volume_gb	number	the module’s own
runner_root_volume_gb	number	the module’s own
request_quota	bool	the module’s own
max_runners	number	the module’s own
runner_rollout	string	the module’s own
decommission	bool	the module’s own
monthly_budget_usd	number	the module’s own
budget_emails	list(string)	the module’s own
tags	map(string)	the module’s own

spin_version

The release the installation runs, as v<YYYYMMDD>.<N>: every machine boots the Spin OS image of it (spin-stack/ami), published into this account and tagged spin:version.

• Type: string
• Required

domain

The base domain: the dashboard is app.<domain>, workspaces are *.ws.<domain>.

• Type: string
• Required

name

The installation’s name, one per region of an account (two regions may share it): every resource’s prefix, the SSM path /spin/<name>/, and with the region every IAM name. 2 to 26 characters; modules/controlplane’s default is spin.

• Type: string
• Default: null (the module’s own default)

acme_email

The address Let’s Encrypt writes to; none is admin@<domain>.

• Type: string
• Default: null (the module’s own default)

admin_email

Who the first administrator signs in as; none is admin@<domain>.

• Type: string
• Default: null (the module’s own default)

runner_policy

The host policy a runner starts with when it joins: shutdown_grace and preemption_source; modules/controlplane’s default is a spot runner on AWS with 100s.

• Type: object({ shutdown_grace = optional(string) preemption_source = optional(string) })
• Default: null (the module’s own default)

proxy_allowed_cidrs

Where users reach the proxy on 443 from; modules/controlplane’s default is anywhere.

• Type: list(string)
• Default: null (the module’s own default)

instance_type

The control plane’s machine; modules/controlplane’s default is t8i.medium.

• Type: string
• Default: null (the module’s own default)

proxy_instance_type

The proxy’s machine; modules/controlplane’s default is t8i.micro.

• Type: string
• Default: null (the module’s own default)

collector

The collector, as modules/controlplane’s collector object: how often metrics are pushed to it; modules/controlplane’s default is 60s. Where it sends is set in the dashboard.

• Type: object({ metric_interval = optional(string) })
• Default: null (the module’s own default)

controlplane_volume_gb

The control plane’s disk, which /var - the database and the stores - takes all of past the OS; modules/controlplane’s default is 40.

• Type: number
• Default: null (the module’s own default)

image_ids

Spin OS AMIs of your own, one per role - control-plane, runner and proxy - instead of those images.json names for spin_version in this region.

• Type: map(string)
• Default: null (the module’s own default)

image_measurements

The builds of each role’s image - control-plane, runner and proxy - oldest first, each the PCRs an instance of it measures (its manifest’s measurements), instead of measurements.json’s: the control plane’s key is answered to the control plane’s builds, a host joins only as the runner’s, and the proxy is given its token only as the proxy’s. The control plane’s and the runner’s also carry statement and bundle, base64, as spin-os images sign writes them. The last of a role’s is the image image_ids names. Required with image_ids, and for a release published before its PCRs were.

• Type: map(list(object({ pcr4 = string pcr7 = string pcr12 = string statement = optional(string) bundle = optional(string) revoked = optional(string) })))
• Default: null (the module’s own default)

installation_config

The installation’s config file (spin’s configs/spin-example.yaml), as YAML: the control plane seeds its database from it at start, and shows a later change to it in the dashboard to apply or dismiss.

• Type: string
• Default: null (the module’s own default)

runner_idle_minutes

How long the fleet is idle before its runners’ group is emptied; modules/controlplane’s default is 60.

• Type: number
• Default: null (the module’s own default)

quiet_hours

HH:MM-HH:MM in time_zone when an idle fleet is emptied at once; none is none.

• Type: string
• Default: null (the module’s own default)

time_zone

The IANA zone quiet_hours are in; modules/controlplane’s default is UTC.

• Type: string
• Default: null (the module’s own default)

runner_instance_types

What the runners’ group may start, most preferred first, one CPU generation; see modules/runners.

• Type: list(string)
• Default: null (the module’s own default)

runner_spot

Every runner a spot instance; modules/runners’ default is true.

• Type: bool
• Default: null (the module’s own default)

runner_data_volume_gb

An EBS volume for each runner’s data, for instance types with no local NVMe (none of sa-east-1’s with nested virtualization have one). modules/runners’ default, 0, uses the instance store.

• Type: number
• Default: null (the module’s own default)

runner_root_volume_gb

Each runner’s root disk: the OS and the machine’s files. modules/runners’ default is 30.

• Type: number
• Default: null (the module’s own default)

request_quota

Ask AWS for the vCPU quota max_runners runners need when the account’s is lower; modules/runners’ default is true.

• Type: bool
• Default: null (the module’s own default)

max_runners

The most runners the group may have; the control plane decides how many it has. modules/runners’ default is 1.

• Type: number
• Default: null (the module’s own default)

runner_rollout

How a new release reaches the runners: idle, when the fleet next empties, moving no workspace (modules/runners’ default); or rolling, replacing them at once, their workspaces suspended and resumed on the new hosts.

• Type: string
• Default: null (the module’s own default)

decommission

Set to true and apply before tofu destroy: the buckets lose their VPC-only policies and a destroy empties them, data included (README.md, “Removing an installation”). modules/controlplane’s default is false.

• Type: bool
• Default: null (the module’s own default)

monthly_budget_usd

What the installation may cost in a month, in US dollars: an AWS Budget the control plane reads and whose alerts go to budget_emails. Null is no budget.

• Type: number
• Default: null (the module’s own default)

budget_emails

Who is emailed when the month’s cost passes 80 % or 100 % of monthly_budget_usd, or is forecast to pass it.

• Type: list(string)
• Default: null (the module’s own default)

tags

Tags on everything both modules create.

• Type: map(string)
• Default: null (the module’s own default)

Outputs

Output	What it is
next_steps	What to do now that the apply is done, in order: DNS, the first sign-in, what the runners do, and how to reach a machine. Read it with tofu output -raw next_steps.
dashboard	The installation’s dashboard.
first_sign_in	The setup page, the first administrator, and the command that reads their one-time password: an SSM SecureString this apply wrote without it ever being in the state.
name_servers	The domain’s zone’s nameservers: what its registrar, or its parent’s zone, points at.
proxy_ip	The proxy’s elastic IP, where app.<domain>, tunnel.app.<domain> and *.ws.<domain> point: the one address of the installation the internet reaches.
controlplane_group	The control plane’s group of one; its machine is reached with aws ssm start-session --target &lt;instance>.
update_status	After an apply that changed a machine: how its replacement went. Successful, InProgress, or RollbackSuccessful with the reason - after which the old machine serves again, at once or, for a control plane that had handed its database over, once its watch has restored it from the archive.
update_abort	After an apply whose new machine will not come up: the command that stops waiting for it - rolls the refresh back and abandons the launch the hook still holds - so the next apply can change the group (task update:abort).
boot_log	By role, the command that reads what its machines’ boots said - the ones that are gone included - and follows the next one’s.
runners_group	The runners’ group, which the control plane sizes: empty until a workspace waits for one.
controlplane	Everything modules/controlplane outputs.
runners	Everything modules/runners outputs.