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,

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.

Sharing a runner

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:

EndpointPurposeProtocolPortDirection
app.gitpod.ioGitpod Service (management plane)HTTPS443Outbound
*.us01.gitpod.devGitpod Service (gateway)HTTPS8443Outbound
35.171.240.32Gitpod Service (gateway)UDP4242Outbound
public.ecr.awsContainer imagesHTTPS443Outbound
*.amazonaws.comAWS API callsHTTPS443Outbound
SCM ServicesSource code repositoriesHTTPS443Outbound
(optional) Prometheus Remote writeMetrics endpointHTTPS443Outbound
(optional) Container RegistriesCustom container registriesHTTPS443Outbound

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
  • 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 ServiceEndpoint TypeRequired For
Amazon S3GatewayStoring and retrieving artifacts
Amazon ECRInterfaceContainer image access
Amazon CloudWatch LogsInterfaceLogging
Amazon ECSInterfaceContainer orchestration
AWS Systems ManagerInterfaceParameter management
AWS Secrets ManagerInterfaceSecure credential storage
Amazon DynamoDBGatewayRunner 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 NameOwner Account IDOwnerPurpose
bottlerocket-aws-ecs-1-x86_64149721548608AmazonRunner service
gitpod/images/gitpod-next/ec2-runner-ami-995913728426GitpodDevelopment 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