# seeker89/chaos-engineering-book architecture

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

- Interactive diagram: https://gitdiagram.com/seeker89/chaos-engineering-book
- Repository: https://github.com/seeker89/chaos-engineering-book

## Overview

##### Project type & purpose
- Type: A book’s companion repository containing
– Infrastructure-as-code (Packer + Ansible) for building a VM image
– Chapter‐organized chaos-engineering experiments (scripts, containers, Kubernetes manifests, small apps in Python/JavaScript/C)
- Purpose: Teach chaos-engineering by provisioning an isolated VM environment, deploying sample apps/services, then running fault-injection experiments and observing resilience.

##### File-structure highlights
– Root: Makefile, getting-started docs, per-chapter markdown folders (ch02…ch12)
– vm/: Packer template (packer.json), Ansible playbooks & roles to provision a VM (e.g., install services or WordPress)
– examples/: subfolders grouping experiments by technology (app, busy-neighbours, js, jvm, killer-whiles, poking-docker, kubernetes, etc.)
– media/: images for the book
– README.md + getting-started.md: instructions on cloning, building the VM, then running examples.

##### High-level components
A. Developer Workstation (local machine)
– Git & Make (clone + `make vm`)
– Packer CLI + Ansible CLI
– Experiment runners (Python scripts, shell scripts)
B. Environment Provisioner
– Packer (builds VM image)
– Ansible roles & playbooks (vm/ansible/)
C. Target VM (VirtualBox/QEMU)
– Base OS image
– Provisioned services (e.g., sample web app, WordPress, Docker engine, Kubernetes tools, monitoring agents)
D. Chaos-Engineering Experiments (examples/)
– Scripted fault injectors: CPU/memory hogs, I/O starvation, process kills, network partitions
– Container-based experiments (poking-docker)
– Kubernetes manifests (examples/kubernetes)
– Language-agent examples (JVM agents, JS experiments)
– C-based syscall filters & seccomp profiles (who-you-gonna-call)
E. Observability & Logging (optional external)
– Local or in-VM logs, metrics output (not shipped but implied in chapters on observability)

##### Interactions & data flow
- Workstation → Packer → VM image
- Workstation → Ansible → VM configuration
- Workstation/VM → sample application deployed on VM
- Experiment scripts (on host or inside VM) → Target services
– Fault injection APIs (Docker daemon, Kubernetes API, direct syscalls)
– Traffic generators (ab, curl, fetch/XMLHttpRequest)
- Monitoring/Logging (metrics, consoles) ← All components

##### Architectural patterns & principles
– Infrastructure-as-Code for deterministic environment (Packer + Ansible)
– Clear separation: provisioning layer vs. experimentation layer vs. target application layer
– Modular experiments: each examples/* subdirectory is self-contained
– Layered “blast radius”: OS-level faults, container-level faults, orchestration-level faults

##### Final checklist
– Clear component boundaries (Host vs. VM vs. External)
– Labels for each folder/technology (Makefile, Packer, Ansible, Python scripts, shell scripts, Kubernetes YAML, etc.)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Developer Workstation
    subgraph "Developer Workstation"
        direction TB
        MW["Makefile"]:::workstation
        GS["getting-started.md"]:::workstation
        RD["README.md"]:::workstation
        PCLI["Packer CLI"]:::workstation
        ACLI["Ansible CLI"]:::workstation
        ER["Experiment Runners"]:::workstation
    end

    %% Environment Provisioner
    subgraph "Environment Provisioner (IaC)"
        direction TB
        PT["packer.json"]:::provisioning
        VM_MK["vm/Makefile"]:::provisioning
        VBOX["install-virtualbox-guest-additions.sh"]:::provisioning
        ACFG["ansible.cfg"]:::provisioning
        PLAY["site.yml"]:::provisioning
        PRQ["prerequisites/"]:::provisioning
    end

    %% Target VM
    subgraph "Target VM"
        direction TB
        PRESEED["preseed.cfg"]:::target
        HTTP["vm/http/"]:::target
        OSIMG["Base OS Image"]:::target
        SERVICES["Provisioned Services\n(Web App, Docker, K8s, Monitoring)"]:::target
    end

    %% Chaos-Engineering Experiments
    subgraph "Chaos-Engineering Experiments"
        direction TB
        subgraph "examples/app" 
            direction TB
            APPPY["app.py"]:::experiment
        end
        subgraph "examples/busy-neighbours"
            direction TB
            BN["busy-neighbours scripts"]:::experiment
        end
        subgraph "examples/js"
            direction TB
            JS["JS network experiments"]:::experiment
        end
        subgraph "examples/jvm"
            direction TB
            JVM["JVM agent experiments"]:::experiment
        end
        subgraph "examples/killer-whiles"
            direction TB
            KW["killer-whiles scripts"]:::experiment
        end
        subgraph "examples/poking-docker"
            direction TB
            PD["poking-docker experiments"]:::experiment
        end
        subgraph "examples/kubernetes"
            direction TB
            K8S["Kubernetes manifests"]:::experiment
        end
        subgraph "examples/who-you-gonna-call"
            direction TB
            WC["seccomp & syscall filters"]:::experiment
        end
    end

    %% Observability & Logging
    OBS["Logs & Metrics"]:::observability

    %% Connections
    MW -->|clones & build vm| PT
    MW -->|clones & build vm| PLAY
    PCLI -->|build image| PT
    ACLI -->|provision VM| PLAY
    PLAY -->|configures| OSIMG
    PT -->|injects preseed| PRESEED
    PRESEED --> HTTP
    HTTP --> OSIMG
    OSIMG --> SERVICES
    ER --> APPPY
    ER --> BN
    ER --> JS
    ER --> JVM
    ER --> KW
    ER --> PD
    ER --> K8S
    ER --> WC
    APPPY -->|runs on| SERVICES
    BN -->|injects faults into| SERVICES
    JS -->|injects faults via network| SERVICES
    JVM -->|attaches agent to| SERVICES
    KW -->|kills processes on| SERVICES
    PD -->|uses Docker API on| SERVICES
    K8S -->|applies manifests to| SERVICES
    WC -->|applies seccomp on| SERVICES
    SERVICES -->|emits logs| OBS

    %% Click Events
    click MW "https://github.com/seeker89/chaos-engineering-book/tree/master/./Makefile"
    click GS "https://github.com/seeker89/chaos-engineering-book/blob/master/./getting-started.md"
    click RD "https://github.com/seeker89/chaos-engineering-book/blob/master/./README.md"
    click PT "https://github.com/seeker89/chaos-engineering-book/blob/master/./vm/packer.json"
    click VM_MK "https://github.com/seeker89/chaos-engineering-book/tree/master/./vm/Makefile"
    click VBOX "https://github.com/seeker89/chaos-engineering-book/blob/master/./vm/install-virtualbox-guest-additions.sh"
    click ACFG "https://github.com/seeker89/chaos-engineering-book/blob/master/./vm/ansible.cfg"
    click PLAY "https://github.com/seeker89/chaos-engineering-book/blob/master/./vm/ansible/site.yml"
    click PRQ "https://github.com/seeker89/chaos-engineering-book/tree/master/./vm/ansible/prerequisites/"
    click PRESEED "https://github.com/seeker89/chaos-engineering-book/blob/master/./vm/http/preseed.cfg"
    click HTTP "https://github.com/seeker89/chaos-engineering-book/tree/master/./vm/http/"
    click APPPY "https://github.com/seeker89/chaos-engineering-book/blob/master/./examples/app/app.py"
    click BN "https://github.com/seeker89/chaos-engineering-book/tree/master/./examples/busy-neighbours/"
    click JS "https://github.com/seeker89/chaos-engineering-book/tree/master/./examples/js/"
    click JVM "https://github.com/seeker89/chaos-engineering-book/tree/master/./examples/jvm/"
    click KW "https://github.com/seeker89/chaos-engineering-book/tree/master/./examples/killer-whiles/"
    click PD "https://github.com/seeker89/chaos-engineering-book/tree/master/./examples/poking-docker/"
    click K8S "https://github.com/seeker89/chaos-engineering-book/tree/master/./examples/kubernetes/"
    click WC "https://github.com/seeker89/chaos-engineering-book/tree/master/./examples/who-you-gonna-call/"

    %% Styles
    classDef workstation fill:#FFD580,stroke:#E69A2E,color:#000;
    classDef provisioning fill:#A0C4FF,stroke:#4682B4,color:#000;
    classDef target fill:#C0E6A1,stroke:#3E8E41,color:#000;
    classDef experiment fill:#FFB3B3,stroke:#D44D4D,color:#000;
    classDef observability fill:#E0E0E0,stroke:#999,color:#000;
```
