laboratori-cloud/.planning/phases/04-lab-03-compute-ec2/04-02-PLAN.md

---
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>