Wave Architecture

Wave is built with a cloud-native architecture designed for scalability, reliability, and seamless integration with existing Kubernetes environments. The system consists of five core components deployed across two workloads: a centralized StatefulSet and a distributed DaemonSet.

System Components

Wave deploys as a single StatefulSet pod containing three containers, plus a DaemonSet that runs two containers on every node.

Component Overview

Component	Type	Port	Primary Function
Core	StatefulSet	3024	API server & orchestration
Web Console	StatefulSet	3025	Management UI
Intelligence	StatefulSet	3026	ML engine
Agent	DaemonSet	-	Metrics collection
cAdvisor	DaemonSet	8080	Container metrics

Resource requests are not fixed values; they scale with the size of your cluster. See Resource Requirements below.

StatefulSet Components

Wave's StatefulSet runs three tightly-coupled containers in a single pod:

Wave Core

Port 3024

Kubernetes resource management and API server

Key Responsibilities

Central orchestration of all automation actions
RESTful API for Web Console and external integrations
Cluster resource monitoring and management
Autopilot and Smart Sizing execution
Kubernetes API interaction (scaling, sizing, updates)

Wave Web Console

Port 3025

Browser-based UI for monitoring and configuration

Technology: Node.js web application

Key Responsibilities

Real-time dashboard for cluster metrics
Workload management interface
Configuration and policy management
Insights and recommendations visualization

Wave Intelligence

Port 3026

Machine learning model training and predictions

Technology: Python application using Gunicorn WSGI server

Key Responsibilities

ML model training using historical metrics
Workload pattern prediction
Optimization recommendations
Autopilot decision support

DaemonSet Components (Per Node)

Wave's Agent DaemonSet deploys two containers on every cluster node:

Wave Agent

Collects node-level and pod metrics

Key Responsibilities

Node-level resource monitoring
Pod metrics collection
Host system statistics gathering
Metrics forwarding to Core service
Connects to Core API
Queries local cAdvisor

cAdvisor

Port 8080

Exposes container and system metrics in Prometheus format

Key Responsibilities

Container-level metrics collection
CPU, memory, disk I/O, network monitoring
OOM event tracking
System pressure metrics

Deployment Architecture

Wave deploys within your Kubernetes cluster using standard Kubernetes resources:

Kubernetes Resources

Namespace: wave-autoscale (default, configurable)
StatefulSet: Single replica pod with 3 containers (Core, Web Console, Intelligence)
DaemonSet: Per-node pod with 2 containers (Agent, cAdvisor)
Service: ClusterIP service exposing ports 3024 (Core API), 3025 (Web Console), 3026 (Intelligence), and 3027 (gRPC agent metrics)
ServiceAccounts: Two accounts with distinct RBAC permissions
PersistentVolumeClaim: 40Gi shared storage (default, configurable)
ClusterRoles & ClusterRoleBindings: Custom RBAC for cluster-wide access
SecurityContextConstraints (OpenShift): Priority SCCs for privileged operations

Custom Resources

Wave's Helm chart installs 14 CustomResourceDefinitions (wavek8s.com/v1alpha1) by default (crds.install: true). How you use them depends on the operation mode:

Console Mode (default): you configure Wave through the web console and Wave stores the settings. The CRDs are installed, but you don't author Custom Resources by hand.
CRD Mode: you declare operational settings as Custom Resources in Git and apply them with kubectl or ArgoCD; the console becomes read-only for those settings.

Each CRD carries helm.sh/resource-policy: keep, so your Custom Resources survive a helm uninstall. See CRD Mode for the full list of kinds and the GitOps workflow.

Component Communication

Internal Communication Flow

Agent→cAdvisor

Agent queries cAdvisor metrics endpoint on the same node (localhost:8080)
cAdvisor exposes Prometheus-formatted container metrics
Communication happens entirely within the DaemonSet pod

Agent→Core Service

Agent forwards collected metrics to the Core service over gRPC, the default transport, on port 3027
Uses Kubernetes service DNS: wave-autoscale-svc.wave-autoscale.svc.cluster.local:3027
Agents from all nodes send metrics to the single Core instance

Core↔Intelligence

Both containers share the same PersistentVolume
Intelligence writes ML models to /app/wave-intelligence/data
Core reads models and stores training data in /app/autopilot/data
Enables tight integration without network overhead

Web Console↔Core

Web Console communicates with Core via localhost (same pod on port 3024)
Core API provides data for dashboard visualization
Efficient communication without network traversal

Data Flow

📊

Metrics Collection

cAdvisor collects container-level metrics from the local node
Agent queries cAdvisor and enriches with node metadata
Agent forwards metrics to Core service

💾

Storage & Analysis

Core receives metrics from all nodes
Historical metrics stored in persistent volume
Intelligence component trains ML models using historical data

🧠

Decision Making

Core analyzes real-time and historical metrics
Intelligence provides ML-based predictions and recommendations
Core determines optimal scaling and sizing actions

⚡

Execution

Core executes changes via Kubernetes API
Creates/updates HorizontalPodAutoscalers
Patches pod resources (CPU/memory requests/limits)
Manages PersistentVolume expansion

🔄

Feedback Loop

Results of actions are monitored via continued metrics collection
Intelligence models continuously retrain on new data
System learns and improves optimization over time

Storage Configuration

Wave's StatefulSet uses a single shared PersistentVolumeClaim (default 40Gi, ReadWriteOnce). All three containers mount it: Core at /app/core/data, Intelligence at /app/wave-intelligence/data, and Autopilot at /app/autopilot/data (models + stores). The PVC is retained when the StatefulSet is deleted or scaled down.

Platform Compatibility

Runs on any conformant Kubernetes 1.26+, including Amazon EKS, Google GKE, Microsoft AKS, Red Hat OpenShift 4.13+, and self-managed clusters. See Installation Guides for platform-specific setup.

Integration Points

Wave integrates with your existing Kubernetes ecosystem:

📊
Metrics Export: Prometheus-compatible metrics from Core service
🔔
Alerting: Webhook-based alert notifications
🕸️
Service Mesh: Optional Istio integration with dedicated admin role
🔌
API Access: RESTful API on port 3024 for external automation
🔐
Authentication: Kubernetes RBAC-based access control

Resource Requirements

Wave's resource requests are not fixed values. They scale with the size of your cluster: the number of nodes, the number of pods and workloads Wave manages, and how much metric history it retains. Size the StatefulSet up for larger clusters and down for smaller ones; the per-node DaemonSet footprint grows with node count.

StatefulSet (Core, Intelligence, Web Console): scales primarily with the number of workloads and the volume of metrics Wave analyzes. Core and Intelligence carry most of the load.
DaemonSet (Agent, cAdvisor): a small, roughly constant per-node footprint that grows linearly with node count.
Storage: the shared PVC grows with metric retention and cluster size.

For concrete starting points by cluster size (for example, 300 vCPUs vs 2000 vCPUs), see the resource sizing guidelines in Helm Values. Set requests and limits per component through the spec.<component>.resources Helm values.

High Availability Considerations

StatefulSet runs as a single replica by design: Core, Web Console, and Intelligence share one Pod and one PVC.
DaemonSet uses system-node-critical priority for guaranteed scheduling on every node.
The PVC is retained on uninstall; back it up with standard Kubernetes tools to enable disaster recovery.

Wave vs HPA, VPA, and Prometheus Important: Before You Begin