Before installing Gitpod Runners on AWS, you need to prepare your AWS infrastructure. This guide walks you through the account setup and networking configuration.

​

Quick Start: Using the Default VPC

The fastest way to get started is to use the default VPC provided by AWS. It comes pre-configured with all necessary components:

• Internet gateways
• Route tables
• Subnets across multiple Availability Zones

If you’re using the default VPC,

• you can skip the Capacity Planning.
• you can skip the rest of this chapter and proceed directly to Setting up an AWS runner.

​

AWS Account Setup

You can use either an existing AWS account or create a new one. When using an existing account, ensure no running services will conflict with Gitpod.

Before proceeding, complete the Capacity Planning to create your planning table.

​

Network Configuration

Gitpod requires specific network configurations to communicate with Gitpod services and to launch and manage environments. The following sections outline the requirements in detail.

​

Network Connectivity Requirements

​

Inbound Requirements

• Port 22999 (TCP) must be open for SSH access to development environments
• Configure security groups to allow this traffic to EC2 instances

​

Outbound Requirements

Your subnets must have outbound access to these endpoints:

Endpoint	Purpose	Protocol	Port	Direction
app.gitpod.io	Gitpod Service (management plane)	HTTPS	443	Outbound
*.us01.gitpod.dev	Gitpod Service (gateway)	HTTPS	8443	Outbound
35.171.240.32	Gitpod Service (gateway)	UDP	4242	Outbound
public.ecr.aws	Container images	HTTPS	443	Outbound
*.amazonaws.com	AWS API calls	HTTPS	443	Outbound
SCM Services	Source code repositories	HTTPS	443	Outbound
(optional) Prometheus Remote write	Metrics endpoint	HTTPS	443	Outbound
(optional) Container Registries	Custom container registries	HTTPS	443	Outbound

​

Internal Communication

• Gitpod Runner connects to environments on port 22999 (HTTP)
• Clients connect to Environments on port 29222 (SSH)
• Gitpod Runner ECS task performs internal HTTP healthcheck on port 9090

​

Deployment Options

​

1. Public Subnet Configuration

• Place Gitpod in a public subnet with an Internet Gateway
• Ensure proper security group rules are in place

​

2. Private Subnet Configuration (Recommended for Production)

• Place Gitpod Runner in a private subnet
• Configure a NAT Gateway in a public subnet
• Ensure the route table directs outbound traffic through the NAT Gateway
• Consider using VPC endpoints for AWS services
• Optionally connect through a Transit Gateway with internet access

​

VPC Endpoints (Optional)

To reduce data transfer costs and improve security, you can use VPC endpoints for AWS services:

AWS Service	Endpoint Type	Required For
Amazon S3	Gateway	Storing and retrieving artifacts
Amazon ECR	Interface	Container image access
Amazon CloudWatch Logs	Interface	Logging
Amazon ECS	Interface	Container orchestration
AWS Systems Manager	Interface	Parameter management
AWS Secrets Manager	Interface	Secure credential storage
Amazon DynamoDB	Gateway	Runner state management

Note: Even with VPC endpoints, outbound internet access to Gitpod services and public ECR is still required.

​

Security Group Configuration

The CloudFormation template creates a default security group with:

• All egress traffic allowed
• Ingress from any IP on port 22999
• Ingress from runner security group on port 29222

For custom security groups, ensure:

Inbound Rules:

• Allow port 29222 for user access to environments
• Allow internal VPC traffic on port 22999 for runner communication

Outbound Rules:

• Allow HTTPS (443) to app.gitpod.io
• Allow HTTPS (8443) to *.us01.gitpod.dev
• Allow UDP (4242) to *.us01.gitpod.dev
• Allow access to required development services
• Allow necessary internet access

​

Infrastructure Components

​

1. Subnets

Create subnets according to your capacity plan:

• Create all subnets in the same AWS account and VPC, unless specifically required otherwise
• Follow the sizes determined in your capacity planning

​

2. IAM Role (Optional)

If you want to apply the CloudFormation template with a specific role, create an IAM role with permissions to access the required AWS services.

​

3. AMI Access

If your AWS Organization has restricted access to AMIs, ensure your AWS account can launch EC2 instances from these AMIs:

AMI Name	Owner Account ID	Owner	Purpose
bottlerocket-aws-ecs-1-x86_64	149721548608	Amazon	Runner service
gitpod/images/gitpod-next/ec2-runner-ami-	995913728426	Gitpod	Development environments

Gitpod updates AMIs regularly. We recommend allowing access by Owner Account ID rather than AMI ID when implementing allowlisting.

​

Troubleshooting Network Issues

If you experience connectivity issues:

1. Verify security group configurations
2. Check route table configurations
3. Validate network ACL settings
4. Confirm DNS resolution is working
5. Test connectivity to Gitpod services

​

Required AWS Services

Gitpod runners require the following AWS services to be available in your deployment regions:

Core Infrastructure

• EC2: For launching instances in your VPC and subnets
• ECS: With Fargate support for running containerized tasks
• IAM: For access control and permissions
• CloudFormation: For infrastructure deployment

Storage and State Management

• S3: For container images and artifacts
• DynamoDB: For resource information storage

Monitoring and Security

• CloudWatch Logs: For ECS and EC2 instance logging
• Secrets Manager: For sensitive information storage
• Systems Manager (SSM): For configuration management via Parameter Store