# truefoundry/elasti architecture

> Architecture diagram of the GitHub repository truefoundry/elasti, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/truefoundry/elasti
- Repository: https://github.com/truefoundry/elasti

## Overview

##### Project Type and Purpose
**Project Type:**
Elasti is a **Kubernetes-native autoscaling tool** designed to optimize resource usage by scaling services to zero during low or no traffic periods and scaling them back up when demand increases. It acts as a proxy to queue incoming requests for scaled-down services, ensuring no requests are lost.

**Purpose:**
The primary goal of Elasti is to **reduce costs** in Kubernetes clusters by minimizing resource usage without sacrificing service availability. It integrates seamlessly with existing Kubernetes setups, supporting autoscalers like HPA and Keda, and provides robust monitoring through Prometheus metrics.

##### File Structure
**Top-Level Directories and Files:**
- **.github:** Contains GitHub workflows and issue templates for CI/CD, linting, testing, and release management.
- **charts/elasti:** Helm charts for deploying Elasti, including Kubernetes resource definitions and RBAC configurations.
- **docs:** Documentation covering architecture, configuration, development, and monitoring.
- **operator:** Contains the Kubernetes operator code, including API definitions, controllers, configuration files, and internal logic.
- **pkg:** Utility packages for logging, message handling, scaling, and other helper functions.
- **playground:** Configuration and infrastructure files for demo applications and dashboards.
- **resolver:** Handles request routing and proxy functionality when services are scaled to zero.
- **test:** Scripts and logs for load testing and performance evaluation.

**Architectural Indicators:**
- **Operator Pattern:** The `operator` directory suggests the use of the Kubernetes Operator pattern to manage custom resources (`elastiservice`).
- **Helm Charts:** Deployment using Helm indicates a **declarative configuration approach** for Kubernetes resources.
- **Microservices Components:** Separate directories for `resolver` and `operator` imply a **modular architecture** with distinct services handling specific functionalities.
- **Configuration Management:** Use of `kustomization.yaml` and Dockerfiles demonstrates robust configuration and containerization practices.

##### README for Additional Insights
The README provides a comprehensive overview of Elasti's functionality, emphasizing its role in scaling Kubernetes services to zero and back based on traffic. Key points include:
- **Seamless Integration:** Works with existing autoscalers.
- **Prometheus Metrics:** Facilitates monitoring and visualization.
- **Proxy Mechanism:** Manages request queuing during scale-down periods.
- **Generic Service Support:** Compatible with various ingress and service mesh solutions.

**a. Identify the Main Components:**
- **User/Application:** Initiates requests to services managed by Elasti.
- **Elasti Operator:** Manages the scaling logic and interacts with Kubernetes APIs.
- **Resolver Service:** Acts as a proxy to queue and route requests when services are scaled to zero.
- **Kubernetes Cluster:** Hosts the services, including integrations with HPA/Keda.
- **Prometheus:** Collects metrics from Elasti for monitoring.
- **Grafana Dashboard:** Visualizes metrics for real-time insights.
- **Helm Charts:** Deploys Elasti and its components within the Kubernetes environment.

**b. Determine Relationships and Interactions:**
- **Elasti Operator ↔ Kubernetes API:** Manages custom resources and scales services based on traffic.
- **Resolver Service ↔ User/Application:** Intercepts and queues requests when services are inactive.
- **Resolver Service ↔ Elasti Operator:** Notifies when to scale services back up.
- **Prometheus ↔ Elasti Operator:** Receives metrics data for monitoring.
- **Grafana ↔ Prometheus:** Visualizes collected metrics.
- **Helm Charts ↔ Kubernetes Cluster:** Facilitates deployment and updates of Elasti components.

**c. Highlight Architectural Patterns and Design Principles:**
- **Operator Pattern:** Automates the management of Kubernetes custom resources.
- **Proxy Pattern:** Utilizes resolver as a proxy to handle request queuing and routing.
- **Modular Architecture:** Separates concerns into distinct services (`operator`, `resolver`, etc.) for maintainability and scalability.
- **Declarative Configuration:** Uses Helm and Kustomize for consistent deployments.

**d. Include Relevant Technologies, Frameworks, or Libraries:**
- **Kubernetes:** Orchestrates containerized applications.
- **Helm:** Manages Kubernetes packages.
- **Prometheus:** Monitoring and alerting toolkit.
- **Grafana:** Data visualization and monitoring.
- **Go:** Primary programming language for operator and resolver services.
- **Docker:** Containerization of services.
- **Kustomize:** Customizes Kubernetes configurations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global entities
    UA["User/Application"]:::user
    EK["Kubernetes Cluster"]:::cluster

    %% Subgraphs and modules
    subgraph "Deployment Layer"
        HC["Helm Charts"]:::deployment
    end

    subgraph "Elasti Components"
        EO["Elasti Operator"]:::service
        RS["Resolver Service"]:::service
    end

    subgraph "Monitoring"
        P["Prometheus"]:::monitoring
        G["Grafana Dashboard"]:::monitoring
    end

    %% Connections
    UA -->|"sends requests"| RS
    RS -->|"notifies to scale up"| EO
    EO -->|"manages resources"| EK
    EO -->|"sends metrics"| P
    P -->|"provides metrics"| G
    HC -->|"deploys components"| EK

    %% Click Events
    click EO "https://github.com/truefoundry/elasti/tree/main/operator/"
    click RS "https://github.com/truefoundry/elasti/tree/main/resolver/"
    click HC "https://github.com/truefoundry/elasti/tree/main/charts/elasti/"
    click P "https://github.com/truefoundry/elasti/blob/main/operator/config/prometheus/monitor.yaml"

    %% Styles
    classDef user fill:#f96, stroke:#333, stroke-width:2px;
    classDef service fill:#6cf, stroke:#333, stroke-width:2px;
    classDef monitoring fill:#bbf, stroke:#333, stroke-width:2px;
    classDef deployment fill:#bfb, stroke:#333, stroke-width:2px;
    classDef cluster fill:#ffb, stroke:#333, stroke-width:2px;
```
