# mitchross/k3s-argocd-starter architecture

> Architecture diagram of the GitHub repository mitchross/k3s-argocd-starter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mitchross/k3s-argocd-starter
- Repository: https://github.com/mitchross/k3s-argocd-starter

## Overview

##### Project type and purpose
- This is a GitOps-based Kubernetes starter kit. It defines a production-ready K3s cluster layout, bootstraps Argo CD, installs networking (Cilium, Cloudflared, Gateway API), storage (OpenEBS, NFS CSI), certificate management, a monitoring stack (Prometheus, Grafana, AlertManager) and a set of user applications.
- Its goal: demonstrate a two-level Argo CD ApplicationSet structure (Infrastructure vs. Applications vs. Monitoring) with best practices for security boundaries, sync ordering, self-healing and RBAC.

##### File structure
- Top-level directories
– infrastructure: YAML manifests split into controllers (Argo CD, cert-manager), networking (cilium, cloudflared, gateway), storage (OpenEBS, CSI-NFS)
– monitoring: manifests for the Prometheus operator stack, Grafana, AlertManager, NodeExporter
– my-apps: per-application overlays (headlamp, nginx, searxng, proxitok, etc.), plus an applications-ApplicationSet manifest
– docs: auxiliary guides (e.g., AdGuard Home DNS)
– .github, .vscode: CI/configuration
- Key files
– infrastructure/infrastructure-components-appset.yaml
– monitoring/monitoring-components-appset.yaml
– my-apps/myapplications-appset.yaml
– infrastructure/controllers/argocd/* (bootstrap of Argo CD itself)
- Patterns
– GitOps (Argo CD) with ApplicationSets grouped into logical projects
– Kustomize overlays per folder
– Helm values injected via Kustomize
– Clear three-tier separation: Infrastructure, Monitoring, User Applications

##### README for additional insights
– Three Argo CD Projects (Infrastructure, Applications, Monitoring)
– Under Infrastructure: Networking (Cilium, Cloudflared, Gateway), Storage (OpenEBS), Controllers (Cert-Manager)
– Under Monitoring: Prometheus, Grafana, AlertManager, NodeExporter
– Under User Applications: categories (Privacy Apps, Web Apps, Other Apps) and example micro-services
- Details on sync waves, RBAC enforcement, self-healing, prerequisites, and step-by-step quick-start commands

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Services
    subgraph "External Services"
        direction TB
        GitHub["GitHub (Git Repo)"]:::external
        HelmRepo["Helm Repos"]:::external
        CloudflareAPI["Cloudflare API"]:::external
    end

    %% GitOps Engine
    subgraph "GitOps Layer"
        direction TB
        GitRepo["Repo (this)"]:::external
        ArgoCD["Argo CD Server"]:::gitops
        GitHub -->|watches| ArgoCD
        GitRepo -->|sync desired state| ArgoCD
    end

    %% Argo CD Projects & ApplicationSets
    subgraph "Argo CD Projects" 
        direction TB
        InfraProj["Infrastructure Project"]:::gitops
        MonProj["Monitoring Project"]:::gitops
        AppsProj["Applications Project"]:::gitops

        InfraAS["Infrastructure ApplicationSet"]:::gitops
        MonAS["Monitoring ApplicationSet"]:::gitops
        AppsAS["Applications ApplicationSet"]:::gitops

        ArgoCD -->|manages| InfraProj
        ArgoCD -->|manages| MonProj
        ArgoCD -->|manages| AppsProj

        InfraProj -->|contains| InfraAS
        MonProj -->|contains| MonAS
        AppsProj -->|contains| AppsAS
    end

    %% Cluster
    subgraph "K3s Cluster" 
        direction TB
        controlPlane["Control Plane Nodes"]:::cluster
        workerNodes["Worker Nodes"]:::cluster

        controlPlane --> workerNodes

        %% Infrastructure Layer
        subgraph "Infrastructure" 
            direction TB
            InfraControllers["Controllers"]:::infra
            InfraNetworking["Networking"]:::infra
            InfraStorage["Storage"]:::infra

            InfraAS -->|deploys| InfraControllers
            InfraAS -->|deploys| InfraNetworking
            InfraAS -->|deploys| InfraStorage

            %% Controllers
            subgraph "Controllers" 
                direction TB
                ArgoBootstrap["Argo CD Bootstrap"]:::infra
                CertManager["Cert-Manager"]:::infra

                InfraControllers --> ArgoBootstrap
                InfraControllers --> CertManager
            end

            %% Networking
            subgraph "Networking"
                direction TB
                Cilium["Cilium CNI"]:::infra
                Cloudflared["Cloudflared Tunnel"]:::infra
                GatewayAPI["Gateway API"]:::infra

                InfraNetworking --> Cilium
                InfraNetworking --> Cloudflared
                InfraNetworking --> GatewayAPI
            end

            %% Storage
            subgraph "Storage"
                direction TB
                OpenEBS["OpenEBS"]:::infra
                CSINFS["CSI-NFS"]:::infra

                InfraStorage --> OpenEBS
                InfraStorage --> CSINFS
            end
        end

        %% Monitoring Layer
        subgraph "Monitoring" 
            direction TB
            MonProjectDef["Monitoring Project Definition"]:::monitor
            MonNamespace["Monitoring Namespace"]:::monitor
            MonAS -->|deploys| MonProjectDef
            MonAS -->|deploys| MonNamespace

            subgraph "Monitoring Stack"
                direction TB
                Prometheus["Prometheus Operator"]:::monitor
                AlertManager["AlertManager"]:::monitor
                Grafana["Grafana"]:::monitor
                NodeExporter["Node Exporter"]:::monitor

                MonNamespace --> Prometheus
                MonNamespace --> AlertManager
                MonNamespace --> Grafana
                MonNamespace --> NodeExporter
            end
        end

        %% Applications Layer
        subgraph "Applications" 
            direction TB
            AppsAS -->|deploys| AppsProj

            %% Example Apps
            Headlamp["Headlamp"]:::apps
            HelloWorld["HelloWorld"]:::apps
            Dashboard["Homepage Dashboard"]:::apps
            ITTools["IT Tools"]:::apps
            LibReddit["LibReddit"]:::apps
            NginxApp["Nginx"]:::apps
            ProxiTok["ProxiTok"]:::apps
            SearxNG["SearxNG"]:::apps

            AppsProj --> Headlamp
            AppsProj --> HelloWorld
            AppsProj --> Dashboard
            AppsProj --> ITTools
            AppsProj --> LibReddit
            AppsProj --> NginxApp
            AppsProj --> ProxiTok
            AppsProj --> SearxNG
        end

        %% Flows
        CertManager -->|DNS-01| CloudflareAPI
        GatewayAPI -->|routes traffic| Cloudflared
        Prometheus -->|scrapes| controlPlane
        Prometheus -->|scrapes| Cilium
        Prometheus -->|scrapes| NodeExporter
        Prometheus -->|scrapes| Headlamp
        Prometheus -->|scrapes| HelloWorld
    end

    %% Click Events
    click InfraAS "https://github.com/mitchross/k3s-argocd-starter/blob/main/infrastructure/infrastructure-components-appset.yaml"
    click ArgoBootstrap "https://github.com/mitchross/k3s-argocd-starter/tree/main/infrastructure/controllers/argocd"
    click CertManager "https://github.com/mitchross/k3s-argocd-starter/tree/main/infrastructure/controllers/cert-manager"
    click Cilium "https://github.com/mitchross/k3s-argocd-starter/tree/main/infrastructure/networking/cilium"
    click Cloudflared "https://github.com/mitchross/k3s-argocd-starter/tree/main/infrastructure/networking/cloudflared"
    click GatewayAPI "https://github.com/mitchross/k3s-argocd-starter/tree/main/infrastructure/networking/gateway"
    click OpenEBS "https://github.com/mitchross/k3s-argocd-starter/tree/main/infrastructure/storage/openebs"
    click CSINFS "https://github.com/mitchross/k3s-argocd-starter/tree/main/infrastructure/storage/csi-driver-nfs"
    click MonAS "https://github.com/mitchross/k3s-argocd-starter/blob/main/monitoring/monitoring-components-appset.yaml"
    click MonProjectDef "https://github.com/mitchross/k3s-argocd-starter/blob/main/monitoring/project.yaml"
    click MonNamespace "https://github.com/mitchross/k3s-argocd-starter/blob/main/monitoring/namespace.yaml"
    click Prometheus "https://github.com/mitchross/k3s-argocd-starter/tree/main/monitoring/prometheus-stack"
    click AppsAS "https://github.com/mitchross/k3s-argocd-starter/blob/main/my-apps/myapplications-appset.yaml"
    click Headlamp "https://github.com/mitchross/k3s-argocd-starter/tree/main/my-apps/headlamp"
    click HelloWorld "https://github.com/mitchross/k3s-argocd-starter/tree/main/my-apps/hello-world"
    click Dashboard "https://github.com/mitchross/k3s-argocd-starter/tree/main/my-apps/homepage-dashboard"
    click ITTools "https://github.com/mitchross/k3s-argocd-starter/tree/main/my-apps/it-tools"
    click LibReddit "https://github.com/mitchross/k3s-argocd-starter/tree/main/my-apps/libreddit"
    click NginxApp "https://github.com/mitchross/k3s-argocd-starter/tree/main/my-apps/nginx"
    click ProxiTok "https://github.com/mitchross/k3s-argocd-starter/tree/main/my-apps/proxitok"
    click SearxNG "https://github.com/mitchross/k3s-argocd-starter/tree/main/my-apps/searxng"

    %% Styles
    classDef external fill:#cccccc,stroke:#333,stroke-width:1px
    classDef gitops fill:#a0c4ff,stroke:#333,stroke-width:1px
    classDef cluster fill:#eaeaea,stroke:#333,stroke-width:1px
    classDef infra fill:#caffbf,stroke:#333,stroke-width:1px
    classDef monitor fill:#ffd6a5,stroke:#333,stroke-width:1px
    classDef apps fill:#bdb2ff,stroke:#333,stroke-width:1px
```
