# kubesphere/kubekey architecture

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

- Interactive diagram: https://gitdiagram.com/kubesphere/kubekey
- Repository: https://github.com/kubesphere/kubekey

## Overview

KubeKey is a task-flow automation tool, with Kubernetes installation and lifecycle management as a major use case. A user can invoke a built-in cluster workflow from the CLI; task templates and playbooks are executed through the task engine, which uses modules, variables, and node connectors to perform work. The repository also provides Kubernetes controllers for cloud-native batch management and a Web API/UI. Several subsystem links below are documented rather than source-verified: unsampled implementation details are not inferred as call relationships.

Main entry points: [`cmd/controller-manager/controller_manager.go`](https://github.com/kubesphere/kubekey/blob/main/cmd/controller-manager/controller_manager.go) (Controller Manager), [`pkg/controllers/core/playbook_controller.go`](https://github.com/kubesphere/kubekey/blob/main/pkg/controllers/core/playbook_controller.go) (Playbook Controller), [`pkg/proxy/internal/file_storage.go`](https://github.com/kubesphere/kubekey/blob/main/pkg/proxy/internal/file_storage.go) (Resource Storage), [`pkg/executor/task_executor.go`](https://github.com/kubesphere/kubekey/blob/main/pkg/executor/task_executor.go) (Task Execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_cli["KK CLI<br/>[root.go]"]
  node_builtin["Cluster Workflows"]
  node_web["Web API and UI<br/>[service.go]"]
end

subgraph group_workflow["Task Workflow"]
  node_projects["Task Projects<br/>[project.go]"]
  node_playbooks["Playbook Model<br/>[playbook.go]"]
  node_converter["Task Converter<br/>[converter.go]"]
end

subgraph group_runtime["Execution Runtime"]
  node_execution["Task Execution<br/>[task_executor.go]"]
  node_modules["Task Modules<br/>[module.go]"]
  node_variables["Variables<br/>[variable.go]"]
  node_connectors["Node Connectors<br/>[connector.go]"]
end

subgraph group_cluster["Cluster Management"]
  node_playbook_controller["Playbook Controller"]
  node_inventory_controller["Inventory Controller"]
  node_cluster_controller["KKCluster Controller"]
  node_machine_controller["KKMachine Controller"]
  node_controller_manager["Controller Manager"]
end

subgraph group_service["API and Storage"]
  node_web_handlers["Web Handlers<br/>[resources.go]"]
  node_proxy["Resource Proxy<br/>[router.go]"]
  node_proxy_storage[("Resource Storage<br/>[file_storage.go]")]
  node_playbook_storage[("Playbook Storage<br/>[storage.go]")]
  node_inventory_storage[("Inventory Storage<br/>[storage.go]")]
  node_task_storage[("Task Storage<br/>[storage.go]")]
end

node_user(("Operator"))
node_kubernetes[("Kubernetes API")]

node_user -->|"invokes"| node_cli
node_cli -.->|"selects workflow"| node_builtin
node_user -->|"uses UI"| node_web
node_builtin -.->|"loads templates"| node_projects
node_projects -->|"uses model"| node_playbooks
node_execution -->|"converts tasks"| node_converter
node_execution -->|"runs modules"| node_modules
node_execution -->|"resolves variables"| node_variables
node_web -->|"routes requests"| node_web_handlers
node_web_handlers -->|"uses connectors"| node_connectors
node_controller_manager -->|"registers"| node_playbook_controller
node_controller_manager -->|"registers"| node_inventory_controller
node_controller_manager -->|"registers"| node_cluster_controller
node_controller_manager -->|"registers"| node_machine_controller
node_playbook_controller -->|"creates pods"| node_kubernetes
node_inventory_controller -->|"creates playbooks"| node_playbook_controller
node_cluster_controller -->|"manages inventory"| node_inventory_controller
node_machine_controller -->|"creates playbooks"| node_playbook_controller
node_proxy -.->|"uses file storage"| node_proxy_storage
node_playbook_storage -.->|"may persist locally"| node_proxy_storage
node_inventory_storage -.->|"may persist locally"| node_proxy_storage
node_task_storage -.->|"stores tasks locally"| node_proxy_storage

click node_cli "https://github.com/kubesphere/kubekey/blob/main/cmd/kk/app/root.go"
click node_builtin "https://github.com/kubesphere/kubekey/tree/main/cmd/kk/app/builtin"
click node_web "https://github.com/kubesphere/kubekey/blob/main/pkg/web/service.go"
click node_projects "https://github.com/kubesphere/kubekey/blob/main/pkg/project/project.go"
click node_playbooks "https://github.com/kubesphere/kubekey/blob/main/api/project/v1/playbook.go"
click node_converter "https://github.com/kubesphere/kubekey/blob/main/pkg/converter/converter.go"
click node_execution "https://github.com/kubesphere/kubekey/blob/main/pkg/executor/task_executor.go"
click node_modules "https://github.com/kubesphere/kubekey/blob/main/pkg/modules/module.go"
click node_variables "https://github.com/kubesphere/kubekey/blob/main/pkg/variable/variable.go"
click node_connectors "https://github.com/kubesphere/kubekey/blob/main/pkg/connector/connector.go"
click node_playbook_controller "https://github.com/kubesphere/kubekey/blob/main/pkg/controllers/core/playbook_controller.go"
click node_inventory_controller "https://github.com/kubesphere/kubekey/blob/main/pkg/controllers/infrastructure/inventory_controller.go"
click node_cluster_controller "https://github.com/kubesphere/kubekey/blob/main/pkg/controllers/infrastructure/kkcluster_controller.go"
click node_machine_controller "https://github.com/kubesphere/kubekey/blob/main/pkg/controllers/infrastructure/kkmachine_controller.go"
click node_controller_manager "https://github.com/kubesphere/kubekey/blob/main/cmd/controller-manager/controller_manager.go"
click node_web_handlers "https://github.com/kubesphere/kubekey/blob/main/pkg/web/handler/resources.go"
click node_proxy "https://github.com/kubesphere/kubekey/blob/main/pkg/proxy/router.go"
click node_proxy_storage "https://github.com/kubesphere/kubekey/blob/main/pkg/proxy/internal/file_storage.go"
click node_playbook_storage "https://github.com/kubesphere/kubekey/blob/main/pkg/proxy/resources/playbook/storage.go"
click node_inventory_storage "https://github.com/kubesphere/kubekey/blob/main/pkg/proxy/resources/inventory/storage.go"
click node_task_storage "https://github.com/kubesphere/kubekey/blob/main/pkg/proxy/resources/task/storage.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_cli,node_builtin,node_web toneBlue
class node_projects,node_playbooks,node_converter,node_kubernetes toneAmber
class node_execution,node_modules,node_variables,node_connectors toneMint
class node_playbook_controller,node_inventory_controller,node_cluster_controller,node_machine_controller,node_controller_manager toneRose
class node_web_handlers,node_proxy,node_proxy_storage,node_playbook_storage,node_inventory_storage,node_task_storage,node_user toneIndigo
```

## Components

### User Interfaces

- [KK CLI](https://github.com/kubesphere/kubekey/blob/main/cmd/kk/app/root.go): `cmd/kk/app/root.go`
- [Cluster Workflows](https://github.com/kubesphere/kubekey/tree/main/cmd/kk/app/builtin): `cmd/kk/app/builtin`
- [Web API and UI](https://github.com/kubesphere/kubekey/blob/main/pkg/web/service.go): `pkg/web/service.go`

### Task Workflow

- [Task Projects](https://github.com/kubesphere/kubekey/blob/main/pkg/project/project.go): `pkg/project/project.go`
- [Playbook Model](https://github.com/kubesphere/kubekey/blob/main/api/project/v1/playbook.go): `api/project/v1/playbook.go`
- [Task Converter](https://github.com/kubesphere/kubekey/blob/main/pkg/converter/converter.go): `pkg/converter/converter.go`

### Execution Runtime

- [Task Execution](https://github.com/kubesphere/kubekey/blob/main/pkg/executor/task_executor.go): `pkg/executor/task_executor.go`
- [Task Modules](https://github.com/kubesphere/kubekey/blob/main/pkg/modules/module.go): `pkg/modules/module.go`
- [Variables](https://github.com/kubesphere/kubekey/blob/main/pkg/variable/variable.go): `pkg/variable/variable.go`
- [Node Connectors](https://github.com/kubesphere/kubekey/blob/main/pkg/connector/connector.go): `pkg/connector/connector.go`

### Cluster Management

- [Playbook Controller](https://github.com/kubesphere/kubekey/blob/main/pkg/controllers/core/playbook_controller.go): `pkg/controllers/core/playbook_controller.go`
- [Inventory Controller](https://github.com/kubesphere/kubekey/blob/main/pkg/controllers/infrastructure/inventory_controller.go): `pkg/controllers/infrastructure/inventory_controller.go`
- [KKCluster Controller](https://github.com/kubesphere/kubekey/blob/main/pkg/controllers/infrastructure/kkcluster_controller.go): `pkg/controllers/infrastructure/kkcluster_controller.go`
- [KKMachine Controller](https://github.com/kubesphere/kubekey/blob/main/pkg/controllers/infrastructure/kkmachine_controller.go): `pkg/controllers/infrastructure/kkmachine_controller.go`
- [Controller Manager](https://github.com/kubesphere/kubekey/blob/main/cmd/controller-manager/controller_manager.go): `cmd/controller-manager/controller_manager.go`

### API and Storage

- [Web Handlers](https://github.com/kubesphere/kubekey/blob/main/pkg/web/handler/resources.go): `pkg/web/handler/resources.go`
- [Resource Proxy](https://github.com/kubesphere/kubekey/blob/main/pkg/proxy/router.go): `pkg/proxy/router.go`
- [Resource Storage](https://github.com/kubesphere/kubekey/blob/main/pkg/proxy/internal/file_storage.go): `pkg/proxy/internal/file_storage.go`
- [Playbook Storage](https://github.com/kubesphere/kubekey/blob/main/pkg/proxy/resources/playbook/storage.go): `pkg/proxy/resources/playbook/storage.go`
- [Inventory Storage](https://github.com/kubesphere/kubekey/blob/main/pkg/proxy/resources/inventory/storage.go): `pkg/proxy/resources/inventory/storage.go`
- [Task Storage](https://github.com/kubesphere/kubekey/blob/main/pkg/proxy/resources/task/storage.go): `pkg/proxy/resources/task/storage.go`

### Other components

- **Operator**
- **Kubernetes API**

## Connections

- Operator → KK CLI: invokes (evidence: `README.md`)
- KK CLI → Cluster Workflows: selects workflow
- Operator → Web API and UI: uses UI (evidence: `README.md`)
- Cluster Workflows → Task Projects: loads templates
- Task Projects → Playbook Model: uses model (evidence: `pkg/project/project.go`)
- Task Execution → Task Converter: converts tasks (evidence: `pkg/executor/task_executor.go`)
- Task Execution → Task Modules: runs modules (evidence: `pkg/executor/task_executor.go`)
- Task Execution → Variables: resolves variables (evidence: `pkg/executor/task_executor.go`)
- Web API and UI → Web Handlers: routes requests (evidence: `pkg/web/service.go`)
- Web Handlers → Node Connectors: uses connectors (evidence: `pkg/web/handler/resources.go`)
- Controller Manager → Playbook Controller: registers (evidence: `cmd/controller-manager/controller_manager.go`)
- Controller Manager → Inventory Controller: registers (evidence: `cmd/controller-manager/controller_manager.go`)
- Controller Manager → KKCluster Controller: registers (evidence: `cmd/controller-manager/controller_manager.go`)
- Controller Manager → KKMachine Controller: registers (evidence: `cmd/controller-manager/controller_manager.go`)
- Playbook Controller → Kubernetes API: creates pods (evidence: `pkg/controllers/core/playbook_controller.go`)
- Inventory Controller → Playbook Controller: creates playbooks (evidence: `pkg/controllers/infrastructure/inventory_controller.go`)
- KKCluster Controller → Inventory Controller: manages inventory (evidence: `pkg/controllers/infrastructure/kkcluster_controller.go`)
- KKMachine Controller → Playbook Controller: creates playbooks (evidence: `pkg/controllers/infrastructure/kkmachine_controller.go`)
- Resource Proxy → Resource Storage: uses file storage
- Playbook Storage → Resource Storage: may persist locally
- Inventory Storage → Resource Storage: may persist locally
- Task Storage → Resource Storage: stores tasks locally
