# k8up-io/k8up architecture

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

- Interactive diagram: https://gitdiagram.com/k8up-io/k8up
- Repository: https://github.com/k8up-io/k8up

## Overview

- K8up Operator Module:
- Represented by directories such as “operator”, “cmd/operator”, and the various controller subdirectories (e.g., backupcontroller, archivecontroller, checkcontroller, prunecontroller, restorecontroller, schedulecontroller).
- This is where the continuous reconciliation loops run within the Kubernetes cluster.
- Restic Module:
- Represented by the “restic” directory and associated CLI interfaces under “cmd/restic” and “cli/restore”.
- This module is invoked as a short-lived job for performing backup/restore operations.
- CRDs and API Schemas:
- Represented by the “api” directory where Kubernetes Custom Resource Definitions (CRDs) are defined.
- Also, look at the “config/crd” directory where YAML definitions for installing these CRDs are available.
- Auxiliary Components:
- “cmd” directory: Contains various entrypoints for CLI tools.
- “charts”: Helm charts and templates to deploy K8up onto a cluster.
- “docs”: Documentation in AsciiDoc, which further explains usage, configuration, and integration.
- “e2e” and “envtest”: Represent integration and end-to-end test infrastructure, which provide evidence of real-world usage and validate interactions.

##### Lay Out the Relationships and Data Flow
- The Kubernetes Cluster Node:
- CRDs Interaction:
- Operator Reconciliation Loop:
- Triggering Restic Jobs:
- External System Interactions:
- Connections from both the Operator and Restic modules to external services:
- A “Storage Repository” (which might be backed by cloud storage like S3, or other persistent storage).
- “Prometheus” for monitoring, as the operator exposes endpoints for metrics.
- Optionally, include elements like “Helm Charts” (from the charts folder) to illustrate how deployments are templated.

##### Architectural Patterns and Technologies
- Operator Pattern:
- That the operator constantly watches the state inside the Kubernetes cluster, using event-driven reconciliation loops.
- Kubebuilder Framework:
- That the project uses Kubebuilder (as stated in the README) for scaffolding the operator and generating API/CRD code.
- Go-based Micro-Components:
- The codebase is written in Go, and the modularity between operator and restic emphasizes separation of concerns.
- Testing Infrastructure:
- A testing component that represents “e2e tests” and “envtest” which confirm that the interaction between controllers and jobs is correct.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Kubernetes Cluster and Operator Module
    subgraph "Kubernetes Cluster"
        CRDs["Custom Resource Definitions (CRDs)"]:::crd
        subgraph "K8up Operator Module"
            OModule["Operator Module Code"]:::operator
            OpEntrypoint["Operator Entrypoint"]:::operator
            OModule --> OpEntrypoint
            subgraph "Operator Controllers"
                Backup["BackupController"]:::controller
                Archive["ArchiveController"]:::controller
                Check["CheckController"]:::controller
                Prune["PruneController"]:::controller
                Restore["RestoreController"]:::controller
                Schedule["ScheduleController"]:::controller
            end
        end
    end

    %% Restic Module
    subgraph "Restic Module"
        RModule["Restic Module Code"]:::restic
        REntrypoint["Restic Entrypoint"]:::restic
        RModule --> REntrypoint
    end

    %% External Systems: Deployment & Monitoring
    subgraph "Deployment & Monitoring"
        Helm["Helm Deployment"]:::helm
        Prometheus["Prometheus Metrics Endpoint"]:::monitoring
        ExternalStorage["Storage Repository"]:::storage
    end

    %% Auxiliary Components
    subgraph "Auxiliary Components"
        CLI["CLI Tools"]:::aux
        Docs["Documentation"]:::aux
        Testing["Testing (e2e & envtest)"]:::testing
    end

    %% Relationships and Data Flow
    CRDs -->|"trigger_event"| OpEntrypoint
    OpEntrypoint -->|"initiates_job"| REntrypoint
    OpEntrypoint -->|"pushes_metrics"| Prometheus
    OpEntrypoint -->|"updates_backup"| ExternalStorage
    Helm -->|"deploys"| OpEntrypoint
    Testing -->|"validates"| OpEntrypoint

    %% Click Events
    click OModule "https://github.com/k8up-io/k8up/tree/master/operator"
    click OpEntrypoint "https://github.com/k8up-io/k8up/blob/master/cmd/operator/main.go"
    click RModule "https://github.com/k8up-io/k8up/tree/master/restic"
    click REntrypoint "https://github.com/k8up-io/k8up/blob/master/cmd/restic/main.go"
    click CRDs "https://github.com/k8up-io/k8up/tree/master/api"
    click CRDs_Yaml "https://github.com/k8up-io/k8up/tree/master/config/crd/apiextensions.k8s.io/v1"
    click CLI "https://github.com/k8up-io/k8up/tree/master/cmd/cli"
    click CLI_Restore "https://github.com/k8up-io/k8up/tree/master/cli/restore"
    click Helm "https://github.com/k8up-io/k8up/tree/master/charts/k8up"
    click Docs "https://github.com/k8up-io/k8up/tree/master/docs"
    click Testing "https://github.com/k8up-io/k8up/tree/master/e2e"
    click EnvTest "https://github.com/k8up-io/k8up/tree/master/envtest"

    %% Styles
    classDef operator fill:#f9c,stroke:#333,stroke-width:2px;
    classDef controller fill:#ccf,stroke:#333,stroke-width:2px;
    classDef crd fill:#cfc,stroke:#333,stroke-width:2px;
    classDef restic fill:#fc9,stroke:#333,stroke-width:2px;
    classDef helm fill:#fcc,stroke:#333,stroke-width:2px;
    classDef monitoring fill:#ffc,stroke:#333,stroke-width:2px;
    classDef storage fill:#cff,stroke:#333,stroke-width:2px;
    classDef aux fill:#def,stroke:#333,stroke-width:2px;
    classDef testing fill:#9fc,stroke:#333,stroke-width:2px;
```
