Workspace Manager Bridge API

Overview

The Workspace Manager Bridge API defines the gRPC interfaces for the Workspace Manager Bridge service, which enables dynamic management of workspace clusters within the Gitpod platform. This API allows for the registration, updating, and deregistration of workspace clusters, facilitating multi-cluster deployments and cluster lifecycle management.

Purpose

This API provides a standardized interface for:

Registering new workspace clusters
Updating properties of existing workspace clusters
Deregistering workspace clusters
Listing currently registered workspace clusters
Managing admission constraints for workspace clusters
Controlling cluster state (available, cordoned, draining)

Architecture

The Workspace Manager Bridge API is implemented as a gRPC service defined in Protocol Buffer files. These definitions are used to generate client and server code in Go and TypeScript for use by the workspace manager bridge and other components in the system.

Key Services

ClusterService

Provides methods for managing workspace clusters:

Register: Registers a new workspace cluster
Update: Modifies properties of an already registered workspace cluster
Deregister: Removes a workspace cluster from available clusters
List: Returns the currently registered workspace clusters

Key Data Structures

ClusterStatus

Represents the current status of a workspace cluster:

Name and URL
State (UNKNOWN, AVAILABLE, CORDONED, DRAINING)
Score and maximum score
Admission constraints
Region information
Whether the cluster is static or governed

TlsConfig

Contains TLS configuration for secure communication with a cluster:

CA certificate
Client certificate
Client key

RegistrationHints

Provides hints for cluster registration:

Preferability (None, Prefer, DontSchedule)
Cordoned status

AdmissionConstraint

Defines constraints for workspace admission to a cluster:

Feature preview constraints
Permission-based constraints

Communication Patterns

The API uses gRPC for efficient, typed communication
Requests include cluster names to identify the relevant cluster
Updates can be applied to specific properties of a cluster
Deregistration can be forced even if instances are still running

Dependencies

Used by the server component for cluster management
Used by the ws-manager-bridge to communicate with workspace managers
Integrated with Kubernetes for cluster management

Usage Examples

Cluster management systems use this API to register new workspace clusters
Load balancing systems use this API to update cluster scores
Administrative tools use this API to cordon or drain clusters
Monitoring systems use this API to list available clusters

Version Compatibility

The API uses Protocol Buffers version 3 (proto3) syntax, which provides forward and backward compatibility features. The service is designed to allow for the addition of new cluster management features without breaking existing clients.

Code Generation and Building

Regenerating Code from Protobuf Definitions

The Workspace Manager Bridge API uses Protocol Buffers and gRPC for defining interfaces. When changes are made to the .proto files, the corresponding code in Go and TypeScript needs to be regenerated.

To regenerate the code:

Navigate to the ws-manager-bridge-api directory:
bash
```
cd components/ws-manager-bridge-api
```
Run the generate script:
bash
```
./generate.sh
```

This script performs the following actions:

Installs necessary dependencies (protoc plugins)
Generates code using buf based on the configuration in buf.gen.yaml
Updates license headers

The buf.gen.yaml file configures the code generation:

Generates Go code with appropriate module paths
Generates JavaScript and TypeScript code with gRPC support

Building After Code Generation

After regenerating the code, you may need to rebuild components that depend on the Workspace Manager Bridge API. This typically involves:

For Go components:

bash

cd <component-directory>
go build ./...

For TypeScript components:

bash

cd <component-directory>
yarn install
yarn build

Using Leeway (for CI/CD):

bash

leeway build -D components/<component-name>:app

The Workspace Manager Bridge API is primarily used by the ws-manager-bridge component, which bridges between workspace managers and the rest of the platform. It plays a critical role in multi-cluster deployments by enabling dynamic management of workspace clusters, facilitating load balancing, and providing a unified interface for cluster operations.