Setup and Preparation
Overview
This section is designed to guide you through the process of selecting an AWS account, choosing a region from Gitpod’s list of supported regions, and setting up the necessary resources for the Gitpod Enterprise installation. It’s here to ensure you have all the prerequisites in place before moving forward with the deployment.
When selecting an AWS account for deploying Gitpod Enterprise, ensure it meets two critical criteria:
You will need to have familiarity with AWS, specifically CloudFormation, in order to execute this guide. Please read through the entire guide or review it with your Gitpod engineer to ensure you understand all the requirements and steps.
Request template
Gitpod Enterprise Setup Requirements
Before starting your Gitpod Enterprise setup, ensure you meet the following requirements. Detailed instructions for each requirement are provided in the linked sections.- 1. AWS Account and Region Selection Select an appropriate AWS account and a supported AWS region for deploying Gitpod.
- 2. Networking Configuration Set up a working network configuration in your chosen account. We provide guidance to help you with this step.
- 3. Optionally setting up a domain name and TLS certificate Gitpod deployment automatically assigns a default domain, but you can opt for a custom domain by selecting one and securing the necessary TLS certificate.
- 4. SSO Application Create an SSO application for Gitpod login post-setup. This is essential for enabling secure access to your Gitpod installation.
AWS Account and Region
1. Choosing the AWS Account
For pre-production (e.g. proof of concept) installations, it is acceptable to use an existing AWS account. Using an empty AWS account removes risks of existing resources interfering with the Enterprise installation, please speak to your Gitpod account manager for more information. For a production installation, Enterprise requires an empty AWS account as the account acts as a security and responsibility boundary.
- Resource Quota Limits: Your account must have the required resource quota limits available. Below is a table detailing the necessary quotas. Adjust these values based on your specific requirements.
Please follow AWS official guide to increase the quota requests
| Service | Name | Value | Reasoning |
|---|---|---|---|
| Amazon Elastic Compute Cloud (Amazon EC2) - vCPU limit | Running On-Demand Standard (A, C, D, H, I, M, R, T, Z) Instances | 256 | The vCPU value depends on the number of concurrent developers using the instance. 256 is the minimum recommended setting and is suitable for proof-of-value trials. Consult with your engineer on an appropriate setting for your expected usage levels. Each workspace node consumes 36 vCPUs. So calculate accordingly |
| Amazon Elastic Block Store (Amazon EBS) - storage | Storage for General Purpose SSD (gp3) volumes, in TiB | 10 | The default is 50 (or more, depending on region), and is more than acceptable for proof-of-value trials. At a minimum, 10 is needed to support 256 vCPU. Consult with your engineer on an appropriate setting for your expected usage levels. Every 36 vCPU requires 1 TiB of storage. |
| AWS Lambdas - concurrent executions | Concurrent executions | 30 | The default is 1,000, and is more than acceptable for proof-of-value trials. 30 is required for Lambdas to interact with your account and the Gitpod Enterprise control plane. |
-
Cross-Region Communication: The account must permit cross-account and cross-region communication with the
eu-central-1region. This is crucial as our control plane, which delivers regular updates, is located in this region. Make sure you have no SCPs denying this communication. For more information about our control plane and regular updates follow Architecture section. -
AWS account for Gitpod AMIs: The account must allow EC2 instances to use AMI from AWS account ID
995913728426. It is exclusively used for Gitpod Enterprise AMI. Make sure you have no SCPs denying related usage. Gitpod distributes new AMI to ship fixes, new features, and security updates.
2. Selecting the AWS Region
After choosing your AWS account, the next step is to select an appropriate AWS region based on the following criteria:- Availability Zones: The region should have at least 2 Availability Zones (AZs), though we recommend 3 AZs for production use cases to ensure high availability.
- Supported Regions: Ensure the region is among those supported by Gitpod Enterprise. Our supported regions are designed to provide the best balance of performance and availability for your Gitpod installation Additionally, please communicate the AWS account ID and the region you’ve chosen to your Gitpod account manager. This step is vital for ensuring seamless integration and support throughout the setup process.
Network Setup Requirements
A proper network setup is crucial for the successful deployment and operation of Gitpod Enterprise. The requirements include:- Availability Zones: Your AWS VPC should span at least two Availability Zones for high availability.
- Subnet Configuration: You should have at least two sets of subnets across these Availability Zones, each with a minimum size of /24. This setup supports a separation of resources, with one set primarily for the cluster’s resources and another for pods or workspaces. It is recommended that the latter employs a non-routable range, such as CGNAT.
- Service Access: Ensure access from all subnets to several AWS services and the SCM and SSO services you plan to use. This access can be facilitated through a VPC endpoint or a NAT gateway. For detailed service requirements, see the Networking Requirements and Setup section.
DNS and TLS Certificate Setup
For streamlined deployment processes, Gitpod furnishes a default domain name in the format<your-chosen-instance-name>.gitpod.cloud. During the deployment of Gitpod, an SSL certificate is automatically generated on your behalf via the AWS Certificate Manager.
Should you opt to utilize a custom domain name, you have the option to disable the automatic certificate generation during deployment by adjusting the relevant parameters. Subsequently, you may supply your preferred domain name and SSL certificate. Below are the necessary details for configuring your SSL certificate:
- Certificate Source: The certificate must be provisioned via the AWS Certificate Manager (ACM).
- Account and Region Consistency: Ensure the certificate is created within the same AWS account and region selected for the Gitpod deployment, as AWS does not support cross-account or cross-region sharing of certificates.
- Subject Alternative Names (SANs): The certificate should cover the following SANs:
yourgitpoddomain.com*.yourgitpoddomain.com*.ws.yourgitpoddomain.com(required since the above entry does not include second-level subdomains)
SSO Application
- Set Up an SSO Application: Integration with an SSO application is required post-setup for Gitpod. This could be AWS Cognito, Okta, Google SSO, etc. It’s advisable to prepare this in advance, as obtaining or configuring an SSO application may take some time. For additional details, link to the SSO Setup section.