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 <noreply@anthropic.com>
This commit is contained in:
Luca Sacchi Ricciardi
95
.planning/phases/03-lab-02-network-vpc/03-VALIDATION.md
Normal file
95
.planning/phases/03-lab-02-network-vpc/03-VALIDATION.md
Normal file
@@ -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 `<automated>` 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
|
||||
145
CLAUDE.md
Normal file
145
CLAUDE.md
Normal file
@@ -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.
|
||||
63
prd.md
Normal file
63
prd.md
Normal file
@@ -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`.
|
||||
|
||||
Reference in New Issue
Block a user