# akintunero/k8s-chaos-engineering architecture

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

- Interactive diagram: https://gitdiagram.com/akintunero/k8s-chaos-engineering
- Repository: https://github.com/akintunero/k8s-chaos-engineering

## Overview

##### Project Type and Purpose
- This is a Kubernetes-based Chaos Engineering demo.
- Purpose: Deploy a simple Flask web application into a K8s cluster, monitor it with Prometheus, and run chaos experiments (CPU hog, network latency, pod deletion) using LitmusChaos.

##### File Structure
- hello-world-app/
- Flask application source (app.py), packaged via Dockerfile.
- deployments/
- Raw Kubernetes YAML for Deployment + Service of the Flask app.
- experiments/
- LitmusChaos experiment manifests (cpu-hog, network-latency, pod-delete).
- helm/
- Helm Chart for templated deployment of the Flask app (Chart.yaml, values.yaml, deployment/service templates).
- monitoring/
- prometheus.yaml: K8s resources for Prometheus server + Service.
- .github/workflows/ci-cd.yaml
- CI/CD workflow for build, push, and helm/kubectl deploy.

##### Key Components
a. K8s Cluster
- Namespace(s) for: application, monitoring, chaos experiments
- Cluster control plane (API server, scheduler, etcd) – optional detail
b. Container Registry
- Docker registry where `flask-chaos-demo` image is pushed
c. Continuous Integration/Deployment
- GitHub Actions workflow:
- Triggers on push → Builds Docker image → Pushes to registry → Runs `kubectl apply` or `helm install/upgrade`
d. Application Layer
- Flask app Pods behind a Service (ClusterIP or LoadBalancer)
e. Observability
- Prometheus deployment & Service
- ServiceDiscovery scraping Flask app metrics endpoint
f. Chaos Engineering
- LitmusChaos Operator running in cluster
- ChaosExperiment CRs (cpu-hog, network-latency, pod-delete) targeting the Flask app pods

##### Relationships & Interactions
- Developer (GitHub) → CI/CD workflow → Container Registry & K8s API
- Client/User → K8s Service → Flask Pod
- Flask Pod → Exposes HTTP /metrics for Prometheus
- Prometheus → Scrapes `/metrics` from Flask Service
- LitmusChaos Operator → Reads ChaosExperiment CRDs → Injects faults into Flask Pods
- Monitoring & Chaos feedback loop: metrics degrade under fault injection

##### Architectural Patterns & Design Principles
- Infrastructure as Code: raw YAML + Helm templating
- Microservices‐style separation: app, monitoring, chaos engine in discrete namespaces
- 12-factor App: externalizing configuration via Helm values, stateless containers
- Feedback Loop: Observability informs resilience under chaos

##### Essential Details to Capture
- Namespace separation (e.g., default vs. monitoring vs. litmus)
- Workflow triggers and artifacts (image tag flows)
- Helm values override: indicate that the Chart/values.yaml drives deployment parameters
- Experiment scheduling: experiments applied after app + monitoring are up

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD Layer
    subgraph "CI/CD Pipeline"
        CICD["GitHub Actions CI/CD"]:::cicd
    end

    %% Registry
    Registry["Container Registry"]:::cicd

    CICD -->|"build & push image"| Registry
    CICD -->|"deploy via kubectl/helm"| K8sAPI
    Registry -->|"image pull"| K8sAPI

    %% Kubernetes Control Plane
    subgraph "Kubernetes Cluster"
        K8sAPI["K8s API Server"]:::control
        subgraph "Namespaces"
            subgraph "app"
                Service["Flask Service (ClusterIP)"]:::app
                Pod["Flask Pod"]:::app
            end
            subgraph "monitoring"
                Prometheus["Prometheus Server"]:::monitor
            end
            subgraph "chaos"
                Operator["LitmusChaos Operator"]:::chaos
                subgraph "ChaosExperiments"
                    CPU["cpu-hog.yaml"]:::chaos
                    Net["network-latency.yaml"]:::chaos
                    Delete["pod-delete.yaml"]:::chaos
                end
            end
        end
    end

    %% Application flow
    Service -->|"routes /, /metrics"| Pod
    Pod -->|"exposes metrics"| Service

    %% Monitoring flow
    Prometheus -->|"scrape HTTP /metrics"| Service

    %% Chaos flow
    Operator -->|"reads CRDs & injects faults"| Pod
    CPU -->|targets| Pod
    Net -->|targets| Pod
    Delete -->|targets| Pod

    %% CI/CD to K8s
    K8sAPI -->|"creates Deployment & Service"| Service
    K8sAPI -->|"schedules Pod"| Pod
    K8sAPI -->|"deploys Prometheus"| Prometheus
    K8sAPI -->|"deploys Litmus Operator & CRDs"| Operator

    %% File Structure Mappings
    click CICD "https://github.com/akintunero/k8s-chaos-engineering/blob/main/.github/workflows/ci-cd.yaml"
    click AppSrc "https://github.com/akintunero/k8s-chaos-engineering/blob/main/hello-world-app/app.py"
    click Requirements "https://github.com/akintunero/k8s-chaos-engineering/blob/main/hello-world-app/requirements.txt"
    click Dockerfile "https://github.com/akintunero/k8s-chaos-engineering/tree/main/hello-world-app/Dockerfile"
    click RawYAML "https://github.com/akintunero/k8s-chaos-engineering/blob/main/deployments/flask-app.yaml"
    click ChartYAML "https://github.com/akintunero/k8s-chaos-engineering/blob/main/helm/Chart.yaml"
    click ValuesYAML "https://github.com/akintunero/k8s-chaos-engineering/blob/main/helm/values.yaml"
    click HelmDeploy "https://github.com/akintunero/k8s-chaos-engineering/blob/main/helm/templates/deployment.yaml"
    click HelmHello "https://github.com/akintunero/k8s-chaos-engineering/blob/main/helm/templates/hello-world-deployment.yaml"
    click HelmService "https://github.com/akintunero/k8s-chaos-engineering/blob/main/helm/templates/service.yaml"
    click PromYaml "https://github.com/akintunero/k8s-chaos-engineering/blob/main/monitoring/prometheus.yaml"
    click CPU "https://github.com/akintunero/k8s-chaos-engineering/blob/main/experiments/cpu-hog.yaml"
    click Net "https://github.com/akintunero/k8s-chaos-engineering/blob/main/experiments/network-latency.yaml"
    click Delete "https://github.com/akintunero/k8s-chaos-engineering/blob/main/experiments/pod-delete.yaml"

    %% Styles
    classDef cicd fill:#D0E8FF,stroke:#1E70BF,color:#000
    classDef control fill:#F0F0F0,stroke:#333,color:#000
    classDef app fill:#E0FFE0,stroke:#2D8A1F,color:#000
    classDef monitor fill:#FFE8B0,stroke:#D98C00,color:#000
    classDef chaos fill:#FFD0D0,stroke:#BF1E1E,color:#000
```
