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:

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:

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:

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:

cd labs/lab-03-compute
bash tests/99-final-verification.sh

Expected Result: All checks PASS

---

Automated Validation Scripts

Script 1: INF-03 Compliance

#!/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

#!/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

#!/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