v3.4 changelog
quickstart →

Flex Terraform inputs

Every input of the RunsOn Flex Terraform / OpenTofu module, with types, defaults, and allowed values.

The Terraform module ↗ (runs-on/runs-on/aws//modules/flex) exposes the inputs below. It also works with OpenTofu ↗. Setup steps are in Install Flex.

The module deploys into an existing VPC, so vpc_id and public_subnet_ids are required. It also covers setups the CloudFormation stack does not, such as GHES and IAM permission boundaries. Input names differ from the CloudFormation parameters: app_size instead of AppSize, for example.

To change a value, edit the input in your Terraform configuration and re-apply, as described in Upgrades.

Required inputs#

github_organization#

  • Type: string
  • Required: yes
  • Description: GitHub organization or username for RunsOn integration

license_key#

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

vpc_id#

  • Type: string
  • Required: yes
  • Description: VPC ID where RunsOn infrastructure will be deployed

public_subnet_ids#

  • Type: list(string)
  • Required: yes
  • Description: List of public subnet IDs for runner instances. Required unless private_mode is “only”.

email#

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

Optional inputs#

stack_name#

  • Type: string
  • Default: "runs-on"
  • Description: Name for the RunsOn stack (used for resource naming)

environment#

cost_allocation_tag#

  • Type: string
  • Default: "stack"
  • Description: Name of the tag key used for cost allocation and tracking

tags#

  • Type: map(string)
  • Default: {}
  • Description: Tags to apply to all resources. Note: ‘runs-on-stack-name’ is added automatically for resource discovery.

github_enterprise_url#

  • Type: string
  • Default: ""
  • Description: GitHub Enterprise web URL for GHE.com data residency or GitHub Enterprise Server (optional, leave empty for github.com)

private_subnet_ids#

  • Type: list(string)
  • Default: []
  • Description: List of private subnet IDs for runner instances (required if private_mode is not ‘false’)

private_mode#

  • Type: string
  • Default: "false"
  • Allowed values: false, true, always, only
  • Description: Private networking mode: ‘false’ (disabled), ‘true’ (opt-in with label), ‘always’ (default with opt-out), ‘only’ (forced, no public option)

private_mode_delay#

  • Type: string
  • Default: "0s"
  • Description: Delay before starting the worker service in private mode, to allow NAT gateways to become ready. Set to ”60s” or higher for fresh NAT gateway deployments.

security_group_ids#

  • Type: list(string)
  • Default: []
  • Description: Security group IDs for runner instances and the worker service. If empty list provided, security groups will be created automatically.

ssh_allowed#

  • Type: bool
  • Default: false
  • Description: Allow SSH access to runner instances

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 to runner instances (only applies if ssh_allowed is true)

cache_expiration_days#

  • Type: number
  • Default: 10
  • Description: Number of days to retain cache artifacts in S3 before expiration

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.

locks_table_point_in_time_recovery_enabled#

  • Type: bool
  • Default: false
  • Description: Enable DynamoDB point-in-time recovery on the locks table. Its rows are transient and expire through TTL, so this only helps satisfy policies that require PITR on every table, at extra storage cost.

force_destroy_buckets#

  • Type: bool
  • Default: false
  • Description: Allow S3 buckets to be destroyed even when not empty. Set to false for production environments to prevent accidental data loss.

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: Number of days to retain CloudWatch logs. Runner instance logs use this value as is; control-plane and Lambda logs keep at least 14 days.

permission_boundary_arn#

  • Type: string
  • Default: ""
  • Description: IAM permissions boundary ARN to attach to all IAM roles (optional)

ipv6_enabled#

  • Type: bool
  • Default: false
  • Description: Enable IPv6 support for runner instances

ebs_encryption_key_id#

  • Type: string
  • Default: ""
  • Description: KMS key ID for explicit EBS volume encryption. Leave empty to omit explicit EBS encryption fields, use alias/aws/ebs for the AWS-managed EBS key, or provide a customer-managed key ID, alias, or ARN. Prefer a full ARN for customer-managed keys, especially cross-account keys. Customer-managed keys must also trust the generated RunsOn worker task role in their key policy.

app_image#

  • Type: string
  • Default: "public.ecr.aws/c5h5o9k1/runs-on/runs-on:v3.4.0@sha256:08c80b917f9c3e7e3968e2e030ced82b2fd5319b03679339484c2debeb4c6eb5"
  • Description: Container image for the RunsOn worker service. Published module releases inject a pinned public default during mirror publication.

app_tag#

  • Type: string
  • Default: "v3.4.0"
  • Description: Application version tag for RunsOn service. Published module releases inject the released default during mirror publication.

bootstrap_tag#

  • Type: string
  • Default: "v0.1.12"
  • Description: Bootstrap script version tag

maintenance_mode#

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

app_size#

  • Type: string
  • Default: "small"
  • Allowed values: small, medium, high, xhigh
  • Description: Preset for the 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 RunsOn worker service. Use fargate_spot to lower idle cost for small installs; interrupted in-flight queue messages retry after the SQS visibility timeout.

app_force_new_deployment#

  • Type: bool
  • Default: false
  • Description: Force a new ECS deployment of the RunsOn control-plane service. Set to true for one apply when migrating existing installs across the v3.0.6 ECS capacity provider change or when changing app_capacity_provider.

app_ecr_repository_url#

  • Type: string
  • Default: ""
  • Description: Private ECR repository URL for RunsOn image (e.g., 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-repo:tag). When specified, the worker service will pull from this private ECR instead of public ECR.

app_custom_policy_arns#

  • Type: list(string)
  • Default: []
  • Description: Optional managed IAM policy ARNs to attach to the RunsOn service role.

github_app_id#

  • Type: number
  • Default: null
  • Description: GitHub App ID. If provided along with other github_app_* variables, creates a Secrets Manager secret and skips the web-based GitHub App setup flow.

github_app_private_key#

  • Type: string
  • Default: ""
  • Sensitive: yes
  • Description: GitHub App private key (PEM format)

github_app_webhook_secret#

  • Type: string
  • Default: ""
  • Sensitive: yes
  • Description: GitHub App webhook secret

github_app_client_id#

  • Type: string
  • Default: ""
  • Description: GitHub App client ID

github_app_client_secret#

  • Type: string
  • Default: ""
  • Sensitive: yes
  • Description: GitHub App client secret

github_api_boost_apps#

  • Type: map(object({ github_app_id = number github_app_private_key = string github_app_client_id = string github_app_client_secret = string github_app_label = optional(string, "") }))
  • Default: {}
  • Sensitive: yes
  • Description: Additional same-org GitHub Apps used only for API boost capacity. These entries omit webhook secrets and are written under the shared GitHub apps secret.

github_api_strategy#

  • Type: string
  • Default: "normal"
  • Allowed values: normal, conservative
  • Description: Strategy for GitHub API calls (normal, conservative)

runner_max_runtime#

  • Type: number
  • Default: 720
  • Description: Maximum runtime in minutes for runners before forced termination

runner_custom_policy_arns#

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

runner_config_auto_extends_from#

  • Type: string
  • Default: ".github-private"
  • Description: Auto-extend runner configuration from this base config

runner_custom_tags#

  • Type: list(string)
  • Default: []
  • Description: Custom tags to apply to runner instances (comma-separated list)

enable_cost_reports#

  • Type: string
  • Default: "daily"
  • Allowed values: no, daily, weekly, monthly
  • Description: Cost report email cadence: no, daily, weekly, or monthly. Legacy true/false values must be replaced with daily/no when upgrading.

spot_circuit_breaker#

  • Type: string
  • Default: "2/15/30"
  • Description: Spot instance circuit breaker configuration (e.g., ‘2/15/30’ = 2 failures in 15min, block for 30min)

enable_warm_pools#

  • Type: bool
  • Default: true
  • Description: Whether this stack keeps warm pool instances. When false, jobs with a pool= label still run on this stack, on a newly launched instance.

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. For AWS Organizations member accounts, activate the cost allocation tag in the management account’s Billing settings.

enable_default_dashboard#

  • Type: bool
  • Default: true
  • Description: Create the default RunsOn CloudWatch dashboard. Set to false when managing a custom dashboard separately.

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_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

logger_level#

  • Type: string
  • Default: "info"
  • Allowed values: debug, info, warn, error
  • Description: Logging level for RunsOn service (debug, info, warn, error)

extra_env_vars#

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

alert_slack_webhook_url#

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

mandatory_extras#

  • Type: list(string)
  • Default: []
  • Description: Runner extras (e.g. s3-cache, otel) that are always enabled for every runner, regardless of label or repo config overrides.

enable_efs#

  • Type: bool
  • Default: false
  • Description: Enable EFS file system for shared storage across runners

enable_ecr#

  • Type: bool
  • Default: false
  • Description: Enable ECR repository for ephemeral Docker image 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 runner image pulls. Create or import the regional rules outside the RunsOn module.

enable_bedrock#

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

prevent_destroy_optional_resources#

  • Type: bool
  • Default: true
  • Description: Prevent destruction of durable optional resources such as EFS. ECR contains ephemeral runner images and is force-deleted by default.

enable_waf#

  • Type: bool
  • Default: false
  • Description: Enable AWS WAF for the public ingress

enable_admin_routes#

  • Type: bool
  • Default: true
  • Description: Enable the admin Lambda routes (/, /setup, /setup/{proxy+}, /readyz) on the public ingress

public_ingress_web_acl_arn#

  • Type: string
  • Default: ""
  • Description: Optional user-managed AWS WAFv2 Web ACL ARN to associate with the public ingress. When set, RunsOn will not manage webhook IP synchronization.

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