Skip to content

Architecture

Jump to bottom
genesluna edited this page Jan 2, 2026 · 1 revision

Architecture

Welcome to the architecture documentation for the k8s-ephemeral-environments platform. This section provides comprehensive information about the system design, infrastructure components, and technical decisions that power ephemeral PR environments.

Overview

The platform creates isolated Kubernetes environments for each Pull Request, enabling developers to preview and test changes in a production-like setting before merging. Each environment includes the application, databases, and observability tooling, all automatically provisioned and destroyed with the PR lifecycle.

+------------------------------------------------------------------+
|                    Platform Architecture                          |
+------------------------------------------------------------------+
|                                                                   |
|  +------------------+    +------------------+    +--------------+ |
|  |   GitHub PR      |    |  GitHub Actions  |    |   k3s        | |
|  |   (Trigger)      |--->|  (CI/CD)         |--->|   Cluster    | |
|  +------------------+    +------------------+    +--------------+ |
|                                                         |         |
|                                                         v         |
|  +----------------------------------------------------------+    |
|  |                    Ephemeral Namespace                    |    |
|  |  +----------+  +----------+  +----------+  +----------+  |    |
|  |  |   App    |  |   DB     |  |  Redis   |  |  MinIO   |  |    |
|  |  |   Pod    |  |   Pod    |  |   Pod    |  |   Pod    |  |    |
|  |  +----------+  +----------+  +----------+  +----------+  |    |
|  +----------------------------------------------------------+    |
|                                                                   |
+------------------------------------------------------------------+

Architecture Sections

System-Overview

Detailed technical documentation covering:

  • High-level architecture - Visual diagram of the complete system
  • Namespace structure - How namespaces are organized (permanent vs ephemeral)
  • Technology stack - All components and their justifications
  • PR environment lifecycle - Step-by-step flow from PR open to close
  • Resource quota system - Dynamic resource allocation based on database configuration

EKS-Migration-Guide

Planning documentation for Phase 2 migration:

  • Current vs target architecture - k3s to EKS comparison
  • Cluster-specific configurations - NetworkPolicy, PriorityClasses, storage
  • Migration checklist - Step-by-step migration tasks
  • Environment variables - Configuration differences between phases

Key Design Principles

Principle Implementation
Isolation Each PR gets its own namespace with NetworkPolicies
Automation Zero manual intervention for environment lifecycle
Observability Full metrics, logs, and alerting for every environment
Cost efficiency Automatic cleanup and resource quotas
Security Network isolation, sealed secrets, minimal RBAC

Quick Architecture Facts

Component Phase 1 (Current) Phase 2 (Future)
Kubernetes k3s (single-node) Amazon EKS (multi-node)
Infrastructure Oracle Cloud VPS (ARM64) AWS (Graviton or x86)
Ingress Traefik (bundled) AWS ALB or Traefik
Storage Local Path Provisioner EBS (gp3)
Database CloudNativePG (in-cluster) CloudNativePG or RDS

Architecture Decision Records

Key decisions made during platform development:

  1. k3s over full Kubernetes - Lightweight, fast installation, ideal for single-node VPS
  2. CloudNativePG over external RDS - Complete isolation per PR, simplified lifecycle
  3. Helm over raw manifests - Flexible templating, large community ecosystem
  4. Local charts for PRs - Enables testing chart changes before publishing
  5. Dynamic quotas - Automatically calculated based on enabled databases

Note: The architecture is designed to be portable. Phase 2 migration to EKS requires minimal application changes, primarily infrastructure configuration updates.

Related Pages

Home

Getting Started

User Guides

Troubleshooting

Operations

Architecture

Demo Applications

Development

Clone this wiki locally