> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Frame caption="Role template landing page">
  <img src="https://mintcdn.com/gitpod-13c83c2b/1T56zcBWQ3jfH-V2/images/enterprise/role-cf-template-landing.png?fit=max&auto=format&n=1T56zcBWQ3jfH-V2&q=85&s=d841ddf0c7ce51f56e7842f96c21fd5a" width="1600" height="709" data-path="images/enterprise/role-cf-template-landing.png" />
</Frame>

### Parameters in the Role Creation Template

<Frame caption="Role template parameters">
  <img src="https://mintcdn.com/gitpod-13c83c2b/1T56zcBWQ3jfH-V2/images/enterprise/role-template-parameters.png?fit=max&auto=format&n=1T56zcBWQ3jfH-V2&q=85&s=d6cc38ff9ee528bce52ab6e40d468f8a" width="3580" height="1588" data-path="images/enterprise/role-template-parameters.png" />
</Frame>

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.

<Frame caption="Role template output">
  <img src="https://mintcdn.com/gitpod-13c83c2b/1T56zcBWQ3jfH-V2/images/enterprise/role-output.png?fit=max&auto=format&n=1T56zcBWQ3jfH-V2&q=85&s=b7a28b38be188bd84bb1278029bc3143" width="2482" height="864" data-path="images/enterprise/role-output.png" />
</Frame>

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

<Frame caption="Role details in IAM Console">
  <img src="https://mintcdn.com/gitpod-13c83c2b/1T56zcBWQ3jfH-V2/images/enterprise/role-iam-console.png?fit=max&auto=format&n=1T56zcBWQ3jfH-V2&q=85&s=667dda30a06d8a4d78ca3b60abd23335" width="3272" height="1550" data-path="images/enterprise/role-iam-console.png" />
</Frame>

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

<Frame caption="Instance template landing page">
  <img src="https://mintcdn.com/gitpod-13c83c2b/1T56zcBWQ3jfH-V2/images/enterprise/instance-cf-template-landing.png?fit=max&auto=format&n=1T56zcBWQ3jfH-V2&q=85&s=5127a925061ad9d1c4efa66fd902be8e" width="3598" height="1571" data-path="images/enterprise/instance-cf-template-landing.png" />
</Frame>

### 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

<Note>
  {' '}

  Please refer to the [Network Setup](/classic/admin/getting-started/networking) to
  understand the networking requirements and/or to create the network using our
  standard CF templates
</Note>

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

<Frame caption="Instance template networking configurations">
  <img src="https://mintcdn.com/gitpod-13c83c2b/1T56zcBWQ3jfH-V2/images/enterprise/instance-parameter-network-config.png?fit=max&auto=format&n=1T56zcBWQ3jfH-V2&q=85&s=1bb55999e9585eb8e6fae313f75ae406" width="3152" height="1233" data-path="images/enterprise/instance-parameter-network-config.png" />
</Frame>

| Parameter Name                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Required |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| Availability Zones                 | Select all the availability zones supported by the VPC. There should be at least 2.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Yes      |
| VPC                                | The ID of the VPC.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Yes      |
| Main Subnets                       | Primary subnet used by the installation. The clusters, databases, management lambdas etc. will be created here. Should match the number of AZs chosen. At least a /24 per AZ would be necessary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Yes      |
| Pod Subnets                        | Subnets for the pods in the Kubernetes clusters to use, should match the number of AZs chosen (**Can be same as Main Subnets** - but we recommend each of these being a /18 for prod use and no routing from external services are expected).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Yes      |
| Loadbalancer Subnets               | Subnets for the loadbalancer creation, Selection should match the availability zones chosen (**can be same as Main Subnets**).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Yes      |
| Loadbalancer Visibility Type       | What kind of load balancer should be created? Choose internet-facing only if your loadbalancer subnets are public.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Yes      |
| Loadbalancer Access Prefix List ID | This parameter identifies the managed prefix list containing CIDR blocks allowed to access the load balancer. A [managed prefix list in AWS](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-managed-prefix-lists.html) is a reusable set of CIDR blocks centrally managed to simplify network access control across VPCs, security groups, and route tables. To provide maximum flexibility and privacy, we let you manage the allowed loadbalancer traffic via a prefix list that you can manage separately. The security group of loadbalancer will allow traffic only from this prefix list. Follow [this](#creating-a-managed-prefix-list-to-control-traffic-to-loadbalancer) section below to see a step-by-step guide to create this. **Change for existing installations requires collaboration with Gitpod during an outage window. After the CloudFormation update is complete, during cleanup, Gitpod must then trigger an update to honor changed security groups.** | No       |

<br />

<Accordion title="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:

  <Frame caption="Managed prefix-list lookup">
    <img src="https://mintcdn.com/gitpod-13c83c2b/1T56zcBWQ3jfH-V2/images/enterprise/managed-prefix-list-lookup.png?fit=max&auto=format&n=1T56zcBWQ3jfH-V2&q=85&s=c91e4af130d1d902abf0e5e124bd45c7" width="1656" height="1268" data-path="images/enterprise/managed-prefix-list-lookup.png" />
  </Frame>

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

  <Frame caption="Managed prefix-list dashboard">
    <img src="https://mintcdn.com/gitpod-13c83c2b/1T56zcBWQ3jfH-V2/images/enterprise/managed-prefix-list-dashboard.png?fit=max&auto=format&n=1T56zcBWQ3jfH-V2&q=85&s=e8460e70c8ad229a3cf28a355db7e4d0" width="3892" height="954" data-path="images/enterprise/managed-prefix-list-dashboard.png" />
  </Frame>

  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.

  <Frame caption="Managed prefix-list create">
    <img src="https://mintcdn.com/gitpod-13c83c2b/1T56zcBWQ3jfH-V2/images/enterprise/managed-prefix-list-create.png?fit=max&auto=format&n=1T56zcBWQ3jfH-V2&q=85&s=920e5c54107ca89381bfa3ece3a0cd73" width="1403" height="1385" data-path="images/enterprise/managed-prefix-list-create.png" />
  </Frame>

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

  <Frame caption="Managed prefix-list create">
    <img src="https://mintcdn.com/gitpod-13c83c2b/1T56zcBWQ3jfH-V2/images/enterprise/managed-prefix-list-copy.png?fit=max&auto=format&n=1T56zcBWQ3jfH-V2&q=85&s=3efde52b96ba46d5d0c5605a1f709014" width="3805" height="1237" data-path="images/enterprise/managed-prefix-list-copy.png" />
  </Frame>
</Accordion>

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

<Warning>
  **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`

  `*.yourdomainname.com`

  `*.ws.yourdomainname.com`
</Warning>

If you decide to self-manage DNS, you'll receive domain mapping information as CloudFormation Outputs, which should be added to Route 53 or your DNS management service. More about this will be covered in the [Complete DNS Configuration](/classic/admin/deploy-gitpod/dns-setup) 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.
</Note>

Below are the parameters for DNS configuration:

<Frame caption="DNS Configuration">
  <img src="https://mintcdn.com/gitpod-13c83c2b/1T56zcBWQ3jfH-V2/images/enterprise/dns-configuration-parameter.png?fit=max&auto=format&n=1T56zcBWQ3jfH-V2&q=85&s=d9d5903e01cadc3a33400708405bc7cb" width="3104" height="521" data-path="images/enterprise/dns-configuration-parameter.png" />
</Frame>

| Parameter                                   | Description                                                                                                                                                                                                                                             | Required                  |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| Auto-generate route53 zone in the CF stack? | If set to 'Yes', Gitpod will auto-generate and manage a Route53 zone and certificate. 'No' requires manual DNS configuration.                                                                                                                           | Yes                       |
| Domain name                                 | The domain name associated with Gitpod load balancers. Defaults to a `*.gitpod.cloud` subdomain if Gitpod manages DNS.                                                                                                                                  | No                        |
| Certificate ARN for the domain              | ARN of the ACM certificate that includes the necessary SANs for your domain. Mandatory for self-managed DNS. [Guidelines for creating/importing certs.](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/tls-listener-certificates.html) | Yes, if self-managing DNS |

#### Application Settings (Optional)

This optional section allows for specifying custom CA certificates 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]().

<Frame caption="Application Configuration">
  <img src="https://mintcdn.com/gitpod-13c83c2b/1T56zcBWQ3jfH-V2/images/enterprise/app-params.png?fit=max&auto=format&n=1T56zcBWQ3jfH-V2&q=85&s=669b88841a23b1a5bcffecc30ab979c0" width="3110" height="224" data-path="images/enterprise/app-params.png" />
</Frame>

| Parameter            | Description                                          | Required |
| -------------------- | ---------------------------------------------------- | -------- |
| Additional custom CA | ARN of the secret storing the Custom CA certificate. | No       |

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.

<Frame caption="Advanced Configuration">
  <img src="https://mintcdn.com/gitpod-13c83c2b/1T56zcBWQ3jfH-V2/images/enterprise/advanced-configuration.png?fit=max&auto=format&n=1T56zcBWQ3jfH-V2&q=85&s=d4bc0dc4566d8dd20f3cc7e07126e810" width="1470" height="431" data-path="images/enterprise/advanced-configuration.png" />
</Frame>

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](#expose-gitpod-services-publicly)**

<Note>
  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.
</Note>

| Parameter                                         | Description                                                                                                                                      | Required |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
| Expose Gitpod webhooks and IDP services publicly? | This option configures a public API gateway for webhooks and IDP services, which is crucial for internal-only network connectivity environments. | No       |

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.

* **[Enable super large workspaces (3XL and 4XL) for computationally intense workloads](#enable-xl-workspaces)**

<Note>
  Important: Enabling this option, will make these two new workspace classes
  available in Gitpod
</Note>

| Parameter                 | Description                                                                                                                                                                                                                                                             | Required |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| Enable XL size Workspaces | Enabling this field will introduce two new workspace classes to your Gitpod instance suitable for very heavy workloads. The specs of the classes are:<br />`3XLarge`: **30 vCPU, 128GB memory, 100GB disk**<br />`4XLarge`: **60 vCPU, 256GB memory, 100GB disk**<br /> | No       |

The setting for enabling large workspaces does not apply until the next application release. This is due to the need for a full application update to activate the feature. Releases happen daily at 2:00AM UTC. To verify your cell has been updated correctly, see the [Available Workspace Classes](/classic/user/configure/workspaces/workspace-classes#available-workspace-classes) section in your Gitpod instance organization settings.

* **[Enable GPU workspaces](#enable-gpu-workspaces)**

<Note>
  Important: Enabling this option, will make these a new workspace class available in
  Gitpod
</Note>

| Parameter             | Description                                                                                                                   | Required |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------- |
| Enable GPU workspaces | Enabling this field will introduce a new workspace classes to your Gitpod instance suitable for AI workloads with GPU support | No       |

The setting for enabling GPU workspaces does not apply until the next application release. This is due to the need for a full application update to activate the feature. Releases happen daily at 2:00AM UTC. To verify your cell has been updated correctly, see the [Available Workspace Classes](/classic/user/configure/workspaces/workspace-classes#available-workspace-classes) section in your Gitpod instance organization settings.

* **[Opt-out of enhanced cluster management](#opt-out-enhanced-cluster-management)**

| Parameter                              | Description                                                                                                                                                                                                   | Required |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| Opt-out of enhanced cluster management | This feature enables enhanced Kubernetes operations for faster debugging and issue diagnosis. Opting out may occasionally require manual execution of support tasks to assist in troubleshooting when needed. | No       |

This feature significantly reduces your Kubernetes management overhead by allowing the Gitpod Engineering team to perform essential maintenance operations when needed. For full transparency, you can audit all allowed permissions in the CloudFormation template and monitor any executed actions. All cluster outputs are sanitized at source, ensuring your sensitive information remains protected. This capability is vital for maintaining optimal cluster performance and enabling swift incident resolution, ultimately minimizing your team's operational burden while ensuring cluster reliability. For more details, see our [Enhanced Cluster Management documentation](/classic/admin/reference/enhanced-cluster-management).

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

<Frame caption="Role Configuration">
  <img src="https://mintcdn.com/gitpod-13c83c2b/1T56zcBWQ3jfH-V2/images/enterprise/role-select.png?fit=max&auto=format&n=1T56zcBWQ3jfH-V2&q=85&s=5d6668fe5cedd1a5deaba88021603943" width="3700" height="1634" data-path="images/enterprise/role-select.png" />
</Frame>

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

<Note> The CF stack apply should take around 30 minutes to complete </Note>

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

<Frame caption="Instance Configuration">
  <img src="https://mintcdn.com/gitpod-13c83c2b/1T56zcBWQ3jfH-V2/images/enterprise/instance-output.png?fit=max&auto=format&n=1T56zcBWQ3jfH-V2&q=85&s=a9b7bec3bfa3404782ab144db5fd9cbe" width="2808" height="696" data-path="images/enterprise/instance-output.png" />
</Frame>

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:

<Note>
  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](/classic/admin/manage-gitpod/overview).
</Note>

### [Completing DNS Setup](/classic/admin/deploy-gitpod/dns-setup)

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

### [Using Private VPC Resolvers](/classic/admin/deploy-gitpod/using-private-vpc-resolvers)

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