# karmada-io/karmada architecture

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

- Interactive diagram: https://gitdiagram.com/karmada-io/karmada
- Repository: https://github.com/karmada-io/karmada

## Overview

Karmada is a Kubernetes-native, multi-cluster orchestration control plane. The principal workflow is that users submit workloads and propagation policies to the control-plane API; controllers and the scheduler select member clusters, create per-cluster Work objects, and the execution controller applies those resources to member-cluster APIs. Separate controller branches support cluster lifecycle and health, recovery, scaling, and cross-cluster services; search and the operator provide additional product capabilities. The workflow edges follow the README; sampled source corroborates execution, cluster, search, and scaling responsibilities, but does not expose every controller’s wiring.

Main entry points: [`cmd/controller-manager/app/controllermanager.go`](https://github.com/karmada-io/karmada/blob/master/cmd/controller-manager/app/controllermanager.go) (Controller Manager), [`pkg/aggregatedapiserver/apiserver.go`](https://github.com/karmada-io/karmada/blob/master/pkg/aggregatedapiserver/apiserver.go) (Karmada API), [`pkg/apis/work/v1alpha2/binding_types.go`](https://github.com/karmada-io/karmada/blob/master/pkg/apis/work/v1alpha2/binding_types.go) (Resource Bindings), [`pkg/controllers/binding/binding_controller.go`](https://github.com/karmada-io/karmada/blob/master/pkg/controllers/binding/binding_controller.go) (Binding Controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control Plane"]
  node_api["Karmada API<br/>[apiserver.go]"]
  node_etcd[("Control-Plane etcd")]
  node_apis["Karmada API Types"]
  node_manager["Controller Manager"]
end

subgraph group_propagation["Propagation"]
  node_scheduler["Scheduler<br/>[scheduler.go]"]
  node_bindingctl["Binding Controller"]
  node_bindings["Resource Bindings<br/>[binding_types.go]"]
  node_works["Work Objects<br/>[work_types.go]"]
  node_distributor["Dependency Distribution"]
  node_interpreter["Resource Interpreter<br/>[interpreter.go]"]
end

subgraph group_members["Member Clusters"]
  node_clusterctl["Cluster Controller"]
  node_statusctl["Cluster Status"]
  node_execution["Execution Controller"]
  node_member["Member Cluster APIs"]
end

subgraph group_capabilities["Product Capabilities"]
  node_recovery["Failover Controllers"]
  node_autoscaling["Federated Autoscaling"]
  node_mcs["Multi-Cluster Services<br/>[mcs_controller.go]"]
  node_search["Multi-Cluster Search<br/>[apiserver.go]"]
  node_searchstore[("Search Storage<br/>[search.go]")]
end

subgraph group_operations["Operations"]
  node_operator["Karmada Operator<br/>[controller.go]"]
  node_ctl["karmadactl<br/>[karmadactl.go]"]
end

node_user(("Kubernetes User"))

node_user -->|"submits resources"| node_api
node_api -->|"stores objects"| node_etcd
node_api -->|"serves types"| node_apis
node_manager -->|"watches objects"| node_api
node_manager -->|"runs controller"| node_clusterctl
node_manager -->|"runs controller"| node_statusctl
node_manager -->|"runs controller"| node_bindingctl
node_manager -->|"runs controller"| node_execution
node_clusterctl -->|"manages clusters"| node_member
node_statusctl -->|"checks health"| node_member
node_scheduler -->|"selects clusters"| node_bindings
node_bindingctl -->|"creates bindings"| node_bindings
node_bindingctl -->|"creates per-cluster work"| node_works
node_execution -->|"watches work"| node_works
node_execution -->|"applies resources"| node_member
node_distributor -->|"distributes dependencies"| node_member
node_interpreter -.->|"provides interpretation"| node_manager
node_recovery -->|"handles failover"| node_bindings
node_autoscaling -->|"scales workloads"| node_member
node_mcs -->|"propagates services"| node_bindings
node_search -->|"queries resources"| node_searchstore
node_search -->|"collects cluster data"| node_member
node_operator -->|"manages control plane"| node_api
node_ctl -->|"administers resources"| node_api

click node_api "https://github.com/karmada-io/karmada/blob/master/pkg/aggregatedapiserver/apiserver.go"
click node_apis "https://github.com/karmada-io/karmada/tree/master/pkg/apis"
click node_manager "https://github.com/karmada-io/karmada/blob/master/cmd/controller-manager/app/controllermanager.go"
click node_clusterctl "https://github.com/karmada-io/karmada/blob/master/pkg/controllers/cluster/cluster_controller.go"
click node_statusctl "https://github.com/karmada-io/karmada/blob/master/pkg/controllers/status/cluster_status_controller.go"
click node_scheduler "https://github.com/karmada-io/karmada/blob/master/pkg/scheduler/scheduler.go"
click node_bindingctl "https://github.com/karmada-io/karmada/blob/master/pkg/controllers/binding/binding_controller.go"
click node_bindings "https://github.com/karmada-io/karmada/blob/master/pkg/apis/work/v1alpha2/binding_types.go"
click node_works "https://github.com/karmada-io/karmada/blob/master/pkg/apis/work/v1alpha1/work_types.go"
click node_execution "https://github.com/karmada-io/karmada/blob/master/pkg/controllers/execution/execution_controller.go"
click node_distributor "https://github.com/karmada-io/karmada/blob/master/pkg/dependenciesdistributor/dependencies_distributor.go"
click node_interpreter "https://github.com/karmada-io/karmada/blob/master/pkg/resourceinterpreter/interpreter.go"
click node_recovery "https://github.com/karmada-io/karmada/tree/master/pkg/controllers/applicationfailover"
click node_autoscaling "https://github.com/karmada-io/karmada/blob/master/pkg/controllers/federatedhpa/federatedhpa_controller.go"
click node_mcs "https://github.com/karmada-io/karmada/blob/master/pkg/controllers/multiclusterservice/mcs_controller.go"
click node_search "https://github.com/karmada-io/karmada/blob/master/pkg/search/apiserver.go"
click node_searchstore "https://github.com/karmada-io/karmada/blob/master/pkg/registry/search/storage/search.go"
click node_operator "https://github.com/karmada-io/karmada/blob/master/operator/pkg/controller/karmada/controller.go"
click node_ctl "https://github.com/karmada-io/karmada/blob/master/pkg/karmadactl/karmadactl.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_api,node_etcd,node_apis,node_manager,node_user toneBlue
class node_scheduler,node_bindingctl,node_bindings,node_works,node_distributor,node_interpreter toneAmber
class node_clusterctl,node_statusctl,node_execution,node_member toneMint
class node_recovery,node_autoscaling,node_mcs,node_search,node_searchstore toneRose
class node_operator,node_ctl toneIndigo
```

## Components

### Control Plane

- [Karmada API](https://github.com/karmada-io/karmada/blob/master/pkg/aggregatedapiserver/apiserver.go): `pkg/aggregatedapiserver/apiserver.go`
- **Control-Plane etcd**
- [Karmada API Types](https://github.com/karmada-io/karmada/tree/master/pkg/apis): `pkg/apis`
- [Controller Manager](https://github.com/karmada-io/karmada/blob/master/cmd/controller-manager/app/controllermanager.go): `cmd/controller-manager/app/controllermanager.go`

### Propagation

- [Scheduler](https://github.com/karmada-io/karmada/blob/master/pkg/scheduler/scheduler.go): `pkg/scheduler/scheduler.go`
- [Binding Controller](https://github.com/karmada-io/karmada/blob/master/pkg/controllers/binding/binding_controller.go): `pkg/controllers/binding/binding_controller.go`
- [Resource Bindings](https://github.com/karmada-io/karmada/blob/master/pkg/apis/work/v1alpha2/binding_types.go): `pkg/apis/work/v1alpha2/binding_types.go`
- [Work Objects](https://github.com/karmada-io/karmada/blob/master/pkg/apis/work/v1alpha1/work_types.go): `pkg/apis/work/v1alpha1/work_types.go`
- [Dependency Distribution](https://github.com/karmada-io/karmada/blob/master/pkg/dependenciesdistributor/dependencies_distributor.go): `pkg/dependenciesdistributor/dependencies_distributor.go`
- [Resource Interpreter](https://github.com/karmada-io/karmada/blob/master/pkg/resourceinterpreter/interpreter.go): `pkg/resourceinterpreter/interpreter.go`

### Member Clusters

- [Cluster Controller](https://github.com/karmada-io/karmada/blob/master/pkg/controllers/cluster/cluster_controller.go): `pkg/controllers/cluster/cluster_controller.go`
- [Cluster Status](https://github.com/karmada-io/karmada/blob/master/pkg/controllers/status/cluster_status_controller.go): `pkg/controllers/status/cluster_status_controller.go`
- [Execution Controller](https://github.com/karmada-io/karmada/blob/master/pkg/controllers/execution/execution_controller.go): `pkg/controllers/execution/execution_controller.go`
- **Member Cluster APIs**

### Product Capabilities

- [Failover Controllers](https://github.com/karmada-io/karmada/tree/master/pkg/controllers/applicationfailover): `pkg/controllers/applicationfailover`
- [Federated Autoscaling](https://github.com/karmada-io/karmada/blob/master/pkg/controllers/federatedhpa/federatedhpa_controller.go): `pkg/controllers/federatedhpa/federatedhpa_controller.go`
- [Multi-Cluster Services](https://github.com/karmada-io/karmada/blob/master/pkg/controllers/multiclusterservice/mcs_controller.go): `pkg/controllers/multiclusterservice/mcs_controller.go`
- [Multi-Cluster Search](https://github.com/karmada-io/karmada/blob/master/pkg/search/apiserver.go): `pkg/search/apiserver.go`
- [Search Storage](https://github.com/karmada-io/karmada/blob/master/pkg/registry/search/storage/search.go): `pkg/registry/search/storage/search.go`

### Operations

- [Karmada Operator](https://github.com/karmada-io/karmada/blob/master/operator/pkg/controller/karmada/controller.go): `operator/pkg/controller/karmada/controller.go`
- [karmadactl](https://github.com/karmada-io/karmada/blob/master/pkg/karmadactl/karmadactl.go): `pkg/karmadactl/karmadactl.go`

### Other components

- **Kubernetes User**

## Connections

- Kubernetes User → Karmada API: submits resources
- Karmada API → Control-Plane etcd: stores objects
- Karmada API → Karmada API Types: serves types
- Controller Manager → Karmada API: watches objects
- Controller Manager → Cluster Controller: runs controller
- Controller Manager → Cluster Status: runs controller
- Controller Manager → Binding Controller: runs controller
- Controller Manager → Execution Controller: runs controller
- Cluster Controller → Member Cluster APIs: manages clusters
- Cluster Status → Member Cluster APIs: checks health
- Scheduler → Resource Bindings: selects clusters
- Binding Controller → Resource Bindings: creates bindings
- Binding Controller → Work Objects: creates per-cluster work
- Execution Controller → Work Objects: watches work
- Execution Controller → Member Cluster APIs: applies resources
- Dependency Distribution → Member Cluster APIs: distributes dependencies
- Resource Interpreter → Controller Manager: provides interpretation
- Failover Controllers → Resource Bindings: handles failover
- Federated Autoscaling → Member Cluster APIs: scales workloads
- Multi-Cluster Services → Resource Bindings: propagates services
- Multi-Cluster Search → Search Storage: queries resources
- Multi-Cluster Search → Member Cluster APIs: collects cluster data
- Karmada Operator → Karmada API: manages control plane
- karmadactl → Karmada API: administers resources