# williamkoller/k8s-addon architecture

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

- Interactive diagram: https://gitdiagram.com/williamkoller/k8s-addon
- Repository: https://github.com/williamkoller/k8s-addon

## Overview

##### Project type and purpose
- This is a Kubernetes “operator” / controller addon written in Go.

##### File structure
- **cmd/addon/**: `main.go` entrypoint. Initializes the controller-runtime manager, metrics & health probes, and leader election.
- **internal/controllers/**: two reconcilers (NamespaceReconciler, NodeReconciler) implementing the controller pattern.
- **manifests/**: Kubernetes YAMLs—RBAC rules and Deployment manifest.
- **Dockerfile**, **Makefile**, and test scripts: build, image push, deploy, local/remote tests.

##### README for additional insights
- Uses the Kubernetes controller-runtime library.
- Exposes `/metrics` and `/healthz`, `/readyz` endpoints.
- Configurable via env vars or command-line flags.
- Performs leader election on `coordination.k8s.io/leases`.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    Kubectl["kubectl Users"]:::external
    Prometheus["Prometheus"]:::external

    %% Control Plane
    subgraph "K8s Control Plane"
        direction TB
        APIServer["API Server"]:::controlplane
        ETCD["etcd"]:::datastore
    end

    APIServer --> ETCD

    %% Addon Deployment
    subgraph "Addon Controller (Deployment)" 
        direction TB
        ControllerManager["Controller Manager"]:::addon
        NamespaceController["NamespaceController"]:::addon
        NodeController["NodeController"]:::addon
        ServiceAccount["ServiceAccount & RBAC"]:::rbac
    end

    ControllerManager --> NamespaceController
    ControllerManager --> NodeController
    ControllerManager --> ServiceAccount

    %% Watches and Reconciliations
    ControllerManager -->|"watch Namespaces\nwatch Nodes"| APIServer
    NamespaceController -->|"PATCH label owner"| APIServer
    NodeController -->|"PATCH taint GPU"| APIServer

    %% Observability
    ControllerManager -->|"exposes /metrics"| Prometheus
    ControllerManager -->|"liveness&readiness"| Kubectl

    Prometheus -->|"scrape /metrics"| ControllerManager
    Kubectl -->|"probe /healthz,/readyz"| ControllerManager

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline" 
        direction TB
        CI_Source["Source Code"]:::pipeline
        DockerBuild["Dockerfile"]:::pipeline
        Manifests["K8s Manifests"]:::pipeline
        DeployStep["Makefile & Tests"]:::pipeline
    end

    CI_Source --> DockerBuild
    DockerBuild --> Manifests
    Manifests --> DeployStep
    DeployStep -->|"deploy image & YAMLs"| ControllerManager

    %% Click Events
    click NamespaceController "https://github.com/williamkoller/k8s-addon/blob/main/internal/controllers/namespace_controller.go"
    click NodeController "https://github.com/williamkoller/k8s-addon/blob/main/internal/controllers/node_controller.go"
    click Manifests "https://github.com/williamkoller/k8s-addon/blob/main/manifests/deployment.yaml"
    click Manifests "https://github.com/williamkoller/k8s-addon/blob/main/manifests/rbac.yaml"
    click DockerBuild "https://github.com/williamkoller/k8s-addon/tree/main/Dockerfile"
    click DeployStep "https://github.com/williamkoller/k8s-addon/tree/main/Makefile"
    click CI_Source "https://github.com/williamkoller/k8s-addon/blob/main/README.md"
    click CI_Source "https://github.com/williamkoller/k8s-addon/blob/main/go.mod"
    click CI_Source "https://github.com/williamkoller/k8s-addon/blob/main/go.sum"

    %% Styles
    classDef controlplane fill:#FFD086,stroke:#333,stroke-width:1px
    classDef datastore fill:#DDD,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef addon fill:#A2D5F2,stroke:#333,stroke-width:1px
    classDef external fill:#C2F784,stroke:#333,stroke-width:1px
    classDef rbac fill:#F7A3A3,stroke:#333,stroke-width:1px
    classDef pipeline fill:#FFE699,stroke:#333,stroke-width:1px
```
