Skip to content

GEMINI.md

Latest commit

 

History

History
57 lines (48 loc) · 3.38 KB

GEMINI.md

File metadata and controls

57 lines (48 loc) · 3.38 KB
Raw

KubeRDE Project Context

Project Overview

KubeRDE (Kubernetes Remote Development Environment) is a production-ready, Kubernetes-native system designed to securely expose and manage local services (behind NAT/firewalls). It has evolved from a simple Fast Reverse Proxy (FRP) into a platform for provisioning remote development environments.

Core Architecture

The system consists of five main components:

  1. FRP Server (cmd/server): Public relay node. Accepts WebSocket connections from Agents and proxies incoming user traffic. Handles OIDC authentication and manages the PostgreSQL database.
  2. FRP Agent (cmd/agent): Local client. Connects to the Server via WebSocket and bridges traffic to local targets (e.g., SSH, Code Server).
  3. FRP Operator (cmd/operator): Kubernetes controller. Manages the lifecycle of Agents via the RDEAgent CRD, handling deployments, auto-scaling (scale-to-zero), and configuration.
  4. Web UI (web/): React-based management interface for users to create and manage their workspaces and services using templates.
  5. CLI (cmd/cli): Command-line tool for authentication and establishing connections (e.g., as SSH ProxyCommand).

Key Technologies

  • Language: Go (1.24+)
  • Frontend: React (Vite, Tailwind CSS, TypeScript)
  • Containerization: Docker, Docker Compose
  • Orchestration: Kubernetes (Custom Operator, CRDs)
  • Transport: Gorilla WebSocket + Hashicorp Yamux
  • Auth: Keycloak (OIDC/OAuth2)
  • Database: PostgreSQL (for templates, service metadata, and workspaces)

Development Workflow

Build & Run (Local)

  • Build All Binaries: make build
  • Run Tests: make test (Go) or npm test (Frontend in web/)

Kubernetes Deployment

  • Deploy All: make deploy (Deploys Namespace, CRDs, Server, Operator, Web, Keycloak, PostgreSQL)
  • View Status: make status
  • Logs: make logs-server, make logs-operator, make logs-agent
  • Scale: make scale-up, make scale-down

Directory Structure

  • cmd/: Application entry points (server, agent, operator, cli).
  • deploy/k8s/: Kubernetes manifests (CRDs, Deployments, Services).
  • deploy/migrations/: SQL migrations for PostgreSQL.
  • docs/: Comprehensive documentation. Read docs/ARCHITECTURE.md for deep dives.
  • pkg/: Shared libraries (models, db, protocol).
  • web/: Source code for the Frontend Web UI.
  • archives/: Historical context and analysis reports.

Key Constraints & Conventions

  • Agent Management: Agents are primarily managed via Kubernetes CRDs (RDEAgent), which are generated by the Server based on database templates.
  • Scaling: The system supports TTL-based idle scaledown (replicas=0) and auto-scale-up upon connection request.
  • Authentication: Strictly OIDC-based.
  • Templates: Services are created from templates (SSH, File Browser, Code Server, Jupyter) stored in PostgreSQL.

Recent Status (as of Dec 31, 2025)

  • Phase 5 Completed (Dec 26): Implemented database-driven Agent Templates.
    • Added PostgreSQL integration.
    • Created agent_templates schema and API.
    • Updated Web UI to support template selection and configuration.
    • Implemented async PVC creation for workspaces.
  • Current State: Production Ready.
  • Next Steps: Custom template creation UI, service monitoring, and advanced networking.