Deploy your Enterprise AWS Runner using the enhanced CloudFormation template with custom ingress capabilities.
Prerequisites Before starting the deployment, ensure you have:
Admin access to your Ona organizationAWS Account with appropriate permissions to create CloudFormation stacksVPC and Subnets configured in your AWS accountSSL/TLS Certificate provisioned in AWS Certificate Manager (ACM) with both root domain and wildcard subdomain SANsDomain Name that you control and can modify DNS records forPermissions to deploy CloudFormation stacks with IAM resources
Create Enterprise Runner in Ona Go to Settings -> Runners, and press Setup a new runner :
After choosing AWS from the list of available providers, continue with the Enterprise Runner template .
Choose the Enterprise Runner template , provide 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.
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:
Most parameters are auto-filled already. The template is organized into several parameter groups and has to be filled out carefully.
Ona configuration Core authentication and API connection settings for your Runner.
Parameter Description Required Runner ID Unique identifier for your Runner (auto-generated) ✅ Yes Exchange Token Authentication token for the EC2 Runner (auto-generated) ✅ Yes API Endpoint URL of the API (auto-generated) ✅ Yes
⚠️ Important : These values are automatically generated when you create a Runner configuration. Do not modify these values manually.
Network configuration (required) VPC and subnet settings for deploying the Runner infrastructure.
Parameter Description Example Value Required VPC The VPC where the Runner will be deployed vpc-12345abcd✅ Yes Availability Zones AZs for high availability (select 2-3) us-east-1a, us-east-1b✅ Yes EC2 Instances Subnet Private subnets for EC2 instances (can be non-routable from internal network). Should match the number of AZs subnet-123abc, subnet-456def✅ Yes Loadbalance Subnets Subnets for load balancer with CIDR ranges routable from your internal network. Should match the number of AZs subnet-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 workloadLoad balancer subnets : Must have CIDR ranges routable from your internal network for user accessEnsure connectivity from user locations via VPN, Direct Connect, or Transit Gateway
DNS configuration Domain name, SSL certificate, and load balancer visibility settings.
Parameter Description Example Value Required Load Balancer Visibility Choose between internal or internet-facing internal✅ Yes Domain Name Your domain name for access yourdomain.com✅ Yes Certificate ARN ARN of your SSL certificate from ACM arn: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) Configure additional network settings for enterprise security requirements.
Parameter Description Example Value Required Custom Security Group for Load Balancer Security group to attach to the load balancer for traffic control sg-abcdef123❌ Optional HTTP Proxy HTTP proxy server URL http://proxy.company.com:8080❌ Optional HTTPS Proxy HTTPS proxy server URL https://proxy.company.com:8080❌ Optional No Proxy Comma-separated list of hosts to bypass proxy .internal,169.254.0.0/16,...⚠️ Required if proxy configured Custom CA Certificate Custom certificate authority bundle See Custom CA Certificate below ❌ 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 443If 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 updateComponent-specific timing :
Content initialization: Effective after environment restart
Devcontainer: Effective after rebuild
Docker in Docker: Effective after container recreation
Custom CA Certificate The CustomCATrustBundle parameter accepts three formats:
Format Example Value When to use S3 URL (recommended)s3://gitpod-myorg/shared/ca-bundle.pemBest for large bundles or bundles with multiple certificates HTTPS URL https://internal-server.example.com/ca-bundle.pemWhen the bundle is hosted on an internal web server SSM dynamic reference {{resolve:ssm:/ona/ca-cert}}Only for small single certificates (see warning below)
S3 URL (recommended) Store your CA bundle in S3 and reference it by URL. This avoids the EC2 user data size limit and is the recommended approach for bundles with multiple certificates.
Create an S3 bucket with a name starting with gitpod- (e.g. gitpod-myorg)
Create a shared folder and upload your .pem file:
s3://gitpod-myorg/shared/ca-bundle.pem
Ensure the bucket is accessible by the runner’s IAM role (buckets prefixed with gitpod- are allowed by default)
Set the CustomCATrustBundle parameter to the S3 URL
HTTPS URL If your CA bundle is hosted on an internal web server accessible from the runner’s VPC:
https://internal-pki.example.com/ca-bundle.pem
SSM Parameter Store Use CloudFormation dynamic references to retrieve certificates from AWS SSM Parameter Store. For syntax details, see SSM Parameter Store documentation.
{{resolve:ssm:/ona/ca-cert}}
SSM dynamic references embed the full certificate content into EC2 user data, which has a 16 KB limit. If your CA bundle contains multiple certificates, this can exceed the limit and cause environment creation to fail with "User data is limited to 16384 bytes". Use an S3 URL instead.
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.
Review and Deploy
Review Configuration
Verify all parameters are correctly set
Review the resource summary
Acknowledge Capabilities
Check the box acknowledging that CloudFormation will create IAM resources
This is required for the stack to create necessary service roles
Create Stack
Click “Create stack” to begin deployment
Monitor the deployment progress in the Events tab
The CloudFormation stack deployment typically takes 20-25 minutes.
Monitoring Deployment
Stack Status
Monitor the stack status on the CloudFormation dashboard
Any errors will be displayed in the Events tab
Event Monitoring
Click on the “Events” tab to see real-time deployment progress
Post-Deployment DNS Configuration Retrieve Load Balancer DNS Name After successful deployment:
Navigate to Outputs Tab
Click on your stack name
Go to the “Outputs” tab
Locate DNS Names
Find the output value: LoadBalancerDNS : internal-LoadBa-XXXXX-123456789.us-east-1.elb.amazonaws.com
Create DNS records in your domain registry or DNS provider for the exact domain name you specified in the CloudFormation parameters.
AWS Route 53 If you’re using AWS Route 53 to manage your domain, use alias records for the most AWS-native configuration:
Navigate to Route 53 Console
Create Alias Records
Click “Create record”
Toggle the Alias switch to enable alias functionalityConfigure the following records:
Type Name Alias Target A yourdomain.comSelect “Alias to Network Load Balancer” → Choose your region → Select your load balancer A *.yourdomain.comSelect “Alias to Network Load Balancer” → Choose your region → Select your load balancer
Advantages of Route 53 Alias Records:
No additional charges for alias queries
Automatic health checking
Better performance with shorter resolution times
AWS-native integration with load balancers
Standard DNS Providers (CNAME Records) For other DNS providers or if you prefer CNAME records:
Type Name Value TTL CNAME yourdomain.cominternal-LoadBa-XXXXX-123456789.us-east-1.elb.amazonaws.com300 CNAME *.yourdomain.cominternal-LoadBa-XXXXX-123456789.us-east-1.elb.amazonaws.com300
Example DNS Configuration: If you entered yourdomain.com as your domain name parameter, configure:
yourdomain.com. CNAME internal-LoadBa-XXXXX-123456789.us-east-1.elb.amazonaws.com. *.yourdomain.com. CNAME internal-LoadBa-XXXXX-123456789.us-east-1.elb.amazonaws.com.
⚠️ Important : Replace yourdomain.com with the exact domain name you entered in the CloudFormation parameters.
DNS changes typically propagate within 5-60 minutes
You can verify DNS resolution using tools like nslookup or dig
Test both the root domain and a wildcard subdomain
Verification and Testing
Internal Network Test
Verify that the load balancer is accessible from within your VPC
Test from an EC2 instance in the same VPC: curl -k https://yourdomain.com/_health
DNS Resolution Test
nslookup yourdomain.com nslookup test.yourdomain.com
Important Stack Outputs After deployment, the following outputs provide important information for integration:
Output Name Description Usage LoadBalancerDNS Network Load Balancer DNS name Point your DNS records here EnvironmentRoleArn EC2 Environment Role ARN Used by Ona Environments for all operations InstanceProfileNameOutput EC2 Instance Profile Attached to Runner EC2 instances
Private VPC Endpoints (Optional) For enhanced security, you can connect to AWS services using AWS PrivateLink VPC endpoints instead of traversing the public internet. This provides private connectivity between your runner and AWS services.
For a complete list of required VPC endpoints, configuration instructions, and troubleshooting guidance, see the VPC Endpoints documentation .
Next steps Once your Enterprise Runner is deployed, configure your repository access and Environment classes .
Configure Repository Access Set up access to your repositories
Troubleshoot Resolve common issues including networking problems and Runner configuration
