Stack configuration
The CloudFormation stack that RunsOn creates when installing the service has many parameters. This page lists them all and describes what each one does.
To update a parameter, simply follow the instructions in the Upgrade guide and update the parameter in the CloudFormation interface.
GithubOrganization
Type: String
Description: For instance if your GitHub organization lives at github.com/my-org, then the value of this parameter should be: my-org
MinLength: 1
LicenseKey
Type: String
Description:
License key for RunsOn, either as a string or SSM parameter ARN (with the format arn:aws:ssm:REGION:ACCOUNT:parameter/STACK_NAME/license-key). Get one at https://runs-on.com/pricing ↗.
MinLength: 1
EmailAddress
Type: String
Description: Email address for cost and alert reports. You must confirm the subscription by clicking the link in the email that you will receive after creating the stack.
MinLength: 1
Environment
Type: String
Default: production
MinLength: 1
Description:
Environment for the RunsOn service: you can create multiple RunsOn installations and set this parameter to different values. And then target a single installation by setting the env=ENV_NAME label in the runs-on: definition in your GitHub Actions workflow. If no env label is set in job definitions, the production environment is targeted, so make sure to keep this default value if you only have one RunsOn installation.
AlertTopicSubscriptionHttpsEndpoint
Type: String
Description: HTTPS endpoint for cost and alert reports.
Default:
VpcCidrBlock
Type: String
Description: CIDR block for the VPC. Updating this value after creation will require deleting the stack and recreating it.
Default: 10.1.0.0/16
VpcCidrSubnetBits
Type: Number
Description: Number of bits to allocate for the subnet. For example, if you specify VpcCidrBlock to a /16 (the default), and this value to 12 (the default), you will have 4 bits, i.e. max 16 subnets in the VPC. Updating this value after creation will require deleting the stack and recreating it.
Default: 12
MinValue: 9
MaxValue: 16
Ipv6Enabled
Type: String
Default: false
AllowedValues:
- “true"
- "false”
Description: Enable or disable IPv6 for runners. Disabling ipv6 might help with Docker Hub rate limiting issues.
SSHAllowed
Type: String
Default: true
AllowedValues:
- “true"
- "false”
Description: Allow inbound SSH connections from the specified CIDR range to the runners.
SSHCidrRange
Type: String
Default: 0.0.0.0/0
Description: CIDR range for inbound SSH access. By default, only repository collaborators with admin permission will be able to SSH into the runner instances.
MinLength: 1
Private
Type: String
Default: false
AllowedValues:
- “only"
- "always"
- "true"
- "false”
Description:
Enable (‘true’, ‘always’, ‘only’) or disable (‘false’) private networking. If ‘true’, your jobs can opt-in to launch in private subnets with the private=true label, and they will get a static egress IP. If ‘always’, all jobs will run in private subnets, and they will all get a static egress IP, unless you manually opt-out in your job definition with the private=false label. If ‘only’, then jobs can only launch in private subnets. Note that enabling it will create 1 managed NAT gateway, with the corresponding costs. More details at https://runs-on.com/networking/static-ips/ ↗.
NatGatewayElasticIPCount
Type: Number
Default: 1
MinValue: 1
MaxValue: 8
Description: Number of Elastic IPv4s to attach to each NAT Gateway (if Private mode is enabled). Defaults to 1. Maximum of 8. Increasing this number is useful if you launch a large number of runners and are rate-limited by some external services due to the limited number of NAT Gateway IP addresses. Incurs ~$3.6/month additional cost for each Elastic IP. Note that by default you are limited to 2 EIPs per NAT gateway, but can request a quota increase from AWS.
NatGatewayAvailability
Type: String
Default: SingleAZ
AllowedValues:
- SingleAZ
- MultiAZ
VpcFlowLogFormat
Type: String
Default:
Description: VPC Flow Log format. If blank, the default format will be used. More details at https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs.html#flow-logs-fields ↗
VpcFlowLogS3BucketArn
Type: String
Default:
Description: ARN of an S3 bucket to send VPC Flow Logs to in addition to the default CloudWatch logs group. If blank, the logs will only be sent to CloudWatch Logs.
VpcFlowLogRetentionInDays
Type: Number
Default: 7
MinValue: 1
Description: Retention period in days for VPC Flow Logs.
DefaultPermissionBoundaryArn
Type: String
Default:
Description: ARN of an IAM policy that will be assigned as permission boundary to roles created by the stack. If blank, the roles will not have a permission boundary.
DefaultAdmins
Type: String
Default:
Description: Comma-separated list of GitHub usernames that will always be granted SSH access to all the runner instances (if SSH access is enabled), in addition to any repository admins. If blank, only repository collaborators with admin permission will be able to SSH into the runner instances.
AppEc2QueueSize
Type: Number
Default: 2
MinValue: 1
Description: Rate limit for launching instances, per second. New AWS accounts come with a default of 2 RunInstances call/s, so only increase this if you have requested a higher limit from AWS (https://docs.aws.amazon.com/AWSEC2/latest/APIReference/throttling.html ↗).
AppAlarmDailyMinutes
Type: Number
Default: 4000
Description: Trigger an alarm if the cumulative number of minutes consumed during a day is over that number.
AppCPU
Type: Number
AllowedValues:
- 256
- 512
- 1024
- 2048
- 4096
Default: 256
Description: CPU units for RunsOn service (256 or higher). You might only need to change this if you have 10k+ jobs per day.
AppMemory
Type: Number
AllowedValues:
- 512
- 1024
- 2048
- 3072
- 4096
- 6144
- 8192
Default: 512
Description: Memory in MB for RunsOn service (512 or higher). You might only need to change this if you have 10k+ jobs per day.
AppRegistry
Type: String
Default: public.ecr.aws/c5h5o9k1/runs-on/runs-on
Description: Docker image (public) registry for the RunsOn service.
EncryptEbs
Type: String
Default: false
AllowedValues:
- “true"
- "false”
Description: Encrypt the EBS volumes of the runner instances. Encryption will slow the boot time of runner instances by ~10s.
RunnerDefaultDiskSize
Type: Number
Default: 40
MinValue: 40
Description: Disk size in GB for default runners.
RunnerDefaultVolumeThroughput
Type: Number
Default: 400
MinValue: 125
MaxValue: 1000
Description: Volume throughput in MiB/s for default runners (helps with faster boot times, but costs more).
RunnerLargeDiskSize
Type: Number
Default: 80
MinValue: 40
Description: Disk size in GB for large runners.
RunnerLargeVolumeThroughput
Type: Number
Default: 750
MinValue: 125
MaxValue: 1000
Description: Volume throughput in MiB/s for large runners (helps with faster boot times, but costs more).
RunnerCustomTags
Type: CommaDelimitedList
Default:
Description:
Optional custom tags for the runner instances (e.g. ‘key1=value1,key2=value2’). Tag keys cannot start with runs-on, and can only use letters (a-z, A-Z), numbers (0-9), and the following characters: + - = . , _ : @ (https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#tag-restrictions ↗)
CostReportsEnabled
Type: String
Default: true
AllowedValues:
- “true"
- "false”
Description: Enable or disable cost reports sent by email.
EC2InstanceCustomPolicy
Type: String
Default:
Description: Optional managed IAM Policy ARN to assign to the EC2 runner instances.
ECInstanceDetailedMonitoring
Type: String
Default: false
AllowedValues:
- “true"
- "false”
Description: Enable or disable detailed monitoring for EC2 instances (can incur additional costs).
Ec2LogRetentionInDays
Type: Number
Default: 7
MinValue: 1
Description: Retention period in days for EC2 instance logs.
ServerPassword
Type: String
Default:
Description: Password for the RunsOn server (/metrics endpoint). If blank, the endpoint(s) will be disabled.
CostAllocationTag
Type: String
Default: stack
Description: Cost allocation tag to use for all the deployed resources. Updating this after creation will require deleting the stack and recreating it.