mirror of
https://github.com/gitpod-io/gitpod.git
synced 2025-12-08 17:36:30 +00:00
89e09307b9
* [server] Introduce ReadinessController and probe at /ready Tool: gitpod/catfood.gitpod.cloud * [server] Move /live and /ready endpoints to a separate express app and port Tool: gitpod/catfood.gitpod.cloud * [memory-bank] task-related learnings Tool: gitpod/catfood.gitpod.cloud * [server] Introduce `server_readiness_probe` feature flag so we can disable the ReadinessProbe if required Tool: gitpod/catfood.gitpod.cloud * docs: formalize Product Requirements Document workflow - Add PRD workflow to systemPatterns.md as a standardized development process - Update .clinerules with instructions to follow the PRD workflow - Update activeContext.md and progress.md to reference the new workflow This formalizes the process we used for implementing the server readiness probe feature. Tool: gitpod/catfood.gitpod.cloud * [server] ReadinessProbe: add redis as dependency Tool: gitpod/catfood.gitpod.cloud * review comments Tool: gitpod/catfood.gitpod.cloud * [dev] Remove outdated gopls config Tool: gitpod/catfood.gitpod.cloud * [server] Fix import Tool: gitpod/catfood.gitpod.cloud
148 lines
8.6 KiB
Markdown
148 lines
8.6 KiB
Markdown
# System Patterns: Gitpod
|
|
|
|
## System Architecture
|
|
|
|
Gitpod follows a microservices architecture composed of several key components that work together to provide the complete development environment platform. The system is designed to be:
|
|
|
|
- **Scalable**: Handles many concurrent users and workspaces
|
|
- **Resilient**: Maintains availability despite component failures
|
|
- **Extensible**: Allows for adding new features and integrations
|
|
- **Secure**: Isolates workspaces and protects user data
|
|
|
|
### High-Level Architecture
|
|
|
|
```
|
|
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
|
│ Git Platforms │ │ User Browser │ │ IDE Clients │
|
|
│ (GitHub, etc.) │ │ │ │ (VS Code, etc.)│
|
|
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ API Gateway │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
|
│ Auth Service │ │ Dashboard │ │ IDE Service │
|
|
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
|
│ │ │
|
|
└───────────────┬───────┴───────────────┬───────┘
|
|
│ │
|
|
▼ ▼
|
|
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
|
│ WS Manager │ │ Image Builder │ │ Content Service│
|
|
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Kubernetes Infrastructure │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Key Components
|
|
|
|
### Core Services
|
|
|
|
1. **Workspace Manager (ws-manager)**: Orchestrates workspace lifecycle, managing creation, starting, stopping, and deletion of workspaces.
|
|
|
|
2. **Workspace Daemon (ws-daemon)**: Runs on each node, managing workspace resources, file system operations, and runtime aspects.
|
|
|
|
3. **Image Builder**: Builds Docker images for workspaces based on configuration and caches them for quick startup.
|
|
|
|
4. **Content Service**: Manages file content, including git operations, file synchronization, and backup.
|
|
|
|
5. **IDE Service**: Manages the IDE instances (VS Code, JetBrains) that run in workspaces.
|
|
|
|
6. **Dashboard**: Web UI for managing workspaces, projects, and user settings.
|
|
|
|
7. **Auth Service**: Handles authentication and authorization across the platform.
|
|
|
|
8. **Proxy**: Routes traffic to the appropriate services and workspaces.
|
|
|
|
### Supporting Components
|
|
|
|
1. **Registry Facade**: Provides efficient access to container images.
|
|
|
|
2. **Blobserve**: Serves static content from container images.
|
|
|
|
3. **Supervisor**: Runs inside each workspace, managing the workspace's internal services.
|
|
|
|
4. **Public API**: Provides programmatic access to Gitpod functionality.
|
|
|
|
## Design Patterns
|
|
|
|
### Microservices Pattern
|
|
Gitpod is built as a collection of loosely coupled services, each with a specific responsibility. This enables independent scaling, deployment, and maintenance of components.
|
|
|
|
### Container Orchestration
|
|
Kubernetes is used to manage the deployment, scaling, and operation of application containers across clusters of hosts.
|
|
|
|
### Event-Driven Architecture
|
|
Components communicate through events for asynchronous operations, improving scalability and resilience.
|
|
|
|
### API Gateway Pattern
|
|
A central API gateway routes requests to appropriate services, handling cross-cutting concerns like authentication.
|
|
|
|
### Circuit Breaker Pattern
|
|
Services implement circuit breakers to prevent cascading failures when downstream services are unavailable.
|
|
|
|
### Sidecar Pattern
|
|
The Supervisor component runs alongside workspace applications as a sidecar, providing common functionality.
|
|
|
|
### Immutable Infrastructure
|
|
Workspaces are treated as immutable, with changes to configuration resulting in new environments rather than modifications to existing ones.
|
|
|
|
## Component Relationships
|
|
|
|
### Workspace Lifecycle
|
|
|
|
1. User requests a workspace through the dashboard or Git integration
|
|
2. Auth service validates the request
|
|
3. Workspace Manager creates the workspace specification
|
|
4. Image Builder ensures the required image is available
|
|
5. Workspace Manager instructs Kubernetes to create the workspace pod
|
|
6. Workspace Daemon initializes the workspace environment
|
|
7. Supervisor starts within the workspace
|
|
8. IDE Service connects the IDE to the workspace
|
|
9. Proxy routes user traffic to the workspace
|
|
|
|
### Data Flow
|
|
|
|
1. **User Code**: Managed by Content Service, synchronized between workspace and git repositories
|
|
2. **Configuration**: Stored in database, applied by Workspace Manager during workspace creation
|
|
3. **Build Artifacts**: Cached by Image Builder for reuse in future workspaces
|
|
4. **User Data**: Stored in database, accessed through Dashboard and API
|
|
|
|
## Key Technical Decisions
|
|
|
|
1. **Kubernetes-Based**: Leveraging Kubernetes for container orchestration provides scalability and standardized infrastructure management.
|
|
|
|
2. **Multi-IDE Support**: Supporting multiple IDEs (VS Code, JetBrains) increases flexibility for users with different preferences.
|
|
|
|
3. **Prebuild System**: Prebuilding environments before they're needed significantly reduces startup times.
|
|
|
|
4. **Workspace Pods**: Each workspace runs in its own Kubernetes pod, providing isolation and resource management.
|
|
|
|
5. **TypeScript and Go**: Core services are implemented in TypeScript (user-facing) and Go (system-level), balancing developer productivity and performance.
|
|
|
|
6. **gRPC Communication**: Internal services communicate using gRPC for efficient, typed communication.
|
|
|
|
7. **Leeway Build System**: Custom build system for managing the complex dependencies between components.
|
|
|
|
8. **Kubernetes Deployment Configuration**: All code that defines Kubernetes objects for deployable components lives in `install/installer`. This centralized approach ensures consistent deployment patterns across all components.
|
|
|
|
## Development Workflows
|
|
|
|
### Product Requirements Document (PRD) Workflow
|
|
Gitpod uses a structured PRD workflow for feature development to ensure proper planning, documentation, and implementation:
|
|
|
|
1. **Requirements Gathering** (Plan Mode): Understand the problem, explore existing components, gather information
|
|
2. **PRD Creation** (Plan Mode): Create a detailed document in `prd/` with standardized sections
|
|
3. **Implementation Planning** (Plan Mode): Identify files to modify and plan the approach
|
|
4. **Implementation** (Act Mode): Create/modify necessary files following the plan
|
|
5. **Documentation Update** (Act Mode): Update memory bank with new knowledge
|
|
6. **Verification**: Ensure implementation meets requirements and documentation is complete
|
|
|
|
This workflow ensures thorough planning, clear documentation, and knowledge preservation for all feature development.
|