Getting Started with Gitpod Enterprise

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.

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.

For a successful Gitpod Enterprise configuration, follow the detailed guidelines provided in each section.

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.

When selecting an AWS account for deploying Gitpod Enterprise, ensure it meets two critical criteria:

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

2. Cross-Region Communication: The account must permit cross-account and cross-region communication with the eu-central-1 region. 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.

---

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:

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

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

If your network configuration does not meet these prerequisites or you don’t have a pre-existing networking setup, refer to the Networking Requirements and Setup for guidance and CloudFormation templates designed for various networking needs.

DNS and TLS Certificate Setup

For streamlined deployment processes, Gitpod furnishes a default domain name in the format .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)

Upon completion of your deployment, an additional action is required to finalize the DNS configuration: you must correctly associate the necessary subdomains with the corresponding load balancer DNS name. Further guidance on this process can be found in the section Complete DNS Setup.

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.