From d4c4f7d717562a7fc46ee05269d9d54eb410f1db Mon Sep 17 00:00:00 2001 From: Luca Sacchi Ricciardi Date: Wed, 25 Mar 2026 15:55:18 +0100 Subject: [PATCH] docs: add Phase 3 validation strategy and project specifications - Add 03-VALIDATION.md for Phase 3 (Lab 02 Network & VPC) - Add CLAUDE.md v3.3 with hybrid agent-based development standards - Add prd.md with product requirements for cloud course Co-Authored-By: Claude Opus 4.6 --- .../03-lab-02-network-vpc/03-VALIDATION.md | 95 ++++++++++++ CLAUDE.md | 145 ++++++++++++++++++ prd.md | 63 ++++++++ 3 files changed, 303 insertions(+) create mode 100644 .planning/phases/03-lab-02-network-vpc/03-VALIDATION.md create mode 100644 CLAUDE.md create mode 100644 prd.md diff --git a/.planning/phases/03-lab-02-network-vpc/03-VALIDATION.md b/.planning/phases/03-lab-02-network-vpc/03-VALIDATION.md new file mode 100644 index 0000000..8b5fd8d --- /dev/null +++ b/.planning/phases/03-lab-02-network-vpc/03-VALIDATION.md @@ -0,0 +1,95 @@ +--- +phase: 3 +slug: lab-02-network-vpc +status: draft +nyquist_compliant: false +wave_0_complete: false +created: 2026-03-25 +--- + +# Phase 3 — Validation Strategy + +> Per-phase validation contract for network isolation and VPC simulation testing. + +--- + +## Test Infrastructure + +| Property | Value | +|----------|-------| +| **Framework** | bash (test scripts) | +| **Config file** | none | +| **Quick run command** | `bash labs/lab-02-network/tests/quick-test.sh` | +| **Full suite command** | `bash labs/lab-02-network/tests/run-all-tests.sh` | +| **Estimated runtime** | ~30 seconds | + +--- + +## Sampling Rate + +- **After every task commit:** Run `bash labs/lab-02-network/tests/quick-test.sh` +- **After every plan wave:** Run `bash labs/lab-02-network/tests/run-all-tests.sh` +- **Before `/gsd:verify-work`:** Full suite must be green +- **Max feedback latency:** 30 seconds + +--- + +## Per-Task Verification Map + +| Task ID | Plan | Wave | Requirement | Test Type | Automated Command | File Exists | Status | +|---------|------|------|-------------|-----------|-------------------|-------------|--------| +| 03-01-01 | 01 | 1 | LAB-02, TEST-01 | unit | `bash labs/lab-02-network/tests/test-network-isolation.sh` | ❌ W0 | ⬜ pending | +| 03-01-02 | 01 | 1 | INF-02 | integration | `bash labs/lab-02-network/tests/test-private-network-no-expose.sh` | ❌ W0 | ⬜ pending | +| 03-02-01 | 02 | 1 | DOCT-01, DOCT-02 | documentation | File existence check | ❌ W0 | ⬜ pending | +| 03-03-01 | 03 | 2 | LAB-02, INF-02 | infrastructure | `docker-compose config` + container ping test | ❌ W0 | ⬜ pending | + +*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky* + +--- + +## Wave 0 Requirements + +- [ ] `labs/lab-02-network/tests/test-network-isolation.sh` — stubs for network isolation tests +- [ ] `labs/lab-02-network/tests/test-private-network-no-expose.sh` — stubs for INF-02 compliance +- [ ] `labs/lab-02-network/tests/run-all-tests.sh` — test orchestration script +- [ ] `labs/lab-02-network/tests/quick-test.sh` — quick validation script + +--- + +## Manual-Only Verifications + +| Behavior | Requirement | Why Manual | Test Instructions | +|----------|-------------|------------|-------------------| +| Visual verification of network topology | LAB-02 | Requires human interpretation of docker network ls output | Student runs `docker network ls` and compares to expected VPC structure | +| Documentation completeness | DOCT-01, DOCT-02, DOCT-03, DOCT-04 | Requires human judgment of Diátaxis quadrant coverage | Instructor reviews all 4 quadrants for completeness | + +--- + +## Validation Sign-Off + +- [ ] All tasks have `` verify or Wave 0 dependencies +- [ ] Sampling continuity: no 3 consecutive tasks without automated verify +- [ ] Wave 0 covers all MISSING references +- [ ] No watch-mode flags +- [ ] Feedback latency < 30s +- [ ] `nyquist_compliant: true` set in frontmatter + +**Approval:** pending + +--- + +## Integration Points + +### Phase 2 Dependencies +- IAM concepts from Lab 01 are foundational but Network lab can run independently +- Test script patterns from Phase 2 (run-all-tests.sh, color output) should be reused + +### Future Phase Dependencies +- Lab 04 (Storage & S3) will use networks created in this phase +- Lab 05 (Database) will place database in private network created here +- Network isolation is prerequisite for multi-tier architecture + +### INF-02 Compliance Verification +- Private networks must NOT expose ports on 0.0.0.0 +- Test verifies `docker-compose config` output for `127.0.0.1:PORT:PORT` pattern +- Manual verification: `netstat -tlnp | grep docker` shows no 0.0.0.0 bindings for private services diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..b58e9d4 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,145 @@ +**Versione:** 3.3 (Hybrid Agent-Based + Sequential Thinking) + +**Ambito:** Sviluppo Materiale Didattico e Infrastruttura Locale per "Corso Lab Soluzioni Cloud" (Framework Diátaxis). + +**Architettura:** GSD (Orchestration) + Universal Skills Manager (Specialized Agents). + +**Guida Suprema:** *Safety first, little often, double check.* + +--- + +## 1. Filosofia di Sviluppo + +### 1.1 Spec-Driven Infrastructure (SDI) + +Nessun laboratorio o configurazione viene scritto senza una specifica architetturale approvata. + +* **Contratto:** Ogni modulo (Lab) deve avere un PRD che ne definisca l'obiettivo didattico, la topologia di rete, i limiti di risorse e il parallelismo con il servizio Cloud reale (es. AWS VPC, RDS). +* **Validazione:** Si usa `docker-compose config` e validatori YAML formali per garantire che i file di infrastruttura siano corretti prima dell'esecuzione. + +### 1.2 Test-Driven Infrastructure (TDI) + +L'infrastruttura nasce dai test. Seguiamo rigorosamente il ciclo per verificare i criteri di accettazione. + +1. **RED:** Scrittura dello script di test fallimentare (es. uno script bash che fa `curl` o `nc` verso una porta che deve essere isolata o esposta). +2. **GREEN:** Scrittura del minimo codice infrastrutturale (`docker-compose.yml`, regole `iptables`, permessi file) per far passare il test. +3. **REFACTOR:** Ottimizzazione delle immagini Docker, pulizia dei layer e hardening della sicurezza senza rompere i test. + +### 1.3 Hybrid Agent-Assisted Development + +Lo sviluppo è orchestrato da un Agente Primario che genera i contenuti didattici e l'infrastruttura, delegando dove necessario. + +* **Fasi:** Raccolta Requisiti → Pianificazione Architettura → Creazione Test → Stesura Documentazione (Diátaxis) → Validazione. +* **Delega:** L'Agente valuta se usare skill specifiche per l'ottimizzazione di Dockerfile o la generazione di script Bash complessi consultando lo **Universal Skills Manager (USM)**. +* **Controllo:** L'uso di skill è soggetto al protocollo di sicurezza "Curated Skills" (Sezione 7.5). + +--- + +## 2. Standard di Documentazione Obbligatoria (Framework Diátaxis) + +### 2.1 Output Didattico a 4 Quadranti +Per ogni Laboratorio, l'agente deve generare obbligatoriamente quattro tipologie di documento: +1. **Tutorials:** Guida passo-passo incrementale (*little often*) per guidare l'allievo. +2. **How-to Guides:** Procedure specifiche (es. "Come generare chiavi SSH", "Come ripulire i volumi Docker"). +3. **Reference:** Specifiche tecniche nude e crude (mappe IP, tabelle porte esposte, spiegazione direttive `docker-compose`). +4. **Explanation:** Il raccordo concettuale (parallelismo tra l'ambiente locale simulato e i veri servizi Cloud managed). + +### 2.2 File di Gestione Progetto +* **`ARCHITECTURE.md`:** Tracciabilità delle scelte. Perché abbiamo scelto MinIO per simulare S3? Perché usiamo bridge networks isolate? +* **`BUGS.md`:** Registro storico. Es. Conflitti di porte sull'host, container andati in OOM kill durante gli stress test. (Errore, Causa Radice, Soluzione). +* **`PROGRESS.md`:** Tracciamento operativo. Log delle attività e stesura dei moduli completati. + +--- + +## 3. Gestione del Codice (Git Workflow) + +### 3.1 Branching Strategy + +* **`main`:** Solo laboratori completi, testati e documentati. +* **`develop`:** Ramo di integrazione. +* **Lab Branches (`lab-01-iam`, `lab-02-network`):** Sviluppo isolato del singolo modulo didattico. + +### 3.2 Conventional Commits + +Commit atomici per guidare gli allievi con l'esempio: `feat: add private vpc network`, `test: verify db connection via pg_isready`, `docs: write explanation for S3 simulation`. + +--- + +## 4. Stack Tecnologico (Infrastruttura e Simulazione) + +L'infrastruttura si basa su tecnologie open-source standard per simulare i cloud provider. + +| Categoria | Tecnologia | Perché? | +| --- | --- | --- | +| **Orchestrazione** | `docker`, `docker-compose` | Setup riproducibile, isolamento nativo e standard di mercato. | +| **Networking** | `bridge networks`, `iptables` | Simulazione di VPC, Subnets pubbliche/private e NAT Gateway. | +| **Object Storage** | `MinIO` | Compatibilità 100% con le API di AWS S3. | +| **Database** | `PostgreSQL` / `MySQL` | Simulazione di servizi RDS managed con script di init pre-configurati. | +| **Testing** | `bash`, `curl`, `nc`, `nmap` | **Double Check** della connettività e dei confini di sicurezza. | + +### ⚙️ Prerequisiti di Sistema (Host) +Il sistema host o la VM base di laboratorio deve avere installato: +* Docker Engine >= 24.0 +* Docker Compose V2 +* Utility di rete standard (`netcat`, `curl`, `iproute2`) + +--- + +## 5. Standard Sistemistici (Safety First) + +1. **Minimo Privilegio (IAM):** I container non devono mai girare come `root` (usare direttiva `user:` o configurare l'utente nel Dockerfile). +2. **Isolamento di Rete (VPC):** Le reti private non devono esporre porte sull'host (`127.0.0.1:port:port` al massimo, mai `0.0.0.0`). +3. **Enforcement delle Risorse (Compute):** Obbligatorio impostare `cpus` e `mem_limit` nei file compose per simulare le "size" delle istanze cloud ed evitare il blocco della macchina host. +4. **Persistenza (Storage):** I dati devono sopravvivere al riavvio dei container tramite l'uso esplicito di Docker Volumes nominativi. + +--- + +## 6. Checklist di Qualità (Double Check) + +Prima di completare un laboratorio e fare il merge: + +* [ ] I 4 documenti del framework Diátaxis sono stati redatti con un tono diretto e semplice. +* [ ] Il parallelismo Cloud <-> Locale è spiegato chiaramente nella sezione *Explanation*. +* [ ] Il file `docker-compose.yml` rispetta i vincoli di sicurezza (no root, limiti risorse, reti separate). +* [ ] Lo script di test del laboratorio (TDI) esegue correttamente i controlli previsti (es. ping fallito tra reti isolate). +* [ ] I file `ARCHITECTURE.md` e `PROGRESS.md` sono aggiornati. +* [ ] Il ragionamento logico per le architetture di rete complesse è stato validato con **Sequential Thinking** (sezione 7.2). +* [ ] Le configurazioni e le porte standard sono state verificate con **Context7** / **zread** (sezione 7.3 e 7.4). + +--- + +## 7. Integrazione MCP, ZAI Tools e Agenti Specializzati + +L'ambiente è potenziato da strumenti e agenti specializzati. È **vietato** indovinare configurazioni Docker o di rete quando strumenti specifici sono disponibili. + +### 7.1 Memoria Persistente (`claude-mem`) +* **Uso:** Interroga la memoria prima di modificare topologie di rete per mantenere la coerenza degli IP (es. `10.0.x.0/24`) decisa nei laboratori precedenti. + +### 7.2 Ragionamento Passo-Passo (`sequential-thinking`) +* **Obbligatorio:** Mandatorio per configurare regole di routing, NAT tramite `iptables` o quando si impostano i limiti di memoria che potrebbero causare OOM kill incrociati. + +### 7.3 Documentazione Tecnica (`context7`) +* **Uso:** Usalo per verificare le direttive più recenti di Docker Compose V2 o le flag di MinIO. + +### 7.4 Accesso a Repositori Open Source (`zread`) +* **Uso:** Valida le implementazioni di container di test o tool di rete guardando i Dockerfile ufficiali (es. Alpine, Nginx). + +### 7.5 Universal Skills Manager (USM) e Protocollo "Curated Skills" +* Regole di delega per task come: l'ottimizzazione di un `Dockerfile` personalizzato per il Lab, o la generazione di script di validazione bash. Applicare il processo di whitelist e l'approvazione utente come da standard. + +--- + +## 8. Flussi Operativi Obbligatori (Workflows) + +*(I flussi 8.1 - 8.6 rimangono operativi identici alla specifica core, focalizzati sui file markdown, l'infrastruttura Docker e l'USM)* + +### 8.7 Protocollo di Selezione del Modello (Model Escalation) + +**Valutazione della Complessità:** +Un task è definito "Alta Complessità" se coinvolge: +* Progettazione di reti bridge interconnesse con regole di iptables personalizzate. +* Scrittura di guide concettuali (Explanation) che richiedono una profonda conoscenza comparata dei servizi AWS/Azure/GCP. +* Debug di problemi di permessi tra host Linux e container sui volumi bind-mounted. + +**Protocollo Operativo:** +Se il task è di **Alta Complessità**, l'agente deve fermarsi e richiedere l'upgrade del modello (RTU) avvisando l'utente. diff --git a/prd.md b/prd.md new file mode 100644 index 0000000..7e217ae --- /dev/null +++ b/prd.md @@ -0,0 +1,63 @@ +# PRD: Laboratori "Soluzioni Cloud" Simulate in Locale + +## 1. Obiettivo del Progetto +Creare materiale didattico tecnico, strutturato secondo il framework **Diátaxis**, per un corso pratico sulle tecnologie Cloud. I laboratori simuleranno i servizi core di un cloud provider (IAM, Network, Compute, Storage, Database) utilizzando un ambiente locale basato su macchine virtuali (KVM/VirtualBox) e Docker. + +L'output generato dall'LLM dovrà avere un tono diretto, semplice e rigorosamente tecnico. + +## 2. Regole d'Ingaggio per l'Agente LLM (Core Principles) +L'agente LLM incaricato di generare il contenuto deve rispettare tassativamente i seguenti principi nella stesura del codice e dei testi: + +* **Spec-Driven:** Ogni modulo deve iniziare con le specifiche tecniche chiare dell'architettura da realizzare. +* **Infrastructure-TDD (Test-Driven Development):** Prima di fornire i file di configurazione (`docker-compose.yml`, `Dockerfile`, script bash), l'LLM deve fornire i test o i comandi di validazione. Bisogna definire "come testiamo che funzioni" prima di scriverlo. +* **Le 3 Regole d'Oro:** + 1. **Safety first:** Il codice e le architetture devono partire dal principio del minimo privilegio (reti isolate, permessi restrittivi, niente root se non necessario). + 2. **Little often:** I laboratori devono essere incrementali. Piccoli step testabili. + 3. **Double check:** Ogni fase deve concludersi con una verifica esplicita dello stato dell'infrastruttura (connettività, log, processi). +* **Git Flow Avanzato:** Il tutorial deve guidare l'allievo nel versionamento. L'LLM deve suggerire commit atomici utilizzando le convenzioni dei **Conventional Commits** (es. `feat: add private vpc network`, `test: verify db connection via pg_isready`) e indicare le strategie di branching ottimali per isolare i laboratori. + +## 3. Struttura dei Contenuti (Framework Diátaxis) +Per ogni modulo (Lab), l'LLM dovrà produrre 4 artefatti distinti: + +1. **Tutorials (Learning-oriented):** La guida passo-passo che prende per mano l'allievo. Segue la regola del *little often*. Contiene le istruzioni pratiche, i comandi Git e le verifiche (*double check*). +2. **How-to Guides (Goal-oriented):** Ricettari per compiti specifici e slegati dal flusso principale (es. "Come resettare l'ambiente Docker", "Come generare una nuova coppia di chiavi SSH sicure"). +3. **Reference (Information-oriented):** Specifiche tecniche pure. I file `docker-compose.yml` completi, mappe delle reti IP assegnate, tabelle delle porte esposte, spiegazione nuda e cruda dei parametri usati. +4. **Explanation (Understanding-oriented):** Il raccordo concettuale. Spiegazione del parallelismo tra l'infrastruttura locale simulata e i servizi managed reali (es. "Perché questo container MinIO si comporta come un bucket AWS S3"). + +## 4. Specifiche dei Moduli (I Laboratori) + +### Lab 1: IAM & Sicurezza +* **Obiettivo:** Gestione accessi e perimetrazione. +* **Componenti Locali:** Utenti Linux, gruppi, chiavi SSH, permessi Docker socket. +* **Parallelismo Cloud:** AWS IAM, Azure AD, RBAC. +* **Spec-Driven & TDD:** Il test deve provare a eseguire un container privilegiato con un utente non autorizzato e fallire. +* **Git:** Branch `lab-01-iam`. + +### Lab 2: Network +* **Obiettivo:** Isolamento delle risorse e routing. +* **Componenti Locali:** Docker Networks (bridge), configurazione `iptables` per NAT. +* **Parallelismo Cloud:** VPC, Subnets pubbliche/private, Security Groups, NAT Gateway. +* **Spec-Driven & TDD:** I test consistono nell'avviare container sonda (Alpine/Busybox) ed eseguire `ping` e `nc` per verificare che la rete privata non esca su internet se non tramite il NAT, e che le due reti non comunichino senza regole esplicite. +* **Git:** Branch `lab-02-network`. + +### Lab 3: Compute +* **Obiettivo:** Erogazione della potenza di calcolo e containerizzazione. +* **Componenti Locali:** VM (per concetti Hypervisor/IaaS) + Docker (CaaS). Web server leggero (Nginx/Node.js). +* **Parallelismo Cloud:** EC2, Compute Engine, ECS, Fargate. +* **Spec-Driven & TDD:** Configurare i limiti (`cpus`, `mem_limit`) nel Compose. Il test deve essere uno stress-test che causa l'OOM (Out Of Memory) kill del container per dimostrare l'enforcement delle quote. +* **Git:** Branch `lab-03-compute`. + +### Lab 4: Storage +* **Obiettivo:** Persistenza dei dati e object storage. +* **Componenti Locali:** Docker Volumes (Block) e container MinIO (Object). +* **Parallelismo Cloud:** EBS (Block), S3 (Object). +* **Spec-Driven & TDD:** Test API via client CLI (`mc`) per creare un bucket e caricare un file testuale su MinIO. +* **Git:** Branch `lab-04-storage`. + +### Lab 5: Database +* **Obiettivo:** Simulazione di un database gestito e disaccoppiato. +* **Componenti Locali:** Container PostgreSQL/MySQL allocato nella VPC privata con volume persistente. +* **Parallelismo Cloud:** Amazon RDS, Cloud SQL. +* **Spec-Driven & TDD:** Un container applicativo (VPC pubblica) deve eseguire uno script di verifica connessione al DB (VPC privata) all'avvio. Se la connessione fallisce, l'app non si espone (*safety first*). +* **Git:** Branch `lab-05-database`. +