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>
This commit is contained in:
Luca Sacchi Ricciardi
247
.planning/phases/04-lab-03-compute-ec2/04-VALIDATION.md
Normal file
247
.planning/phases/04-lab-03-compute-ec2/04-VALIDATION.md
Normal file
@@ -0,0 +1,247 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user