Planning your AWS infrastructure for Gitpod requires careful consideration of your organization’s network requirements and future growth. This guide helps you plan the required AWS account, regions, availability zones, and subnets for your deployment.

When planning your AWS infrastructure, consider these key objectives:

• Identify regions that offer optimal latency for your users
• Plan network capacity based on anticipated user count and growth
• Ensure system robustness through strategic availability zone selection
• Minimize future infrastructure changes by planning for scale

We’ll create a planning table that will serve as input to set up AWS Account and Networking.

​

Quick start: Standard Capacity

For a basic setup (single runner, single region, fewer than 1000 users):

1. Select your region based on the recommended latency
2. Use the following configuration:

If the Standard Capacity is sufficient for your needs, feel free to skip the rest of this chapter and proceed to Setup the AWS Infrastructure.

​

Example Planning Table

The following table demonstrates how to plan your AWS Runner infrastructure. We’ll use this format to help you plan your specific deployment.

Table Column Definitions

• Runner Name: Choose a meaningful identifier for your runner
• Users: Maximum number of users expected to use the runner, including planned growth
• Region: AWS region where the runner will be deployed
• Number of AZs: Number of Availability Zones for the runner deployment
• Size per Subnet: CIDR block size for each subnet (one subnet per AZ)
• Capacity: Maximum number of dev environments the runner can support.

​

Your Planning Table

Please create your own table and fill in the columns with your values.

​

Infrastructure Considerations

Before creating your planning table, consider these important points:

• Gitpod AWS Runners can share AWS accounts, VPCs, regions, and subnets with other AWS runners
• Runners operate independently and can be deployed across multiple AWS accounts and VPCs
• For multiple runners, you can (but don’t have to) use separate AWS accounts
  • If using multiple AWS accounts, add an “AWS Account” column to your planning table

​

Step 1: Select Regions

Gitpod supports multiple runners that can be added or removed as needed. However, it’s important to plan your regions carefully as you’ll need appropriately sized subnets in each region.

Choose one or more AWS Regions that provide the best latency for your users.

​

Step 2: Estimate Users per Region

For each selected region, estimate the maximum number of users, considering:

• Current number of users
• Expected growth over time
• Peak usage patterns
• Geographic distribution of your team

​

Step 3: Determine Availability Zones

Each AWS Runner requires at least one Availability Zone (AZ) and can utilize all AZs within a region. Key points:

• One subnet is required per AZ
• We recommend using 2-3 AZs per region for optimal availability
• More AZs provide better fault tolerance but increase complexity
• Consider your organization’s high availability requirements

​

Step 4: Plan Subnet Sizes

When planning your subnets, consider:

• Each environment requires one IP address
• Each AZ requires one subnet
• Management services need fewer than five IP addresses
• Environments run as EC2 instances and require routable subnets
• Gitpod does not use Network Address Translation (NAT) for environments
• The minimum subnet size is /28 (supports 10 environments)
• If multiple runners share subnets, they share the available IP address pool
• Maximum capacity = (Total subnet IPs × Number of AZs) - Management IPs
• Note that it’s best practice to choose subnet sizes generously, as expanding a subnet later can be more complex and costly than planning for growth upfront