# lconnell/kubernetes-playground architecture

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

- Interactive diagram: https://gitdiagram.com/lconnell/kubernetes-playground
- Repository: https://github.com/lconnell/kubernetes-playground

## Overview

##### Project Type and Purpose
- The project is a Kubernetes-centric deployment system that leverages an Admission Controller implemented as a webhook and uses kustomize overlays to manage different deployment environments (dev and prod).
- It also integrates with GitOps tools (ArgoCD, Flux) for automated deployment and verification. The README’s build/apply commands using kustomize indicate that this project primarily manages Kubernetes resources.

##### File Structure
- Key Top-Level Directories:
- admission-controller: Contains configuration files (mutating-webhook.yaml, validating-webhook.yaml) and code for the webhook API (webhook.py, Dockerfile, docker-compose.yml). This is the core of the dynamic admission control.
- argocd: Contains YAML configurations (app-dev.yaml, app-prod.yaml) to manage applications in different environments via ArgoCD.
- kustomize: Has a "base" directory defining the fundamental Kubernetes resources (API, DB, secrets, service, config files) and overlay directories (dev and prod) that modify the base configuration for specific environments.
- bin: Houses installation scripts for provisioning essential tools (ArgoCD and Flux), indicating integration with CI/CD pipelines.
- .github/workflows: Indicates automation for validating Kubernetes manifests in CI.
- Architectural Patterns:
- Usage of GitOps (ArgoCD/Flux) to manage cluster configuration.
- Separation of concerns via environment overlays (dev and prod) and a modularized approach to building webhook services.

##### Main Components of the System
a. Admission Controller:
- Components: Webhook API (code and Docker container), webhook configuration (mutating and validating hooks), deployment, and service manifest.
- Interaction: It operates within the Kubernetes cluster to intercept API server requests, perform validations or mutations, and enforce policies.

b. Kustomize-Based Kubernetes Configurations:
- Components: Base Kubernetes resources (API service, database service, secrets, config maps) and overlays for different environments (dev and prod).
- Interaction: These overlays tailor the base deployment according to the target environment.

c. GitOps/CD Integration:
- Components: ArgoCD application definitions for dev/prod (located in the argocd directory) and related installation scripts (bin directory).
- Interaction: They continuously monitor the Git repository for configuration changes and trigger deployments to the cluster.

d. CI/CD Automation:
- Component: GitHub workflows (e.g., validate-k8s.yaml) for automatically validating the Kubernetes manifests, ensuring the integrity of deployments.

##### Relationships and Data Flow
- Developer pushes changes → GitHub Repository:
- CI/CD pipelines (via GitHub Actions in .github/workflows) validate these changes.
- GitOps Tool (ArgoCD) monitors the repository:
- Reads the kustomize directories and overlays.
- Applies deployments to the respective namespaces (development and production).
- Within the Cluster:
- The Admission Controller (with its webhook API) intercepts and processes API requests.
- Other resources (API, DB services, config maps, secrets, etc.) are deployed per the base/overlay kustomize specs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Developer["Developer"]:::external
    Repo["Git Repository"]:::external
    CI["CI/CD Pipeline (GitHubWorkflows)"]:::ci
    GitOps["GitOps Tools (ArgoCD/Flux)"]:::gitops
    Inst["Installation Scripts"]:::gitops

    Developer -->|"pushes"| Repo
    Repo -->|"triggers"| CI
    CI -->|"initiates"| GitOps
    Inst -->|"provisions"| GitOps

    subgraph "Kubernetes Cluster"
        AC["Admission Controller"]:::admission
        KC["Kustomize Resources (Base & Overlays)"]:::kustomize
    end

    GitOps -->|"deploys to"| AC
    GitOps -->|"deploys to"| KC

    %% Click Events
    click AC "https://github.com/lconnell/kubernetes-playground/tree/main/admission-controller/"
    click KC "https://github.com/lconnell/kubernetes-playground/tree/main/kustomize/"
    click GitOps "https://github.com/lconnell/kubernetes-playground/tree/main/argocd/"
    click Inst "https://github.com/lconnell/kubernetes-playground/tree/main/bin/"
    click CI "https://github.com/lconnell/kubernetes-playground/blob/main/.github/workflows/validate-k8s.yaml"

    %% Styles
    classDef external fill:#ffddcc,stroke:#333,stroke-width:2px;
    classDef ci fill:#fff2cc,stroke:#333,stroke-width:2px;
    classDef gitops fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef admission fill:#ffd6cc,stroke:#333,stroke-width:2px;
    classDef kustomize fill:#d6eaff,stroke:#333,stroke-width:2px;
```
