# kubernetes-sigs/controller-runtime architecture

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

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

## Overview

##### Main Components

a) Core Components:
- Manager Component (pkg/manager)
- Controller Component (pkg/controller)
- Cache Component (pkg/cache)
- Client Component (pkg/client)
- Webhook Component (pkg/webhook)
- Metrics Component (pkg/metrics)

b) Supporting Components:
- Certificate Watcher (pkg/certwatcher)
- Event Handling System (pkg/event)
- Reconciliation Engine (pkg/reconcile)
- Source Management (pkg/source)
- Predicate Handling (pkg/predicate)

**┌─────────────────────────────────────────────────────────┐**
- Client Layer                        │
- ┤
- Manager Layer                        │
- ┬───────────────┬────────────────────────┤
- Controllers  │    Cache      │       Webhooks         │
- ┴───────────────┴────────────────────────┤
- Kubernetes API Server                      │
- ┘

##### Detailed Component Breakdown

Manager Component:
**┌─────────── Manager ──────────┐**
- ┌─────────┐    ┌──────────┐ │
- Cache   │    │Controllers│ │
- ┘    └──────────┘ │
- ┌─────────┐    ┌──────────┐ │
- Webhooks │    │ Metrics  │ │
- ┘    └──────────┘ │
- ┘

##### Key Interactions to Highlight

- Controller ↔ Cache: Watch and Get operations
- Controller → Reconciler: Reconciliation requests
- Webhook ↔ API Server: Admission and conversion
- Manager → All Components: Lifecycle management
- Cache ↔ API Server: Data synchronization

##### Additional Elements

Annotations for:
- Configuration options
- Health check endpoints
- Metrics collection points
- Leader election mechanisms
- Resource watching patterns

##### Implementation Notes

- Maintain consistent spacing and alignment
- Version compatibility information
- Notes about extension points
- Document common patterns and flows

## Diagram (Mermaid)

```mermaid
graph TB
    %% Style definitions
    classDef core fill:#3498db,stroke:#2980b9,color:white
    classDef extension fill:#2ecc71,stroke:#27ae60,color:white
    classDef utility fill:#f1c40f,stroke:#f39c12,color:black
    classDef external fill:#95a5a6,stroke:#7f8c8d,color:white
    
    subgraph ClientLayer["Client Layer"]
        Client["Client Component"]:::core
    end

    subgraph ManagerLayer["Manager Layer"]
        Manager["Manager Component"]:::core
        Metrics["Metrics Component"]:::extension
        CertWatcher["Certificate Watcher"]:::utility
    end

    subgraph CoreComponents["Core Processing Layer"]
        Controller["Controller Component"]:::core
        Cache["Cache Component"]:::core
        Webhook["Webhook Component"]:::extension
        
        subgraph EventSystem["Event Processing"]
            EventHandler["Event Handling System"]:::utility
            Source["Source Management"]:::utility
            Predicate["Predicate Handling"]:::utility
            Reconciler["Reconciliation Engine"]:::utility
        end
    end

    subgraph K8s["Kubernetes Layer"]
        APIServer["Kubernetes API Server"]:::external
    end

    %% Relationships
    Client --> Manager
    Manager --> Controller
    Manager --> Cache
    Manager --> Webhook
    Manager --> Metrics
    Manager --> CertWatcher
    
    Controller --> EventHandler
    Controller --> Reconciler
    Controller --> Cache
    
    EventHandler --> Source
    EventHandler --> Predicate
    
    Cache -.-> APIServer
    Webhook -.-> APIServer
    Client -.-> APIServer

    %% Click events for component mapping
    click Manager "https://github.com/kubernetes-sigs/controller-runtime/tree/main/pkg/manager/"
    click Controller "https://github.com/kubernetes-sigs/controller-runtime/tree/main/pkg/controller/"
    click Cache "https://github.com/kubernetes-sigs/controller-runtime/tree/main/pkg/cache/"
    click Client "https://github.com/kubernetes-sigs/controller-runtime/tree/main/pkg/client/"
    click Webhook "https://github.com/kubernetes-sigs/controller-runtime/tree/main/pkg/webhook/"
    click Metrics "https://github.com/kubernetes-sigs/controller-runtime/tree/main/pkg/metrics/"
    click CertWatcher "https://github.com/kubernetes-sigs/controller-runtime/tree/main/pkg/certwatcher/"
    click EventHandler "https://github.com/kubernetes-sigs/controller-runtime/tree/main/pkg/event/"
    click Reconciler "https://github.com/kubernetes-sigs/controller-runtime/tree/main/pkg/reconcile/"
    click Source "https://github.com/kubernetes-sigs/controller-runtime/tree/main/pkg/source/"
    click Predicate "https://github.com/kubernetes-sigs/controller-runtime/tree/main/pkg/predicate/"

    %% Legend
    subgraph Legend
        CoreComp["Core Component"]:::core
        ExtComp["Extension Component"]:::extension
        UtilComp["Utility Component"]:::utility
        ExtSys["External System"]:::external
        DirectDep["→ Direct Dependency"]
        EventFlow["--> Event Flow"]
    end
```
