ws-manager-bridge-api.md

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:

1. Navigate to the ws-manager-bridge-api directory:

   cd components/ws-manager-bridge-api
   

2. Run the generate script:

   ./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:

1. For Go components:

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

2. For TypeScript components:

   cd <component-directory>
   yarn install
   yarn build
   

3. Using Leeway (for CI/CD):

   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.