feat(lab-03): complete Phase 4 - Compute & EC2 lab

Phase Plans (5 files): - 04-RESEARCH.md: Domain research on Docker limits, healthchecks, EC2 parallels - 04-VALIDATION.md: Success criteria and validation strategy - 04-01-PLAN.md: Test infrastructure (RED phase) - 04-02-PLAN.md: Diátxis documentation - 04-03-PLAN.md: Infrastructure implementation (GREEN phase) Test Scripts (6 files, 1300+ lines): - 01-resource-limits-test.sh: Validate INF-03 compliance - 02-healthcheck-test.sh: Validate healthcheck configuration - 03-enforcement-test.sh: Verify resource limits with docker stats - 04-verify-infrastructure.sh: Infrastructure verification - 99-final-verification.sh: End-to-end student verification - run-all-tests.sh: Test orchestration with fail-fast - quick-test.sh: Fast validation (<30s) Documentation (11 files, 2500+ lines): Tutorials (3): - 01-set-resource-limits.md: EC2 instance types, Docker limits syntax - 02-implement-healthchecks.md: ELB health check parallels - 03-dependencies-with-health.md: depends_on with service_healthy How-to Guides (4): - check-resource-usage.md: docker stats monitoring - test-limits-enforcement.md: Stress testing CPU/memory - custom-healthcheck.md: HTTP, TCP, database healthchecks - instance-type-mapping.md: Docker limits → EC2 mapping Reference (3): - compose-resources-syntax.md: Complete deploy.resources reference - healthcheck-syntax.md: All healthcheck parameters - ec2-instance-mapping.md: Instance type mapping table Explanation (1): - compute-ec2-parallels.md: Container=EC2, Limits=Instance Type, Healthcheck=ELB Infrastructure: - docker-compose.yml: 5 services (web, app, worker, db, stress-test) All services: INF-03 compliant (cpus + memory limits) All services: healthcheck configured EC2 parallels: t2.nano, t2.micro, t2.small, t2.medium, m5.large - Dockerfile: Alpine 3.19 + stress tools + non-root user Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-03 15:16:58 +02:00
parent 39b9a56850
commit 23a9ffe443
26 changed files with 5457 additions and 1 deletions
--- a/.planning/phases/04-lab-03-compute-ec2/04-02-PLAN.md
+++ b/.planning/phases/04-lab-03-compute-ec2/04-02-PLAN.md
@@ -0,0 +1,342 @@
+---
+phase: 04-lab-03-compute-ec2
+plan: 02
+type: execute
+wave: 1
+depends_on:
+  - "04-01"
+files_modified:
+  - labs/lab-03-compute/tutorial/01-set-resource-limits.md
+  - labs/lab-03-compute/tutorial/02-implement-healthchecks.md
+  - labs/lab-03-compute/tutorial/03-dependencies-with-health.md
+  - labs/lab-03-compute/how-to-guides/check-resource-usage.md
+  - labs/lab-03-compute/how-to-guides/test-limits-enforcement.md
+  - labs/lab-03-compute/how-to-guides/custom-healthcheck.md
+  - labs/lab-03-compute/how-to-guides/instance-type-mapping.md
+  - labs/lab-03-compute/reference/compose-resources-syntax.md
+  - labs/lab-03-compute/reference/healthcheck-syntax.md
+  - labs/lab-03-compute/reference/ec2-instance-mapping.md
+  - labs/lab-03-compute/explanation/compute-ec2-parallels.md
+autonomous: true
+requirements:
+  - DOCT-01
+  - DOCT-02
+  - DOCT-03
+  - DOCT-04
+  - DOCT-05
+  - LAB-03
+  - PARA-01
+  - PARA-03
+  - PARA-04
+user_setup: []
+
+must_haves:
+  truths:
+    - "All 4 Diátxis document types created (Tutorial, How-to, Reference, Explanation)"
+    - "Tutorials follow 'little often' principle with incremental steps"
+    - "How-to guides are task-focused and procedure-oriented"
+    - "Reference documents provide complete technical specifications"
+    - "Explanation document clearly maps Docker compute to EC2 concepts"
+    - "Minimum line requirements met for all documents"
+  artifacts:
+    - path: "labs/lab-03-compute/tutorial/01-set-resource-limits.md"
+      provides: "Step-by-step resource limits guide"
+      min_lines: 250
+    - path: "labs/lab-03-compute/tutorial/02-implement-healthchecks.md"
+      provides: "Step-by-step healthcheck guide"
+      min_lines: 250
+    - path: "labs/lab-03-compute/tutorial/03-dependencies-with-health.md"
+      provides: "Step-by-step dependency guide"
+      min_lines: 250
+    - path: "labs/lab-03-compute/how-to-guides/check-resource-usage.md"
+      provides: "Resource monitoring procedure"
+      min_lines: 60
+    - path: "labs/lab-03-compute/how-to-guides/test-limits-enforcement.md"
+      provides: "Limits testing procedure"
+      min_lines: 60
+    - path: "labs/lab-03-compute/how-to-guides/custom-healthcheck.md"
+      provides: "Custom healthcheck procedure"
+      min_lines: 60
+    - path: "labs/lab-03-compute/how-to-guides/instance-type-mapping.md"
+      provides: "Instance type selection guide"
+      min_lines: 60
+    - path: "labs/lab-03-compute/reference/compose-resources-syntax.md"
+      provides: "Complete resources syntax reference"
+      min_lines: 120
+    - path: "labs/lab-03-compute/reference/healthcheck-syntax.md"
+      provides: "Complete healthcheck syntax reference"
+      min_lines: 100
+    - path: "labs/lab-03-compute/reference/ec2-instance-mapping.md"
+      provides: "EC2 instance mapping reference"
+      min_lines: 80
+    - path: "labs/lab-03-compute/explanation/compute-ec2-parallels.md"
+      provides: "Compute-to-EC2 conceptual mapping"
+      min_lines: 280
+  key_links:
+    - from: "tutorial/01-set-resource-limits.md"
+      to: "reference/compose-resources-syntax.md"
+      via: "Tutorial links to syntax reference"
+      pattern: "\\[.*Syntax.*\\].*compose-resources-syntax"
+    - from: "tutorial/02-implement-healthchecks.md"
+      to: "reference/healthcheck-syntax.md"
+      via: "Tutorial links to healthcheck reference"
+      pattern: "\\[.*Reference.*\\].*healthcheck-syntax"
+    - from: "explanation/compute-ec2-parallels.md"
+      to: "reference/ec2-instance-mapping.md"
+      via: "Explanation links to instance mapping"
+      pattern: "\\[.*Instance.*\\].*ec2-instance-mapping"
+---
+
+<objective>
+Create comprehensive Diátxis documentation for Lab 03 (Compute & EC2) covering resource limits, healthchecks, and EC2 instance type parallels.
+
+Purpose: Provide students with 4-quadrant documentation following Diátaxis framework: Tutorials (step-by-step learning), How-to Guides (task-focused procedures), Reference (technical specifications), and Explanation (conceptual mapping to EC2).
+
+Output: 11 markdown documents (3 tutorials, 4 how-to guides, 3 reference, 1 explanation) totaling 1800+ lines.
+</objective>
+
+<execution_context>
+@/home/luca/.claude/get-shit-done/workflows/execute-plan.md
+@/home/luca/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/REQUIREMENTS.md
+@.planning/phases/04-lab-03-compute-ec2/04-RESEARCH.md
+@.planning/phases/04-lab-03-compute-ec2/04-VALIDATION.md
+@.planning/phases/03-lab-02-network-vpc/03-02-PLAN.md
+@labs/lab-02-network/explanation/docker-network-vpc-parallels.md
+
+# Diátaxis Framework Overview
+
+From PROJECT.md and Phase 2/3 patterns:
+
+## 1. Tutorials - Learning-Oriented
+- **Purpose:** Guida passo-passo per studenti nuovi
+- **Tone:** Diretto, semplice, incrementale ("little often")
+- **Structure:**
+  - Clear learning objectives
+  - Prerequisites listed
+  - Step-by-step instructions
+  - Verification commands after each step
+  - Troubleshooting tips
+
+## 2. How-to Guides - Task-Oriented
+- **Purpose:** Procedure specifiche e task-focused
+- **Tone:** Pratico, diretto al punto
+- **Structure:**
+  - Single specific task
+  - Prerequisites brief
+  - Step-by-step procedure
+  - Expected results
+  - Common issues
+
+## 3. Reference - Information-Oriented
+- **Purpose:** Specifiche tecniche nude e crude
+- **Tone:** Formale, completo, conciso
+- **Structure:**
+  - Complete parameter reference
+  - All options documented
+  - Examples for each option
+  - No tutorial content
+
+## 4. Explanation - Understanding-Oriented
+- **Purpose:** Parallelismi concettuali locale ↔ cloud
+- **Tone:** Educativo, comparativo
+- **Structure:**
+  - Concept introduction
+  - Side-by-side comparisons
+  - Key differences highlighted
+  - When to use what
+
+# Lab 03 Content Guidelines
+
+## EC2 Instance Type Parallels
+
+**Core Concept:** Docker resource limits simulate EC2 instance types
+
+| Docker | EC2 | Use Case |
+|--------|-----|----------|
+| cpus: '0.5', memory: 512M | t2.nano | Dev/test |
+| cpus: '1', memory: 1G | t2.micro | Small services |
+| cpus: '1', memory: 2G | t2.small | Web servers |
+| cpus: '2', memory: 4G | t2.medium | Application servers |
+| cpus: '2', memory: 8G | m5.large | Production apps |
+| cpus: '4', memory: 16G | m5.xlarge | High-traffic services |
+
+**Key Teaching Points:**
+1. Resource limits = Cost control (pay for what you use)
+2. Different instance types for different workloads
+3. Burstable (t2/t3) vs. consistent performance (m5/c5)
+4. Right-sizing prevents over-provisioning
+
+## Healthcheck Parallels
+
+**Core Concept:** Docker healthchecks simulate ELB health checks
+
+| Docker | AWS |
+|--------|-----|
+| healthcheck.test | ELB health check path |
+| healthcheck.interval | ELB interval (default 30s) |
+| healthcheck.timeout | ELB timeout (default 5s) |
+| healthcheck.retries | ELB unhealthy threshold |
+| healthcheck.start_period | ELB grace period |
+| docker ps --filter health=healthy | ELB target health |
+
+**Key Teaching Points:**
+1. Healthchecks detect failing services
+2. Dependencies wait for healthy status
+3. Prevents cascading failures
+4. Enables zero-downtime deployments
+
+# Documentation Structure
+
+## Tutorial 1: Set Resource Limits
+**Learning Objectives:**
+- Understand EC2 instance types
+- Learn Docker Compose resource syntax
+- Set CPU and memory limits
+- Verify with docker stats
+
+**Outline:**
+1. What are EC2 Instance Types? (5 min)
+2. Docker Resource Limits Syntax (10 min)
+3. Practice: Set limits for t2.micro (15 min)
+4. Practice: Set limits for t2.small (15 min)
+5. Verification with docker stats (5 min)
+
+## Tutorial 2: Implement Healthchecks
+**Learning Objectives:**
+- Understand healthcheck purpose
+- Learn healthcheck syntax
+- Add healthcheck to web service
+- Monitor health status
+
+**Outline:**
+1. What are Healthchecks? (5 min)
+2. ELB Health Check Parallel (5 min)
+3. Healthcheck Parameters (10 min)
+4. Practice: Add HTTP healthcheck (15 min)
+5. Practice: Add database healthcheck (10 min)
+6. Monitor health status (5 min)
+
+## Tutorial 3: Dependencies with Health
+**Learning Objectives:**
+- Understand service dependencies
+- Use depends_on with conditions
+- Implement ordered startup
+- Verify dependency chain
+
+**Outline:**
+1. Service Dependencies (5 min)
+2. depends_on Conditions (10 min)
+3. Practice: Web depends on App (15 min)
+4. Practice: App depends on DB (15 min)
+5. Verify startup order (5 min)
+
+# Implementation Notes
+
+1. **File Locations:**
+```
+labs/lab-03-compute/
+├── tutorial/
+│   ├── 01-set-resource-limits.md
+│   ├── 02-implement-healthchecks.md
+│   └── 03-dependencies-with-health.md
+├── how-to-guides/
+│   ├── check-resource-usage.md
+│   ├── test-limits-enforcement.md
+│   ├── custom-healthcheck.md
+│   └── instance-type-mapping.md
+├── reference/
+│   ├── compose-resources-syntax.md
+│   ├── healthcheck-syntax.md
+│   └── ec2-instance-mapping.md
+├── explanation/
+│   └── compute-ec2-parallels.md
+└── README.md
+```
+
+2. **Code Examples:**
+   - Use realistic examples (nginx, postgres, redis)
+   - Show complete docker-compose.yml snippets
+   - Include verification commands
+   - Add expected output
+
+3. **Parallelism Emphasis:**
+   - Always show AWS equivalent
+   - Explain "why" not just "how"
+   - Highlight key differences
+   - Link to AWS documentation
+
+# Success Criteria
+
+Plan 04-02 is complete when:
+1. All 11 documents created
+2. Minimum line requirements met
+3. Tutorials follow "little often" principle
+4. How-to guides are task-focused
+5. Reference documents are complete specifications
+6. Explanation clearly maps Docker → EC2
+7. Cross-references between documents
+8. Italian language (consistent with other labs)
+</context>
+
+<tasks>
+1. Create tutorial/ directory
+2. Create tutorial/01-set-resource-limits.md (250+ lines)
+   - EC2 instance types introduction
+   - Docker resource limits syntax
+   - Practice exercises
+   - Verification steps
+3. Create tutorial/02-implement-healthchecks.md (250+ lines)
+   - Healthcheck concept and ELB parallel
+   - Healthcheck parameters
+   - Practice: HTTP healthcheck
+   - Practice: Database healthcheck
+4. Create tutorial/03-dependencies-with-health.md (250+ lines)
+   - Service dependency concepts
+   - depends_on conditions
+   - Practice: Multi-tier dependencies
+   - Startup order verification
+5. Create how-to-guides/ directory
+6. Create how-to-guides/check-resource-usage.md (60+ lines)
+   - docker stats usage
+   - Real-time monitoring
+   - Interpreting output
+7. Create how-to-guides/test-limits-enforcement.md (60+ lines)
+   - CPU limit testing
+   - Memory OOM testing
+   - Verification procedures
+8. Create how-to-guides/custom-healthcheck.md (60+ lines)
+   - Writing custom healthcheck commands
+   - Best practices
+   - Debugging failures
+9. Create how-to-guides/instance-type-mapping.md (60+ lines)
+   - Docker limits → EC2 mapping
+   - Selecting appropriate types
+   - Cost considerations
+10. Create reference/ directory
+11. Create reference/compose-resources-syntax.md (120+ lines)
+    - Complete deploy.resources reference
+    - CPU and memory syntax
+    - Reservations vs limits
+    - All options with examples
+12. Create reference/healthcheck-syntax.md (100+ lines)
+    - All healthcheck parameters
+    - Test command formats
+    - Status values
+    - Examples for each service type
+13. Create reference/ec2-instance-mapping.md (80+ lines)
+    - Complete mapping table
+    - Instance type descriptions
+    - Use case recommendations
+14. Create explanation/ directory
+15. Create explanation/compute-ec2-parallels.md (280+ lines)
+    - Container = EC2 Instance
+    - Resource limits = Instance types
+    - Healthcheck = ELB/Status checks
+    - Docker stats = CloudWatch
+    - Key differences (credits, pricing, etc.)
+    - Command equivalents table
+</tasks>