Upgrade Guides and Breaking Changes

⚠️ 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.

This page informs you if there are specific considerations to take into account when upgrading to a specific version. If no breaking changes and thus specific recommendations when updating are mentioned here (or if they do not apply to you), please follow the normal upgrade procedure mentioned on the Updating your Gitpod Installation page.



This release includes security fixes addressing information leakage in logs; see the security announcement log for more information.

Breaking Changes

  • Single Cluster Reference Architecture changes:
    • Regular workspaces and headless workspaces are isolated to separate node pools to help avoid noisy neighbor issues between the two and guarantee maximum performance for workspaces
    • Workspace Services (such as ws-manager) are deployed to the services nodepool to prevent potential service degradation from high ws-daemon memory use.
    • We’ve increased the default node size to 16 core / 64 GB nodes. This is to allow for more workspaces per node, and avoid the scenario where there is just one workspace per node. We’ve also added documentation to detail our recommendations around workspace resources.


There is no expected impact from these changes if using KOTS. These are documented for transparency purposes only. Custom labels from the pod selector labels removed

11954: remove custom labels from the pod selector labels. This removes this limitation so this is a long-term improvement. The impact of this should be handled transparently for you by the KOTS installer.

Usage of PodSecurityPolicies removed

12336: Removal of PodSecurityPolicies. These were deprecated from Kubernetes 1.21 and removed from 1.25. This allows Gitpod to run on Kubernetes 1.25+, which is scheduled for imminent release. If you have PodSecurityPolicies enabled on your cluster, we suggest you disable them as soon as possible. If an installation is deployed to a cluster with PSPs enabled, you will need to add experimental.common.usePodSecurityPolicies = true to a config-patch file - however, do note that this is deprecated and exists to ease the transition away from PSPs.


Setting the service type of the proxy component

You can now configure the service type of the proxy service in the installation UI (see image below) - you do not need to upload a .yaml file as a config patch anymore to configure this. However, having it in the config patch will still work until December.

proxy service type UI

Setting the default workspace image and which image registries the default image can be pulled from

We’ve moved the configuration of the default workspace image and the default base image registry whitelist out of the experimental section of the config-patch file. The latter was also renamed. Using them in the experimental section will still work for the time being (until approx. December 2022).


language icon yml
                - <allowed registries>
            workspaceImage: <path to your default workspace image>


language icon yml
    workspaceImage: <path to your default workspace image>
        - <allowed registries>

Was this helpful?