Apply Cloudformation templates

Gitpod is deployed through Cloud Formation templates. They set up Kubernetes clusters and other essential AWS resources like lambdas and databases. They facilitate not just the deployment but also enable remote management capabilities for your Gitpod environment. You can read more about this in the Architecture section. Due to specific permission requirements for installing Gitpod, we provide a preliminary template to set up a role with the necessary permissions. This role is then used when configuring the main Gitpod template. Therefore, deploying Gitpod involves two main steps:

Step 1: Role Creation

To start, click on the first deep link URL to launch the role creation template. This action opens the AWS CloudFormation console to the welcome screen for setting up the template.

Parameters in the Role Creation Template

This template includes two configurable options:

• Add Route 53 management permissions to the role: If you plan to manage your DNS settings manually, you can opt to disable this option and not add Route53 specific permissions to the role.
• Enable Public API Gateway Permissions: This option should be considered based on how you intend to use Gitpod. If Gitpod is to be set up without public internet access, but you require GitHub webhooks and Identity Provider (IDP) features to be publicly accessible (e.g., for integration with a public SCM), then you will need to enable this feature in the main Gitpod CF template. Selecting “Yes” here ensures the necessary permissions are established.

After configuring these parameters to suit your deployment needs, proceed to apply the template. Upon completion, the output section will display the name of the created role.

You can inspect this role further by visiting the IAM console.

Step 2: Deploying the Gitpod Instance

With the necessary role in place, the next step involves applying the main Gitpod deployment template. This section will guide you through the process, highlighting how to select the role created in the previous step and configure additional parameters for your Gitpod setup.

As you did with the role deep link URL, click and launch the gitpod instance creation template. You should land on a welcome screen that looks like this:

Parameters in the Instance Creation Template

The deployment template includes numerous parameters, providing significant control over the configuration. These parameters are divided into sections on the page, which we will address section by section.

Networking Configurations

Please refer to the Network Setup to understand the networking requirements and/or to create the network using our standard CF templates

This section focuses on configuring the network settings for your Gitpod setup, including VPC selection, subnet configurations, and load balancer options.

Creating a managed prefix list to control traffic to loadbalancer

Creating a managed prefix list to control traffic to loadbalancer

1. In the AWS Account in which you are deploying Gitpod Enterprise instance, go to the Managed prefix list console under the VPC services:

2. Click on Create Prefix List at the top right corner of the page

2. Give the Prefix list an appropriate name, choose the maximum number of CIDRs. The maximum number of CIDRs should be less that your account’s rule per security group limit, which is by default 60 but more than the number of CIDRs you want to specify. Add the CIDRs using the Add new entry option.

3. Copy the ID of the Managed prefix list and use it directly as the value for cloudformation parameter Loadbalancer Access Prefix List ID

DNS Configuration

For a seamless experience, Gitpod can manage a DNS name and corresponding certificate within our *.gitpod.cloud domain. Alternatively, you may opt to configure your own domain and match it with an ACM-stored certificate.

Important: The certificate must include SANs that match your specific domain name, if your chosen domain name is yourdomainname.com , the the certificate should cover:
yourdomainname.com
ws.yourdomainname.com
*.yourdomainname.com
*.ws.yourdomainname.com

If you decide to self-manage DNS, you’ll receive domain mapping information in the setup output, which should be added to Route 53 or your DNS management service. More about this will be covered in the Complete DNS Configuration section.

Note: If you’re using the auto-generated domain by setting auto-generation to “Yes,” ensure you’ve also selected “Yes” for the parameter Add Route 53 management permissions to the role? in the role creation template. If this wasn’t set initially, please update the role template to align with your DNS configuration choice.

Below are the parameters for DNS configuration:

Application Settings (Optional)

This optional section allows for specifying custom CA certificates and proxy settings for your Gitpod workspaces. While these settings offer additional customization for specific scenarios, they are not required for all installations.

• Additional Custom CA: If Gitpod needs to interact with resources that use a Custom CA (e.g., Source Control Management systems), you can specify the ARN of the secret where the certificate is stored. For guidance on using custom or private CAs with Gitpod, refer back to our documentation in the preparation section.

• Proxy Settings: Set the HTTP and HTTPS proxy URLs that the workspaces should use, as well as URLs that should bypass the proxy. These are set as environment variables within the pods of the Gitpod installation.

Remember, these settings are optional and should only be configured if your workspace environments require them.

Advanced Configuration (Optional)

This section contains settings for specific scenarios that might not be essential for every Gitpod instance but are critical for certain use cases, particularly if your deployment has unique requirements.

These advanced configurations offer you the ability to tailor your Gitpod setup more closely to your operational needs. If your VPC is private or has restricted access from the public internet, you will find the settings here especially relevant.

• Expose Gitpod Services Publicly

Important: This setting is particularly relevant if your VPC is private or restricts public internet access. It ensures that even with stringent network controls, essential Gitpod services remain accessible as needed.

When you enable this, a public API gateway will be established, allowing webhooks and IDP services to be accessed publicly, despite the VPC being private or internet-restricted. It is essential to configure this correctly for your Gitpod services to function as intended in a restricted network setup. It is required that you have selected Enable Public API Gateway Permissions in the role creation template otherwise the role we use to apply the cloud formation template will not have the required permissions.

Choosing the right role for the stack execution

After choosing the right parameters based on your requirements, before proceeding to apply the CF template, we should choose the role that was created by the previous CF template to execute the current one. To do so, hit the Next button once you have chosen all the required parameters and you will end up in a page that looks like below:

Choose the IAM Role that you found in the output of the role CF template from the dropdown. If you don’t see the role there, try pressing the refresh icon to the side to get an updated list of roles. Once you have chosen this, you can proceed to apply your CF template, by continuing to the next page, checking the acknowledgement box and clicking Submit.

Next Steps

The CF stack apply should take around 30 minutes to complete

Once the stack creation completes, you will see a stack output that looks like this

To complete your setup, go ahead and ensure that you complete the DNS setup pointing the loadbalancer endpoints to the corresponding subdomains and making sure you do any extra routing requirements as needed:

If you have chosen auto-configured DNS name and have no more routing requirements, you can get in touch with your Gitpod account manager who should generate an admin URL for your setup and you should be able to proceed to Configuring your instance.

Completing DNS Setup

Learn how to finalize your DNS configuration, ensuring that your Gitpod instance is accessible and secure.

Using Private VPC Resolvers

Explore how to utilize private VPC resolvers within Gitpod for enhanced networking and connectivity.