To streamline and add flexibility to your Gitpod deployment, we’ve decoupled the networking from the application components. You can either opt for our recommended networking configurations for guided assistance or utilize your current network setup—if it aligns with Gitpod’s specific requirements. The transit gateway is your integration point for private ingress and/or egress for Gitpod-regardless of which option you choose. Some use cases are:
  • Exposing it to your VPN
  • Integrating with private SSO or SCM
  • Sharing private resources with developers for their workspaces, such as APIs, databases, file systems, or other resources
  • Granting Internet egress by relaying traffic through a NAT gateway and egress only internet gateway
  • Granting Internet egress by relaying traffic to a proxy server
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:

Networking flowchart

​
Option 1: 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)

Open Networking

  • 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:

Private Networking

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

Private Networking

Parameter NameDescriptionRequired
Primary CIDR for the VPCCIDR to be used as the primary CIDR range for the VPC. It has to be at least a block of CIDR with prefix /22 to meet the IP needs of the network. This is the range you may have to route from your transit gateway (Default range: 10.106.188.0/22 ).Yes
Transit Gateway IDIf you want Gitpod instance to access resources from your internal network (like SCM, SSO, etc.), then you can allow that by using AWS transit gateways. The transit gateway that provides access to your internal network can be attached to the VPC by providing the ID here. This is optional.No
CIDR to route Via the Transit GatewayIf you have provided a transit gateway ID, and have one CIDR range for internal resources, provide the IP range here.No
Prefix List ID containing CIDRs to route via the Transit GatewayIf you have provided a transit gateway ID, you have to also specify the CIDR ranges that should be access via this transit gateway. Create a prefix list, containing the IP ranges associated with your internal resources, and provide the prefix list ID here.No
  • 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

​
Private networking configuration (highly restrictive)

Private Networking

  • 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:

Private Networking landing

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

Private Networking paramas

Parameter NameDescriptionRequired
Primary CIDR for the VPCSince the Gitpod network will have to be routed to from your internal network, we make the primary CIDR of the network configurable. It has to be at least a block of CIDR with prefix /22 to meet the IP needs of the network (Default range: 10.106.188.0/22 ).Yes
Transit Gateway IDYou must associate your VPC with a transit gateway ID that will control the inbound and outbound communication from the VPC. All the traffic outside of the VPC will be routed via the transit gatewayYes
  • 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

  • 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.

​
Option 2: 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. We suggest the VPC primary CIDR be at least /22 or bigger.
  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 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 with Private DNS named enabled set to Yes, and 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.