Networking Recommendations for Gitpod

To streamline and add flexibility to your Gitpod deployment, we’ve decoupled the networking from the application components. You can either utilize your current network setup—if it aligns with Gitpod’s specific requirements—or opt for our recommended networking configurations for guided assistance. This page is designed to clarify Gitpod’s necessities and match them with your needs, allowing you to make the best choice for your setup.

Navigate through the following decision flow to find the most suitable networking configuration for your Gitpod Enterprise deployment:

Option 1: Re-use an existing AWS Network (VPC, Subnets, etc.)

Requirements

1. Availability Zones

• To ensure high availability of Gitpod services, we require the usage of at least 2 Availability Zone or higher. This means that the VPC you are going to use to setup Gitpod should be spanning atleast across 2 Availability Zones of the region you are choosing for Gitpod

2. Subnet Separation

All chosen set of subnets should span across the chosen availability zones

Keeping in mind separation of concerns and efficient use of resources, logically we have separated our resources into 3 different subnets. Cloudformation template you will later use to deploy Gitpod Enterprise will require you to specify subnets in your VPC that you want to associate with these. You can choose to respect the separation or use the same subnets for all the 3 categories if you are setting up a Gitpod instance for non-production use. Here is are 3 subnets we expect:

1. Load Balancer Subnets
   • Purpose: Dedicated exclusively to hosting load balancers.
   • Design Rationale: The subnet type determines public accessibility. A private subnet secures the load balancer from direct public access, while a public subnet allows it.
   • Capacity Planning: Minimal IP allocation required due to hosting only two load balancers.
2. Main Subnets
   • Purpose: Accommodates the bulk of resources including RDS databases, Redis caches, two EKS clusters, and various Lambda functions.
   • Network Interaction: Requires connectivity to AWS services and the Gitpod control plane via AWS and Gitpod APIs.
   • Capacity Planning: Significant IP space needed, with at least a /24 CIDR block in each availability zone recommended.
3. Pod Subnets
   • Purpose: Utilizes AWS VPC CNI’s custom networking to facilitate pod creation in separate subnets.
   • Networking Mechanism: Pods operate through a secondary network interface, allowing for isolation from the main node network.
   • Capacity Planning: Expansive IP range allocation, using non-routable CIDR blocks (e.g., CGNAT ranges) is advisable.
   • Requirements Guess: Large IP space to accommodate numerous pods without requiring routability.

If you have a secondary allocation to your VPC with some non-routable IP ranges like CGNAT range, that is the perfect CIDR to create the Pod subnets with. The resources created in these subnets do not need any access from outside the network and uses EC2 nodes created in the Main subnets to do NAT traversal for outbound traffic.

3. Access to AWS Services

• Gitpod Enterprise utilizes several AWS Services effectively to efficiently deploy Gitpod and ensure the continued remote management and support of the same. Hence there should be access to several AWS services from all the subnets involved. Following are the AWS services we need access Gitpod needs access to:

Autoscaling                  CloudFormation
CloudWatch                   EC2
EC2messages                  ECR
ECR Api                      EKS
Elastic LoadBalancing        KMS
Kinesis Firehose             SSM
SSMmessages                  SecretsManager
Sts                          DynamoDB
S3

You can either use VPC endpoints or a NAT Gateways to access these services.

Gitpod Enterprise deploys several AWS Lambdas to the Main subnet for efficient management of Gitpod. When using NAT Gateways to access AWS Services, one should ensure that there is route from the Main subnet to NAT Gateways in the public subnet. Refer this AWS Guide to understand this requirement better.

4. Access to Gitpod Control Plane API Endpoint

Gitpod Control Plane API is hosted as a AWS Private API Gateway service. To be able to access this, you should have an execute-api VPC endpoint created in your VPC allowing HTTPS (port 443) communication for the entire VPC CIDR. The endpoint should span across all the availability zones being used by the VPC.

How to verify if your network is setup correctly

You can programmatically verify if the network is setup correctly by using our gitpod-network-check CLI tool that is a part of our Enterprise deployment toolkit. Please refer the README in the repo to use it.

Option 2: Create an AWS Networking setup using Gitpod Network CF templates

If you’re starting fresh without a pre-existing AWS network, or if your current setup doesn’t quite fit with Gitpod’s requirements, don’t worry—we’ve got you covered. Our aim is to make your network configuration process as straightforward as possible with the help of our CloudFormation templates, crafted to cater to diverse networking needs.

We offer two primary CloudFormation template options for your network setup:

• 1. Less Restrictive Network Configuration
  Our first option is a VPC configured with an Internet Gateway, which allows your Gitpod deployment to communicate with the internet. This template is designed with flexibility in mind, providing you with settings to control and limit access to your network as necessary. This is ideal if you require some level of internet access while maintaining control over your network traffic.

• 2. Completely Private Network Setup
  For those seeking a higher level of privacy and security, our second template is the way to go. It establishes a completely private VPC without an Internet Gateway or NAT Gateways. All external communications are routed through VPC endpoints, ensuring that your network remains isolated from the internet. This setup is perfect for organizations with strict security policies that require maximum privacy.

In the upcoming sections, we’ll explore the architecture of these networks in detail. Then, we’ll guide you through the process of deploying your chosen network configuration using the CloudFormation templates we provide. This will set the stage for a secure and efficient Gitpod deployment tailored to your organizational needs.

Open networking configuration (least restrictive)

• The VPC itself is spanned across 2 AZs and has 2 different CIDRs associated with it. Primary CIDR being 10.106.188.0/22 and secondary CIDR being the non-routable CGNAT CIDR 100.64.0.0/18
• This configuration has 3 different subnets spread across 2 availability zones in the VPC created
• With the smallest set of subnets, we associate NAT Gateways and Internet Gateway, essentially making it public and we call it the loadbalancer subnets
• This has quite a lot of implications:
  • The other two subnets will be able to access resources from the public Internet via the NAT Gateway and Internet Gateway of the public subnet
  • We can use this public subnets for the loadbalancers if you want your Loadbalancer to be accessible from the public internet (you can limit access via security groups)
  • Since we create AWS Lambdas in one of the subnets, if it has to access AWS resources via an NAT Gateway, it should be in a separate subnet that has route to the subnet with the NAT gateway
• The other two set of subnets are: main subnets and the pod subnets. The main subnets is the one uses the most of the primary CIDR. This is the CIDR where most of the important components in Gitpod deployment lives like EKS Clusters, databases, et. The pod subnet using exclusively the CGNAT CIDR range. This subnet will only be used for the pod network in the EKS clusters. Both these subnets can access resources and public internet via the NAT Gateway
• If you have internal resources that should be accessed from this network, there is also the provision to associate a transit gateway to the VPC and decide which all CIDR ranges should be accessed through this transit gateway from the Gitpod network

When should you choose this network?

• If you want a network with resource access via Internet Gateway
• Reduced usage cost
• If you want your Gitpod instance to be accessible from public Internet

How to use the Cloudformation template

Your Gitpod account manager will share with you a deep link URL, which you can click on to get to your AWS Cloudformation Console will prefilled template URL as follows:

• Clicking on Next, you will find the available configuration options in the template as parameters:

• If you don’t require any of the customizations listed, you can leave all the fields empty and continue via Next
• Click on Submit on the last page to stack deploying the networking configuration
• You will find the IDs of the resources created in the output of the stack as follows. These values will be necessary when deploying the Gitpod template.

Private networking configuration (highly restrictive)

• Like the above networking configuration, The VPC itself is spanned across 2 AZs and has 2 different CIDRs associated with it. Primary CIDR being 10.106.188.0/22 and secondary CIDR being the non-routable CGNAT CIDR 100.64.0.0/18
• This configuration has 2 different subnets spread across 2 availability zones in the VPC created
• The two set of subnets are: main subnets and the pod subnets. The main subnets is the one uses the most of the primary CIDR. This is the CIDR where most of the important components in Gitpod deployment lives like EKS Clusters, databases, et. The pod subnet using exclusively the CGNAT CIDR range. This subnet will only be used for the pod network in the EKS clusters.
• We create 15 VPC endpoints in the Main subnets to access all the necessary AWS Services and connect to the Gitpod control plane API endpoint
• The VPC is associated with a transit gateway ID that you provide which will be the only entry point to the network.

When should you choose this network?

• You want to build a highly restrictive networking allowing access only from your internal network

How to use the Cloudformation template

Your Gitpod account manager will share with you a deep link URL, which you can click on to get to your AWS Cloudformation Console will prefilled template URL as follows:

• Clicking on Next, you will find the available configuration options in the template as parameters:

• Click on Submit on the last page to stack deploying the networking configuration
• You will find the IDs of the resources created in the output of the stack as follows. These values will be necessary when deploying the Gitpod template.

• Make sure there is a route on your transit gateway route table that routes the connection to the VPC primary CIDR to the transit gateway attachment ID specified in the output. You can follow this AWS Guide to add this association.

If your transit gateway has auto-propagation enabled, you will see that the route to both of the CIDRs of the VPC are automatically propagated. The route to secondary CIDR (100.64.0.0/16) is unnecessary. Please feel free to delete this route.