Setup

Deploy your Enterprise AWS Runner using our enhanced CloudFormation template with custom ingress capabilities. This comprehensive guide walks you through the complete deployment process using the AWS Management Console.

​

Prerequisites

Before starting the deployment, ensure you have:

• Admin access to the Gitpod organization
• AWS Account with appropriate permissions to create CloudFormation stacks
• VPC and Subnets configured in your AWS account
• SSL/TLS Certificate provisioned in AWS Certificate Manager (ACM) with both root domain and wildcard subdomain SANs
• Domain Name that you control and can modify DNS records for
• Permissions to deploy CloudFormation stacks with IAM resources

​

Create Enterprise Runner in Gitpod

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 Gitpod.

​

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:

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

​

Gitpod Configuration

Core authentication and API connection settings for your Gitpod Runner.

⚠️ Important: These values are automatically generated by Gitpod when you create a Runner configuration. Do not modify these values manually.

​

Network Configuration (Mandatory)

VPC and subnet settings for deploying the Runner infrastructure.

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

​

Network Configuration (Optional)

Additional security group customization for load balancer traffic control.

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

​

DNS Configuration

Domain name, SSL certificate, and load balancer visibility settings.

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)

​

Review and Deploy

1. Review Configuration
   • Verify all parameters are correctly set
   • Review the resource summary
2. Acknowledge Capabilities
   • Check the box acknowledging that CloudFormation will create IAM resources
   • This is required for the stack to create necessary service roles
3. Create Stack
   • Click “Create stack” to begin deployment
   • Monitor the deployment progress in the Events tab

​

Monitoring Deployment

1. Stack Status
   • Monitor the stack status on the CloudFormation dashboard
   • Any errors will be displayed in the Events tab
2. 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:

1. Navigate to Outputs Tab
   • Click on your stack name
   • Go to the “Outputs” tab
2. Locate DNS Names
   • Find the output value: LoadBalancerDNS: internal-LoadBa-XXXXX-123456789.us-east-1.elb.amazonaws.com

​

Configure DNS Records

Create DNS records in your domain registry or DNS provider for the exact domain name you specified in the CloudFormation parameters:

​

Required DNS Records

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.

• 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

1. 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
2. DNS Resolution Test
   Copy

   Ask AI

   nslookup yourdomain.com
   nslookup test.yourdomain.com
   

​

Important Stack Outputs

After deployment, the following outputs provide important information for integration:

​

Next Steps

Once your Enterprise Runner is deployed, configure your repository access and Environment classes.