laboratori-cloud/prd.md

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.