self-host →

Fleet configuration

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

RunsOn Fleet is installed exclusively through the Terraform / OpenTofu module — 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.

runners.<name>.retry#

Fleet can rerun failed first-attempt jobs on On-Demand capacity after a Spot interruption. Set retry: false on a runner to opt it out of those automatic reruns; interruption detection still feeds the Spot circuit breaker. GitHub Apps need Actions: read and write permission for recovery reruns.

Terraform inputs#

The Terraform module ↗ (runs-on/runs-on/aws//modules/fleet) exposes the following inputs.

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: map(any)
  • Required: yes
  • Description: Runner catalog keyed by runner name. Entries must use fields supported by Fleet’s RunnerSpec.

fleets#

  • Type: map(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 host root URL. Leave the default for github.com and set a GHES host root such as https://ghe.example.com ↗ when needed.

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: map(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.

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.

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.2.3@sha256:6c2d5ede8996d875578e2fd6a5f472f89a75c7773525f1c747ec333065425e73"
  • 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 (optional)

otel_exporter_temporality#

  • Type: string
  • Default: "cumulative"
  • Allowed values: cumulative, delta
  • Description: OTLP metrics temporality: cumulative (default) or delta

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.

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.2.3"
  • 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.

permission_boundary_arn#

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

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