# eddycharly/kind-playground architecture

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

- Interactive diagram: https://gitdiagram.com/eddycharly/kind-playground
- Repository: https://github.com/eddycharly/kind-playground

## Overview

##### Project type and purpose
- This is an infrastructure-as-code/GitOps “playground” for spinning up a local Kubernetes cluster using Kind, Cilium CNI, MetalLB, ingress-nginx, dnsmasq, Keycloak SSO and an ArgoCD-driven GitOps pipeline. It combines shell scripts, Helm charts, Terraform, raw manifests and ArgoCD Application definitions to bootstrap, configure and operate your entire stack locally.

##### File structure
- Top-level scripts:
- cluster.sh: bootstraps Kind cluster + Cilium CNI, MetalLB, ingress, dnsmasq, container-registry proxies
- keycloak.sh: deploys Keycloak + configures it via Terraform for OIDC
- argocd.sh: deploys ArgoCD configured for Keycloak OIDC
- argocd-applications.sh/gitops.sh: batch-apply ArgoCD Application manifests
- wipe.sh: teardown logic
- Directories:
- argocd/: ArgoCD Application manifests (one YAML per app)
- helm/gitops/: a Helm chart packaging all core components (argocd, cert-manager, cilium, ingress-nginx, etc.) plus network policy templates
- manifests/: raw Kubernetes manifests (Mattermost ingress)
- terraform/keycloak/: Terraform code to configure Keycloak realm, clients, users for SSO
- Configuration files:
- Helm Chart.yaml, values.yaml, .helmignore
- Terraform .tf files
- .gitignore

##### Extract additional insights from README
- Workflow:
- Run cluster.sh → Kind cluster + core networking + identity proxy
- Run keycloak.sh → Keycloak installed in the cluster + Terraform-backed realm/client setup
- Run argocd.sh → ArgoCD installed, pointing at Keycloak OIDC
- Use ArgoCD CLI or UI to sync Applications declared in argocd/
- Emphasis on local “play” environment, SSO integration, GitOps control plane

a. Main components
- Developer workstation (scripts + Git repository)
- Kind Kubernetes cluster (control plane & worker nodes)
- Core cluster services: Cilium CNI, MetalLB, ingress-nginx, dnsmasq, registry proxies
- Identity layer: Keycloak (deployed inside the cluster + external access)
- GitOps control plane: ArgoCD
- Application layer: cluster apps managed by ArgoCD (Cert-Manager, Gitea, Prometheus, etc.)
- Terraform module (external process) configuring Keycloak realm/client
b. Relationships & interactions
- Dev runs shell scripts → calls kind + kubectl + helm to install core services
- Terraform CLI → interacts with Keycloak’s HTTP API inside cluster
- ArgoCD watches this Git repo → reads argocd/*.yaml → deploys/monitors target apps
- Kubernetes API server delegates auth to Keycloak OIDC
- External traffic flows through MetalLB → ingress-nginx → specific services
- Cilium enforces network policies (from helm/gitops/templates/network-policies)
c. Architectural patterns & principles
- GitOps: declarative desired state in Git, ArgoCD as reconciliation engine
- Infrastructure as code: scripts + Helm + Terraform
- Modular: each system component (network, identity, GitOps, apps) isolated in its own manifest/chart/module
- Zero trust networking via Cilium + network-policy templates
d. Key technologies/frameworks
- Kind (Kubernetes-in-Docker)
- Kubernetes API, kubectl
- Cilium CNI, MetalLB, ingress-nginx, dnsmasq
- Helm chart for core services
- Terraform for Keycloak realm configuration
- Keycloak (OIDC provider)
- ArgoCD (GitOps controller)
- Various cluster applications (Cert-Manager, Gitea, Prometheus, Mattermost, etc.)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Provisioning Layer
    subgraph "Provisioning" 
        direction TB
        BS["_bootstrap.sh"]:::provisioning
        CSH["cluster.sh"]:::provisioning
        KSH["keycloak.sh"]:::provisioning
        ASH["argocd.sh"]:::provisioning
        AASH["argocd-applications.sh"]:::provisioning
        GSH["gitops.sh"]:::provisioning
        GTSH["gitea.sh"]:::provisioning
        PPSH["kube-prometheus-stack.sh"]:::provisioning
        WSH["wipe.sh"]:::provisioning
    end

    %% Cluster Core Layer
    subgraph "Cluster Core" 
        direction TB
        K8S["Kind Kubernetes\n(control plane & worker)"]:::cluster
        CIL["Cilium CNI"]:::cluster
        MLB["MetalLB"]:::cluster
        ING["ingress-nginx"]:::cluster
        DNS["dnsmasq"]:::cluster
        REG["Registry Proxies"]:::cluster
    end

    %% Identity Layer
    subgraph "Identity" 
        direction TB
        KC["Keycloak (OIDC)"]:::identity
        TF["Terraform Module"]:::identity
    end

    %% GitOps & Apps Layer
    subgraph "GitOps & Apps" 
        direction TB
        ARGO["ArgoCD"]:::gitops
        GITREP["Git Repository\n(argocd/ manifests)"]:::gitops
        APPS["Cluster Applications\n(Cert-Manager, Gitea, Prometheus, Mattermost, etc.)"]:::gitops
    end

    %% External Clients
    EXT["External Clients"]:::external

    %% Workflow arrows
    BS --> CSH
    BS --> KSH
    BS --> ASH
    BS --> AASH
    CSH -->|helm/kubectl| K8S
    CSH -->|Helm Chart| CIL
    CSH --> MLB
    CSH --> ING
    CSH --> DNS
    CSH --> REG
    KSH -->|Terraform CLI| TF
    TF -->|HTTP API| KC
    ASH -->|kubectl| ARGO
    ARGO -->|pull| GITREP
    ARGO -->|push/kubectl| K8S
    GITREP --> APPS
    EXT -->|TCP| MLB
    MLB --> ING
    ING --> APPS

    %% Click events Provisioning
    click BS "https://github.com/eddycharly/kind-playground/blob/main/./_bootstrap.sh"
    click CSH "https://github.com/eddycharly/kind-playground/blob/main/./cluster.sh"
    click KSH "https://github.com/eddycharly/kind-playground/blob/main/./keycloak.sh"
    click ASH "https://github.com/eddycharly/kind-playground/blob/main/./argocd.sh"
    click AASH "https://github.com/eddycharly/kind-playground/blob/main/./argocd-applications.sh"
    click GSH "https://github.com/eddycharly/kind-playground/blob/main/./gitops.sh"
    click GTSH "https://github.com/eddycharly/kind-playground/blob/main/./gitea.sh"
    click PPSH "https://github.com/eddycharly/kind-playground/blob/main/./kube-prometheus-stack.sh"
    click WSH "https://github.com/eddycharly/kind-playground/blob/main/./wipe.sh"

    %% Click events Helm Chart
    click CIL "https://github.com/eddycharly/kind-playground/blob/main/helm/gitops/templates/cilium.yaml"
    click MLB "https://github.com/eddycharly/kind-playground/blob/main/helm/gitops/templates/metallb.yaml"
    click ING "https://github.com/eddycharly/kind-playground/blob/main/helm/gitops/templates/ingress-nginx.yaml"
    click KC "https://github.com/eddycharly/kind-playground/blob/main/helm/gitops/templates/keycloak.yaml"
    click TF "https://github.com/eddycharly/kind-playground/blob/main/terraform/keycloak/main.tf"

    %% Click events ArgoCD and apps
    click ARGO "https://github.com/eddycharly/kind-playground/blob/main/argocd/argocd.yaml"
    click GITREP "https://github.com/eddycharly/kind-playground/blob/main/argocd/cert-manager.yaml"
    click APPS "https://github.com/eddycharly/kind-playground/blob/main/argocd/mattermost-team-edition.yaml"

    %% Click raw manifest
    click EXT "https://github.com/eddycharly/kind-playground/blob/main/manifests/mattermost-team-edition/ingress.yaml"

    %% Styling
    classDef provisioning fill:#e2f0d9,stroke:#82c341,color:#000;
    classDef cluster fill:#daf1fc,stroke:#33a6cc,color:#000;
    classDef identity fill:#ffe5b4,stroke:#ff8c00,color:#000;
    classDef gitops fill:#f3dafc,stroke:#b24fff,color:#000;
    classDef external fill:#f0f0f0,stroke:#999,color:#000;
```
