# thatmlopsguy/k8s-homelab architecture

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

- Interactive diagram: https://gitdiagram.com/thatmlopsguy/k8s-homelab
- Repository: https://github.com/thatmlopsguy/k8s-homelab

## Overview

##### Main components
a. Developer Workstation
- Local tools: Docker, Kind (Kubernetes-in-Docker), Helm, Kustomize, Kubectl, k9s
- `make` entrypoints (e.g. `make terraform-apply`)
b. Code Repository (GitHub)
- Top-level folders:
- `terraform/` – IaC to bootstrap and configure the Kind cluster, providers, variables.
- `clusters/` – Helm/Kustomize values for “main” cluster and its addons (Cert-Manager, VictoriaMetrics, etc.).
- `environments/` – Environment overlays (defaults & addons).
- `gitops/` – ArgoCD AppSets and Project definitions to drive GitOps sync of all addons.
- `docs/`, `mkdocs.yaml`, `requirements/docs.txt` – Documentation site.
- CI workflows: `.github/workflows/docs.yml`, `scorecard.yml`
c. CI/CD Pipeline (GitHub Actions)
- Docs build & deploy
- Security checks (Checkov, Scorecard)
d. Terraform (IaC)
- `terraform/bootstrap` – initial cluster setup, ArgoCD installation if `enable_gitops_bridge = true`.
- `terraform/main.tf`, providers, variables, locals.
e. Kubernetes (Kind) Cluster
- Control plane & worker nodes (all local)
- Namespaces for addons (cert-manager, keda, dapr, external-secrets, victoria-metrics)
- ArgoCD installed as an in-cluster component (optional)
f. ArgoCD (GitOps Controller)
- Watches the `gitops/` directory in the GitHub repo
- Uses AppSets to split and deploy each addon chart in the target cluster
g. Addon Components
- Cert-Manager
- Dapr
- External Secrets
- KEDA
- Victoria-Metrics
h. User / Inspect Tools
- Kubectl / k9s to inspect cluster status

##### Relationships & interactions
a. Developer → GitHub: Pushes code to branches → triggers CI/CD workflows
b. GitHub Actions → Documentation & Static Analysis → updates docs site, reports findings
c. Developer → Terraform CLI (`make terraform-apply`):
- Terraform creates Kind cluster (via bootstrap module)
- Optionally installs ArgoCD in the cluster
d. Terraform → Kubernetes API: Applies manifests for cluster provisioning
e. ArgoCD → GitHub Repo: Polls `gitops/` paths → generates AppSets → deploys addons into the cluster
f. Developer → Kubectl/k9s: Inspects live cluster, pods, services

##### Architectural patterns & principles
- Infrastructure as Code: Terraform for cluster provisioning
- GitOps pattern: ArgoCD + AppSets for continuous delivery of Helm/Kustomize manifests
- Layered configuration:
- Base cluster config in `clusters/`
- Environment overlays in `environments/`
- GitOps sync in `gitops/`
- Modular, declarative definitions for addons

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Layer
    subgraph "Developer Workstation" 
        direction TB
        DevTools["Developer Workstation"]:::green
    end
    click DevTools "https://github.com/thatmlopsguy/k8s-homelab/tree/main/Makefile"

    %% Code Repository & CI/CD
    subgraph "Code Repository (GitHub)" 
        direction TB
        GitHubRepo["GitHub Repository"]:::blue

        subgraph "Terraform IaC" 
            direction TB
            TerraformRepo["terraform/"]:::green
            click TerraformRepo "https://github.com/thatmlopsguy/k8s-homelab/tree/main/terraform/"
            subgraph "Bootstrap Module" 
                direction TB
                TerraformBootstrap["terraform/bootstrap/"]:::green
                click TerraformBootstrap "https://github.com/thatmlopsguy/k8s-homelab/tree/main/terraform/bootstrap/"
            end
            subgraph "Main Config Files" 
                direction TB
                MainTF["main.tf"]:::green
                ProvidersTF["providers.tf"]:::green
                VariablesTF["variables.tf"]:::green
                LocalsTF["locals.tf"]:::green
                TFVars["terraform.tfvars"]:::green
                click MainTF "https://github.com/thatmlopsguy/k8s-homelab/blob/main/terraform/main.tf"
                click ProvidersTF "https://github.com/thatmlopsguy/k8s-homelab/blob/main/terraform/providers.tf"
                click VariablesTF "https://github.com/thatmlopsguy/k8s-homelab/blob/main/terraform/variables.tf"
                click LocalsTF "https://github.com/thatmlopsguy/k8s-homelab/blob/main/terraform/locals.tf"
                click TFVars "https://github.com/thatmlopsguy/k8s-homelab/blob/main/terraform/terraform.tfvars"
            end
        end

        subgraph "Cluster Config" 
            direction TB
            ClustersMain["clusters/main/"]:::blue
            click ClustersMain "https://github.com/thatmlopsguy/k8s-homelab/tree/main/clusters/main/"
            VictoriaValues["victoria-metrics values"]:::orange
            click VictoriaValues "https://github.com/thatmlopsguy/k8s-homelab/blob/main/clusters/main/addons/victoria-metrics-k8s-stack/values.yaml"
        end

        subgraph "Environment Overlays" 
            direction TB
            EnvDefault["environments/default/"]:::blue
            click EnvDefault "https://github.com/thatmlopsguy/k8s-homelab/tree/main/environments/default/"
            CertValues["cert-manager values"]:::orange
            click CertValues "https://github.com/thatmlopsguy/k8s-homelab/blob/main/environments/default/addons/cert-manager/values.yaml"
        end

        subgraph "GitOps Definitions" 
            direction TB
            GitopsRepo["gitops/"]:::purple
            click GitopsRepo "https://github.com/thatmlopsguy/k8s-homelab/tree/main/gitops/"
            AppSets["ArgoCD AppSets"]:::purple
            click AppSets "https://github.com/thatmlopsguy/k8s-homelab/blob/main/gitops/addons/appsets/addons-*.yaml"
            Projects["ArgoCD Projects"]:::purple
            click Projects "https://github.com/thatmlopsguy/k8s-homelab/blob/main/gitops/addons/projects/infrastructure.yaml"
        end

        subgraph "Documentation" 
            direction TB
            DocsSource["docs/index.md"]:::blue
            click DocsSource "https://github.com/thatmlopsguy/k8s-homelab/blob/main/docs/index.md"
            Mkdocs["mkdocs.yaml"]:::blue
            click Mkdocs "https://github.com/thatmlopsguy/k8s-homelab/blob/main/mkdocs.yaml"
            Requirements["requirements/docs.txt"]:::blue
            click Requirements "https://github.com/thatmlopsguy/k8s-homelab/blob/main/requirements/docs.txt"
        end

        subgraph "CI/CD Workflows" 
            direction TB
            DocsWF["Docs Build & Deploy"]:::purple
            click DocsWF "https://github.com/thatmlopsguy/k8s-homelab/blob/main/.github/workflows/docs.yml"
            SecWF["Security Checks"]:::purple
            click SecWF "https://github.com/thatmlopsguy/k8s-homelab/blob/main/.github/workflows/scorecard.yml"
        end
    end

    %% Terraform to Cluster
    subgraph "Kubernetes (Kind) Cluster" 
        direction TB
        KindCluster["Kind Cluster"]:::orange
        subgraph "Namespaces & Addons" 
            direction TB
            CertManager["Cert-Manager"]:::orange
            Dapr["Dapr"]:::orange
            ExternalSecrets["External Secrets"]:::orange
            KEDA["KEDA"]:::orange
            VictoriaMetrics["Victoria-Metrics"]:::orange
        end
    end

    %% ArgoCD Layer
    ArgoCD["ArgoCD (GitOps Controller)"]:::purple

    %% Inspect Tools
    Kubectl["kubectl / k9s"]:::green

    %% Connections
    DevTools -->|"git push"| GitHubRepo
    GitHubRepo -->|"trigger"| DocsWF
    GitHubRepo -->|"trigger"| SecWF
    DevTools -->|"make terraform-apply"| TerraformBootstrap
    TerraformBootstrap -->|"provision cluster"| KindCluster
    TerraformBootstrap -->|"install ArgoCD"| ArgoCD
    ArgoCD -.->|"poll gitops/ sync"| GitopsRepo
    ArgoCD -->|"deploy addons"| KindCluster
    GitopsRepo -->|"defines apps"| ArgoCD
    KindCluster -->|"resources"| CertManager
    KindCluster -->|"resources"| Dapr
    KindCluster -->|"resources"| ExternalSecrets
    KindCluster -->|"resources"| KEDA
    KindCluster -->|"resources"| VictoriaMetrics
    DevTools -->|"inspect"| Kubectl
    Kubectl -->|"get pods/services"| KindCluster

    %% Styles
    classDef blue fill:#cce5ff,stroke:#004085;
    classDef green fill:#d4edda,stroke:#155724;
    classDef orange fill:#ffe5b4,stroke:#e65c00;
    classDef purple fill:#e2ccf9,stroke:#5e35b1;
```
