⚠️ Gitpod Self-hosted has been replaced with Gitpod Dedicated, a self-hosted, single-tenant managed service that runs in your private cloud account but is managed by us. Try out Gitpod Dedicated.
Status:
Alpha
Intended for:
Trying out Gitpod in a representative way but with only the minimum of infrastructure required
Limitations:
- Not intended for long-term, production usage - Higher risk of data loss due to in-cluster dependencies - if you lose your cluster, you may lose your data - Data is not carried over when moving to the Single Cluster Reference Architecture for production purposes
Overview
This reference architecture provides you with a setup where all components that are needed to operate Gitpod are deployed within the Kubernetes cluster. In contrast to a production-oriented setup, this means that the required database, object storage, well as a registry are deployed for you within the cluster. All cluster services and workspaces are deployed on a single autoscaling node group.
You need to prepare your workstation and your cloud provider (e.g. creating a project and preparing service accounts) to be able to replicate this reference architecture.
Independent of the cloud provider you are using, you need to have kubectl installed on your workstation and configured to access your cluster after creation.
First, create a GCP project and enable billing (you have to enable billing to enable GKE). You can freely choose a name for your project (hereinafter referred to as environment variable PROJECT_NAME). You also need the billing account ID (referred to as BILLING_ACCOUNT). To see available lDs, run gcloud alpha billing accounts list.
Now, you are prepared to create your Kubernetes cluster.
Kubernetes Cluster
The heart of this reference architecture is a Kubernetes cluster where all components are deployed to. This cluster has a single node pool that needs to have all of the following labels:
gitpod.io/workload_meta=true
gitpod.io/workload_ide=true
gitpod.io/workload_workspace_services=true
gitpod.io/workload_workspace_regular=true
gitpod.io/workload_workspace_headless=true
The following table gives an overview of the node types for the different cloud providers that are used by this reference architecture.
GCP
AWS
Gitpod Node Pool
n2d-standard-16
m6i.4xlarge
Cloud provider specific instructions
Google Cloud Platform (GCP)GCP
Amazon Web Services (AWS)AWS
First, we create a service account for the cluster. The service account needs to have the following roles:
Roles
roles/logging.logWriter
roles/monitoring.metricWriter
roles/container.admin
Run the following commands to create the service account:
For each Gitpod installation, you need a domain. In this guide, we use gitpod.example.com as a placeholder for your domain. Gitpod also uses different subdomains for some components as well as dynamically for the running workspaces. That’s why you need to configure your DNS server and your TLS certificates for your Gitpod domain with the following wildcards:
The entry point for all traffic is the proxy component which has a service of type LoadBalancer that allows inbound traffic on ports 80 (HTTP) and 443 (HTTPS) as well as port 22 (SSH access to the workspaces).
SSH access is required to work with desktop IDEs, such as VS Code Desktop and JetBrains via JetBrains Gateway. To enable SSH, your load balancer needs to be capable of working with L4 protocols.
For Gitpod, we support Calico as CNI only. You need to make sure that you DO NOT use GKE Dataplan V2. That means, do not add the --enable-dataplane-v2 flag during the cluster creation.
External DNS
You also need to configure your DNS server. If you have your own DNS server for your domain, make sure the domain with all wildcards points to your load balancer.
Creating a dedicated DNS zone is recommended when using cert-manager or external-dns but is not required. A pre-existing DNS zone may be used as long as the cert-manager and/or external-dns services are authorized to manage DNS records within that zone. If you are providing your own TLS certificates and will manually create A records pointing to Gitpod’s public load balancer IP addresses then creating a zone is unnecessary.
First, we need a service account with role roles/dns.admin. This service account is needed by cert-manager to alter the DNS settings for the DNS-01 resolution.
DOMAIN=gitpod.example.com
gcloud dns managed-zones create "${CLUSTER_NAME}"\
--dns-name "${DOMAIN}."\--description"Automatically managed zone by kubernetes.io/external-dns"
Now we are ready to install External DNS. Please refer to the External DNS GKE docs.
Depending on what your DNS setup for your domain looks like, you most probably want to configure the nameservers for your domain. Run the following command to get a list of nameservers used by your Cloud DNS setup:
language:
bash
gcloud dns managed-zones describe ${CLUSTER_NAME}--format json | jq '.nameServers'
cert-manager
Gitpod uses TLS secure external traffic bound for Gitpod as well as identifying, authorizing, and securing internal traffic between Gitpod’s internal components. While you can provide your own TLS certificate for securing external connections to Gitpod, cert-manager is required to generate internal TLS certificates.
In this reference architecture, we use cert-manager to also create TLS certificates for the Gitpod domain. Since we need wildcard certificates for the subdomains, you must use the DNS-01 challenge.
Using a certificate issued by Let’s Encrypt is recommended as it minimizes overhead involving TLS certificates and managing CA certificate trust, but is not required. If you already have TLS certificates for your Gitpod installation with suitable DNS names you can skip this step and use your own certificates during the installation.
language: