# santidelacarrera/kubecost_auto_hpa architecture

> Architecture diagram of the GitHub repository santidelacarrera/kubecost_auto_hpa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/santidelacarrera/kubecost_auto_hpa
- Repository: https://github.com/santidelacarrera/kubecost_auto_hpa

## Overview

KubeCost Auto-HPA is a Kubernetes operator and CLI for cost-aware workload rightsizing and replica scaling, with a Python decision engine and enterprise API. The principal flow reads workload and metric/cost evidence, generates an explainable recommendation, applies fail-closed policy and approval controls, then observes changes and can roll them back. The README also describes read-only capacity, cost, and billing reports. Several engine and operator subsystems are included because they are documented capabilities or core modules; unsampled implementation details limit some relationships.

Main entry points: [`engine/kubecost_engine/server.py`](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/server.py) (HTTP engine API), [`operator/cmd/rightsize/main.go`](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/operator/cmd/rightsize/main.go) (Rightsize commands), [`engine/kubecost_engine/enterprise.py`](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/enterprise.py) (Enterprise workflows), [`operator/internal/controller/kubecosthpa_controller.go`](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/operator/internal/controller/kubecosthpa_controller.go) (KubeCostHPA reconciler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator["Kubernetes operator"]
  node_autoscaler["Replica autoscaler"]
  node_hpa_controller["KubeCostHPA reconciler"]
  node_metrics_cache["Metrics and cache"]
  node_actuator["Workload actuators<br/>[resize.go]"]
end

subgraph group_cli["Recommendation and CLI"]
  node_node_analysis["Node capacity analysis<br/>[capacity.go]"]
  node_recommend_cli["Read-only recommender<br/>[main.go]"]
  node_recommendation["Recommendation logic<br/>[recommend.go]"]
  node_rightsize_cli["Rightsize commands<br/>[main.go]"]
  node_policy["Fail-closed policy<br/>[safety.go]"]
  node_execution["Apply and rollback<br/>[execute.go]"]
  node_audit["Audit chain<br/>[chain.go]"]
end

subgraph group_engine["Decision engine"]
  node_engine_api["HTTP engine API<br/>[server.py]"]
  node_binpacking["Bin packing<br/>[binpacking.py]"]
  node_predictive["Predictive analysis<br/>[predictive.py]"]
  node_oom["OOM protection<br/>[oom_shield.py]"]
  node_scaling["Scaling decisions<br/>[scaling.py]"]
  node_economics["Cost economics<br/>[economics.py]"]
  node_greenops["GreenOps guardrails"]
  node_cast["Cluster assessment<br/>[cast_suite.py]"]
  node_bootstrap["Engine bootstrap<br/>[bootstrap.py]"]
  node_persistence[("Engine persistence<br/>[persistence.py]")]
  node_maintenance["Maintenance workflows<br/>[maintenance.py]"]
  node_optimization["Optimization<br/>[optimization.py]"]
end

subgraph group_enterprise["Enterprise services"]
  node_security["Auth and security<br/>[security.py]"]
  node_billing["Tenant billing<br/>[auth_billing.py]"]
  node_enterprise_service["Enterprise workflows<br/>[enterprise.py]"]
  node_saas["SaaS control plane<br/>[saas.py]"]
  node_users["Tenant users<br/>[users.py]"]
end

node_operator_user(("Operator user"))
node_k8s(("Kubernetes cluster"))
node_prometheus(("Prometheus"))
node_opencost(("OpenCost / KubeCost"))

node_operator_user -->|"runs commands"| node_rightsize_cli
node_rightsize_cli -->|"requests plan"| node_recommendation
node_recommend_cli -->|"computes recommendation"| node_recommendation
node_recommendation -->|"queries history"| node_prometheus
node_rightsize_cli -->|"checks policy"| node_policy
node_rightsize_cli -->|"applies or rolls back"| node_execution
node_execution -->|"records actions"| node_audit
node_execution -->|"changes workloads"| node_k8s
node_rightsize_cli -->|"plans capacity"| node_node_analysis
node_autoscaler -->|"reconciles replicas"| node_k8s
node_autoscaler -->|"reads allocation costs"| node_opencost
node_autoscaler -->|"reads resource metrics"| node_prometheus
node_hpa_controller -->|"loads snapshots"| node_metrics_cache
node_hpa_controller -->|"requests decisions"| node_engine_api
node_hpa_controller -->|"resizes workloads"| node_actuator
node_hpa_controller -->|"reconciles pods"| node_k8s
node_engine_api -->|"authenticates requests"| node_security
node_engine_api -->|"dispatches requests"| node_binpacking
node_engine_api -->|"dispatches requests"| node_predictive
node_engine_api -->|"dispatches requests"| node_oom
node_engine_api -->|"dispatches requests"| node_scaling
node_engine_api -->|"dispatches requests"| node_economics
node_engine_api -->|"dispatches requests"| node_greenops
node_engine_api -->|"dispatches requests"| node_cast
node_engine_api -->|"initializes services"| node_bootstrap
node_bootstrap -->|"configures storage"| node_persistence
node_engine_api -->|"dispatches workflows"| node_enterprise_service
node_saas -->|"uses workflows"| node_enterprise_service
node_enterprise_service -->|"uses maintenance"| node_maintenance
node_enterprise_service -->|"uses optimization"| node_optimization
node_enterprise_service -->|"uses billing"| node_billing
node_billing -->|"uses credentials"| node_security
node_billing -->|"resolves users"| node_users
node_users -->|"uses authorization"| node_security

click node_autoscaler "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/operator/internal/controller/kubecostautoscaler_controller.go"
click node_hpa_controller "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/operator/internal/controller/kubecosthpa_controller.go"
click node_metrics_cache "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/operator/internal/controller/kubecosthpa_controller.go"
click node_actuator "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/operator/internal/actuator/resize.go"
click node_node_analysis "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/operator/internal/capacity/capacity.go"
click node_recommend_cli "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/operator/cmd/recommend/main.go"
click node_recommendation "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/operator/internal/recommend/recommend.go"
click node_rightsize_cli "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/operator/cmd/rightsize/main.go"
click node_policy "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/operator/internal/safety/safety.go"
click node_execution "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/operator/internal/execute/execute.go"
click node_audit "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/operator/internal/execute/chain.go"
click node_engine_api "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/server.py"
click node_binpacking "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/binpacking.py"
click node_predictive "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/predictive.py"
click node_oom "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/oom_shield.py"
click node_scaling "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/scaling.py"
click node_economics "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/economics.py"
click node_greenops "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/greenops_guardrail.py"
click node_cast "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/cast_suite.py"
click node_bootstrap "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/bootstrap.py"
click node_persistence "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/persistence.py"
click node_security "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/security.py"
click node_billing "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/auth_billing.py"
click node_enterprise_service "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/enterprise.py"
click node_saas "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/saas.py"
click node_users "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/users.py"
click node_maintenance "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/maintenance.py"
click node_optimization "https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/optimization.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_autoscaler,node_hpa_controller,node_metrics_cache,node_actuator,node_operator_user toneBlue
class node_node_analysis,node_recommend_cli,node_recommendation,node_rightsize_cli,node_policy,node_execution,node_audit toneAmber
class node_engine_api,node_binpacking,node_predictive,node_oom,node_scaling,node_economics,node_greenops,node_cast,node_bootstrap,node_persistence,node_maintenance,node_optimization toneMint
class node_security,node_billing,node_enterprise_service,node_saas,node_users toneRose
class node_k8s,node_prometheus,node_opencost toneIndigo
```

## Components

### Kubernetes operator

- [Replica autoscaler](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/operator/internal/controller/kubecostautoscaler_controller.go): `operator/internal/controller/kubecostautoscaler_controller.go`
- [KubeCostHPA reconciler](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/operator/internal/controller/kubecosthpa_controller.go): `operator/internal/controller/kubecosthpa_controller.go`
- [Metrics and cache](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/operator/internal/controller/kubecosthpa_controller.go): `operator/internal/controller/kubecosthpa_controller.go`
- [Workload actuators](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/operator/internal/actuator/resize.go): `operator/internal/actuator/resize.go`

### Recommendation and CLI

- [Node capacity analysis](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/operator/internal/capacity/capacity.go): `operator/internal/capacity/capacity.go`
- [Read-only recommender](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/operator/cmd/recommend/main.go): `operator/cmd/recommend/main.go`
- [Recommendation logic](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/operator/internal/recommend/recommend.go): `operator/internal/recommend/recommend.go`
- [Rightsize commands](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/operator/cmd/rightsize/main.go): `operator/cmd/rightsize/main.go`
- [Fail-closed policy](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/operator/internal/safety/safety.go): `operator/internal/safety/safety.go`
- [Apply and rollback](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/operator/internal/execute/execute.go): `operator/internal/execute/execute.go`
- [Audit chain](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/operator/internal/execute/chain.go): `operator/internal/execute/chain.go`

### Decision engine

- [HTTP engine API](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/server.py): `engine/kubecost_engine/server.py`
- [Bin packing](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/binpacking.py): `engine/kubecost_engine/binpacking.py`
- [Predictive analysis](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/predictive.py): `engine/kubecost_engine/predictive.py`
- [OOM protection](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/oom_shield.py): `engine/kubecost_engine/oom_shield.py`
- [Scaling decisions](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/scaling.py): `engine/kubecost_engine/scaling.py`
- [Cost economics](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/economics.py): `engine/kubecost_engine/economics.py`
- [GreenOps guardrails](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/greenops_guardrail.py): `engine/kubecost_engine/greenops_guardrail.py`
- [Cluster assessment](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/cast_suite.py): `engine/kubecost_engine/cast_suite.py`
- [Engine bootstrap](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/bootstrap.py): `engine/kubecost_engine/bootstrap.py`
- [Engine persistence](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/persistence.py): `engine/kubecost_engine/persistence.py`
- [Maintenance workflows](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/maintenance.py): `engine/kubecost_engine/maintenance.py`
- [Optimization](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/optimization.py): `engine/kubecost_engine/optimization.py`

### Enterprise services

- [Auth and security](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/security.py): `engine/kubecost_engine/security.py`
- [Tenant billing](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/auth_billing.py): `engine/kubecost_engine/auth_billing.py`
- [Enterprise workflows](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/enterprise.py): `engine/kubecost_engine/enterprise.py`
- [SaaS control plane](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/saas.py): `engine/kubecost_engine/saas.py`
- [Tenant users](https://github.com/santidelacarrera/kubecost_auto_hpa/blob/main/engine/kubecost_engine/users.py): `engine/kubecost_engine/users.py`

### Other components

- **Operator user**
- **Kubernetes cluster**
- **Prometheus**
- **OpenCost / KubeCost**

## Connections

- Operator user → Rightsize commands: runs commands (evidence: `operator/cmd/rightsize/main.go`)
- Rightsize commands → Recommendation logic: requests plan (evidence: `operator/cmd/rightsize/main.go`)
- Read-only recommender → Recommendation logic: computes recommendation (evidence: `operator/cmd/recommend/main.go`)
- Recommendation logic → Prometheus: queries history
- Rightsize commands → Fail-closed policy: checks policy
- Rightsize commands → Apply and rollback: applies or rolls back (evidence: `operator/cmd/rightsize/main.go`)
- Apply and rollback → Audit chain: records actions (evidence: `operator/internal/execute/execute.go`)
- Apply and rollback → Kubernetes cluster: changes workloads
- Rightsize commands → Node capacity analysis: plans capacity (evidence: `operator/cmd/rightsize/main.go`)
- Replica autoscaler → Kubernetes cluster: reconciles replicas (evidence: `operator/internal/controller/kubecostautoscaler_controller.go`)
- Replica autoscaler → OpenCost / KubeCost: reads allocation costs
- Replica autoscaler → Prometheus: reads resource metrics
- KubeCostHPA reconciler → Metrics and cache: loads snapshots (evidence: `operator/internal/controller/kubecosthpa_controller.go`)
- KubeCostHPA reconciler → HTTP engine API: requests decisions (evidence: `operator/internal/controller/kubecosthpa_controller.go`)
- KubeCostHPA reconciler → Workload actuators: resizes workloads
- KubeCostHPA reconciler → Kubernetes cluster: reconciles pods (evidence: `operator/internal/controller/kubecosthpa_controller.go`)
- HTTP engine API → Auth and security: authenticates requests (evidence: `engine/kubecost_engine/server.py`)
- HTTP engine API → Bin packing: dispatches requests (evidence: `engine/kubecost_engine/server.py`)
- HTTP engine API → Predictive analysis: dispatches requests (evidence: `engine/kubecost_engine/server.py`)
- HTTP engine API → OOM protection: dispatches requests (evidence: `engine/kubecost_engine/server.py`)
- HTTP engine API → Scaling decisions: dispatches requests (evidence: `engine/kubecost_engine/server.py`)
- HTTP engine API → Cost economics: dispatches requests (evidence: `engine/kubecost_engine/server.py`)
- HTTP engine API → GreenOps guardrails: dispatches requests (evidence: `engine/kubecost_engine/server.py`)
- HTTP engine API → Cluster assessment: dispatches requests (evidence: `engine/kubecost_engine/server.py`)
- HTTP engine API → Engine bootstrap: initializes services (evidence: `engine/kubecost_engine/server.py`)
- Engine bootstrap → Engine persistence: configures storage (evidence: `engine/kubecost_engine/bootstrap.py`)
- HTTP engine API → Enterprise workflows: dispatches workflows (evidence: `engine/kubecost_engine/server.py`)
- SaaS control plane → Enterprise workflows: uses workflows (evidence: `engine/kubecost_engine/saas.py`)
- Enterprise workflows → Maintenance workflows: uses maintenance (evidence: `engine/kubecost_engine/enterprise.py`)
- Enterprise workflows → Optimization: uses optimization (evidence: `engine/kubecost_engine/enterprise.py`)
- Enterprise workflows → Tenant billing: uses billing (evidence: `engine/kubecost_engine/enterprise.py`)
- Tenant billing → Auth and security: uses credentials (evidence: `engine/kubecost_engine/auth_billing.py`)
- Tenant billing → Tenant users: resolves users (evidence: `engine/kubecost_engine/auth_billing.py`)
- Tenant users → Auth and security: uses authorization (evidence: `engine/kubecost_engine/users.py`)
