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
228
.planning/phases/04-lab-03-compute-ec2/04-01-PLAN.md
Normal file
228
.planning/phases/04-lab-03-compute-ec2/04-01-PLAN.md
Normal file
@@ -0,0 +1,228 @@
|
||||
---
|
||||
phase: 04-lab-03-compute-ec2
|
||||
plan: 01
|
||||
type: execute
|
||||
wave: 0
|
||||
depends_on: []
|
||||
files_modified:
|
||||
- labs/lab-03-compute/tests/01-resource-limits-test.sh
|
||||
- labs/lab-03-compute/tests/02-healthcheck-test.sh
|
||||
- labs/lab-03-compute/tests/03-enforcement-test.sh
|
||||
- labs/lab-03-compute/tests/99-final-verification.sh
|
||||
- labs/lab-03-compute/tests/run-all-tests.sh
|
||||
- labs/lab-03-compute/tests/quick-test.sh
|
||||
autonomous: true
|
||||
requirements:
|
||||
- TEST-01
|
||||
- TEST-05
|
||||
- INF-03
|
||||
- LAB-03
|
||||
user_setup: []
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "Test scripts exist and validate resource limits before implementation"
|
||||
- "Tests verify INF-03 compliance (all containers have CPU/memory limits)"
|
||||
- "Tests verify healthcheck implementation"
|
||||
- "Tests can enforce resource limits and verify with docker stats"
|
||||
- "Final verification script provides clear pass/fail report"
|
||||
artifacts:
|
||||
- path: "labs/lab-03-compute/tests/01-resource-limits-test.sh"
|
||||
provides: "Resource limits validation"
|
||||
min_lines: 80
|
||||
- path: "labs/lab-03-compute/tests/02-healthcheck-test.sh"
|
||||
provides: "Healthcheck testing"
|
||||
min_lines: 100
|
||||
- path: "labs/lab-03-compute/tests/03-enforcement-test.sh"
|
||||
provides: "Resource enforcement verification"
|
||||
min_lines: 120
|
||||
- path: "labs/lab-03-compute/tests/99-final-verification.sh"
|
||||
provides: "Student double-check command"
|
||||
min_lines: 100
|
||||
- path: "labs/lab-03-compute/tests/run-all-tests.sh"
|
||||
provides: "Test orchestration with fail-fast"
|
||||
min_lines: 50
|
||||
- path: "labs/lab-03-compute/tests/quick-test.sh"
|
||||
provides: "Quick validation for development"
|
||||
min_lines: 30
|
||||
key_links:
|
||||
- from: "tests/01-resource-limits-test.sh"
|
||||
to: "docker-compose.yml resources"
|
||||
via: "yq or grep for deploy.resources.limits"
|
||||
pattern: "deploy:.*resources:.*limits"
|
||||
- from: "tests/02-healthcheck-test.sh"
|
||||
to: "docker-compose.yml healthcheck"
|
||||
via: "grep for healthcheck section"
|
||||
pattern: "healthcheck:"
|
||||
- from: "tests/03-enforcement-test.sh"
|
||||
to: "docker stats"
|
||||
via: "docker stats --no-stream for verification"
|
||||
pattern: "docker.*stats"
|
||||
- from: "tests/99-final-verification.sh"
|
||||
to: "INF-03 requirement"
|
||||
via: "Verify all services have cpu and memory limits"
|
||||
pattern: "INF-03"
|
||||
---
|
||||
|
||||
<objective>
|
||||
Create comprehensive test infrastructure for Lab 03 (Compute & EC2) following TDD RED phase methodology. Tests validate Docker Compose resource limits (CPU/memory), healthcheck implementation, and INF-03 compliance (all containers must have resource limits).
|
||||
|
||||
Purpose: Establish verification foundation before implementing compute infrastructure. Tests fail initially (RED phase) and pass after implementation (GREEN phase in Plan 04-03).
|
||||
|
||||
Output: 6 bash test scripts covering resource limits validation, healthcheck testing, enforcement verification, and final verification for students.
|
||||
</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-01-PLAN.md
|
||||
|
||||
# Test Patterns from Phase 2 and 3
|
||||
|
||||
From labs/lab-01-iam/tests/run-all-tests.sh:
|
||||
- Use `set -euo pipefail` for error handling
|
||||
- Color-coded output (GREEN for pass, RED for fail, BLUE for info)
|
||||
- Summary with pass/fail counts
|
||||
- Exit code 0 for all pass, 1 for any failure
|
||||
|
||||
From labs/lab-02-network/tests/04-verify-infrastructure.sh:
|
||||
- Parse docker-compose.yml with `docker compose config`
|
||||
- Use jq for JSON parsing when needed
|
||||
- Verify compliance with grep patterns
|
||||
- Use awk for robust counting
|
||||
|
||||
# Key Docker Commands for Testing
|
||||
|
||||
## Resource Limits Verification
|
||||
```bash
|
||||
# Check if service has CPU limit
|
||||
docker compose config | grep -A 10 "service_name:" | grep -c "cpus:"
|
||||
|
||||
# Check if service has memory limit
|
||||
docker compose config | grep -A 10 "service_name:" | grep -c "memory:"
|
||||
|
||||
# Get container limits
|
||||
docker inspect container_name --format '{{.HostConfig.NanoCpus}}'
|
||||
docker inspect container_name --format '{{.HostConfig.Memory}}'
|
||||
```
|
||||
|
||||
## Healthcheck Verification
|
||||
```bash
|
||||
# Check if service has healthcheck
|
||||
docker compose config | grep -A 20 "service_name:" | grep -c "healthcheck:"
|
||||
|
||||
# Get container health status
|
||||
docker inspect container_name --format '{{.State.Health.Status}}'
|
||||
```
|
||||
|
||||
## Resource Monitoring
|
||||
```bash
|
||||
# Get live stats
|
||||
docker stats --no-stream
|
||||
|
||||
# Get specific container stats
|
||||
docker stats container_name --no-stream --format "{{.CPUPerc}}\t{{.MemUsage}}"
|
||||
```
|
||||
|
||||
# Testing Strategy
|
||||
|
||||
## Test 1: Resource Limits Configuration
|
||||
**Purpose:** Verify docker-compose.yml has resource limits defined
|
||||
**Expected Result:** FAIL initially (no limits configured)
|
||||
**Pass Criteria After Implementation:** All services have cpus and memory limits
|
||||
|
||||
## Test 2: Healthcheck Configuration
|
||||
**Purpose:** Verify services have healthchecks defined
|
||||
**Expected Result:** FAIL initially (no healthchecks configured)
|
||||
**Pass Criteria After Implementation:** All services have valid healthchecks
|
||||
|
||||
## Test 3: Resource Enforcement
|
||||
**Purpose:** Deploy test container and verify limits are enforced
|
||||
**Expected Result:** FAIL initially (no test container defined)
|
||||
**Pass Criteria After Implementation:** docker stats shows enforcement
|
||||
|
||||
## Test 4: INF-03 Compliance
|
||||
**Purpose:** Verify mandatory resource limits for all services
|
||||
**Expected Result:** FAIL initially
|
||||
**Pass Criteria After Implementation:** 100% compliance
|
||||
|
||||
# Implementation Notes
|
||||
|
||||
1. **Directory Structure:**
|
||||
```
|
||||
labs/lab-03-compute/
|
||||
├── tests/
|
||||
│ ├── 01-resource-limits-test.sh
|
||||
│ ├── 02-healthcheck-test.sh
|
||||
│ ├── 03-enforcement-test.sh
|
||||
│ ├── 99-final-verification.sh
|
||||
│ ├── run-all-tests.sh
|
||||
│ └── quick-test.sh
|
||||
├── docker-compose.yml (created in 04-03)
|
||||
└── README.md
|
||||
```
|
||||
|
||||
2. **Test Execution Order:**
|
||||
- 01-resource-limits-test.sh: Parse compose file for limits
|
||||
- 02-healthcheck-test.sh: Parse compose file for healthchecks
|
||||
- 03-enforcement-test.sh: Deploy test and verify enforcement
|
||||
- 99-final-verification.sh: End-to-end student verification
|
||||
|
||||
3. **Error Handling:**
|
||||
- Each test should be independent
|
||||
- Use descriptive error messages
|
||||
- Provide remediation hints
|
||||
|
||||
4. **Color Coding:**
|
||||
```bash
|
||||
RED='\033[0;31m'
|
||||
GREEN='\033[0;32m'
|
||||
BLUE='\033[0;34m'
|
||||
BOLD='\033[1m'
|
||||
NC='\033[0m'
|
||||
```
|
||||
|
||||
# Success Criteria
|
||||
|
||||
Plan 04-01 is complete when:
|
||||
1. All 6 test scripts created
|
||||
2. Each script meets minimum line requirements
|
||||
3. Tests fail when executed on empty/non-existent lab-03-compute
|
||||
4. run-all-tests.sh executes all tests in sequence
|
||||
5. Tests cover: resource limits, healthchecks, enforcement, INF-03
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
1. Create labs/lab-03-compute/tests/ directory
|
||||
2. Create 01-resource-limits-test.sh (80+ lines)
|
||||
- Parse docker-compose.yml for deploy.resources.limits
|
||||
- Verify cpus and memory for all services
|
||||
- Report missing limits
|
||||
3. Create 02-healthcheck-test.sh (100+ lines)
|
||||
- Parse docker-compose.yml for healthcheck sections
|
||||
- Verify test, interval, timeout, retries
|
||||
- Report missing healthchecks
|
||||
4. Create 03-enforcement-test.sh (120+ lines)
|
||||
- Deploy test container with stress image
|
||||
- Verify CPU limit enforcement with docker stats
|
||||
- Verify memory OOM on exceed
|
||||
- Cleanup test container
|
||||
5. Create 99-final-verification.sh (100+ lines)
|
||||
- Combine all checks into student-facing verification
|
||||
- INF-03 compliance report
|
||||
- Healthcheck status report
|
||||
- Clear pass/fail summary
|
||||
6. Create run-all-tests.sh (50+ lines)
|
||||
- Execute all test scripts in sequence
|
||||
- Fail-fast on first failure
|
||||
- Summary report
|
||||
7. Create quick-test.sh (30+ lines)
|
||||
- Fast validation (< 30 seconds)
|
||||
- Essential checks only
|
||||
</tasks>
|
||||
342
.planning/phases/04-lab-03-compute-ec2/04-02-PLAN.md
Normal file
342
.planning/phases/04-lab-03-compute-ec2/04-02-PLAN.md
Normal file
@@ -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>
|
||||
335
.planning/phases/04-lab-03-compute-ec2/04-03-PLAN.md
Normal file
335
.planning/phases/04-lab-03-compute-ec2/04-03-PLAN.md
Normal file
@@ -0,0 +1,335 @@
|
||||
---
|
||||
phase: 04-lab-03-compute-ec2
|
||||
plan: 03
|
||||
type: execute
|
||||
wave: 2
|
||||
depends_on:
|
||||
- "04-01"
|
||||
- "04-02"
|
||||
files_modified:
|
||||
- labs/lab-03-compute/docker-compose.yml
|
||||
- labs/lab-03-compute/Dockerfile
|
||||
- labs/lab-03-compute/tests/04-verify-infrastructure.sh
|
||||
autonomous: true
|
||||
requirements:
|
||||
- LAB-03
|
||||
- INF-01
|
||||
- INF-03
|
||||
- PARA-01
|
||||
- PARA-02
|
||||
- TEST-01
|
||||
- TEST-05
|
||||
user_setup: []
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "docker-compose.yml exists and is valid (docker compose config passes)"
|
||||
- "All services have deploy.resources.limits.cpus set (INF-03)"
|
||||
- "All services have deploy.resources.limits.memory set (INF-03)"
|
||||
- "Services have appropriate healthchecks defined"
|
||||
- "depends_on uses condition: service_healthy where appropriate"
|
||||
- "Infrastructure verification passes all checks"
|
||||
- "Cloud nomenclature follows EC2 instance patterns (PARA-02)"
|
||||
artifacts:
|
||||
- path: "labs/lab-03-compute/docker-compose.yml"
|
||||
provides: "Compute infrastructure with limits and healthchecks"
|
||||
min_lines: 100
|
||||
- path: "labs/lab-03-compute/Dockerfile"
|
||||
provides: "Test container image with stress tools"
|
||||
min_lines: 25
|
||||
- path: "labs/lab-03-compute/tests/04-verify-infrastructure.sh"
|
||||
provides: "Infrastructure verification script"
|
||||
min_lines: 100
|
||||
key_links:
|
||||
- from: "docker-compose.yml"
|
||||
to: "tests/01-resource-limits-test.sh"
|
||||
via: "Tests validate deploy.resources.limits"
|
||||
pattern: "deploy:.*resources:.*limits"
|
||||
- from: "docker-compose.yml"
|
||||
to: "tests/02-healthcheck-test.sh"
|
||||
via: "Tests validate healthcheck sections"
|
||||
pattern: "healthcheck:"
|
||||
- from: "docker-compose.yml"
|
||||
to: "reference/compose-resources-syntax.md"
|
||||
via: "Reference documents all resource options"
|
||||
pattern: "deploy:.*resources"
|
||||
- from: "docker-compose.yml"
|
||||
to: "explanation/compute-ec2-parallels.md"
|
||||
via: "Instance types mapped to EC2"
|
||||
pattern: "# EC2|t2\\.micro|m5\\.large"
|
||||
---
|
||||
|
||||
<objective>
|
||||
Implement compute infrastructure for Lab 03 (Compute & EC2) with Docker Compose resource limits and healthchecks. Create docker-compose.yml with services that have mandatory CPU/memory limits (INF-03 compliance) and healthchecks for readiness verification.
|
||||
|
||||
Purpose: GREEN phase implementation - make tests from Plan 04-01 pass by implementing compute infrastructure with proper resource limits and healthchecks.
|
||||
|
||||
Output: docker-compose.yml with 4+ services, Dockerfile for test container, and infrastructure verification script.
|
||||
</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-03-PLAN.md
|
||||
@labs/lab-02-network/docker-compose.yml
|
||||
|
||||
# Infrastructure Requirements
|
||||
|
||||
## INF-03: Mandatory Resource Limits
|
||||
|
||||
**CRITICAL:** Every service MUST have:
|
||||
```yaml
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: 'X' # REQUIRED
|
||||
memory: 'XG' # REQUIRED
|
||||
```
|
||||
|
||||
**NON-COMPLIANT:**
|
||||
```yaml
|
||||
# Missing limits - INF-03 VIOLATION
|
||||
services:
|
||||
app:
|
||||
image: nginx
|
||||
# No deploy section
|
||||
```
|
||||
|
||||
## Service Configuration
|
||||
|
||||
### Tier 1: Web Server (t2.micro parallel)
|
||||
```yaml
|
||||
web:
|
||||
image: nginx:alpine
|
||||
container_name: lab03-web
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '1'
|
||||
memory: 1G
|
||||
healthcheck:
|
||||
test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost/"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 3
|
||||
start_period: 5s
|
||||
```
|
||||
|
||||
### Tier 2: Application Server (t2.small parallel)
|
||||
```yaml
|
||||
app:
|
||||
image: nginx:alpine
|
||||
container_name: lab03-app
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '1'
|
||||
memory: 2G
|
||||
depends_on:
|
||||
web:
|
||||
condition: service_healthy
|
||||
healthcheck:
|
||||
test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost/"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 3
|
||||
```
|
||||
|
||||
### Tier 3: Worker (t2.medium parallel)
|
||||
```yaml
|
||||
worker:
|
||||
image: alpine:3.19
|
||||
container_name: lab03-worker
|
||||
command: ["sh", "-c", "sleep 3600"]
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '2'
|
||||
memory: 4G
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "exit 0"]
|
||||
interval: 30s
|
||||
timeout: 5s
|
||||
retries: 3
|
||||
```
|
||||
|
||||
### Tier 4: Database (t2.medium parallel)
|
||||
```yaml
|
||||
db:
|
||||
image: postgres:16-alpine
|
||||
container_name: lab03-db
|
||||
environment:
|
||||
POSTGRES_DB: lab03_db
|
||||
POSTGRES_USER: lab03_user
|
||||
POSTGRES_PASSWORD: lab03_password
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '2'
|
||||
memory: 4G
|
||||
volumes:
|
||||
- db-data:/var/lib/postgresql/data
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "pg_isready -U lab03_user -d lab03_db"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
start_period: 10s
|
||||
```
|
||||
|
||||
### Test Container (for enforcement testing)
|
||||
```yaml
|
||||
stress-test:
|
||||
image: polinux/stress
|
||||
container_name: lab03-stress
|
||||
command: ["--cpu", "1", "--vm", "1", "--vm-bytes", "256M", "--timeout", "30s"]
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '0.5'
|
||||
memory: 512M
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "exit 0"]
|
||||
interval: 5s
|
||||
timeout: 3s
|
||||
retries: 3
|
||||
```
|
||||
|
||||
# Dockerfile for Test Container
|
||||
|
||||
```dockerfile
|
||||
# Dockerfile for Lab 03 - Compute & EC2
|
||||
# Test container with stress testing tools
|
||||
|
||||
FROM alpine:3.19
|
||||
|
||||
# Create non-root user (INF-01 compliance)
|
||||
RUN addgroup -g 1000 appgroup && \
|
||||
adduser -D -u 1000 -G appgroup appuser
|
||||
|
||||
# Install stress testing tools
|
||||
RUN apk add --no-cache \
|
||||
stress \
|
||||
curl \
|
||||
&& rm -rf /var/cache/apk/*
|
||||
|
||||
# Switch to non-root user
|
||||
USER appuser
|
||||
|
||||
WORKDIR /home/appuser
|
||||
|
||||
# Default command - ready for stress testing
|
||||
CMD ["sh", "-c", "sleep 3600"]
|
||||
```
|
||||
|
||||
# Healthcheck Best Practices
|
||||
|
||||
## HTTP Service Healthcheck
|
||||
```yaml
|
||||
test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost/health"]
|
||||
interval: 10s # Check every 10 seconds
|
||||
timeout: 5s # Fail after 5 seconds
|
||||
retries: 3 # Unhealthy after 3 failures
|
||||
start_period: 5s # Grace period on startup
|
||||
```
|
||||
|
||||
## Database Healthcheck
|
||||
```yaml
|
||||
test: ["CMD-SHELL", "pg_isready -U postgres || exit 1"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5 # More retries for DB (slower startup)
|
||||
start_period: 10s # Longer grace period
|
||||
```
|
||||
|
||||
## Simple Healthcheck
|
||||
```yaml
|
||||
test: ["CMD-SHELL", "exit 0"]
|
||||
interval: 30s # Less frequent for simple checks
|
||||
timeout: 3s
|
||||
retries: 3
|
||||
```
|
||||
|
||||
# Infrastructure Verification Script
|
||||
|
||||
Based on labs/lab-02-network/tests/04-verify-infrastructure.sh pattern:
|
||||
|
||||
## Verification Steps
|
||||
|
||||
1. **File Existence:** docker-compose.yml exists
|
||||
2. **Syntax Validation:** docker compose config passes
|
||||
3. **Resource Limits:** All services have cpus and memory limits
|
||||
4. **Healthchecks:** All services have healthcheck sections
|
||||
5. **INF-03 Compliance:** 100% of services have limits
|
||||
6. **Deploy Services:** docker compose up -d succeeds
|
||||
7. **Health Status:** Services become healthy
|
||||
8. **Resource Enforcement:** docker stats shows limits
|
||||
9. **Dependency Order:** Services start in correct order
|
||||
10. **Final Report:** Pass/fail summary
|
||||
|
||||
# Cloud Nomenclature (PARA-02)
|
||||
|
||||
Service names should reflect EC2 instance parallels:
|
||||
- `web` → Web tier (t2.micro)
|
||||
- `app` → Application tier (t2.small)
|
||||
- `worker` → Background processing (t2.medium)
|
||||
- `db` → Database tier (t2.medium)
|
||||
|
||||
# Implementation Notes
|
||||
|
||||
1. **Version:** Use `version: "3.8"` for compatibility
|
||||
2. **Networks:** Can reuse networks from Lab 02 or create new
|
||||
3. **Volumes:** Use named volumes for database persistence
|
||||
4. **Security:** Follow INF-01 (no root), INF-02 (no 0.0.0.0 bindings)
|
||||
5. **Parallelism:** Comments should show EC2 equivalent
|
||||
|
||||
# Success Criteria
|
||||
|
||||
Plan 04-03 is complete when:
|
||||
1. docker-compose.yml created with 4+ services
|
||||
2. All services have resource limits (INF-03)
|
||||
3. All services have healthchecks
|
||||
4. docker compose config validates
|
||||
5. Services deploy and become healthy
|
||||
6. Infrastructure verification passes all checks
|
||||
7. Tests from 04-01 now pass (GREEN phase)
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
1. Create labs/lab-03-compute/ directory structure
|
||||
2. Create docker-compose.yml (100+ lines)
|
||||
- Service: web (nginx, t2.micro: 1 CPU, 1G RAM)
|
||||
- Service: app (nginx, t2.small: 1 CPU, 2G RAM)
|
||||
- Service: worker (alpine, t2.medium: 2 CPU, 4G RAM)
|
||||
- Service: db (postgres, t2.medium: 2 CPU, 4G RAM)
|
||||
- Service: stress-test (enforcement testing)
|
||||
- All services: deploy.resources.limits
|
||||
- All services: healthcheck sections
|
||||
- Proper depends_on with conditions
|
||||
- Named volumes for database
|
||||
3. Create Dockerfile (25+ lines)
|
||||
- Alpine 3.19 base
|
||||
- Non-root user (INF-01)
|
||||
- Install stress tools
|
||||
- Minimal and secure
|
||||
4. Create tests/04-verify-infrastructure.sh (100+ lines)
|
||||
- Verify docker-compose.yml exists
|
||||
- Validate syntax
|
||||
- Check INF-03 compliance
|
||||
- Verify healthchecks
|
||||
- Deploy and test services
|
||||
- Check resource enforcement
|
||||
- Final summary report
|
||||
5. Test infrastructure:
|
||||
- docker compose config
|
||||
- docker compose up -d
|
||||
- docker stats verification
|
||||
- health status check
|
||||
- docker compose down
|
||||
</tasks>
|
||||
209
.planning/phases/04-lab-03-compute-ec2/04-RESEARCH.md
Normal file
209
.planning/phases/04-lab-03-compute-ec2/04-RESEARCH.md
Normal file
@@ -0,0 +1,209 @@
|
||||
# Phase 4 Research - Lab 03: Compute & EC2
|
||||
|
||||
## Domain Research: Docker Resource Limits & Healthchecks
|
||||
|
||||
### 1. Docker Compose Resource Limits
|
||||
|
||||
**CPU Limits:**
|
||||
```yaml
|
||||
services:
|
||||
app:
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '0.5' # 50% of 1 CPU core
|
||||
# OR
|
||||
cpus: '2' # 2 full CPU cores
|
||||
```
|
||||
|
||||
**Memory Limits:**
|
||||
```yaml
|
||||
services:
|
||||
app:
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
memory: 512M # 512 MB
|
||||
# OR
|
||||
memory: 2G # 2 GB
|
||||
```
|
||||
|
||||
**Non-Swap Memory:**
|
||||
```yaml
|
||||
services:
|
||||
app:
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
memory: 512M
|
||||
reservations:
|
||||
memory: 256M
|
||||
```
|
||||
|
||||
### 2. EC2 Instance Types Parallel
|
||||
|
||||
| Docker Limits | EC2 Equivalent | Instance Type |
|
||||
|---------------|----------------|---------------|
|
||||
| cpus: '0.5', memory: 512M | t2.nano (0.5 vCPU, 512MB) | Burstable |
|
||||
| cpus: '1', memory: 1G | t2.micro (1 vCPU, 1GB) | Burstable |
|
||||
| cpus: '1', memory: 2G | t2.small (1 vCPU, 2GB) | Burstable |
|
||||
| cpus: '2', memory: 4G | t2.medium (2 vCPU, 4GB) | Burstable |
|
||||
| cpus: '2', memory: 8G | m5.large (2 vCPU, 8GB) | General Purpose |
|
||||
| cpus: '4', memory: 16G | m5.xlarge (4 vCPU, 16GB) | General Purpose |
|
||||
|
||||
**Key Parallelism:**
|
||||
- Docker CPU fractions = AWS vCPUs
|
||||
- Docker memory limits = AWS instance memory
|
||||
- No swap enforcement = AWS EBS-optimized instances
|
||||
- Resource reservations = AWS instance type guarantees
|
||||
|
||||
### 3. Healthcheck Implementation
|
||||
|
||||
**Docker Compose Healthcheck:**
|
||||
```yaml
|
||||
services:
|
||||
web:
|
||||
image: nginx:alpine
|
||||
healthcheck:
|
||||
test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:80"]
|
||||
interval: 10s # Check every 10 seconds
|
||||
timeout: 5s # Timeout after 5 seconds
|
||||
retries: 3 # Mark unhealthy after 3 failures
|
||||
start_period: 10s # Grace period on startup
|
||||
```
|
||||
|
||||
**Healthcheck with curl:**
|
||||
```yaml
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "curl -f http://localhost/ || exit 1"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
start_period: 5s
|
||||
```
|
||||
|
||||
**Database Healthcheck:**
|
||||
```yaml
|
||||
db:
|
||||
image: postgres:16-alpine
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "pg_isready -U postgres || exit 1"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
start_period: 10s
|
||||
```
|
||||
|
||||
**Application Healthcheck:**
|
||||
```yaml
|
||||
app:
|
||||
image: myapp:latest
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "node healthcheck.js || exit 1"]
|
||||
interval: 15s
|
||||
timeout: 3s
|
||||
retries: 3
|
||||
start_period: 30s
|
||||
```
|
||||
|
||||
### 4. Service Dependencies with Health
|
||||
|
||||
**Wait for healthy service:**
|
||||
```yaml
|
||||
services:
|
||||
app:
|
||||
depends_on:
|
||||
db:
|
||||
condition: service_healthy
|
||||
redis:
|
||||
condition: service_started
|
||||
```
|
||||
|
||||
**Lifecycle:**
|
||||
1. `service_started`: Container started (default)
|
||||
2. `service_healthy`: Healthcheck passing (requires healthcheck section)
|
||||
|
||||
### 5. Resource Monitoring
|
||||
|
||||
**docker stats:**
|
||||
```bash
|
||||
docker stats --no-stream # Single snapshot
|
||||
docker stats lab03-app --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}"
|
||||
```
|
||||
|
||||
**Inspect limits:**
|
||||
```bash
|
||||
docker inspect lab03-app --format '{{.HostConfig.Memory}}' # Memory limit in bytes
|
||||
docker inspect lab03-app --format '{{.HostConfig.NanoCpus}}' # CPU quota (1e9 = 1 CPU)
|
||||
```
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Test Scenarios
|
||||
|
||||
1. **Resource Limit Enforcement:**
|
||||
- Deploy container with CPU limit (e.g., 0.5 CPU)
|
||||
- Run CPU-intensive task
|
||||
- Verify with `docker stats` that CPU usage doesn't exceed limit
|
||||
|
||||
2. **Memory Limit Enforcement:**
|
||||
- Deploy container with memory limit (e.g., 512M)
|
||||
- Run memory allocation task
|
||||
- Verify container is OOM killed when exceeding limit
|
||||
|
||||
3. **Healthcheck Validation:**
|
||||
- Deploy service with healthcheck
|
||||
- Verify status transitions: starting → healthy
|
||||
- Verify `depends_on: condition: service_healthy` waits
|
||||
|
||||
4. **Resource Verification:**
|
||||
- Parse docker-compose.yml for `deploy.resources.limits`
|
||||
- Verify all services have mandatory limits
|
||||
- Report missing limits
|
||||
|
||||
## Security Requirements
|
||||
|
||||
**INF-03: Mandatory Resource Limits**
|
||||
- Every container MUST have `cpus` limit specified
|
||||
- Every container MUST have `memory` limit specified
|
||||
- No container can run with unlimited resources (security risk)
|
||||
|
||||
**Safety First:**
|
||||
- Resource limits prevent DoS from runaway processes
|
||||
- Memory limits prevent host OOM
|
||||
- CPU limits ensure fair resource sharing
|
||||
|
||||
## Cloud Parallels
|
||||
|
||||
### Docker → AWS EC2
|
||||
|
||||
| Docker | AWS EC2 |
|
||||
|--------|---------|
|
||||
| `cpus: '0.5'` | 0.5 vCPU (t2.nano) |
|
||||
| `memory: 512M` | 512 MB RAM |
|
||||
| `healthcheck` | EC2 Status Checks + ELB Health |
|
||||
| `docker stats` | CloudWatch Metrics |
|
||||
| `OOM kill` | Instance termination (out of credit) |
|
||||
| `depends_on: healthy` | Auto Scaling Group health checks |
|
||||
|
||||
### Instance Type Selection
|
||||
|
||||
**Burstable Instances (t2/t3):**
|
||||
- Credit-based CPU
|
||||
- Good for dev/test
|
||||
- Docker: Small limits with occasional bursts
|
||||
|
||||
**General Purpose (m5):**
|
||||
- Balanced compute/memory
|
||||
- Docker: Medium limits (2-4 vCPU, 8-16 GB)
|
||||
|
||||
**Compute Optimized (c5):**
|
||||
- High CPU ratio
|
||||
- Docker: High CPU limits (4+ vCPU, lower memory)
|
||||
|
||||
## Sources
|
||||
|
||||
- [Docker Compose Resources](https://docs.docker.com/compose/compose-file/compose-file-v3/#resources)
|
||||
- [Docker Healthcheck](https://docs.docker.com/engine/reference/builder/#healthcheck)
|
||||
- [AWS EC2 Instance Types](https://aws.amazon.com/ec2/instance-types/)
|
||||
- [Docker Stats](https://docs.docker.com/engine/reference/commandline/stats/)
|
||||
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