# martinohmann/home-ops architecture

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

- Interactive diagram: https://gitdiagram.com/martinohmann/home-ops
- Repository: https://github.com/martinohmann/home-ops

## Overview

##### Project type and purpose
- This is an **Infrastructure as Code (IaC) & GitOps** monorepo for a home Kubernetes environment.
- Purpose:
- Provision Proxmox VMs via Terraform
- Bootstrap and configure k3s clusters (main & storage) via Ansible
- Drive cluster state through Flux (GitOps)
- Automate dependency updates via Renovate and CI via GitHub Actions

##### File structure
- Top-level directories:
- **terraform/** – Terraform modules for Proxmox, Cloudflare, MinIO, etc.
- **ansible/** – Ansible playbooks for Kubernetes, Proxmox, WireGuard
- **kubernetes/** – Flux-driven Kubernetes manifests, separated into `main` and `storage` clusters, each with `bootstrap/`, `components/`, `apps/`, `flux/`
- **.github/** – GitHub Actions workflows, Renovate configuration
- Patterns:
- Two clusters (main & storage) each with identical structure: bootstrap procedures, reusable components, Flux core config, and apps
- Flux Kustomizations and HelmReleases under `apps/...` for each application
- CI/CD: GitHub Actions in `.github/workflows`, Renovate config in `.github/renovate`

##### README for additional insights
- High-level architecture: Terraform → Proxmox VMs → Ansible → k3s clusters
- Core cluster services: cilium, cert-manager, ingress-nginx, external-dns, longhorn, system-upgrade-controller, volsync, actions-runner
- Flux scans kubernetes/<cluster>/apps recursively for kustomizations to apply

a. Main components:
1. **GitHub Monorepo**
– Code: terraform/, ansible/, kubernetes/, .github workflows, Renovate
2. **CI/CD Layer**
– GitHub Actions (e.g., release.yaml, flux-diff.yaml)
– RenovateBot
3. **Terraform**
– Proxmox provider modules → creates Proxmox VMs
– Cloudflare, MinIO, Authentik, etc. modules
4. **Ansible**
– k3s cluster provisioning on those VMs
– WireGuard, Proxmox node setup
5. **GitOps Engine (Flux)**
– Watches kubernetes/main and kubernetes/storage directories
– Applies bootstrap → components → apps via Kustomize & HelmRelease
6. **k3s Clusters**
– **Main cluster**: hosts core services + workloads
– **Storage cluster**: dedicated storage controllers + storage-oriented apps
7. **Cluster Services**
– Networking: Cilium, Ingress-NGINX
– Certificates: cert-manager
– DNS: external-dns (Cloudflare)
– Storage: Longhorn, Volsync, NFS server (separate host)
– CI runners: actions-runner-controller
– Observability: Prometheus stack, Grafana, Loki, exporters
– Secrets: SOPS, External-Secrets
8. **External Services**
– DNS provider (Cloudflare)
– Proxmox VE cluster management
– NFS/Bulk storage server

b. Relationships & interactions:
- **Developer** pushes to **GitHub** → triggers **GitHub Actions** & **Renovate**
- **Terraform** workflow provisions VMs in **Proxmox**
- **Ansible** playbooks configure VMs with k3s, networking, storage prerequisites
- **Flux controllers** in each cluster watch Git repo → pull manifests → apply via Kustomize/Helm
- **Applications** (HelmRelease) deployed into namespaces
- **Secrets** encrypted with **SOPS**, decrypted by Flux/Ansible/Terraform
- **Volsync** replicates PersistentVolumes between main & storage clusters

c. Architectural patterns/design principles:
– **GitOps**: Flux as the single source of truth for cluster state
– **Immutable infrastructure**: declarative Terraform & Ansible
– **Modular IaC**: Terraform modules, Ansible roles, reusable Kustomize components
– **Separation of concerns**: distinct layers (provisioning vs configuration vs application)
– **DRY + Reuse**: shared components under `kubernetes/*/components`

d. Key technologies:
– IaC: Terraform (HCL), Ansible (YAML)
– Kubernetes: k3s, Kustomize, HelmRelease
– GitOps: Flux v2
– CI/CD: GitHub Actions, Renovate
– Networking: Cilium, ingress-nginx
– Storage: Longhorn, volsync, NFS, MinIO, CloudNative-PG
– Secrets: Mozilla SOPS, External-Secrets
– Observability: Prometheus, Grafana, Loki, Alertmanager, exporters

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors & Repo
    Developer["Developer"] 
    GitHub["GitHub Monorepo"]:::gitops
    Developer -->|push| GitHub

    %% CI/CD Lane
    subgraph "CI/CD Layer"
        GH_Actions["GitHub Actions"]:::ci
        Renovate["Renovate Bot"]:::ci
    end
    GitHub --> GH_Actions
    GitHub --> Renovate

    %% Provisioning Lane
    subgraph "Infrastructure Provisioning" 
        Terraform["Terraform"]:::iac
        Ansible["Ansible"]:::iac

        Terraform --> ProxmoxVM["Proxmox VM Provisioning"]:::iac
        Terraform --> TF_Cloudflare["Cloudflare DNS (Terraform)"]:::external
        Terraform --> TF_MinIO["MinIO Buckets (Terraform)"]:::storage
        Terraform --> TF_SOPS["Kubernetes SOPS Secrets"]:::service
        Terraform --> TF_Auth["Authentik Identity"]:::service

        Ansible --> Ansible_Prox["Ansible Proxmox Bootstrap"]:::iac
        Ansible --> Ansible_MainK3s["Ansible k3s Main Cluster"]:::iac
        Ansible --> Ansible_StorK3s["Ansible k3s Storage Cluster"]:::iac
        Ansible --> Ansible_WG["Ansible WireGuard Setup"]:::iac
    end
    GH_Actions --> Terraform
    GH_Actions --> Ansible

    %% GitOps Lane
    subgraph "GitOps Engine"
        FluxMain["Flux Main Cluster"]:::gitops
        FluxStor["Flux Storage Cluster"]:::gitops
    end
    GitHub --> FluxMain
    GitHub --> FluxStor

    %% Clusters Layer
    subgraph "k3s Clusters"
        subgraph "Main Cluster"
            MC_Components["Reusable Components"]:::service
            MC_Apps["All Apps"]:::service
            subgraph "Services"
                Cilium["Cilium (Networking)"]:::service
                Ingress["Ingress-NGINX"]:::service
                CertMgr["Cert-Manager"]:::service
                ExtDNS["External-DNS"]:::service
                Longhorn["Longhorn Storage"]:::storage
                Volsync["VolSync Replication"]:::storage
                CSI_NFS["CSI Driver NFS"]:::storage
                ARunner["Actions-Runner Controller"]:::service
                subgraph "Observability"
                    PromStack["Prometheus Stack"]:::service
                    Grafana["Grafana"]:::service
                    Loki["Loki"]:::service
                    Exporters["Exporters"]:::service
                end
                ExtSecrets["External-Secrets"]:::service
            end
        end

        subgraph "Storage Cluster"
            SC_Components["Reusable Components"]:::service
            SC_Apps["All Apps"]:::service
            subgraph "Services"
                Cilium2["Cilium (Networking)"]:::service
                Ingress2["Ingress-NGINX"]:::service
                CertMgr2["Cert-Manager"]:::service
                ExtDNS2["External-DNS"]:::service
            end
        end
    end
    ProxmoxVM -->|provides VMs| Ansible_Prox
    Ansible_Prox -->|bootstraps| MC_Components
    Ansible_MainK3s --> MC_Components
    Ansible_StorK3s --> SC_Components

    FluxMain --> MC_Components
    FluxMain --> MC_Apps
    FluxStor --> SC_Components
    FluxStor --> SC_Apps

    MC_Apps --> Cilium
    MC_Apps --> Ingress
    MC_Apps --> CertMgr
    MC_Apps --> ExtDNS
    MC_Apps --> Longhorn
    MC_Apps --> Volsync
    MC_Apps --> CSI_NFS
    MC_Apps --> ARunner
    MC_Apps --> PromStack
    MC_Apps --> Grafana
    MC_Apps --> Loki
    MC_Apps --> Exporters
    MC_Apps --> ExtSecrets

    SC_Apps --> Cilium2
    SC_Apps --> Ingress2
    SC_Apps --> CertMgr2
    SC_Apps --> ExtDNS2

    %% Inter-cluster replication
    Volsync -->|replicates PVs| Volsync

    %% External Services
    subgraph "External Services"
        DNSProvider["Cloudflare DNS"]:::external
        NFS_Server["NFS Server"]:::storage
        ProxVE["Proxmox VE Cluster"]:::external
    end
    TF_Cloudflare --> DNSProvider
    CSI_NFS --> NFS_Server
    ProxmoxVM --> ProxVE
    ExtDNS --> DNSProvider
    ExtDNS2 --> DNSProvider

    %% Click Events
    click GitHub "https://github.com/martinohmann/home-ops/tree/main//"
    click GH_Actions "https://github.com/martinohmann/home-ops/blob/main//.github/workflows/*.yaml"
    click Renovate "https://github.com/martinohmann/home-ops/blob/main//.github/renovate.json5"
    click ProxmoxVM "https://github.com/martinohmann/home-ops/tree/main//terraform/proxmox"
    click TF_Cloudflare "https://github.com/martinohmann/home-ops/tree/main//terraform/cloudflare"
    click TF_MinIO "https://github.com/martinohmann/home-ops/tree/main//terraform/minio"
    click TF_SOPS "https://github.com/martinohmann/home-ops/tree/main//terraform/kubernetes/secrets"
    click TF_Auth "https://github.com/martinohmann/home-ops/tree/main//terraform/authentik"
    click Ansible_Prox "https://github.com/martinohmann/home-ops/tree/main//ansible/proxmox/playbooks"
    click Ansible_MainK3s "https://github.com/martinohmann/home-ops/tree/main//ansible/kubernetes/main/playbooks"
    click Ansible_StorK3s "https://github.com/martinohmann/home-ops/tree/main//ansible/kubernetes/storage/playbooks"
    click Ansible_WG "https://github.com/martinohmann/home-ops/tree/main//ansible/wireguard/playbooks"
    click FluxMain "https://github.com/martinohmann/home-ops/tree/main//kubernetes/main/flux"
    click FluxStor "https://github.com/martinohmann/home-ops/tree/main//kubernetes/storage/flux"
    click MC_Components "https://github.com/martinohmann/home-ops/tree/main//kubernetes/main/components"
    click SC_Components "https://github.com/martinohmann/home-ops/tree/main//kubernetes/storage/components"
    click MC_Apps "https://github.com/martinohmann/home-ops/tree/main//kubernetes/main/apps"
    click SC_Apps "https://github.com/martinohmann/home-ops/tree/main//kubernetes/storage/apps"
    click Cilium "https://github.com/martinohmann/home-ops/tree/main//kubernetes/main/apps/kube-system/cilium"
    click Ingress "https://github.com/martinohmann/home-ops/tree/main//kubernetes/main/apps/networking/nginx"
    click CertMgr "https://github.com/martinohmann/home-ops/tree/main//kubernetes/main/apps/cert-manager"
    click ExtDNS "https://github.com/martinohmann/home-ops/tree/main//kubernetes/main/apps/networking/external-dns"
    click Longhorn "https://github.com/martinohmann/home-ops/tree/main//kubernetes/main/apps/longhorn-system"
    click Volsync "https://github.com/martinohmann/home-ops/tree/main//kubernetes/main/apps/volsync-system"
    click CSI_NFS "https://github.com/martinohmann/home-ops/tree/main//kubernetes/main/apps/kube-system/csi-driver-nfs"
    click ARunner "https://github.com/martinohmann/home-ops/tree/main//kubernetes/main/apps/actions-runner-system"
    click PromStack "https://github.com/martinohmann/home-ops/tree/main//kubernetes/main/apps/monitoring/kube-prometheus-stack"
    click Grafana "https://github.com/martinohmann/home-ops/tree/main//kubernetes/main/apps/monitoring/grafana"
    click Loki "https://github.com/martinohmann/home-ops/tree/main//kubernetes/main/apps/monitoring/loki"
    click Exporters "https://github.com/martinohmann/home-ops/tree/main//kubernetes/main/apps/monitoring/<exporter-name>"
    click ExtSecrets "https://github.com/martinohmann/home-ops/tree/main//kubernetes/main/apps/external-secrets"
    click DNSProvider "https://github.com/martinohmann/home-ops/tree/main//terraform/cloudflare"
    click NFS_Server "https://github.com/martinohmann/home-ops/tree/main//kubernetes/main/apps/kube-system/csi-driver-nfs"

    %% Styles
    classDef iac fill:#cce5ff,stroke:#004085,color:#004085
    classDef gitops fill:#d4edda,stroke:#155724,color:#155724
    classDef ci fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef service fill:#fff3cd,stroke:#856404,color:#856404
    classDef storage fill:#ffeeba,stroke:#856404,color:#856404
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24
```
