# this-is-tobi/homelab architecture

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

- Interactive diagram: https://gitdiagram.com/this-is-tobi/homelab
- Repository: https://github.com/this-is-tobi/homelab

## Overview

##### Project Type and Purpose
- This is an infrastructure‐as‐code and GitOps homelab project. It uses Ansible to bootstrap and configure a two‐tier environment:
- “Infra” layer: a gateway node (running HAProxy, Pi-Hole, WireGuard) plus a K3s cluster (masters & workers).
- “Kube” layer: Kubernetes services and applications deployed via Ansible and managed over GitOps (Argo CD + Helm charts).
- Purpose: rapid stand‐up of a homelab for testing CI/CD, monitoring, security, etc.

##### File Structure Analysis
- Top‐level:
- ansible/infra: playbooks, roles, inventory for provisioning VMs/hosts.
- ansible/kube: playbooks, roles, inventory for deploying to the K3s cluster.
- argo-cd directory: Helm apps definitions for GitOps (Chart.yaml, values, templates).
- docs, scripts, run.sh: documentation and helper scripts.
- Patterns & Config files:
- Ansible roles follow a clear separation: common, gateway, k3s.
- Kubernetes services organized into “core”, “additional”, “utils” roles.
- Argo CD manifests group each service as a Helm app under argo-cd/apps.

##### README Insights
- Confirms two installation stages: “Infra” via ansible/infra/install.yml, then “Kubernetes” via ansible/kube/install.yml.
- Encourages use of run.sh wrapper to invoke Ansible with inventories.
- Services include monitoring (Prometheus/Grafana), CI runners, registries, identity (Keycloak, Vault), storage (MinIO, Longhorn), etc.

a. Main Components
- Ansible Control Host (your laptop/CI)
- Gateway Host (bare metal/VM)
- K3s Master Nodes (HA API, scheduling)
- K3s Worker Nodes (app execution)
- Argo CD (GitOps control plane)
- Core Services (Cert-Manager, Traefik, SSO, Vault)
- Additional Services (Harbor, Gitea, SonarQube, etc.)
- Monitoring Stack (Prometheus, Grafana, Loki)
- External Services/Users (Internet DNS, VPN clients)
b. Relationships & Data Flows
1. Ansible → Gateway + K3s nodes: SSH to provision OS, Docker, WireGuard, K3s.
2. Gateway → Internet: DNS resolution (Pi-Hole), load balancing (HAProxy), VPN ingress/egress (WireGuard).
3. K3s Masters ←→ Workers: Kubernetes control‐plane communication.
4. Ansible-Kube → K3s API: deploy core & additional Helm charts.
5. Argo CD monitors Git repo (argo-cd/apps & envs) → pushes manifests to K3s API.
6. Users/CI → WireGuard VPN → internal services; external web clients → HAProxy → Traefik ingress.
c. Architectural Patterns
- IaC with Ansible roles & inventories
- Microservices on Kubernetes
- GitOps via Argo CD + Helm charts
- Layered network: gateway perimeter → internal cluster
- Role separation: core infra vs. dev/test services
d. Technologies & Frameworks
- Ansible (roles, playbooks, inventories)
- K3s (lightweight Kubernetes)
- Docker (gateway containers)
- Helm & Argo CD (GitOps)
- WireGuard, HAProxy, Pi-Hole (network gateway)
- Cert-Manager, Traefik, Vault, Keycloak, MinIO, etc.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Entities
    subgraph "External Zone"
        direction TB
        Internet["Internet DNS & Clients"]:::external
        VPN["VPN Clients"]:::external
    end

    %% Infra Layer
    subgraph "Infra Layer" 
        direction TB
        subgraph "Ansible Infra" 
            direction TB
            AControl["Ansible Control Host"]:::infra
            PIWrap["run.sh"]:::ansible
            InfraPlaybook["ansible/infra/install.yml"]:::ansible
            InfraInv["ansible/infra/inventory-example/hosts.yml"]:::ansible
            InfraGV["ansible/infra/inventory-example/group_vars"]:::ansible
            RoleCommon["ansible/infra/roles/common"]:::ansible
            RoleGateway["ansible/infra/roles/gateway"]:::ansible
            RoleK3sMasters["ansible/infra/roles/k3s/deploy/masters"]:::ansible
            RoleK3sWorkers["ansible/infra/roles/k3s/deploy/workers"]:::ansible
            RolePrereq["ansible/infra/roles/k3s/prereq"]:::ansible
            RoleRegistry["ansible/infra/roles/k3s/registry"]:::ansible
            RoleDestroy["ansible/infra/roles/k3s/destroy"]:::ansible

            AControl -->|runs| PIWrap
            PIWrap --> InfraPlaybook
            InfraPlaybook --> InfraInv
            InfraPlaybook --> InfraGV
            InfraPlaybook --> RoleCommon
            InfraPlaybook --> RoleGateway
            InfraPlaybook --> RolePrereq
            InfraPlaybook --> RoleRegistry
            InfraPlaybook --> RoleK3sMasters
            InfraPlaybook --> RoleK3sWorkers
            InfraPlaybook --> RoleDestroy
        end

        Gateway["Gateway Host\n(HAProxy, Pi-Hole, WireGuard)"]:::infra
        Masters["K3s Master Nodes"]:::infra
        Workers["K3s Worker Nodes"]:::infra

        RoleGateway --> Gateway
        RoleK3sMasters --> Masters
        RoleK3sWorkers --> Workers
        RolePrereq --> Masters & Workers
        RoleRegistry --> Masters & Workers
    end

    %% Kubernetes Layer
    subgraph "Kubernetes Layer"
        direction TB
        subgraph "Ansible Kube"
            direction TB
            KubePlaybook["ansible/kube/install.yml"]:::ansible
            KubeGV["ansible/kube/inventory-example/group_vars"]:::ansible
            RoleProjects["ansible/kube/roles/projects/setup"]:::ansible
            RoleCore["ansible/kube/roles/services/core"]:::ansible
            RoleAdd["ansible/kube/roles/services/additional"]:::ansible
            RoleUtils["ansible/kube/roles/services/utils"]:::ansible
            KubeTpl["ansible/kube/templates"]:::ansible

            KubePlaybook --> KubeGV
            KubePlaybook --> RoleProjects
            KubePlaybook --> RoleCore
            KubePlaybook --> RoleAdd
            KubePlaybook --> RoleUtils
            KubePlaybook --> KubeTpl
        end

        subgraph "GitOps Control Plane"
            direction TB
            Repo["Git Repo\n(argo-cd/apps & argo-cd/envs)"]:::git
            Platform["argo-cd/platform-manager.yaml"]:::git
            Apps["argo-cd/apps"]:::git
            Envs["argo-cd/envs/01-production.json"]:::git

            Repo --> Platform
            Repo --> Apps
            Repo --> Envs
        end

        GitOps["Argo CD"]:::k8s

        KubePlaybook -->|provisions Helm apps| GitOps
        Platform --> GitOps
        Apps --> GitOps
        Envs --> GitOps
        GitOps -->|"deploys via K8s API"| Masters
    end

    %% Traffic Flows
    Internet -->|DNS/HTTP| Gateway
    VPN -->|VPN Tunnel| Gateway
    Gateway -->|Load Balance/Ingress| Masters
    VPN -->|VPN Tunnel| Masters
    AControl -->|SSH Provisioning| Gateway & Masters & Workers

    %% Styles
    classDef infra fill:#FFCC99,stroke:#333,stroke-width:1px
    classDef k8s fill:#99CCFF,stroke:#333,stroke-width:1px
    classDef service fill:#99FF99,stroke:#333,stroke-width:1px
    classDef external fill:#DDDDDD,stroke:#333,stroke-width:1px
    classDef ansible fill:#FFB3B3,stroke:#333,stroke-width:1px
    classDef git fill:#FFE599,stroke:#333,stroke-width:1px

    %% Click Events
    click PIWrap "https://github.com/this-is-tobi/homelab/blob/main/run.sh"
    click InfraPlaybook "https://github.com/this-is-tobi/homelab/blob/main/ansible/infra/install.yml"
    click InfraInv "https://github.com/this-is-tobi/homelab/blob/main/ansible/infra/inventory-example/hosts.yml"
    click InfraGV "https://github.com/this-is-tobi/homelab/tree/main/ansible/infra/inventory-example/group_vars"
    click RoleCommon "https://github.com/this-is-tobi/homelab/tree/main/ansible/infra/roles/common"
    click RoleGateway "https://github.com/this-is-tobi/homelab/tree/main/ansible/infra/roles/gateway"
    click RoleK3sMasters "https://github.com/this-is-tobi/homelab/tree/main/ansible/infra/roles/k3s/deploy/masters"
    click RoleK3sWorkers "https://github.com/this-is-tobi/homelab/tree/main/ansible/infra/roles/k3s/deploy/workers"
    click RolePrereq "https://github.com/this-is-tobi/homelab/tree/main/ansible/infra/roles/k3s/prereq"
    click RoleRegistry "https://github.com/this-is-tobi/homelab/tree/main/ansible/infra/roles/k3s/registry"
    click RoleDestroy "https://github.com/this-is-tobi/homelab/tree/main/ansible/infra/roles/k3s/destroy"
    click KubePlaybook "https://github.com/this-is-tobi/homelab/blob/main/ansible/kube/install.yml"
    click KubeGV "https://github.com/this-is-tobi/homelab/tree/main/ansible/kube/inventory-example/group_vars"
    click RoleProjects "https://github.com/this-is-tobi/homelab/tree/main/ansible/kube/roles/projects/setup"
    click RoleCore "https://github.com/this-is-tobi/homelab/tree/main/ansible/kube/roles/services/core"
    click RoleAdd "https://github.com/this-is-tobi/homelab/tree/main/ansible/kube/roles/services/additional"
    click RoleUtils "https://github.com/this-is-tobi/homelab/tree/main/ansible/kube/roles/services/utils"
    click KubeTpl "https://github.com/this-is-tobi/homelab/tree/main/ansible/kube/templates"
    click Platform "https://github.com/this-is-tobi/homelab/blob/main/argo-cd/platform-manager.yaml"
    click Apps "https://github.com/this-is-tobi/homelab/tree/main/argo-cd/apps"
    click Envs "https://github.com/this-is-tobi/homelab/blob/main/argo-cd/envs/01-production.json"
    click docs "https://github.com/this-is-tobi/homelab/tree/main/docs/"
    click scripts "https://github.com/this-is-tobi/homelab/tree/main/scripts/"
```
