Skip to main content
Requires Enterprise plan. Contact sales for access.
Deploy your AWS Runner using CloudFormation. Before starting, ensure you’ve completed the prerequisites.

​
Create runner in Ona

Go to Settings → Runners and click Setup a new runner:
Ona settings page showing Runners section with Setup a new runner button

Runners in settings

From the list of available providers, choose AWS.
Runner provider selection showing AWS, GCP, and other cloud options

Provider selection

Choose a name and select the AWS region to deploy the Runner into. Then, press Create. This creates the Runner reference in Ona.
Runners are regional, and can only launch Environments in the AWS region they are deployed in. For multi-region support we recommend setting up multiple Runners in different regions. The region cannot be changed once deployed.
AWS Runner creation form with name field and region selector

Add an AWS Runner

Runner details page showing CloudFormation deployment options and connection status

Runner details

​
CloudFormation Template Deployment

Next, ensure you are signed into the right AWS account in the AWS console, and then press Open AWS CloudFormation to start deploying the Runner into your AWS account. This will link you to the AWS console to create the CloudFormation stack:
AWS CloudFormation Quick create stack page with pre-filled Ona Runner template parameters

Create stack in AWS

Most parameters are auto-filled already. The template is organized into several parameter groups and has to be filled out carefully.

​
Ona configuration

The Runner ID, Exchange Token, and API Endpoint are auto-generated. Do not modify these values.

​
Network configuration (required)

VPC and subnet settings for the Runner.
ParameterDescriptionExample ValueRequired
VPCThe VPC where the Runner will be deployedvpc-12345abcd✅ Yes
Availability ZonesAZs for high availability (select 2-3)us-east-1a, us-east-1b✅ Yes
EC2 Instances SubnetPrivate subnets for EC2 instances (can be non-routable from internal network). Should match the number of AZssubnet-123abc, subnet-456def✅ Yes
Loadbalance SubnetsSubnets for load balancer with CIDR ranges routable from your internal network. Should match the number of AZssubnet-123abc, subnet-456def✅ Yes
Recommendations:
  • Select 2-3 Availability Zones for high availability
  • EC2 subnets: Use private subnets, must be sufficiently large for your expected workload
  • Load balancer subnets: Must have CIDR ranges routable from your internal network for user access
  • Ensure connectivity from user locations via VPN, Direct Connect, or Transit Gateway

​
DNS configuration

Domain name, SSL certificate, and load balancer visibility.
ParameterDescriptionExample ValueRequired
Load Balancer VisibilityChoose between internal or internet-facinginternal✅ Yes
Domain NameYour domain name for accessyourdomain.com✅ Yes
Certificate ARNARN of your SSL certificate from ACMarn:aws:acm:us-east-1:123456789012:certificate/abc123...✅ Yes
Load Balancer Visibility Options:
  • internal: Load balancer is only accessible from within your VPC (recommended for private deployments)
  • internet-facing: Load balancer is accessible from the internet (only if using public subnets)

​
Network configuration (optional)

Additional settings for enterprise security requirements.
ParameterDescriptionExample ValueRequired
Custom Security Group for Load BalancerSecurity group to attach to the load balancer for traffic controlsg-abcdef123❌ Optional
HTTP ProxyHTTP proxy server URLhttp://proxy.company.com:8080❌ Optional
HTTPS ProxyHTTPS proxy server URLhttps://proxy.company.com:8080❌ Optional
No ProxyComma-separated list of hosts to bypass proxy.internal,169.254.0.0/16,...⚠️ Required if proxy configured
Custom CA CertificateCustom certificate authority from SSM Parameter Store{{resolve:ssm:/ona/ca-cert}}❌ Optional
Security Group Behavior:
  • If not provided: An automatic security group will be created that allows all traffic (0.0.0.0/0) to ports 80 and 443
  • If provided: You can specify a custom security group to narrow down the allowed traffic sources for enhanced security
Proxy Configuration: When configuring HTTP/HTTPS proxy, NO_PROXY must include: .internal, 169.254.0.0/16, app.gitpod.io, and .amazonaws.com. Proxy Update Behavior:
  • Runner infrastructure: Changes take effect immediately after CloudFormation update
  • Component-specific timing:
    • Content initialization: Effective after environment restart
    • Devcontainer: Effective after rebuild
    • Docker in Docker: Effective after container recreation
Custom CA Certificate: Use CloudFormation dynamic references to retrieve certificates from AWS SSM Parameter Store. For syntax details, see SSM Parameter Store documentation.
Custom CA certificates work in runner, content init (SCM), and docker pull operations. However, they are not supported in devcontainer and devcontainer image build phases - you must add CA certificates to your images for these use cases.

​
Deploy

  1. Review all parameters
  2. Check the box acknowledging CloudFormation will create IAM resources
  3. Click Create stack
Deployment typically takes 20-25 minutes. Monitor progress in the CloudFormation Events tab.

​
Configure DNS

After deployment, get the load balancer DNS name from the CloudFormation Outputs tab (look for LoadBalancerDNS). Create DNS records pointing to this value for your domain.

​
Route 53

Create alias records pointing to your Network Load Balancer:
TypeNameAlias Target
Ayourdomain.comAlias to Network Load Balancer → your region → your load balancer
A*.yourdomain.comAlias to Network Load Balancer → your region → your load balancer
AWS Route 53 record creation showing alias configuration pointing to Network Load Balancer

Route 53 alias records

​
Other DNS providers

Create CNAME records pointing to your load balancer DNS:
TypeNameValueTTL
CNAMEyourdomain.cominternal-LoadBa-XXXXX-123456789.us-east-1.elb.amazonaws.com300
CNAME*.yourdomain.cominternal-LoadBa-XXXXX-123456789.us-east-1.elb.amazonaws.com300
DNS changes typically propagate within 5-60 minutes.

​
Verify deployment

Test connectivity from within your VPC: 
curl -k https://yourdomain.com/_health
nslookup yourdomain.com

​
Next steps