v3.5 changelog
quickstart →

Fleet configuration

Complete reference for configuring RunsOn Fleet — every input of the Terraform module.

RunsOn Fleet is installed exclusively through the Terraform / OpenTofu module ↗ (runs-on/runs-on/aws//modules/fleet) — there is no CloudFormation option. This page is the full reference for every module input.

The runner and fleet catalogs (runners, fleets, images) are passed as Terraform inputs too; see Runner fleets for how to model them, and Configuration for how Fleet’s catalog-driven configuration compares to Flex.

To change a value, edit your Terraform configuration and re-apply — see the Upgrade guide.

Fleet catalog fields#

Fleet rejects unknown catalog fields during terraform plan.

fleets.<name>.max_runners#

max_runners is the fleet’s sustained concurrency ceiling. It defaults to 1000; set it to 0 to drain a fleet while keeping its configuration. max_launch_batch_size is separate: it controls the rate at which Fleet approaches that ceiling.

fleets.<name>.max_launch_batch_size#

max_launch_batch_size limits the new capacity one serialized target reconciliation can process. It defaults to 50; omitting it or setting it to 0 uses that default. Fleet finishes EC2 placement, claim persistence, and JIT/config finalization for the batch before reevaluating the latest desired runner count.

Raise this value when large cold bursts repeatedly launch in full 50-runner waves. app_size controls the workers that finalize each batch, so tune both settings together. A value above max_runners has no effect. See Rate limits and scale: Fleet burst launches for a tuning sequence, example, and diagnostic fields.

runners.<name>.retry#

Fleet can start up to two failed-job reruns after a Spot interruption. It sends new recovery capacity to on-demand, but GitHub may assign an existing matching Spot runner. Set retry: false on a runner to opt it out of automatic reruns; interruption detection still feeds the Spot circuit breaker. GitHub Apps need Actions: read and write permission for recovery reruns.

Required inputs#

stack_name#

  • Type: string
  • Required: yes
  • Description: Name of the RunsOn Fleet stack.

license_key#

  • Type: string
  • Required: yes
  • Sensitive: yes
  • Description: RunsOn license key obtained from runs-on.com

email#

  • Type: string
  • Required: yes
  • Description: Email address for alerts and notifications (requires confirmation)

runners#

  • Type: any
  • Required: yes
  • Description: Runner catalog keyed by runner name. Entries must use fields supported by Fleet’s RunnerSpec.

fleets#

  • Type: any
  • Required: yes
  • Description: Fleet catalog keyed by fleet name. Entries configure a runner reference and Fleet-specific settings.

vpc_id#

  • Type: string
  • Required: yes
  • Description: VPC ID where the Fleet stack will run.

Optional inputs#

github_app_id#

  • Type: number
  • Default: null
  • Description: GitHub App ID used by the Fleet runtime.

github_app_private_key#

  • Type: string
  • Default: null
  • Sensitive: yes
  • Description: GitHub App private key in PEM format.

github_enterprise_pat#

  • Type: string
  • Default: null
  • Sensitive: yes
  • Description: Classic PAT used for enterprise-target Fleet mode. Must start with ghp_ when set.

github_base_url#

  • Type: string
  • Default: "https://github.com"
  • Description: GitHub web host root URL (https). Leave the default for github.com, or set a GHE.com data-residency or GHES host.

github_enterprise_name#

  • Type: string
  • Default: null
  • Description: GitHub Enterprise slug used when github_enterprise_pat is set.

alert_slack_webhook_url#

  • Type: string
  • Default: ""
  • Sensitive: yes
  • Description: Slack webhook URL for alert notifications (optional)

environment#

  • Type: string
  • Default: "production"
  • Description: Environment name used by the workflow targeting contract.

images#

  • Type: any
  • Default: {}
  • Description: Custom runner image catalog keyed by image name. Built-in image names such as ubuntu24-full-x64 and ubuntu26-full-x64 do not need entries here.

spot_circuit_breaker#

  • Type: string
  • Default: ""
  • Description: Spot circuit breaker for Fleet launches, formatted as COUNT/WINDOW_MINUTES/RECOVERY_MINUTES: after COUNT spot interruptions within WINDOW_MINUTES, launch on-demand for RECOVERY_MINUTES. “false” disables it; empty uses the built-in default “2/15/30” (same semantics as the Flex SpotCircuitBreaker stack parameter).

public_subnet_ids#

  • Type: list(string)
  • Default: []
  • Description: Public subnet IDs used for runners and Fargate. Required unless private_mode is “only”.

private_subnet_ids#

  • Type: list(string)
  • Default: []
  • Description: Private subnet IDs used for Fargate and runners when private_mode is enabled.

security_group_ids#

  • Type: list(string)
  • Default: []
  • Description: Security group IDs for runners and the Fleet worker. Leave empty to create a dedicated group.

private_mode#

  • Type: string
  • Default: "false"
  • Allowed values: false, true, always, only
  • Description: Private networking mode: false, true, always, or only.

ssh_allowed#

  • Type: bool
  • Default: false
  • Description: Allow SSH ingress when the module creates its own security group.

ssm_allowed#

  • Type: bool
  • Default: true
  • Description: Enable SSM access for runner instances. When true, this attaches AmazonSSMManagedEC2InstanceDefaultPolicy to the runner instance role.

ssh_cidr_range#

  • Type: string
  • Default: "0.0.0.0/0"
  • Description: CIDR range allowed for SSH access when the module creates its own security group.

cost_allocation_tag#

  • Type: string
  • Default: "stack"
  • Description: Tag key used for cost allocation.

app_budget_daily_usd#

  • Type: number
  • Default: 10
  • Description: Daily AWS cost budget in USD for this stack, filtered by the configured cost allocation tag. Set to 0 to disable the budget. Fleet does not activate the cost allocation tag: activate it in AWS Billing (in the management account for AWS Organizations member accounts), or the budget sees no spend.

tags#

  • Type: map(string)
  • Default: {}
  • Description: Additional tags applied to all created AWS resources.

runtime_image#

  • Type: string
  • Default: "public.ecr.aws/c5h5o9k1/runs-on/runs-on:v3.5.0@sha256:eb2a7a059c1859de1e565152b0c4fc548d9a35cf551aff1aa500b8bb1ea5a4fc"
  • Description: RunsOn worker image containing the fleetd binary. Override with a runs-on-ci image for live validation. Passing null falls back to the default, which release publication pins to the released image.

extra_env_vars#

  • Type: map(string)
  • Default: {}
  • Description: Additional environment variables to set on the Fleet worker service.

integration_step_security_api_key#

  • Type: string
  • Default: ""
  • Sensitive: yes
  • Description: API key for StepSecurity integration (optional).

otel_exporter_endpoint#

  • Type: string
  • Default: ""
  • Description: OpenTelemetry exporter endpoint for observability (optional)

otel_exporter_headers#

  • Type: string
  • Default: ""
  • Sensitive: yes
  • Description: OpenTelemetry exporter headers as comma-separated key=value pairs, as in OTEL_EXPORTER_OTLP_HEADERS. Values may be percent-encoded: authorization=Bearer%20KEY and authorization=Bearer KEY are equivalent (optional)

otel_exporter_temporality#

  • Type: string
  • Default: "cumulative"
  • Allowed values: cumulative, delta
  • Description: OTLP metrics temporality: cumulative (default, for Prometheus-compatible backends) or delta (recommended for SigNoz, required by Datadog). Delta applies to counters and histograms; up-down counters stay cumulative.

otel_resource_attributes#

  • Type: string
  • Default: ""
  • Description: Extra OTLP resource attributes as comma-separated key=value pairs, set as OTEL_RESOURCE_ATTRIBUTES. They override RunsOn defaults such as deployment.environment, except service.name. (optional)

otel_logs_enabled#

  • Type: bool
  • Default: true
  • Description: Enable OpenTelemetry log export

otel_traces_enabled#

  • Type: bool
  • Default: true
  • Description: Enable OpenTelemetry trace export

app_size#

  • Type: string
  • Default: "small"
  • Allowed values: small, medium, high, xhigh
  • Description: Preset for the Fleet worker service, default EC2 launch concurrency, and default registration concurrency. Allowed values: small, medium, high, xhigh.

container_insights_enabled#

  • Type: bool
  • Default: false
  • Description: Enable ECS Container Insights on the control-plane cluster. Disabled by default: Container Insights publishes custom CloudWatch metrics billed per metric, a fixed cost the RunsOn dashboards do not need.

app_capacity_provider#

  • Type: string
  • Default: "fargate"
  • Allowed values: fargate, fargate_spot
  • Description: Fargate capacity provider for the Fleet worker service. Use fargate_spot to lower idle cost for small installs; interrupted in-flight assigned jobs are reconciled by the Fleet runtime.

maintenance_mode#

  • Type: bool
  • Default: false
  • Description: Enable maintenance mode (disables queue processing and leader election)

bootstrap_tag#

  • Type: string
  • Default: "v0.1.17"
  • Description: Bootstrap release tag used by the shared compute bootstrap template.

app_tag#

  • Type: string
  • Default: "v3.5.0"
  • Description: Application/agent tag published into the cache bucket and passed to runners. Passing null falls back to the default, which release publication pins to the released version.

runner_max_runtime#

  • Type: number
  • Default: 60
  • Description: Maximum runtime in minutes passed to the shared compute bootstrap template.

cache_expiration_days#

  • Type: number
  • Default: 10
  • Description: Number of days to retain cache artifacts.

cache_bucket_namespace#

  • Type: string
  • Default: "global"
  • Allowed values: global, account-regional
  • Description: S3 namespace for the cache bucket. Use account-regional when an organization SCP requires account-regional S3 bucket names.

cache_bucket_versioning_enabled#

  • Type: bool
  • Default: false
  • Description: Enable S3 object versioning for the cache bucket.

force_destroy_buckets#

  • Type: bool
  • Default: false
  • Description: Allow the cache bucket to be destroyed while non-empty.

enable_ecr#

  • Type: bool
  • Default: false
  • Description: Enable an ECR repository for ephemeral Docker image and BuildKit cache storage.

ecr_pull_through_cache_rules#

  • Type: map(object({ ecr_repository_prefix = string upstream_registry_url = string upstream_repository_prefix = optional(string) }))
  • Default: {}
  • Description: Existing ECR pull-through cache rules to reference for Fleet runner image pulls. Create or import the regional rules outside the RunsOn module.

log_retention_days#

  • Type: number
  • Default: 7
  • Allowed values: 1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1827, 3653
  • Description: CloudWatch Logs retention in days. Control-plane Lambda logs keep at least 14 days.

permission_boundary_arn#

  • Type: string
  • Default: ""
  • Description: Optional IAM permission boundary ARN applied to created roles.

messaging_kms_key_arn#

  • Type: string
  • Default: ""
  • Description: Customer-managed KMS key ARN used to encrypt the SNS alerts topic (Fleet creates no SQS queues). Leave empty for no SSE on the topic (SNS default disk encryption only). The module grants RunsOn roles access through IAM, so the key policy must delegate to IAM in this account, and must allow budgets.amazonaws.com kms:GenerateDataKey and kms:Decrypt when app_budget_daily_usd > 0.

runner_custom_policy_arns#

  • Type: list(string)
  • Default: []
  • Description: Optional managed policy ARNs attached to the EC2 runner role. Use this when policy ARNs are computed by other resources.

enable_bedrock#

  • Type: bool
  • Default: false
  • Description: Enable Amazon Bedrock access for EC2 runner instances.

ipv6_enabled#

  • Type: bool
  • Default: false
  • Description: Enable IPv6 on EC2 runner launch templates.

runner_custom_tags#

  • Type: list(string)
  • Default: []
  • Description: Additional custom tags propagated to launched runner instances.

enable_cache_isolation#

  • Type: bool
  • Default: false
  • Description: Enable brokered, per-repository/per-branch credentials for Magic Cache data under scoped-cache/. Direct S3 cache integrations keep instance-profile access to the stack-shared cache/ namespace and are not repository-isolated. Opt-in

enable_stickydisk_isolation#

  • Type: bool
  • Default: false
  • Description: Remove the legacy EBS volume/snapshot permissions from the runner instance role, so all sticky-disk EBS operations happen exclusively on the control plane. Breaks the legacy v1 runs-on/snapshot action. Opt-in