promzeus/kubeequalizer repository overview

⁠Repository Overview

KubeEqualizer is a lightweight Kubernetes utility designed to ensure balanced deployment replicas across multiple namespaces or availability zones.

In complex multi-zone Kubernetes clusters, replicas can become unevenly distributed due to autoscaling or manual interventions, causing some zones to run excessive pods while others have too few. This leads to performance degradation, increased cross-zone network traffic, and suboptimal resource utilization.

KubeEqualizer periodically checks replica counts in configured namespaces for a specified deployment and automatically adjusts them to maintain an even distribution based on a configurable imbalance threshold. This tool helps optimize workload distribution, reduce latency, and improve cluster efficiency in multi-zone or multi-namespace Kubernetes environments.

---

⁠Environment Variables

• NAMESPACES
  A comma-separated list of Kubernetes namespaces to monitor and balance deployment replicas within.
  Example: "axis-stage,axis-stage-1b"
  Default: "axis-stage,axis-stage-1b"
  Use this to specify which namespaces (zones) you want KubeEqualizer to consider when balancing replicas.

• DEPLOYMENT
  The name of the Kubernetes deployment whose replicas you want to balance across the specified namespaces.
  Example: "axis-gam"
  Default: "axis-gam"
  Set this to the exact deployment name you want KubeEqualizer to manage.

• INTERVAL
  The frequency, in seconds, at which KubeEqualizer will poll the Kubernetes API to check the current replica distribution and perform balancing if needed.
  Example: "300" (which means every 5 minutes)
  Default: "300"
  Adjust this to control how often balancing decisions are made; shorter intervals mean quicker adjustments but higher API load.

• THRESHOLD
  A decimal value between 0 and 1 representing the minimum imbalance ratio that triggers balancing.
  Example: "0.3" means balancing will trigger when the difference between max and min replicas across namespaces exceeds 30% of the average.
  Default: "0.3"
  Use this to control the sensitivity of balancing — lower values make the tool react to smaller imbalances.