Cluster Requirements
⚠️ Gitpod Self-hosted is no longer supported
The last update of Gitpod Self-hosted product was November 2022. Users can still request our free community license however there will be no support or updates to the product. If you are interested in an isolated, private installation of Gitpod, take a look at Gitpod Dedicated.
Gitpod is a Kubernetes application running with certain expectations on the characteristics of the cluster it is running on.
Reference Architectures
We have created a set of reference architectures for all the major cloud providers that fulfil the requirements below. These are intended as a starting point for you to create an environment to install Gitpod into. If you wish to use K3s, please refer to the k3s guide.
Supported Kubernetes Distributions
Gitpod requires Kubernetes as an orchestration technology in order to spin workspaces up and down—ideally in combination with cluster autoscaling to minimize cost. We strongly recommend deploying a dedicated Kubernetes cluster just for Gitpod Self-Hosted.
Kubernetes version
1.21
or above is required
Gitpod Self-Hosted runs well on:
- Amazon Elastic Kubernetes Service
- Google Kubernetes Engine
- Microsoft Azure Kubernetes Service
- K3s
Incompatible Kubernetes Distributions
These platforms do not currently work with Gitpod Self-Hosted but we would like to support them in the future. Gitpod is an open-source project, maybe you could contribute the required changes to help get them working sooner?
If you are considering purchasing a commercial license for Gitpod Self-Hosted and need one of the above platforms then please contact us to start discussions about making support for them happen sooner.
Node Affinity Labels Requirements
Your Kubernetes cluster must have node(s) with the following labels applied to them:
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
It is recommended to have a minimum of two node pools, grouping the meta
and ide
nodes into one node pool and workspace
related nodes into another. These two groups of workloads have different performance characteristics. Separating them into node pools after the fact is more difficult and incurs downtime.
Node and Container Requirements
These are the components expected on each node:
- Either Ubuntu 18.04 with ≥ v5.4 kernel or Ubuntu 20.04 with ≥ v5.4 kernel
- Calico for the networking overlay and network policy
- Containerd ≥ 1.5
- At least 4 vCPU and 16GB of RAM
Kubernetes Privilege Requirements
Your Kubernetes cluster must allow Gitpod to run privileged pods and manage PodSecurityPolicies, as Gitpod depends on these privileges to provide workspace isolation.
Load Balancer Requirements
Gitpod uses LoadBalancer
type services to expose the Gitpod Dashboard, browser-based IDEs, and SSH connections used by desktop IDEs. Your Kubernetes cluster must be able to provision layer 4 or layer 7 load balancers for LoadBalancer
type services that can route HTTP(S) connections to Gitpod services. If you intend to use desktop IDEs or SSH to workspaces then your cluster must also be able to provision layer 4 load balancers that can route SSH connection to Gitpod services.
All supported Kubernetes distributions provide load balancers that meet Gitpod’s needs. For more information see the Kubernetes distribution documentation below:
- Google Kubernetes Engine
- Amazon Elastic Kubernetes Engine:
- Layer 4/7 (default): Classic Load Balancer
- Layer 4 only: Network Load Balancing
- Microsoft Azure Kubernetes Service
- K3s