AWS Infrastructure
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.
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:
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:
- Verify security group configurations
- Check route table configurations
- Validate network ACL settings
- Confirm DNS resolution is working
- 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
Was this page helpful?