# kubernetes-sigs/kwok architecture

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

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

## Overview

##### Project type and purpose
- This is a full‑stack CLI + simulator toolkit for Kubernetes (“KWOK” = Kubernetes WithOut Kubelet).
- Purpose: simulate large Kubernetes clusters (thousands of nodes/pods) with minimal resources for testing, benchmarking, and development.

##### File structure
- Top‐level executables:
- cmd/kwok → “kwok” server binary (implements API server + controllers)
- cmd/kwokctl → “kwokctl” CLI (cluster orchestration)
- API & controllers:
- pkg/apis → CRD definitions for Nodes, Pods, Stages, Metrics, etc.
- pkg/client → generated clientsets for those CRDs
- pkg/kwok/server → custom API server code
- pkg/kwok/controllers → reconciliation loops (NodeController, PodController, StageController, etc.)
- pkg/kwok/metrics → metrics gathering & export
- Orchestration & runtime:
- pkg/kwokctl/{cmd,components,etcd,k8s,pki,recording,runtime,scale,snapshot} → CLI commands + helpers to launch etcd, API server, controller manager, scheduler, metrics server, dashboards, etc., via container runtimes (docker, nerdctl, kind, compose, binary)
- Deployment templates:
- charts/… → Helm charts
- kustomize/… → Kustomize overlays for CRDs and components
- images/… → Dockerfiles for cluster and kwok images
- Tests & demos: hack/, test/, demo/ → integration & e2e tests, demonstration scripts, sample manifests

##### README for additional insights
- “kwok” simulates lifecycles of fake nodes/pods via CRDs & controllers
- “kwokctl” simplifies cluster creation & management by orchestrating control‑plane components in containers or processes
- Compatibility with any Kubernetes client (kubectl, helm, etc.) and standard Kubernetes APIs

##### Don’t overthink—be comprehensive
- Break the system into as many logical components as it has: CLI, runtime, CRDs, API server, controllers, metrics, storage, external clients.
- Every essential architectural element, even optional ones (e.g., various runtime backends, chart templates).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    UserClients["External Clients\n(kubectl, helm, custom apps)"]:::external

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        kwokctlCLI["kwokctl CLI"]:::orchestration
        Components["Control-Plane Components Definitions"]:::orchestration
        RuntimeAbstraction["Runtime Abstractions"]:::orchestration
        EtcdHelper["etcd Orchestration & Metadata"]:::orchestration
        K8sHelper["Kubernetes Feature-Gate & Tracing Config"]:::orchestration
        PKI["PKI & Certificate Utilities"]:::orchestration
        Recording["Recording Support"]:::orchestration
        Scale["Cluster Scaling Logic"]:::orchestration
        Snapshot["Snapshot Integration"]:::orchestration
    end

    %% Container/Process Runtime Layer
    Runtime["Container/Process Runtime\n(docker, nerdctl, kind, compose, binary)"]:::orchestration

    %% Control-Plane Components
    subgraph "Control-Plane Components"
        direction TB
        etcd[(etcd)]:::controlplane
        ApiServer["k8s API Server\n(or custom kwok API server)"]:::controlplane
        Clientsets["Generated Clientsets\nfor CRDs"]:::controlplane
        ControllerMgr["Controller Manager\n(NodeController, PodController, StageController)"]:::controllers
        MetricsServer["Metrics Server"]:::controlplane
    end

    %% CRDs & Custom Resources
    CRDs["CRDs & Custom Resources\n(Node, Pod, Stage, Metric)"]:::crd

    %% Monitoring & Tracing
    subgraph "Monitoring & Tracing"
        direction TB
        Prometheus["Prometheus"]:::monitoring
        Jaeger["Jaeger"]:::monitoring
    end

    %% Connections
    UserClients -->|invoke| kwokctlCLI
    kwokctlCLI -->|orchestrates| RuntimeAbstraction
    RuntimeAbstraction -->|launches| Runtime
    Runtime -->|starts| etcd
    Runtime -->|starts| ApiServer
    UserClients -->|CRUD on resources| ApiServer
    ApiServer -->|store/read| etcd
    etcd -->|serves data| ApiServer
    ApiServer -->|uses| Clientsets
    ApiServer -->|List/Watch| ControllerMgr
    ControllerMgr -->|Update statuses| ApiServer
    ControllerMgr -->|manages| CRDs
    MetricsServer -->|scrapes| ApiServer
    MetricsServer -->|scrapes| ControllerMgr
    Prometheus -->|scrape metrics| MetricsServer
    Prometheus -->|scrape endpoints| ApiServer
    Jaeger -->|trace| MetricsServer

    %% Click Events
    click kwokctlCLI "https://github.com/kubernetes-sigs/kwok/tree/main/pkg/kwokctl/cmd"
    click Components "https://github.com/kubernetes-sigs/kwok/tree/main/pkg/kwokctl/components"
    click RuntimeAbstraction "https://github.com/kubernetes-sigs/kwok/tree/main/pkg/kwokctl/runtime"
    click EtcdHelper "https://github.com/kubernetes-sigs/kwok/tree/main/pkg/kwokctl/etcd"
    click K8sHelper "https://github.com/kubernetes-sigs/kwok/tree/main/pkg/kwokctl/k8s"
    click PKI "https://github.com/kubernetes-sigs/kwok/tree/main/pkg/kwokctl/pki"
    click Recording "https://github.com/kubernetes-sigs/kwok/tree/main/pkg/kwokctl/recording"
    click Scale "https://github.com/kubernetes-sigs/kwok/tree/main/pkg/kwokctl/scale"
    click Snapshot "https://github.com/kubernetes-sigs/kwok/tree/main/pkg/kwokctl/snapshot"
    click ApiServer "https://github.com/kubernetes-sigs/kwok/tree/main/pkg/kwok/server"
    click Clientsets "https://github.com/kubernetes-sigs/kwok/tree/main/pkg/client"
    click ControllerMgr "https://github.com/kubernetes-sigs/kwok/tree/main/pkg/kwok/controllers"
    click MetricsServer "https://github.com/kubernetes-sigs/kwok/tree/main/pkg/kwok/metrics"
    click CRDs "https://github.com/kubernetes-sigs/kwok/tree/main/pkg/apis"

    %% Styles
    classDef orchestration fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef controlplane fill:#90EE90,stroke:#333,stroke-width:1px
    classDef controllers fill:#FFA500,stroke:#333,stroke-width:1px
    classDef crd fill:#FFFF99,stroke:#333,stroke-width:1px
    classDef monitoring fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
