# gabeduke/kubernetes-controller-examples architecture

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

- Interactive diagram: https://gitdiagram.com/gabeduke/kubernetes-controller-examples
- Repository: https://github.com/gabeduke/kubernetes-controller-examples

## Overview

##### Project Type and Purpose
- The repository is an educational resource focused on Kubernetes controllers. It’s both a tutorial and an open-source learning tool.
- The intent is to demonstrate key controller components such as queues, informers, reconcilers, and managers (i.e., the control loop concept from Kubernetes).

##### File Structure Analysis
- Three main sections:
- 01.Basics – Simple examples for listing pods.
- 02.Intermediate – Introduces watching resources.
- 03.Advanced – Demonstrates building custom controllers, organizing the logic into components like custom controllers, custom resources, and work queues.

##### Key Components
a. Core Controller Pattern Elements:
- Informer: Represents the component that watches for Kubernetes resource updates.
- Queue: Captures events that need to be processed.
- Reconciler: Implements the logic to compare and align the desired and actual states.
- Manager: Orchestrates the lifecycle by initializing the above parts and triggering the control loop.
b. Supporting Components:
- Kubernetes API Server: The external system being interacted with (source of events).
- Client Libraries (client-go, Kubernetes Python client): Shown as middleware that each of the language-specific examples uses.
- Tutorial Sections: Show how the examples evolve from basic interactions (listing pods) to more complex control loops (custom controllers and work queues).

##### Relationships and Interactions
- Start at the Kubernetes API Server sending events to the Informer.
- Informer updates the Queue.
- The Queue triggers the Reconciler.
- The Reconciler compares the desired vs. actual state and then instructs changes via the Manager to the API Server.

##### Architectural Patterns and Principles
- The repository is a model example of the observer pattern (via informers) and a control loop enforcing eventual consistency.
- Separation of concerns: different language examples achieve the same goals, but the logical flow (watching resources and reconciling state) remains consistent.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Control Loop
    API["Kubernetes API Server"]:::api
    INF["Informer"]:::control
    Q["Queue"]:::control
    REC["Reconciler"]:::control
    MGR["Manager"]:::control

    API -->|"events"| INF
    INF -->|"queuesEvent"| Q
    Q -->|"triggers"| REC
    REC -->|"updatesState"| MGR
    MGR -->|"commands"| API

    %% Tutorial: Basics Subgraph
    subgraph "Tutorial: Basics"
        BL["Bash: List Pods"]:::tutorialBasics
        PL["Python: List Pods"]:::tutorialBasics
        GL["Go: List Pods"]:::tutorialBasics
    end

    %% Tutorial: Intermediate Subgraph
    subgraph "Tutorial: Intermediate"
        BW["Bash: Watch Pods"]:::tutorialIntermediate
        PW["Python: Watch Pods"]:::tutorialIntermediate
        GW["Go: Watch Pods"]:::tutorialIntermediate
    end

    %% Tutorial: Advanced Subgraph
    subgraph "Tutorial: Advanced"
        GC["Go: Custom Controller"]:::tutorialAdvanced
        PC["Python: Custom Controller"]:::tutorialAdvanced
        GQ["Go: Work Queue"]:::tutorialAdvanced
        GR["Go: Custom Resources"]:::tutorialAdvanced
        BA["Bash: Advanced Doc"]:::tutorialAdvanced
    end

    %% Relationships between Tutorial Examples and Core Components
    BL -- "reads" --> API
    PL -- "reads" --> API
    GL -- "reads" --> API

    BW -- "observes" --> INF
    PW -- "observes" --> INF
    GW -- "observes" --> INF

    GC -- "controls" --> REC
    PC -- "controls" --> REC
    GQ -- "processes" --> Q
    GR -- "registersWith" --> MGR
    BA -- "documents" --> MGR

    %% Class Definitions for Styling
    classDef api fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef control fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef tutorialBasics fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef tutorialIntermediate fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef tutorialAdvanced fill:#FFA07A,stroke:#333,stroke-width:2px;

    %% Click Events for Component Mapping (Paths for click events only)
    click BL "https://github.com/gabeduke/kubernetes-controller-examples/blob/main/01.Basics/bash/list_pods.sh"
    click GL "https://github.com/gabeduke/kubernetes-controller-examples/blob/main/01.Basics/client-go/list_pods.go"
    click PL "https://github.com/gabeduke/kubernetes-controller-examples/blob/main/01.Basics/python/list_pods.py"

    click BW "https://github.com/gabeduke/kubernetes-controller-examples/blob/main/02.Intermediate/bash/watch_pods.sh"
    click GW "https://github.com/gabeduke/kubernetes-controller-examples/blob/main/02.Intermediate/client-go/watch_pods.go"
    click PW "https://github.com/gabeduke/kubernetes-controller-examples/blob/main/02.Intermediate/python/watch_pods.py"

    click GC "https://github.com/gabeduke/kubernetes-controller-examples/blob/main/03.Advanced/client-go/basic_controller/custom_controller.go"
    click PC "https://github.com/gabeduke/kubernetes-controller-examples/blob/main/03.Advanced/python/custom_controller.py"
    click GQ "https://github.com/gabeduke/kubernetes-controller-examples/blob/main/03.Advanced/client-go/work_queue/work_queue.go"
    click GR "https://github.com/gabeduke/kubernetes-controller-examples/blob/main/03.Advanced/client-go/custom_resources/custom_resources.go"
    click BA "https://github.com/gabeduke/kubernetes-controller-examples/blob/main/03.Advanced/bash/README.md"
```
