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

# Phase 4 Validation - Lab 03: Compute & EC2

## Validation Strategy

### Goal-Backward Verification

We verify that Phase 4 achieves its goals by checking the success criteria from the Phase definition.

## Success Criteria (from ROADMAP)

1. **Studente può deploy container con limiti CPU/memoria obbligatori** (simulazione instance types)
2. **Studente può implementare healthchecks per verificare che servizi siano "healthy"**
3. **Tutti i container hanno `cpus` e `mem_limit` configurati** (enforcement risorse cloud)
4. **Studente comprende il parallelismo tra container con limiti e EC2 instances**
5. **Lab include test che verificano resource limits con `docker stats` e healthcheck readiness**

## Validation Checklist

### 04-01: Test Infrastructure (RED Phase)

**Acceptance Criteria:**
- [ ] Test script `01-resource-limits-test.sh` validates:
  - Parse docker-compose.yml for `deploy.resources.limits.cpus`
  - Parse docker-compose.yml for `deploy.resources.limits.memory`
  - Report services without mandatory limits
  - Test should FAIL initially (no limits configured)
- [ ] Test script `02-healthcheck-test.sh` validates:
  - Services have `healthcheck` section defined
  - Healthcheck command is valid
  - `interval`, `timeout`, `retries` configured
  - Test should FAIL initially (no healthchecks configured)
- [ ] Test script `03-resource-enforcement-test.sh` validates:
  - Deploy test container with limits
  - Run CPU-intensive task
  - Verify `docker stats` shows enforcement
  - Run memory allocation task
  - Verify OOM kill on exceed
- [ ] Final verification `99-final-verification.sh` validates:
  - All services have resource limits
  - All services have healthchecks
  - Healthchecks pass
  - Resource limits enforced
  - INF-03 compliance verified

**Verification Command:**
```bash
cd labs/lab-03-compute
bash tests/run-all-tests.sh
```

**Expected Result:** All tests FAIL initially (RED phase), then PASS after implementation (GREEN phase)

---

### 04-02: Diátxis Documentation

**Acceptance Criteria:**

**Tutorials (3):**
- [ ] `tutorial/01-set-resource-limits.md` (min 250 lines)
  - Explain EC2 instance types concept
  - Show Docker CPU/memory limits syntax
  - Practice: Set limits for different instance types
  - Verify with `docker stats`
- [ ] `tutorial/02-implement-healthchecks.md` (min 250 lines)
  - Explain healthcheck purpose (ELB parallel)
  - Show healthcheck syntax and parameters
  - Practice: Add healthcheck to web service
  - Verify with `docker ps` and health status
- [ ] `tutorial/03-dependencies-with-health.md` (min 250 lines)
  - Explain service dependencies
  - Show `depends_on: condition: service_healthy`
  - Practice: Multi-tier with health-based startup
  - Verify startup order

**How-to Guides (4):**
- [ ] `how-to-guides/check-resource-usage.md` (min 60 lines)
  - How to use `docker stats`
  - How to inspect limits
  - How to monitor in real-time
- [ ] `how-to-guides/test-limits-enforcement.md` (min 60 lines)
  - How to trigger CPU limit
  - How to trigger memory OOM
  - How to verify enforcement
- [ ] `how-to-guides/custom-healthcheck.md` (min 60 lines)
  - How to write custom healthcheck
  - Healthcheck best practices
  - Debugging healthcheck failures
- [ ] `how-to-guides/instance-type-mapping.md` (min 60 lines)
  - Docker limits → EC2 instance mapping
  - Selecting appropriate instance type
  - Cost optimization parallels

**Reference (3):**
- [ ] `reference/compose-resources-syntax.md` (min 120 lines)
  - Complete `deploy.resources` reference
  - CPU and memory limit syntax
  - Reservations vs limits
- [ ] `reference/healthcheck-syntax.md` (min 100 lines)
  - Healthcheck parameters
  - Test command formats
  - Status values and transitions
- [ ] `reference/ec2-instance-mapping.md` (min 80 lines)
  - Docker limits → EC2 instance table
  - Parallelism documentation
  - Command equivalents

**Explanation (1):**
- [ ] `explanation/compute-ec2-parallels.md` (min 280 lines)
  - Container = EC2 Instance
  - Resource limits = Instance types
  - Healthcheck = ELB/Status checks
  - Docker stats = CloudWatch
  - Differences (credits, pricing, etc.)

**Verification:**
```bash
find labs/lab-03-compute -name "*.md" | wc -l        # Expect: 11
wc -l labs/lab-03-compute/tutorial/*.md              # Expect: 750+
wc -l labs/lab-03-compute/how-to-guides/*.md         # Expect: 240+
wc -l labs/lab-03-compute/reference/*.md             # Expect: 300+
wc -l labs/lab-03-compute/explanation/*.md           # Expect: 280+
```

---

### 04-03: Infrastructure Implementation (GREEN Phase)

**Acceptance Criteria:**
- [ ] `docker-compose.yml` exists and is valid
- [ ] All services have `deploy.resources.limits.cpus` set
- [ ] All services have `deploy.resources.limits.memory` set
- [ ] Services have appropriate healthchecks defined
- [ ] Healthcheck parameters are reasonable (interval, timeout, retries)
- [ ] `depends_on` uses `condition: service_healthy` where appropriate
- [ ] INF-03 compliance: NO service without resource limits
- [ ] Cloud nomenclature: Service names follow EC2 instance patterns
- [ ] Infrastructure verification passes all checks

**INF-03 Compliance Check:**
```bash
grep -c "deploy:" labs/lab-03-compute/docker-compose.yml  # Should equal service count
grep -c "cpus:" labs/lab-03-compute/docker-compose.yml     # Should equal service count
grep -c "memory:" labs/lab-03-compute/docker-compose.yml   # Should equal service count
```

**Services Configuration:**

| Service | Instance Type Parallel | CPUs | Memory | Healthcheck |
|---------|----------------------|------|--------|-------------|
| web | t2.micro | 1 | 1G | HTTP endpoint |
| app | t2.small | 1 | 2G | HTTP endpoint |
| worker | t2.medium | 2 | 4G | Custom command |
| db | t2.medium | 2 | 4G | pg_isready |

**Verification Command:**
```bash
cd labs/lab-03-compute
bash tests/99-final-verification.sh
```

**Expected Result:** All checks PASS

---

## Automated Validation Scripts

### Script 1: INF-03 Compliance
```bash
#!/bin/bash
# Verify all services have resource limits

SERVICES=$(docker compose config --services)
for service in $SERVICES; do
    has_cpu=$(docker compose config | grep -A 10 "$service:" | grep -c "cpus:")
    has_mem=$(docker compose config | grep -A 10 "$service:" | grep -c "memory:")
    if [[ $has_cpu -eq 0 || $has_mem -eq 0 ]]; then
        echo "FAIL: $service missing resource limits"
        exit 1
    fi
done
echo "PASS: All services have resource limits"
```

### Script 2: Healthcheck Verification
```bash
#!/bin/bash
# Verify all services have healthchecks

SERVICES=$(docker compose config --services)
for service in $SERVICES; do
    has_hc=$(docker compose config | grep -A 20 "$service:" | grep -c "healthcheck:")
    if [[ $has_hc -eq 0 ]]; then
        echo "FAIL: $service missing healthcheck"
        exit 1
    fi
done
echo "PASS: All services have healthchecks"
```

### Script 3: Resource Enforcement Test
```bash
#!/bin/bash
# Deploy container with limits and verify enforcement

docker compose up -d test-stress
sleep 2

# Get limits
CPU_LIMIT=$(docker inspect test-stress --format='{{.HostConfig.NanoCpus}}')
MEM_LIMIT=$(docker inspect test-stress --format='{{.HostConfig.Memory}}')

# Start stress test
docker exec test-stress stress --cpu 1 &
sleep 5

# Verify CPU doesn't exceed 50%
CPU_USAGE=$(docker stats test-stress --no-stream --format "{{.CPUPerc}}")
if [[ $CPU_USAGE > 50 ]]; then
    echo "FAIL: CPU limit not enforced"
    exit 1
fi

echo "PASS: Resource limits enforced"
```

## Final Validation Checklist

- [ ] All 6 test scripts created (RED phase)
- [ ] All 11 documentation files created (Diátxis)
- [ ] docker-compose.yml implemented (GREEN phase)
- [ ] All tests pass after implementation
- [ ] INF-03 compliance verified
- [ ] Student can follow tutorial end-to-end
- [ ] Parallelism to EC2 documented
- [ ] Resource limits enforced (verified with docker stats)
- [ ] Healthchecks functional
- [ ] Service dependencies work correctly

## Sign-off

Phase 4 is complete when:
1. Student can deploy container with resource limits
2. Student can add healthchecks to services
3. All tests pass (99-final-verification.sh)
4. Documentation follows Diátxis framework
5. INF-03 compliance is mandatory and enforced