Get started / Capacity policy

Approve alternatives and prepare for busy hours.

Controller v0.7.0 and module 0.7.0 add ordered EC2 instance alternatives and UTC minimum-capacity windows. Both are optional. Fleets retain their labels, architecture, network, images, and permissions.

Approve instance alternatives

Merge an ordered list into your existing fleet. Review each type’s architecture, AMI compatibility, CPU, memory, local storage, EBS and networking limits, quotas, regional availability, and price.

fleets = {
  linux-build = {
    scale_set_name            = "gondola-linux-build"
    architecture              = "x64"
    instance_type             = "m7i.large"
    instance_type_alternatives = ["m7a.large", "m6i.large"]
    capacity_mode             = "spot-with-on-demand-fallback"
    subnet_ids                = var.approved_runner_subnets
    min_runners               = 0
    max_runners               = 8
  }
}

Gondola tries the primary type across the configured subnets, then alternatives in the listed order. It advances after a definitive AWS capacity rejection. Ambiguous responses, authorization failures, and configuration errors stop the attempt. Spot-only fleets remain Spot; Spot-with-On-Demand fallback exhausts approved Spot candidates before trying approved On-Demand candidates.

The limit is eight distinct types including the primary and 32 type/subnet combinations per fleet. All types must match the fleet’s architecture. An empty list preserves single-type behavior. Legacy single-fleet installations use runner_instance_type_alternatives.

Selected types, subnets, market, and fallback decisions appear in controller logs. Gondola does not automatically discover cheaper types or switch regions. This launch fallback does not retry a job interrupted after launch. Changes affect future launches, including fleets using S3 caching.

Raise the minimum during predictable busy periods

The following window maintains a minimum of two available runners from 12:00 to 22:00 UTC on weekdays, subject to the fleet’s maximum and normal reconciliation. Use the same fleet key as above.

warm_windows = {
  linux-build = [
    {
      days             = ["mon", "tue", "wed", "thu", "fri"]
      start_utc        = "12:00"
      duration_minutes = 600
      min_runners      = 2
    }
  ]
}

Use default as the key for a legacy single fleet. Each fleet accepts up to 16 windows, one through seven unique lowercase weekday names, a UTC HH:MM start, and a duration of 15 through 1,440 whole minutes. The minimum must be between zero and the fleet’s max_runners. Review and apply your Terraform/OpenTofu plan.

Times are always UTC; daylight-saving changes are not applied. Windows can cross midnight or the end of the week. Start is inclusive and end is exclusive. Overlapping windows take the highest minimum and never lower the fleet’s ordinary minimum. Assigned jobs are added to that minimum, capped by max_runners.

Plan for launch time and wind-down

Set windows early enough for EC2 launch and runner registration. They take effect on the next successful reconciliation; an unavailable controller or GitHub connection cannot launch capacity. Logs show effective-minimum changes. With metrics enabled, configured fleets also emit MinimumRunners.

Budget for the higher minimum and delayed wind-down. Alternative types and minimum windows are not spending caps or guarantees of shorter queues. See the AWS cost model and docs/capacity.md in the signed operator-guide bundle.