# kubernetes-sigs/descheduler architecture

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

- Interactive diagram: https://gitdiagram.com/kubernetes-sigs/descheduler
- Repository: https://github.com/kubernetes-sigs/descheduler

## Overview

Descheduler is a Kubernetes workload rebalancer: it evaluates already-running pods against a configurable policy and evicts eligible pods; Kubernetes’ default scheduler handles replacements. The main flow is server startup and policy setup, strategy evaluation through framework profiles and plugins, then guarded eviction through the Kubernetes API. The README also documents utilization-based strategies, Prometheus and metrics-provider inputs, and metrics exposure. Several orchestration and integration files were not sampled, so uncertain internal links are omitted or marked unverified.

Main entry points: [`pkg/descheduler/scheme/scheme.go`](https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/descheduler/scheme/scheme.go) (API scheme), [`pkg/descheduler/evictions/evictions.go`](https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/descheduler/evictions/evictions.go) (Pod eviction), [`cmd/descheduler/app/server.go`](https://github.com/kubernetes-sigs/descheduler/blob/master/cmd/descheduler/app/server.go) (CLI command), [`pkg/framework/profile/profile.go`](https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/framework/profile/profile.go) (Profile execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and policy"]
  node_command["CLI command<br/>[server.go]"]
  node_options["Server options<br/>[options.go]"]
  node_policy["Policy API<br/>[types.go]"]
  node_scheme["API scheme<br/>[scheme.go]"]
end

subgraph group_framework["Strategy framework"]
  node_runner["Descheduler cycle<br/>[descheduler.go]"]
  node_profile["Profile execution<br/>[profile.go]"]
  node_registry["Plugin registry<br/>[pluginregistry.go]"]
end

subgraph group_strategies["Descheduling strategies"]
  node_default_evictor["Default evictor<br/>[defaultevictor.go]"]
  node_utilization["Node utilization"]
  node_usage["Usage clients<br/>[usageclients.go]"]
  node_pod_lifetime["Pod lifetime<br/>[pod_lifetime.go]"]
  node_duplicates["Duplicate pods"]
  node_failed["Failed pods<br/>[failedpods.go]"]
  node_topology["Topology spread"]
  node_affinity["Affinity and taints<br/>[node_affinity.go]"]
end

subgraph group_cluster["Cluster operations"]
  node_evictor["Pod eviction<br/>[evictions.go]"]
  node_clients["Kubernetes clients<br/>[client.go]"]
  node_sandbox["Client sandbox"]
  node_promcontroller["Prometheus controller"]
  node_metrics["Utilization metrics"]
  node_telemetry["Exported metrics<br/>[metrics.go]"]
end

node_operator(("Operator / deployment"))
node_kubernetes[("Kubernetes API")]
node_prometheus[("Prometheus")]

node_operator -->|"starts"| node_command
node_command -->|"configures"| node_options
node_options -->|"loads scheme"| node_scheme
node_command -->|"runs"| node_runner
node_runner -.->|"dispatches cycle"| node_profile
node_policy -.->|"configures"| node_profile
node_profile -->|"uses registry"| node_registry
node_profile -->|"invokes eviction"| node_evictor
node_scheme -->|"registers"| node_default_evictor
node_scheme -->|"registers"| node_utilization
node_scheme -->|"registers"| node_pod_lifetime
node_scheme -->|"registers"| node_duplicates
node_scheme -->|"registers"| node_failed
node_scheme -->|"registers"| node_topology
node_scheme -->|"registers"| node_affinity
node_utilization -->|"reads usage"| node_usage
node_usage -->|"queries metrics"| node_metrics
node_usage -.->|"queries optionally"| node_prometheus
node_promcontroller -->|"creates client"| node_clients
node_clients -->|"connects"| node_prometheus
node_evictor -->|"evicts pods"| node_kubernetes
node_runner -.->|"reads cluster"| node_kubernetes
node_command -->|"serves metrics"| node_telemetry
node_evictor -->|"records evictions"| node_telemetry
node_default_evictor -->|"filters pods"| node_evictor
node_pod_lifetime -->|"requests eviction"| node_evictor
node_duplicates -->|"requests eviction"| node_evictor
node_failed -->|"requests eviction"| node_evictor
node_topology -->|"requests eviction"| node_evictor

click node_command "https://github.com/kubernetes-sigs/descheduler/blob/master/cmd/descheduler/app/server.go"
click node_options "https://github.com/kubernetes-sigs/descheduler/blob/master/cmd/descheduler/app/options/options.go"
click node_policy "https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/api/v1alpha2/types.go"
click node_scheme "https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/descheduler/scheme/scheme.go"
click node_runner "https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/descheduler/descheduler.go"
click node_profile "https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/framework/profile/profile.go"
click node_registry "https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/framework/pluginregistry/pluginregistry.go"
click node_default_evictor "https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/framework/plugins/defaultevictor/defaultevictor.go"
click node_utilization "https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/framework/plugins/nodeutilization/highnodeutilization.go"
click node_usage "https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/framework/plugins/nodeutilization/usageclients.go"
click node_pod_lifetime "https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/framework/plugins/podlifetime/pod_lifetime.go"
click node_duplicates "https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/framework/plugins/removeduplicates/removeduplicates.go"
click node_failed "https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/framework/plugins/removefailedpods/failedpods.go"
click node_topology "https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/framework/plugins/removepodsviolatingtopologyspreadconstraint/topologyspreadconstraint.go"
click node_affinity "https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/framework/plugins/removepodsviolatingnodeaffinity/node_affinity.go"
click node_evictor "https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/descheduler/evictions/evictions.go"
click node_clients "https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/descheduler/client/client.go"
click node_sandbox "https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/descheduler/kubeclientsandbox.go"
click node_promcontroller "https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/descheduler/prom_client_controller.go"
click node_metrics "https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/descheduler/metricscollector/metricscollector.go"
click node_telemetry "https://github.com/kubernetes-sigs/descheduler/blob/master/metrics/metrics.go"

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_command,node_options,node_policy,node_scheme toneBlue
class node_runner,node_profile,node_registry,node_kubernetes,node_prometheus toneAmber
class node_default_evictor,node_utilization,node_usage,node_pod_lifetime,node_duplicates,node_failed,node_topology,node_affinity toneMint
class node_evictor,node_clients,node_sandbox,node_promcontroller,node_metrics,node_telemetry toneRose
class node_operator toneIndigo
```

## Components

### Startup and policy

- [CLI command](https://github.com/kubernetes-sigs/descheduler/blob/master/cmd/descheduler/app/server.go): `cmd/descheduler/app/server.go`
- [Server options](https://github.com/kubernetes-sigs/descheduler/blob/master/cmd/descheduler/app/options/options.go): `cmd/descheduler/app/options/options.go`
- [Policy API](https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/api/v1alpha2/types.go): `pkg/api/v1alpha2/types.go`
- [API scheme](https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/descheduler/scheme/scheme.go): `pkg/descheduler/scheme/scheme.go`

### Strategy framework

- [Descheduler cycle](https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/descheduler/descheduler.go): `pkg/descheduler/descheduler.go`
- [Profile execution](https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/framework/profile/profile.go): `pkg/framework/profile/profile.go`
- [Plugin registry](https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/framework/pluginregistry/pluginregistry.go): `pkg/framework/pluginregistry/pluginregistry.go`

### Descheduling strategies

- [Default evictor](https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/framework/plugins/defaultevictor/defaultevictor.go): `pkg/framework/plugins/defaultevictor/defaultevictor.go`
- [Node utilization](https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/framework/plugins/nodeutilization/highnodeutilization.go): `pkg/framework/plugins/nodeutilization/highnodeutilization.go`
- [Usage clients](https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/framework/plugins/nodeutilization/usageclients.go): `pkg/framework/plugins/nodeutilization/usageclients.go`
- [Pod lifetime](https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/framework/plugins/podlifetime/pod_lifetime.go): `pkg/framework/plugins/podlifetime/pod_lifetime.go`
- [Duplicate pods](https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/framework/plugins/removeduplicates/removeduplicates.go): `pkg/framework/plugins/removeduplicates/removeduplicates.go`
- [Failed pods](https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/framework/plugins/removefailedpods/failedpods.go): `pkg/framework/plugins/removefailedpods/failedpods.go`
- [Topology spread](https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/framework/plugins/removepodsviolatingtopologyspreadconstraint/topologyspreadconstraint.go): `pkg/framework/plugins/removepodsviolatingtopologyspreadconstraint/topologyspreadconstraint.go`
- [Affinity and taints](https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/framework/plugins/removepodsviolatingnodeaffinity/node_affinity.go): `pkg/framework/plugins/removepodsviolatingnodeaffinity/node_affinity.go`

### Cluster operations

- [Pod eviction](https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/descheduler/evictions/evictions.go): `pkg/descheduler/evictions/evictions.go`
- [Kubernetes clients](https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/descheduler/client/client.go): `pkg/descheduler/client/client.go`
- [Client sandbox](https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/descheduler/kubeclientsandbox.go): `pkg/descheduler/kubeclientsandbox.go`
- [Prometheus controller](https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/descheduler/prom_client_controller.go): `pkg/descheduler/prom_client_controller.go`
- [Utilization metrics](https://github.com/kubernetes-sigs/descheduler/blob/master/pkg/descheduler/metricscollector/metricscollector.go): `pkg/descheduler/metricscollector/metricscollector.go`
- [Exported metrics](https://github.com/kubernetes-sigs/descheduler/blob/master/metrics/metrics.go): `metrics/metrics.go`

### Other components

- **Operator / deployment**
- **Kubernetes API**
- **Prometheus**

## Connections

- Operator / deployment → CLI command: starts
- CLI command → Server options: configures (evidence: `cmd/descheduler/app/server.go`)
- Server options → API scheme: loads scheme (evidence: `cmd/descheduler/app/options/options.go`)
- CLI command → Descheduler cycle: runs (evidence: `cmd/descheduler/app/server.go`)
- Descheduler cycle → Profile execution: dispatches cycle
- Policy API → Profile execution: configures
- Profile execution → Plugin registry: uses registry (evidence: `pkg/framework/profile/profile.go`)
- Profile execution → Pod eviction: invokes eviction (evidence: `pkg/framework/profile/profile.go`)
- API scheme → Default evictor: registers (evidence: `pkg/descheduler/scheme/scheme.go`)
- API scheme → Node utilization: registers (evidence: `pkg/descheduler/scheme/scheme.go`)
- API scheme → Pod lifetime: registers (evidence: `pkg/descheduler/scheme/scheme.go`)
- API scheme → Duplicate pods: registers (evidence: `pkg/descheduler/scheme/scheme.go`)
- API scheme → Failed pods: registers (evidence: `pkg/descheduler/scheme/scheme.go`)
- API scheme → Topology spread: registers (evidence: `pkg/descheduler/scheme/scheme.go`)
- API scheme → Affinity and taints: registers (evidence: `pkg/descheduler/scheme/scheme.go`)
- Node utilization → Usage clients: reads usage (evidence: `pkg/framework/plugins/nodeutilization/usageclients.go`)
- Usage clients → Utilization metrics: queries metrics (evidence: `pkg/framework/plugins/nodeutilization/usageclients.go`)
- Usage clients → Prometheus: queries optionally
- Prometheus controller → Kubernetes clients: creates client (evidence: `pkg/descheduler/prom_client_controller.go`)
- Kubernetes clients → Prometheus: connects (evidence: `pkg/descheduler/client/client.go`)
- Pod eviction → Kubernetes API: evicts pods
- Descheduler cycle → Kubernetes API: reads cluster
- CLI command → Exported metrics: serves metrics (evidence: `cmd/descheduler/app/server.go`)
- Pod eviction → Exported metrics: records evictions (evidence: `pkg/descheduler/evictions/evictions.go`)
- Default evictor → Pod eviction: filters pods (evidence: `pkg/framework/plugins/defaultevictor/defaultevictor.go`)
- Pod lifetime → Pod eviction: requests eviction
- Duplicate pods → Pod eviction: requests eviction (evidence: `pkg/framework/plugins/removeduplicates/removeduplicates.go`)
- Failed pods → Pod eviction: requests eviction (evidence: `pkg/framework/plugins/removefailedpods/failedpods.go`)
- Topology spread → Pod eviction: requests eviction (evidence: `pkg/framework/plugins/removepodsviolatingtopologyspreadconstraint/topologyspreadconstraint.go`)
