# clastix/kamaji architecture

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

- Interactive diagram: https://gitdiagram.com/clastix/kamaji
- Repository: https://github.com/clastix/kamaji

## Overview

##### Main Components

a. Management Cluster Layer:
- Kamaji Controller (core component)
- Custom Resources (TenantControlPlane and Datastore)
- Webhook Server (for validation and mutation)
- Certificate Management System

b. Data Layer:
- Multiple Datastore options (etcd, MySQL, PostgreSQL, NATS)
- Kine adapter for non-etcd datastores
- Storage configuration and migration components

c. Control Plane Layer:
- Tenant Control Plane Pods
- Core Kubernetes components (API Server, Controller Manager, Scheduler)
- -ons (CoreDNS, kube-proxy)
- Konnectivity Server/Agent

##### Relationship Flows

- Control flow from Kamaji Controller to Tenant Control Planes
- Data flow between Control Planes and Datastores
- Certificate management flows
- Webhook validation/mutation paths
- Worker node connections through Konnectivity

##### Specific Implementation Details

- Custom Resources (purple rectangles)
- Controllers (blue rectangles)
- Kubernetes components (orange rectangles)

##### Key Architectural Patterns to Highlight

- Operator pattern for TenantControlPlane management
- Multi-tenancy support in datastores
- Blue/Green deployment for updates
- Webhook-based validation chain
- Certificate rotation mechanism

##### Additional Elements

Include:
- Version information
- Supported Kubernetes versions
- External integration points (Cluster API, etc.)
- Resource requirements and scaling indicators

##### Technical Details

- API versions (v1alpha1)
- Supported datastore types
- Certificate management flows
- Resource boundaries
- Network paths for control plane access

- The separation between management and tenant clusters
- The flexibility in datastore selection
- The automated certificate management
- The scalability aspects
- The multi-tenancy capabilities

Remember to:
- Keep components grouped logically
- Clear boundaries between different responsibility areas
- Failure domains and high availability patterns
- Document all external integration points

This system design should reflect Kamaji's role as a control plane manager while showing its integration with standard Kubernetes components and external systems.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Management
        KC["Kamaji Controller"]:::controller
        CRD["Custom Resources"]:::crd
        WH["Webhook Server"]:::webhook
        CM["Certificate Manager"]:::cert
    end

    subgraph "Control Plane Layer"
        TCP["Tenant Control Plane Pod"]:::k8s
        APIC["API Server"]:::k8s
        CMC["Controller Manager"]:::k8s
        SCH["Scheduler"]:::k8s
        KON["Konnectivity Server"]:::network
        
        subgraph "Add-ons"
            DNS["CoreDNS"]:::addon
            KP["Kube Proxy"]:::addon
        end
    end

    subgraph "Data Layer"
        ETCD[("etcd")]:::db
        MYSQL[("MySQL")]:::db
        PSQL[("PostgreSQL")]:::db
        NATS[("NATS")]:::db
        KINE["Kine Adapter"]:::adapter
    end

    subgraph "Worker Nodes"
        WN["Worker Node"]:::worker
        KONA["Konnectivity Agent"]:::network
    end

    %% Relationships
    KC --> TCP
    KC --> CRD
    KC --> WH
    KC --> CM
    
    TCP --> APIC
    TCP --> CMC
    TCP --> SCH
    TCP --> KON
    
    APIC --> DNS
    APIC --> KP
    
    KON --> KONA
    KONA --> WN
    
    KINE --> MYSQL
    KINE --> PSQL
    KINE --> NATS
    
    TCP --> ETCD
    TCP --> KINE

    %% Click Events
    click KC "https://github.com/clastix/kamaji/blob/master/controllers/tenantcontrolplane_controller.go"
    click CRD "https://github.com/clastix/kamaji/tree/master/api/v1alpha1"
    click WH "https://github.com/clastix/kamaji/tree/master/internal/webhook"
    click CM "https://github.com/clastix/kamaji/blob/master/controllers/certificate_lifecycle_controller.go"
    click DNS "https://github.com/clastix/kamaji/blob/master/internal/resources/addons/coredns.go"
    click KP "https://github.com/clastix/kamaji/blob/master/internal/resources/addons/kube_proxy.go"
    click KON "https://github.com/clastix/kamaji/tree/master/internal/resources/konnectivity"
    click ETCD "https://github.com/clastix/kamaji/blob/master/internal/datastore/etcd.go"
    click MYSQL "https://github.com/clastix/kamaji/blob/master/internal/datastore/mysql.go"
    click PSQL "https://github.com/clastix/kamaji/blob/master/internal/datastore/postgresql.go"
    click NATS "https://github.com/clastix/kamaji/blob/master/internal/datastore/nats.go"

    %% Styling
    classDef controller fill:#2196F3,stroke:#1565C0,color:white
    classDef crd fill:#9C27B0,stroke:#7B1FA2,color:white
    classDef webhook fill:#FF9800,stroke:#F57C00,color:white
    classDef cert fill:#4CAF50,stroke:#388E3C,color:white
    classDef k8s fill:#FF5722,stroke:#E64A19,color:white
    classDef network fill:#00BCD4,stroke:#0097A7,color:white
    classDef addon fill:#FFC107,stroke:#FFA000,color:black
    classDef db fill:#8BC34A,stroke:#689F38,color:white
    classDef adapter fill:#3F51B5,stroke:#303F9F,color:white
    classDef worker fill:#795548,stroke:#5D4037,color:white

    %% Legend
    subgraph Legend
        L1["Controller"]:::controller
        L2["Custom Resource"]:::crd
        L3["Webhook"]:::webhook
        L4["Certificate"]:::cert
        L5["K8s Component"]:::k8s
        L6["Network"]:::network
        L7["Add-on"]:::addon
        L8[("Database")]:::db
        L9["Adapter"]:::adapter
        L10["Worker"]:::worker
    end
```
