• Substrate = The control plane that manages Enterprise instances
  • Bootstrap = Initial set up required to create an instance of Enterprise
  • Cell = An instance of Enterprise

​
Overview

Enterprise Architecture

Enterprise is powered and managed by a Control Plane that sits above Enterprise Instances (a.k.a Cells). Controllers, implemented as Lambdas, are mainly used to create and update components. They compare the desired state (as defined by a spec that lives in the Control Plane) with the actual state, and then work to resolve any discrepancies. Deployment and operation can be divided into three stages:
  1. Bootstrap (initial set up of infrastructure)
  2. Registration
  3. Updates and ongoing operations

​
Bootstrap Stage

The initial infrastructure required is created using a CloudFormation template executed by the customer. The customer must create a new & dedicated AWS account (as per Getting Started) and and then execute the CloudFormation template within it. Please see Getting Started for detailed instructions.

​
Registration stage

Once the CloudFormation template successfully executes, the instance will register itself with the Gitpod Control Plane.
Registration happens via an outgoing connection only that uses AWS PrivateLink - the Control Plane has no ingoing connection to the instance. See Networking and Data Flows.
Upon registration, the instance will check for the newest version of Gitpod and install it onto itself. This happens via the normal update mechanism which is described below.

​
Updates and Ongoing Operations

Application Updates
The initial application update is handled just like any other, with the only difference being that no application is installed yet. I.e. all of Gitpod’s components are installed from scratch after the instance has registered itself.
Enterprise is deployed and operated in the same way as other SaaS offerings, i.e. in a continuous manner. Deployment happens first to our internal staging environments, then gitpod.io, and only then to Dedicated customers.
Changes are deployed and new features are enabled independently, using feature flags. Gitpod plans to deploy changes perpetually, but enable new functionality in a way that aligns with release communication.
The instance connects to the Control Plane (via an outgoing connection only; using AWS PrivateLink) to periodically check for updates. When it learns that a new version is available, it pulls the latest images (also via PrivateLink), applies them to update to the latest version and shares the status with the Control Plane.
Maintenance mode: Upon updates of certain application components, the instance may enter maintenance mode - in this mode, workspaces are temporarily blocked from starting and stopping and it is not possible to take a workspace snapshot. Running workspaces are not affected and this should only last a few minutes. During maintenance mode, users see the following error:Enterprise Deployment overview
Ongoing Operations Some detail for Gitpod infrastructure is collected and shared with the Control Plane to aid in troubleshooting. This is limited to:
  • Values for required AWS service quotas
  • Cloud Formation stack status, changeset status, and drift detection results
  • Parameters for the Instance Cloud Formation template

​
Infrastructure updates

Occasionally, infrastructure updates are required to keep a customer’s instance up to date. In such cases, an updated CloudFormation template will be provided, which can be run against the existing stack created by the initial CloudFormation template.
Infrastructure updates are mandatory. Infrastructure updates need to applied within two weeks, as otherwise the instance will no longer receive updates and fall out of the support SLA.

​
Debugging

In the event that there are unforeseen issues with a customer’s installation that cannot be resolved using the data that is exported from an instance (see Data and Observability), the customer is able to get access to the instance in order to jointly debug the instance with a Gitpod employee. This is only a tool used in emergencies. Gitpod is not able to access the instance directly. For more information, see Getting Access to the Instance for Debugging.