lucasacchi/laboratori-cloud
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(03-lab-02-network-vpc): create phase plans (3 plans in 2 waves)

Browse Source
This commit is contained in:
Luca Sacchi Ricciardi
2026-03-25 09:17:22 +01:00
parent ff89202c41
commit dff75ef5ef
4 changed files with 1632 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

375
.planning/phases/03-lab-02-network-vpc/03-01-PLAN.md Normal file
View File

@@ -0,0 +1,375 @@
---
phase: 03-lab-02-network-vpc
plan: 01
type: execute
wave: 0
depends_on: []
files_modified:
- labs/lab-02-network/tests/01-network-creation-test.sh
- labs/lab-02-network/tests/02-isolation-verification-test.sh
- labs/lab-02-network/tests/03-inf02-compliance-test.sh
- labs/lab-02-network/tests/99-final-verification.sh
- labs/lab-02-network/tests/run-all-tests.sh
- labs/lab-02-network/tests/quick-test.sh
autonomous: true
requirements:
- TEST-01
- TEST-05
- INF-02
- LAB-02
user_setup: []
must_haves:
truths:
- "Test scripts exist and validate network infrastructure before implementation"
- "Tests can be executed with single command (run-all-tests.sh)"
- "Tests verify INF-02 compliance (no 0.0.0.0 port bindings)"
- "Tests validate network isolation between bridge networks"
- "Final verification script provides clear pass/fail report"
artifacts:
- path: "labs/lab-02-network/tests/01-network-creation-test.sh"
provides: "Network creation validation"
min_lines: 80
- path: "labs/lab-02-network/tests/02-isolation-verification-test.sh"
provides: "Isolation testing between networks"
min_lines: 100
- path: "labs/lab-02-network/tests/03-inf02-compliance-test.sh"
provides: "INF-02 security compliance verification"
min_lines: 60
- path: "labs/lab-02-network/tests/99-final-verification.sh"
provides: "Student double-check command"
min_lines: 100
- path: "labs/lab-02-network/tests/run-all-tests.sh"
provides: "Test orchestration with fail-fast"
min_lines: 50
- path: "labs/lab-02-network/tests/quick-test.sh"
provides: "Quick validation for development"
min_lines: 30
key_links:
- from: "tests/02-isolation-verification-test.sh"
to: "docker network"
via: "docker network create, docker exec ping"
pattern: "docker.*network.*create"
- from: "tests/03-inf02-compliance-test.sh"
to: "INF-02 requirement"
via: "grep for 0.0.0.0 bindings in docker-compose.yml"
pattern: "0\\.0\\.0\\.0"
---
<objective>
Create comprehensive test infrastructure for Lab 02 (Network & VPC) following TDD RED phase methodology. Tests validate Docker bridge network creation, isolation between networks, and INF-02 compliance (private networks don't expose ports on 0.0.0.0).
Purpose: Establish verification foundation before implementing network infrastructure. Tests fail initially (RED phase) and pass after implementation (GREEN phase in Plan 03-03).
Output: 6 bash test scripts covering network creation, isolation verification, INF-02 compliance, 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/03-lab-02-network-vpc/03-RESEARCH.md
@.planning/phases/03-lab-02-network-vpc/03-VALIDATION.md
@.planning/phases/02-lab-01-iam-sicurezza/02-01-SUMMARY.md
# Test Patterns from Phase 2
From labs/lab-01-iam/tests/run-all-tests.sh:
```bash
#!/bin/bash
set -euo pipefail
# Color output for clarity
RED='\033[0;31m'
GREEN='\033[0;32m'
BLUE='\033[0;34m'
NC='\033[0m'
# Test array with fail-fast behavior
declare -a tests=(
"$TEST_DIR/test-01-user-creation.sh"
"$TEST_DIR/test-02-docker-access.sh"
)
# Counter increment helpers to handle set -e
inc_pass() { ((pass_count++)) || true; }
inc_fail() { ((fail_count++)) || true; }
```
Phase 2 patterns to follow:
- Color-coded output (PASS=green, FAIL=red, SKIP=yellow)
- Helper functions for counter increments with `|| true`
- Fail-fast behavior on test failures
- Test directory relative paths: `$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)`
</context>
<tasks>
<task type="auto">
<name>Task 1: Create network creation test</name>
<files>labs/lab-02-network/tests/01-network-creation-test.sh</files>
<action>
Create bash test script that validates Docker bridge network creation with custom subnets (VPC simulation).
Test cases:
1. Verify docker network create command works with custom subnet (10.0.1.0/24 for vpc-public)
2. Verify network can be created with --internal flag (for private subnet)
3. Verify network shows in docker network ls
4. Verify network inspection shows correct subnet and gateway
5. Cleanup: Remove test networks
Requirements:
- Use `set -euo pipefail` for strict error handling
- Color-coded output (PASS/FAIL/SKIP)
- Helper functions inc_pass() and inc_fail() with `|| true`
- Skip test gracefully if docker-compose.yml doesn't exist yet (YELLOW output)
- Test creates temporary networks for validation, then cleans up
Test validation:
- Network creation: `docker network create --driver bridge --subnet 10.0.1.0/24 test-vpc-public`
- Internal network: `docker network create --driver bridge --internal --subnet 10.0.2.0/24 test-vpc-private`
- Verification: `docker network inspect test-vpc-public | grep "10.0.1.0/24"`
Expected: 5 tests total (network creation, internal network, network listing, inspection, cleanup)
</action>
<verify>
<automated>bash labs/lab-02-network/tests/01-network-creation-test.sh</automated>
</verify>
<done>Script executes and validates Docker network creation with custom subnets. Tests show SKIP (yellow) if infrastructure not yet created.</done>
</task>
<task type="auto">
<name>Task 2: Create isolation verification test</name>
<files>labs/lab-02-network/tests/02-isolation-verification-test.sh</files>
<action>
Create bash test script that validates network isolation between Docker bridge networks.
Test cases:
1. Containers in same network can communicate (ping success)
2. Containers in different networks CANNOT communicate (ping fails - isolation works)
3. Containers in same network can resolve by name (DNS works)
4. Containers in different networks cannot resolve by name
5. Private network containers cannot reach external internet (if --internal flag used)
Requirements:
- Follow Phase 2 test patterns (color output, helper functions)
- Create test containers in separate networks
- Use alpine images with sleep 3600 for testing
- Use `docker exec container ping -c 2 -W 1 other_container` for connectivity
- Expected FAIL for cross-network communication (isolation = no communication)
- Cleanup: Remove test containers and networks
Test commands:
- Create networks: `docker network create --subnet 10.0.1.0/24 test-net1`, `docker network create --subnet 10.0.2.0/24 test-net2`
- Create containers: `docker run -d --name c1 --network test-net1 alpine sleep 3600`
- Test same-network: `docker exec c1 ping -c 2 -W 1 c2` (should succeed)
- Test cross-network: `docker exec c1 ping -c 2 -W 1 c3` (should FAIL - isolation)
- Test DNS: `docker exec c1 nslookup c2` (should succeed in same network)
Expected: 5 tests total (same-network ping, cross-network isolation, DNS resolution, cross-network DNS failure, private network isolation)
</action>
<verify>
<automated>bash labs/lab-02-network/tests/02-isolation-verification-test.sh</automated>
</verify>
<done>Script validates network isolation. Cross-network tests correctly fail (proving isolation works). Same-network tests succeed.</done>
</task>
<task type="auto">
<name>Task 3: Create INF-02 compliance test</name>
<files>labs/lab-02-network/tests/03-inf02-compliance-test.sh</files>
<action>
Create bash test script that validates INF-02 requirement: private networks must NOT expose ports on 0.0.0.0.
Test cases:
1. Verify docker-compose.yml exists
2. Verify no port bindings use 0.0.0.0 (violates INF-02)
3. Verify private services use 127.0.0.1 binding (localhost only)
4. Verify docker-compose config is valid YAML
5. Verify no published ports for private-only services
Requirements:
- Parse docker-compose.yml for port mappings
- Use grep to find patterns like `ports: ["8080:80"]` (bad - defaults to 0.0.0.0)
- Verify correct pattern: `ports: ["127.0.0.1:8080:80"]` (good - localhost only)
- Test should FAIL if 0.0.0.0 bindings found
- Skip gracefully if docker-compose.yml doesn't exist yet
Test commands:
- Check file exists: `[ -f labs/lab-02-network/docker-compose.yml ]`
- Find port mappings: `grep -E "^\s*-\s*[0-9]+:" docker-compose.yml` or `grep -A 20 "ports:"`
- Check for violations: `grep -E '0\.0\.0\.0:[0-9]+' docker-compose.yml` (should NOT find)
- Validate YAML: `docker-compose -f docker-compose.yml config` (if file exists)
Expected: 5 tests total (file exists, no 0.0.0.0 bindings, 127.0.0.1 bindings used, YAML valid, private services no ports)
</action>
<verify>
<automated>bash labs/lab-02-network/tests/03-inf02-compliance-test.sh</automated>
</verify>
<done>Script validates INF-02 compliance. Fails if 0.0.0.0 port bindings found. Passes if all private services use 127.0.0.1 or no published ports.</done>
</task>
<task type="auto">
<name>Task 4: Create final verification script</name>
<files>labs/lab-02-network/tests/99-final-verification.sh</files>
<action>
Create comprehensive final verification script for students (double-check command).
Test coverage:
1. All networks defined in docker-compose.yml can be created
2. Network isolation works between defined networks
3. INF-02 compliance verified (no 0.0.0.0 bindings)
4. Docker services can start successfully
5. Container connectivity matches expected topology
Requirements:
- End-to-end verification of entire lab
- Clear pass/fail summary with color output
- Student-friendly output explaining what was tested
- Follows Phase 2 pattern from labs/lab-01-iam/tests/99-final-verification.sh
- Includes helpful next steps if tests fail
Script structure:
```bash
#!/bin/bash
# Final verification: Lab 02 - Network & VPC
# Usage: bash labs/lab-02-network/tests/99-final-verification.sh
set -euo pipefail
# Color definitions
RED='\033[0;31m'
GREEN='\033[0;32m'
BLUE='\033[0;34m'
YELLOW='\033[1;33m'
NC='\033[0m'
# Header with lab description
# Test 1: Network creation
# Test 2: Isolation verification
# Test 3: INF-02 compliance
# Test 4: Service startup
# Test 5: Connectivity verification
# Summary with pass/fail counts
# Next steps if failed
```
Expected: 5 comprehensive tests validating entire lab infrastructure
</action>
<verify>
<automated>bash labs/lab-02-network/tests/99-final-verification.sh</automated>
</verify>
<done>Final verification script provides clear pass/fail report. Students can run single command to validate entire lab.</done>
</task>
<task type="auto">
<name>Task 5: Create test orchestration scripts</name>
<files>labs/lab-02-network/tests/run-all-tests.sh, labs/lab-02-network/tests/quick-test.sh</files>
<action>
Create two test orchestration scripts:
1. **run-all-tests.sh**: Full test suite with fail-fast behavior
- Runs all test scripts in sequence
- Stops on first failure (fail-fast)
- Shows summary with pass/fail counts
- Recommends final verification if all pass
- Follows Phase 2 pattern from labs/lab-01-iam/tests/run-all-tests.sh
2. **quick-test.sh**: Quick validation for development (< 30 seconds)
- Runs subset of critical tests
- For use during development (per-task validation)
- Tests: network creation, INF-02 compliance, basic isolation
- Faster feedback loop than full suite
Requirements for both:
- Use `set -euo pipefail`
- Color-coded output
- Relative paths from script directory
- Test array definition for easy modification
- Counter increments with `|| true` helper
run-all-tests.sh structure:
```bash
declare -a tests=(
"$TEST_DIR/01-network-creation-test.sh"
"$TEST_DIR/02-isolation-verification-test.sh"
"$TEST_DIR/03-inf02-compliance-test.sh"
)
```
quick-test.sh structure:
```bash
declare -a tests=(
"$TEST_DIR/01-network-creation-test.sh"
"$TEST_DIR/03-inf02-compliance-test.sh"
)
```
Expected: 2 orchestration scripts enabling both full validation and quick development feedback
</action>
<verify>
<automated>bash labs/lab-02-network/tests/run-all-tests.sh</automated>
</verify>
<done>Orchestration scripts run all tests in sequence. Fail-fast stops on first failure. Quick-test provides rapid feedback during development.</done>
</task>
</tasks>
<verification>
## Test Infrastructure Verification
After all tasks complete, verify:
1. **Test Files Created**: All 6 test scripts exist in labs/lab-02-network/tests/
2. **Scripts Are Executable**: Run `chmod +x labs/lab-02-network/tests/*.sh`
3. **Tests Run Successfully**: `bash labs/lab-02-network/tests/run-all-tests.sh` executes (tests may show SKIP if infrastructure not created)
4. **Quick Test Works**: `bash labs/lab-02-network/tests/quick-test.sh` completes in < 30 seconds
5. **Pattern Consistency**: Tests follow Phase 2 patterns (color output, helper functions, fail-fast)
## Automated Validation Commands
```bash
# Verify all test files exist
ls -la labs/lab-02-network/tests/*.sh
# Run full test suite (should execute, may show SKIP)
bash labs/lab-02-network/tests/run-all-tests.sh
# Run quick test
bash labs/lab-02-network/tests/quick-test.sh
# Run final verification
bash labs/lab-02-network/tests/99-final-verification.sh
```
## Success Criteria
- [ ] All 6 test scripts created
- [ ] Tests follow bash best practices (set -euo pipefail, proper exit codes)
- [ ] Color-coded output (PASS=green, FAIL=red, SKIP=yellow)
- [ ] Tests handle missing infrastructure gracefully (SKIP instead of FAIL)
- [ ] run-all-tests.sh implements fail-fast behavior
- [ ] quick-test.sh completes in < 30 seconds
- [ ] Final verification provides clear student-facing report
</verification>
<success_criteria>
1. Test infrastructure is complete BEFORE implementation (Wave 0 requirement satisfied)
2. All requirement IDs (TEST-01, TEST-05, INF-02, LAB-02) have test coverage
3. Tests can be executed with single command: `bash labs/lab-02-network/tests/run-all-tests.sh`
4. Tests validate network creation, isolation, and INF-02 compliance
5. Final verification script provides clear pass/fail report for students
6. Quick test enables rapid development feedback (< 30 seconds)
7. Test patterns consistent with Phase 2 (color output, helper functions, fail-fast)
</success_criteria>
<output>
After completion, create `.planning/phases/03-lab-02-network-vpc/03-01-SUMMARY.md` with:
- Test files created (6 files, line counts)
- Test coverage details
- Pattern consistency with Phase 2
- Any deviations or issues encountered
- Verification results
</output>

566
.planning/phases/03-lab-02-network-vpc/03-02-PLAN.md Normal file
View File

@@ -0,0 +1,566 @@
---
phase: 03-lab-02-network-vpc
plan: 02
type: execute
wave: 1
depends_on: []
files_modified:
- labs/lab-02-network/tutorial/01-create-vpc-networks.md
- labs/lab-02-network/tutorial/02-deploy-containers-networks.md
- labs/lab-02-network/tutorial/03-verify-network-isolation.md
- labs/lab-02-network/how-to-guides/create-custom-network.md
- labs/lab-02-network/how-to-guides/inspect-network-configuration.md
- labs/lab-02-network/how-to-guides/test-network-isolation.md
- labs/lab-02-network/how-to-guides/cleanup-networks.md
- labs/lab-02-network/reference/docker-network-commands.md
- labs/lab-02-network/reference/compose-network-syntax.md
- labs/lab-02-network/reference/vpc-network-mapping.md
- labs/lab-02-network/explanation/docker-network-vpc-parallels.md
autonomous: true
requirements:
- DOCT-01
- DOCT-02
- DOCT-03
- DOCT-04
- DOCT-05
- PARA-01
- PARA-02
- PARA-03
- PARA-04
user_setup: []
must_haves:
truths:
- "All 4 Diátaxis documents exist (Tutorial, How-to, Reference, Explanation)"
- "Tutorial follows 'little often' principle with small incremental steps"
- "How-to guides are goal-oriented and can be read independently"
- "Reference documents contain technical specifications (commands, syntax, mappings)"
- "Explanation document maps Docker networks to VPC concepts with cloud nomenclature"
artifacts:
- path: "labs/lab-02-network/tutorial/01-create-vpc-networks.md"
provides: "Step-by-step network creation guide"
min_lines: 100
- path: "labs/lab-02-network/tutorial/02-deploy-containers-networks.md"
provides: "Container deployment with network configuration"
min_lines: 100
- path: "labs/lab-02-network/tutorial/03-verify-network-isolation.md"
provides: "Isolation verification procedures"
min_lines: 100
- path: "labs/lab-02-network/explanation/docker-network-vpc-parallels.md"
provides: "Cloud parallelism concepts (PARA-01, PARA-02, PARA-03, PARA-04)"
min_lines: 200
key_links:
- from: "tutorial/01-create-vpc-networks.md"
to: "reference/compose-network-syntax.md"
via: "Cross-reference for detailed syntax"
pattern: "See.*reference.*compose-network-syntax"
- from: "explanation/docker-network-vpc-parallels.md"
to: "PARA-01, PARA-02 requirements"
via: "Component mapping tables"
pattern: "Docker.*VPC|Bridge.*Subnet"
---
<objective>
Create complete Diátaxis documentation for Lab 02 (Network & VPC): 3 tutorials (step-by-step), 4 how-to guides (goal-oriented), 3 reference documents (technical specs), and 1 explanation document (cloud parallels). Documentation teaches Docker bridge networks as VPC/subnet simulation using cloud nomenclature (PARA-02).
Purpose: Provide comprehensive learning materials following Diátaxis framework. Students learn through incremental tutorials (little often), reference specific procedures with how-to guides, access technical specifications in reference docs, and understand cloud parallels in explanation.
Output: 11 markdown documents covering all Diátaxis quadrants with VPC/Subnet terminology throughout.
</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/03-lab-02-network-vpc/03-RESEARCH.md
@.planning/phases/02-lab-01-iam-sicurezza/02-02-SUMMARY.md
@labs/lab-01-iam/tutorial/01-create-linux-users.md
@labs/lab-01-iam/explanation/docker-iam-parallels.md
# Phase 2 Documentation Patterns
From labs/lab-01-iam/tutorial structure:
- Numbered steps (1., 2., 3.) for clarity
- Verification after each step ("Verifica il lavoro...")
- Troubleshooting sections
- Cross-references to related documents
- Italian language (no emojis)
From labs/lab-01-iam/explanation/dockers-iam-parallels.md:
- Side-by-side comparison tables (Docker vs AWS)
- "Parallelismi Chiave" sections
- "Differenze Importanti" sections (PARA-03)
- Command comparison tables (PARA-04)
# Cloud Nomenclature Requirements (PARA-02)
From 03-RESEARCH.md, use consistent naming:
- Networks: `vpc-public`, `vpc-private`, `public-subnet-1a`, `private-subnet-1a`
- Subnet CIDRs: `10.0.1.0/24` for public, `10.0.2.0/24` for private
- VPC CIDR: `10.0.0.0/16` (simulated through multiple /24 subnets)
- Security groups: Referenced as "regole di isolamento rete"
# Diátaxis Framework Requirements
**Tutorial (DOCT-01, DOCT-05):**
- Step-by-step, incremental learning
- "Little often" principle
- Assumes no prior knowledge
- Verification after each step
**How-to Guides (DOCT-02):**
- Goal-oriented, procedure-focused
- Can be read independently
- Solve specific problems
- Not tutorials (don't teach basics)
**Reference (DOCT-03):**
- Technical specifications
- Code examples, syntax, commands
- No explanation of WHY (just WHAT)
- Tables, lists, code blocks
**Explanation (DOCT-04):**
- Conceptual understanding
- Cloud parallels (PARA-01)
- Differences between local and cloud (PARA-03)
- Context and reasoning
</context>
<tasks>
<task type="auto">
<name>Task 1: Create Tutorial Part 1 - Create VPC Networks</name>
<files>labs/lab-02-network/tutorial/01-create-vpc-networks.md</files>
<action>
Create first tutorial document teaching students to create Docker bridge networks that simulate VPC and subnets.
Content structure:
1. **Title and Overview**: "Creare Reti VPC con Docker Bridge Networks"
2. **Learning Objectives**: What students will learn (network creation, subnet concepts)
3. **Prerequisites**: Docker installed, basic Docker knowledge
4. **Step 1: Understanding VPC Concepts**: Brief explanation of VPC, subnets, CIDR blocks
5. **Step 2: Create Public Subnet Network**: `docker network create --driver bridge --subnet 10.0.1.0/24 --gateway 10.0.1.1 lab02-vpc-public`
6. **Verification Step 1**: `docker network ls`, `docker network inspect lab02-vpc-public`
7. **Step 3: Create Private Subnet Network**: `docker network create --driver bridge --subnet 10.0.2.0/24 --internal lab02-vpc-private`
8. **Verification Step 2**: Inspect private network, note `Internal: true`
9. **Troubleshooting**: Common errors (network exists, subnet conflicts)
10. **Summary**: What was created, what's next
Requirements:
- Italian language (no emojis)
- Use cloud nomenclature: "VPC", "subnet", "CIDR"
- "Little often" principle: Small steps with verification after each
- Cross-references: See `reference/compose-network-syntax.md` for full syntax
- Code blocks with exact commands
- Expected output shown in examples
- Verification commands after each step
Key commands to include:
```bash
# Create public subnet network
docker network create --driver bridge --subnet 10.0.1.0/24 --gateway 10.0.1.1 lab02-vpc-public
# Create private subnet network (isolated)
docker network create --driver bridge --subnet 10.0.2.0/24 --internal lab02-vpc-private
# Verify creation
docker network ls
docker network inspect lab02-vpc-public
```
Expected: ~120 lines following Phase 2 tutorial patterns
</action>
<verify>
<automated>grep -E "docker network create|Verifica|Step [0-9]" labs/lab-02-network/tutorial/01-create-vpc-networks.md | head -20</automated>
</verify>
<done>Tutorial document teaches network creation with VPC terminology. Includes verification steps and troubleshooting.</done>
</task>
<task type="auto">
<name>Task 2: Create Tutorial Part 2 - Deploy Containers with Networks</name>
<files>labs/lab-02-network/tutorial/02-deploy-containers-networks.md</files>
<action>
Create second tutorial document teaching students to deploy containers in custom networks using docker-compose.yml.
Content structure:
1. **Title and Overview**: "Distribuire Container in Reti VPC"
2. **Prerequisites**: Tutorial 01 completed, networks created
3. **Step 1: Create docker-compose.yml**: Full file with network definitions
4. **Step 2: Define Networks in Compose**: Custom networks with subnets (10.0.1.0/24, 10.0.2.0/24)
5. **Step 3: Define Services**: Web server in public network, database in private network
6. **Step 4: Port Publishing**: INF-02 compliance (127.0.0.1 binding only)
7. **Verification Step 1**: `docker-compose config`
8. **Step 5: Start Services**: `docker-compose up -d`
9. **Verification Step 2**: `docker-compose ps`, `docker network inspect`
10. **Step 6: Verify Service Placement**: Which network each service is in
11. **Troubleshooting**: Port conflicts, network not found
12. **Summary**: Multi-tier architecture deployed
Requirements:
- Complete docker-compose.yml example (V2 syntax)
- Network definitions with IPAM config
- Services showing multi-tier placement
- INF-02 compliance: `ports: ["127.0.0.1:8080:80"]` for public services
- No ports exposed for private services (database)
- Verification after each step
- Cross-references to Reference for full syntax
docker-compose.yml structure:
```yaml
version: "3.8"
networks:
vpc-public:
driver: bridge
name: lab02-vpc-public
ipam:
config:
- subnet: 10.0.1.0/24
gateway: 10.0.1.1
vpc-private:
driver: bridge
name: lab02-vpc-private
internal: true
ipam:
config:
- subnet: 10.0.2.0/24
services:
web:
image: nginx:alpine
networks:
- vpc-public
ports:
- "127.0.0.1:8080:80" # INF-02 compliant
db:
image: postgres:16-alpine
networks:
- vpc-private
# No ports - private network only
```
Expected: ~130 lines with complete working example
</action>
<verify>
<automated>grep -E "networks:|vpc-public|vpc-private|docker-compose" labs/lab-02-network/tutorial/02-deploy-containers-networks.md | head -15</automated>
</verify>
<done>Tutorial shows complete docker-compose.yml with VPC networks. Services deployed in correct tiers with INF-02 compliance.</done>
</task>
<task type="auto">
<name>Task 3: Create Tutorial Part 3 - Verify Network Isolation</name>
<files>labs/lab-02-network/tutorial/03-verify-network-isolation.md</files>
<action>
Create third tutorial document teaching students to verify network isolation between Docker bridge networks.
Content structure:
1. **Title and Overview**: "Verificare l'Isolamento delle Reti VPC"
2. **Prerequisites**: Tutorials 01 and 02 completed, services running
3. **Step 1: Test Same-Network Communication**: `docker exec web ping -c 2 db` (should FAIL - different networks)
4. **Step 2: Add Service to Both Networks**: Modify docker-compose.yml, add API service to both networks
5. **Step 3: Test Cross-Network Communication**: API can reach both web and db
6. **Verification Step 1**: Connectivity tests between services
7. **Step 4: Test Private Network Isolation**: Private service cannot reach internet (if --internal used)
8. **Step 5: Verify INF-02 Compliance**: Check no 0.0.0.0 bindings with `netstat -tlnp`
9. **Verification Step 2**: Run test scripts from tests/
10. **Troubleshooting**: Unexpected connectivity, DNS resolution issues
11. **Summary**: Isolation verified, architecture secure
Requirements:
- Practical connectivity tests using ping, curl, nc
- Expected results shown (SUCCESS vs FAILURE)
- Explanation of WHY tests fail (isolation working correctly)
- Cross-reference to test scripts: `bash tests/02-isolation-verification-test.sh`
- INF-02 verification steps
- Troubleshooting common issues
Key test commands:
```bash
# Test 1: Same network (should succeed)
docker exec container1 ping -c 2 container2
# Test 2: Different networks (should FAIL - isolation)
docker exec web ping -c 2 db
# Test 3: DNS resolution
docker exec web nslookup db # Should fail (different network)
# Test 4: INF-02 check
netstat -tlnp | grep docker
# Should NOT show 0.0.0.0:8080
# Should show 127.0.0.1:8080
```
Expected: ~120 lines with practical verification steps
</action>
<verify>
<automated>grep -E "ping|curl|isolamento|verify|Verifica" labs/lab-02-network/tutorial/03-verify-network-isolation.md | head -15</automated>
</verify>
<done>Tutorial teaches practical isolation verification. Students test connectivity and understand expected failures.</done>
</task>
<task type="auto">
<name>Task 4: Create How-to Guides</name>
<files>labs/lab-02-network/how-to-guides/create-custom-network.md, labs/lab-02-network/how-to-guides/inspect-network-configuration.md, labs/lab-02-network/how-to-guides/test-network-isolation.md, labs/lab-02-network/how-to-guides/cleanup-networks.md</files>
<action>
Create 4 how-to guides for specific network procedures (goal-oriented, independent reading).
**Guide 1: create-custom-network.md**
- Goal: Create a custom Docker network with specific subnet
- Prerequisites: Docker installed
- Steps: Single procedure with command variations
- Examples: Bridge network, internal network, multiple subnets
- Command reference with all options explained
- ~60 lines
**Guide 2: inspect-network-configuration.md**
- Goal: Inspect and understand Docker network configuration
- Steps: docker network inspect, reading output, understanding IPAM
- Output interpretation: What each field means
- Examples: Show inspect output with annotations
- ~70 lines
**Guide 3: test-network-isolation.md**
- Goal: Verify network isolation between containers
- Steps: Create test containers, run connectivity tests, interpret results
- Tools: ping, curl, nc, netstat
- Expected results: When isolation works (tests fail)
- ~70 lines
**Guide 4: cleanup-networks.md**
- Goal: Remove networks and fix common cleanup issues
- Steps: Remove networks, remove containers, fix "network has active endpoints"
- Commands: docker network rm, docker-compose down -v
- Troubleshooting: Networks that won't delete, orphaned networks
- ~60 lines
Requirements for all guides:
- Goal-oriented title (not "Learn about...")
- Can be read independently (no tutorial dependencies)
- Practical, actionable steps
- Command examples with output
- Italian language, no emojis
- Troubleshooting sections
Expected: 4 guides, ~260 lines total
</action>
<verify>
<automated>ls -la labs/lab-02-network/how-to-guides/*.md && wc -l labs/lab-02-network/how-to-guides/*.md</automated>
</verify>
<done>4 how-to guides created for common network procedures. Each guide is independent and goal-oriented.</done>
</task>
<task type="auto">
<name>Task 5: Create Reference Documents</name>
<files>labs/lab-02-network/reference/docker-network-commands.md, labs/lab-02-network/reference/compose-network-syntax.md, labs/lab-02-network/reference/vpc-network-mapping.md</files>
<action>
Create 3 reference documents with technical specifications (no explanation, just facts).
**Reference 1: docker-network-commands.md**
- Complete command reference for docker network
- Commands: create, ls, inspect, rm, connect, disconnect
- All flags and options documented
- Examples for each command
- Output format explanations
- Table format for quick lookup
- ~100 lines
**Reference 2: compose-network-syntax.md**
- docker-compose.yml network syntax (V3.8)
- Network driver options (bridge, overlay, macvlan)
- IPAM configuration (subnet, gateway, ip_range)
- Network options (internal, attachable)
- Service network attachment
- Port publishing syntax
- Complete example with all options
- ~120 lines
**Reference 3: vpc-network-mapping.md**
- Mapping table: Docker concepts → VPC concepts
- Subnet CIDR assignments: 10.0.1.0/24 (public), 10.0.2.0/24 (private)
- Network naming conventions: lab02-vpc-public, lab02-vpc-private
- Container placement: Which services go in which networks
- Security group equivalents: Docker network isolation = Security groups
- Port binding rules: 127.0.0.1 vs 0.0.0.0
- ASCII diagram of network topology
- ~100 lines
Requirements for all references:
- Technical only (no "why", just "what")
- Tables, lists, code blocks
- Complete and accurate
- Quick lookup format
- Italian language, no emojis
- Based on RESEARCH.md findings
Expected: 3 reference documents, ~320 lines total
</action>
<verify>
<automated>ls -la labs/lab-02-network/reference/*.md && grep -E "docker network|networks:|VPC|mapping" labs/lab-02-network/reference/*.md | head -20</automated>
</verify>
<done>3 reference documents with complete technical specifications. Quick lookup tables for commands, syntax, and mappings.</done>
</task>
<task type="auto">
<name>Task 6: Create Explanation Document (Cloud Parallels)</name>
<files>labs/lab-02-network/explanation/docker-network-vpc-parallels.md</files>
<action>
Create comprehensive explanation document mapping Docker networks to VPC concepts (PARA-01, PARA-02, PARA-03, PARA-04).
Content structure:
1. **Introduction**: Why Docker networks simulate VPC well
2. **Parallelismi Chiave (Key Parallels)** - PARA-01:
- Docker Bridge Network → AWS VPC
- Custom Subnet → VPC Subnet
- Container IP → Instance IP
- Network isolation → Security Group rules
- Docker embedded DNS → VPC DNS resolver
- Bridge driver → VPC routing table
3. **Tabella Comparativa (Comparison Table)**:
- Side-by-side: Docker command vs AWS CLI command
- Example: `docker network create` vs `aws ec2 create-vpc`
4. **Architettura Locale vs Cloud (PARA-02)**:
- Network topology diagram
- Naming: lab02-vpc-public (local) vs public-subnet-1a (cloud)
- CIDR blocks: 10.0.1.0/24 matches AWS convention
5. **Differenze Importanti (PARA-03)**:
- Single host vs Multi-AZ
- No NAT Gateway simulation
- No Internet Gateway
- No real route tables (Docker handles automatically)
- Network is local to one Docker daemon
6. **Command Comparison (PARA-04)**:
- Table: Docker command | AWS CLI equivalent | Purpose
- Examples: network create, network inspect, network ls
7. **Limitazioni della Simulazione**:
- What cannot be simulated locally
- When real cloud networking differs significantly
8. **Conclusion**: Understanding transfers to cloud
Requirements:
- Focus on conceptual understanding (not "how to")
- Cloud nomenclature throughout (PARA-02)
- Side-by-side comparison tables
- Clear differences section (PARA-03)
- Command equivalences (PARA-04)
- Italian language, no emojis
- Based on RESEARCH.md findings
- ~200+ lines
Key parallels to explain:
```
Docker Bridge Network → AWS VPC
───────────────────────────────────────────
10.0.1.0/24 subnet → Public Subnet (10.0.1.0/24)
10.0.2.0/24 subnet → Private Subnet (10.0.2.0/24)
Network isolation → Security Group rules
--internal flag → No Internet Gateway
Container in network → Instance in Subnet
Embedded DNS → VPC DNS Resolver
```
Expected: ~220 lines with comprehensive cloud parallelism explanation
</action>
<verify>
<automated>grep -E "VPC|parallels|Differenze|AWS|compar" labs/lab-02-network/explanation/docker-network-vpc-parallels.md | head -25</automated>
</verify>
<done>Explanation document maps Docker networks to VPC concepts. Includes comparison tables, differences, and command equivalences.</done>
</task>
</tasks>
<verification>
## Documentation Verification
After all tasks complete, verify:
1. **All 4 Diátaxis Quadrants Present**:
- Tutorial: 3 parts (01, 02, 03)
- How-to: 4 guides
- Reference: 3 documents
- Explanation: 1 document
2. **Language and Style**:
- Italian language throughout
- No emojis used
- Direct, simple language
3. **Cross-References**:
- Tutorials reference relevant how-to guides
- All documents reference related materials
- No orphan documents (all linked)
4. **Cloud Nomenclature (PARA-02)**:
- VPC terminology used consistently
- Subnet naming follows cloud pattern
- CIDR blocks match AWS convention (10.0.x.0/24)
5. **Requirement Coverage**:
- DOCT-01: Tutorial exists (3 parts)
- DOCT-02: How-to guides exist (4 guides)
- DOCT-03: Reference documents exist (3 docs)
- DOCT-04: Explanation exists (cloud parallels)
- DOCT-05: Tutorial follows "little often"
- PARA-01: Component mapping in explanation
- PARA-02: Cloud nomenclature used
- PARA-03: Differences documented
- PARA-04: Commands compared
## Automated Validation Commands
```bash
# Count documents by quadrant
echo "Tutorial files: $(ls labs/lab-02-network/tutorial/*.md | wc -l)"
echo "How-to files: $(ls labs/lab-02-network/how-to-guides/*.md | wc -l)"
echo "Reference files: $(ls labs/lab-02-network/reference/*.md | wc -l)"
echo "Explanation files: $(ls labs/lab-02-network/explanation/*.md | wc -l)"
# Verify VPC terminology
grep -r "VPC\|subnet\|CIDR" labs/lab-02-network/ --include="*.md" | wc -l
# Verify cloud parallels in explanation
grep -E "parallels|AWS|compar" labs/lab-02-network/explanation/docker-network-vpc-parallels.md | wc -l
# Check for emojis (should return nothing)
grep -r "[😀-🙏]" labs/lab-02-network/ --include="*.md"
# Verify Italian language (should contain Italian words)
grep -r "creare|verificare|rete|container" labs/lab-02-network/ --include="*.md" | wc -l
```
## Manual Verification
1. Read Tutorial 01 and verify step-by-step format
2. Read one how-to guide and verify it's standalone
3. Check reference for table format
4. Read explanation and verify comparison tables exist
5. Verify all cross-references work (files exist)
</verification>
<success_criteria>
1. All 11 Diátaxis documents created (3 tutorials, 4 how-to, 3 reference, 1 explanation)
2. Tutorial follows "little often" principle with verification after each step
3. How-to guides are goal-oriented and independently readable
4. Reference documents contain technical specifications in table format
5. Explanation document includes cloud parallels (PARA-01), cloud nomenclature (PARA-02), differences (PARA-03), and command comparisons (PARA-04)
6. All documents use Italian language with no emojis
7. Cross-references between related documents
8. VPC terminology used consistently throughout
9. Total documentation: ~900+ lines across all files
</success_criteria>
<output>
After completion, create `.planning/phases/03-lab-02-network-vpc/03-02-SUMMARY.md` with:
- All 11 documents created with line counts
- Diátaxis quadrant coverage verification
- Requirement coverage (DOCT-01 through DOCT-05, PARA-01 through PARA-04)
- Cloud nomenclature usage verified
- Cross-reference validation
- Total documentation metrics
</output>

680
.planning/phases/03-lab-02-network-vpc/03-03-PLAN.md Normal file
View File

@@ -0,0 +1,680 @@
---
phase: 03-lab-02-network-vpc
plan: 03
type: execute
wave: 2
depends_on: ["03-01", "03-02"]
files_modified:
- labs/lab-02-network/docker-compose.yml
- labs/lab-02-network/Dockerfile
- labs/lab-02-network/tests/04-verify-infrastructure.sh
autonomous: true
requirements:
- LAB-02
- INF-02
- TEST-01
user_setup: []
must_haves:
truths:
- "docker-compose.yml defines VPC networks with custom subnets"
- "Private networks use --internal flag and no published ports"
- "Public services bind to 127.0.0.1 only (INF-02 compliant)"
- "Infrastructure verification tests pass (GREEN phase)"
- "All services start successfully with docker-compose up"
artifacts:
- path: "labs/lab-02-network/docker-compose.yml"
provides: "VPC network definition with subnets"
min_lines: 80
contains: "networks:, vpc-public, vpc-private, ipam, subnet"
- path: "labs/lab-02-network/Dockerfile"
provides: "Test container image for network verification"
min_lines: 30
- path: "labs/lab-02-network/tests/04-verify-infrastructure.sh"
provides: "Infrastructure verification script"
min_lines: 100
key_links:
- from: "docker-compose.yml"
to: "INF-02 requirement"
via: "Port bindings use 127.0.0.1, never 0.0.0.0"
pattern: "127\\.0\\.0\\.1:[0-9]+:[0-9]+"
- from: "docker-compose.yml networks"
to: "VPC simulation"
via: "Custom subnets 10.0.1.0/24 and 10.0.2.0/24"
pattern: "10\\.0\\.[12]\\.0/24"
---
<objective>
Create Docker infrastructure (docker-compose.yml and Dockerfile) implementing VPC simulation with isolated bridge networks. Following TDD methodology, this is the GREEN phase - tests already exist from Plan 03-01, and infrastructure should make those tests pass. Infrastructure must enforce INF-02 compliance (private networks don't expose ports on 0.0.0.0).
Purpose: Implement network infrastructure that simulates AWS VPC with public and private subnets. Students learn by running docker-compose and observing isolated networks in action.
Output: Working docker-compose.yml with VPC networks, test container image, and infrastructure verification script that validates all requirements.
</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/03-lab-02-network-vpc/03-RESEARCH.md
@.planning/phases/03-lab-02-network-vpc/03-01-PLAN.md
@.planning/phases/02-lab-01-iam-sicurezza/02-03-SUMMARY.md
@labs/lab-01-iam/docker-compose.yml
@labs/lab-01-iam/Dockerfile
# Phase 2 Infrastructure Patterns
From labs/lab-01-iam/docker-compose.yml:
```yaml
version: "3.8"
services:
lab01-test:
build: .
user: "1000:1000" # INF-01 enforcement
container_name: lab01-iam-test
healthcheck:
test: ["CMD", "sh", "-c", "whoami | grep -q labuser"]
```
From labs/lab-01-iam/Dockerfile:
- Alpine 3.19 base image (minimal, secure)
- Non-root user (labuser, UID 1000)
- USER directive before any operations
- CMD demonstrates functionality
# Network Architecture from RESEARCH.md
From 03-RESEARCH.md, Pattern 1 (VPC Simulation):
```yaml
networks:
vpc-public:
driver: bridge
name: lab02-vpc-public
ipam:
config:
- subnet: 10.0.1.0/24
gateway: 10.0.1.1
vpc-private:
driver: bridge
name: lab02-vpc-private
internal: true # Blocks external internet
ipam:
config:
- subnet: 10.0.2.0/24
gateway: 10.0.2.1
services:
web:
image: nginx:alpine
networks:
- vpc-public
ports:
- "127.0.0.1:8080:80" # INF-02: Only localhost
db:
image: postgres:16-alpine
networks:
- vpc-private
# No ports - private network only
```
# INF-02 Requirement
From REQUIREMENTS.md:
- INF-02: Reti private non espongono porte sull'host (127.0.0.1 max, mai 0.0.0.0)
- Test verifies: grep for 0.0.0.0 bindings (violation)
- Correct pattern: `ports: ["127.0.0.1:8080:80"]`
- Private services: No published ports at all
</context>
<tasks>
<task type="auto">
<name>Task 1: Create docker-compose.yml with VPC networks</name>
<files>labs/lab-02-network/docker-compose.yml</files>
<action>
Create docker-compose.yml implementing VPC simulation with two isolated networks (public and private subnets).
File structure:
1. **Header**: version: "3.8"
2. **Networks section**:
- vpc-public: Bridge driver, subnet 10.0.1.0/24, gateway 10.0.1.1
- vpc-private: Bridge driver, subnet 10.0.2.0/24, gateway 10.0.2.1, internal: true
3. **Services section**:
- **web-service**: Nginx Alpine in vpc-public network
* Image: nginx:alpine
* Container name: lab02-web-public
* Networks: vpc-public only
* Ports: 127.0.0.1:8080:80 (INF-02 compliant - localhost only)
* Restart: unless-stopped
- **api-service**: Custom test image in both networks
* Build: . (uses Dockerfile from Task 2)
* Container name: lab02-api-tier
* Networks: vpc-public AND vpc-private (multi-homed for tier communication)
* Ports: 127.0.0.1:8081:8000 (INF-02 compliant)
* Restart: unless-stopped
- **db-service**: PostgreSQL Alpine in vpc-private only
* Image: postgres:16-alpine
* Container name: lab02-db-private
* Networks: vpc-private only
* Environment: POSTGRES_PASSWORD=testpass (test only)
* NO PORTS - private network isolation
* Restart: unless-stopped
4. **Volumes**: Named volume for database data persistence (INF-04 preparation)
5. **Comments**: Explain VPC simulation, subnet choices, INF-02 compliance
Requirements:
- Use cloud nomenclature: vpc-public, vpc-private
- Subnets: 10.0.1.0/24 (public), 10.0.2.0/24 (private)
- INF-02 strict compliance:
* Public services: `127.0.0.1:PORT:PORT` format
* Private services: No published ports
* NEVER use `0.0.0.0:PORT:PORT`
- vpc-private uses `internal: true` (blocks internet access)
- Multi-tier architecture: web → api → db
- API service connects to both networks (demonstrates multi-homed containers)
- Comments explaining each section
Complete example structure:
```yaml
version: "3.8"
# VPC Network Simulation
# This configuration simulates AWS VPC with public and private subnets
# using Docker bridge networks with custom CIDR blocks
networks:
# Public Subnet: simulates 10.0.1.0/24 with internet access
vpc-public:
driver: bridge
name: lab02-vpc-public
ipam:
driver: default
config:
- subnet: 10.0.1.0/24
gateway: 10.0.1.1
# Private Subnet: simulates 10.0.2.0/24 without internet access
vpc-private:
driver: bridge
name: lab02-vpc-private
internal: true # No internet gateway (private subnet)
ipam:
driver: default
config:
- subnet: 10.0.2.0/24
gateway: 10.0.2.1
services:
# Web Server in Public Subnet
web:
image: nginx:alpine
container_name: lab02-web-public
networks:
- vpc-public
ports:
# INF-02: Bind to localhost only, NOT 0.0.0.0
- "127.0.0.1:8080:80"
restart: unless-stopped
# API Service (multi-homed: both public and private)
api:
build:
context: .
dockerfile: Dockerfile
container_name: lab02-api-tier
networks:
- vpc-public
- vpc-private
ports:
# INF-02: Localhost binding only
- "127.0.0.1:8081:8000"
depends_on:
- db
restart: unless-stopped
# Database in Private Subnet (no internet, no host ports)
db:
image: postgres:16-alpine
container_name: lab02-db-private
networks:
- vpc-private
environment:
POSTGRES_DB: labdb
POSTGRES_USER: labuser
POSTGRES_PASSWORD: testpass
# NO PORTS - private network only (INF-02)
volumes:
- lab02-db-data:/var/lib/postgresql/data
restart: unless-stopped
# Named volume for database persistence (INF-04)
volumes:
lab02-db-data:
driver: local
```
Expected: ~100 lines with complete VPC simulation
</action>
<verify>
<automated>cd labs/lab-02-network && docker-compose config && docker-compose up -d && docker-compose ps</automated>
</verify>
<done>docker-compose.yml defines VPC networks with correct subnets. Services deployed in appropriate tiers. INF-02 compliant (127.0.0.1 bindings only).</done>
</task>
<task type="auto">
<name>Task 2: Create Dockerfile for API service</name>
<files>labs/lab-02-network/Dockerfile</files>
<action>
Create Dockerfile for test API service that demonstrates network connectivity and multi-tier communication.
Requirements:
- Base image: Alpine 3.19 (minimal, consistent with Lab 1)
- Non-root user: labuser UID 1000 (INF-01 compliance from Lab 1)
- Install networking tools: curl, netcat-openbsd, iputils-ping
- Simple test service: Python HTTP server or netcat listener
- Healthcheck: Verify connectivity to database
- Demonstrates: Same-network and cross-network communication
Dockerfile structure:
```dockerfile
# Base image: Alpine 3.19
FROM alpine:3.19
# Install networking tools for testing
RUN apk add --no-cache \
python3 \
curl \
netcat-openbsd \
iputils-ping
# Create non-root user (INF-01 compliance)
RUN addgroup -g 1000 labuser && \
adduser -D -u 1000 -G labuser labuser
# Create working directory
WORKDIR /app
# Create simple test server (Python)
RUN echo '#!/usr/bin/env python3' > test-server.py && \
echo 'import http.server' >> test-server.py && \
echo 'import socket' >> test-server.py && \
echo 'import sys' >> test-server.py && \
echo 'class TestHandler(http.server.SimpleHTTPRequestHandler):' >> test-server.py && \
echo ' def do_GET(self):' >> test-server.py && \
echo ' self.send_response(200)' >> test-server.py && \
echo ' self.send_header("Content-Type", "text/plain")' >> test-server.py && \
echo ' self.end_headers()' >> test-server.py && \
echo ' response = f"API Server\\nContainer: {socket.gethostname()}\\nNetwork: Both public and private\\n"' >> test-server.py && \
echo ' self.wfile.write(response.encode())' >> test-server.py && \
echo 'if __name__ == "__main__":' >> test-server.py && \
echo ' http.server.HTTPServer(("0.0.0.0", 8000), TestHandler).serve_forever()' >> test-server.py && \
chmod +x test-server.py
# Switch to non-root user
USER labuser
# Expose port (internal, not published by default)
EXPOSE 8000
# Healthcheck: Test connectivity to database
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
CMD nc -zv lab02-db-private 5432 || exit 1
# Start test server
CMD ["python3", "test-server.py"]
```
Alternative (simpler - without Python):
```dockerfile
FROM alpine:3.19
# Install minimal tools
RUN apk add --no-cache \
curl \
netcat-openbsd \
iputils-ping \
bash
# Create non-root user
RUN addgroup -g 1000 labuser && \
adduser -D -u 1000 -G labuser labuser
# Create test script
RUN echo '#!/bin/bash' > /app/test-service.sh && \
echo 'echo "API Service - Multi-tier network test"' >> /app/test-service.sh && \
echo 'echo "Connected to both vpc-public and vpc-private"' >> /app/test-service.sh && \
echo 'echo "Testing connectivity..."' >> /app/test-service.sh && \
echo 'while true; do sleep 3600; done' >> /app/test-service.sh && \
chmod +x /app/test-service.sh
USER labuser
WORKDIR /app
EXPOSE 8000
# Healthcheck
HEALTHCHECK --interval=30s --timeout=3s \
CMD nc -zv lab02-db-private 5432 || exit 1
CMD ["/app/test-service.sh"]
```
Requirements:
- Non-root user (INF-01)
- Networking tools installed
- Healthcheck tests connectivity to private network
- Simple enough for Lab 2 (don't overcomplicate)
- ~40-50 lines
Expected: ~45 lines with non-root user and networking tools
</action>
<verify>
<automated>cd labs/lab-02-network && docker-compose build api && docker images | grep lab02-api</automated>
</verify>
<done>Dockerfile builds successfully. Creates non-root container with networking tools. Healthcheck tests connectivity to private network.</done>
</task>
<task type="auto">
<name>Task 3: Create infrastructure verification script</name>
<files>labs/lab-02-network/tests/04-verify-infrastructure.sh</files>
<action>
Create comprehensive infrastructure verification script that validates docker-compose.yml and running services.
Test cases:
1. Verify docker-compose.yml is valid YAML
2. Verify networks defined correctly (vpc-public, vpc-private)
3. Verify subnet configurations (10.0.1.0/24, 10.0.2.0/24)
4. Verify INF-02 compliance (no 0.0.0.0 bindings)
5. Verify private network has internal: true flag
6. Verify docker-compose build succeeds
7. Verify services start successfully
8. Verify network isolation (web cannot ping db)
9. Verify same-network communication (api can reach db)
10. Verify port bindings (127.0.0.1 only)
Requirements:
- Follow Phase 2 test patterns (color output, helper functions)
- Use docker-compose config to validate YAML
- Use docker network inspect to verify network config
- Use docker exec for connectivity tests
- Use grep for INF-02 validation
- Clear pass/fail for each test
- Graceful SKIP if services not running
Script structure:
```bash
#!/bin/bash
# Infrastructure Verification: Lab 02 - Network & VPC
# Validates docker-compose.yml and running services
set -euo pipefail
# Color definitions
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m'
# Test directory
TEST_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
LAB_DIR="$(cd "$TEST_DIR/.." && pwd)"
cd "$LAB_DIR"
# Counter helpers
pass_count=0
fail_count=0
skip_count=0
inc_pass() { ((pass_count++)) || true; }
inc_fail() { ((fail_count++)) || true; }
inc_skip() { ((skip_count++)) || true; }
echo -e "${BLUE}========================================${NC}"
echo -e "${BLUE}Lab 02: Infrastructure Verification${NC}"
echo -e "${BLUE}========================================${NC}"
echo ""
# Test 1: docker-compose.yml is valid
echo -e "[1/10] Testing docker-compose.yml syntax..."
if docker-compose config > /dev/null 2>&1; then
echo -e "${GREEN}PASS${NC}: docker-compose.yml is valid"
inc_pass
else
echo -e "${RED}FAIL${NC}: docker-compose.yml has syntax errors"
inc_fail
fi
# Test 2: Networks defined
echo -e "[2/10] Testing network definitions..."
if docker-compose config | grep -q "vpc-public:" && \
docker-compose config | grep -q "vpc-private:"; then
echo -e "${GREEN}PASS${NC}: vpc-public and vpc-private networks defined"
inc_pass
else
echo -e "${RED}FAIL${NC}: Networks not found in compose file"
inc_fail
fi
# Test 3: Subnet configurations
echo -e "[3/10] Testing subnet configurations..."
if docker-compose config | grep -q "10.0.1.0/24" && \
docker-compose config | grep -q "10.0.2.0/24"; then
echo -e "${GREEN}PASS${NC}: Subnets 10.0.1.0/24 and 10.0.2.0/24 configured"
inc_pass
else
echo -e "${RED}FAIL${NC}: Subnet configurations incorrect"
inc_fail
fi
# Test 4: INF-02 compliance
echo -e "[4/10] Testing INF-02 compliance (no 0.0.0.0 bindings)..."
if docker-compose config | grep -qE '0\.0\.0\.0:[0-9]+'; then
echo -e "${RED}FAIL${NC}: Found 0.0.0.0 port bindings (INF-02 violation)"
inc_fail
else
echo -e "${GREEN}PASS${NC}: No 0.0.0.0 bindings found (INF-02 compliant)"
inc_pass
fi
# Test 5: Private network internal flag
echo -e "[5/10] Testing private network isolation..."
if docker-compose config | grep -A 3 "vpc-private:" | grep -q "internal: true"; then
echo -e "${GREEN}PASS${NC}: vpc-private has internal: true flag"
inc_pass
else
echo -e "${YELLOW}SKIP${NC}: internal flag not found (may be in extended config)"
inc_skip
fi
# Test 6: Build succeeds
echo -e "[6/10] Testing docker-compose build..."
if docker-compose build -q api > /dev/null 2>&1; then
echo -e "${GREEN}PASS${NC}: Docker image builds successfully"
inc_pass
else
echo -e "${YELLOW}SKIP${NC}: Build failed or not needed (images may exist)"
inc_skip
fi
# Test 7-10: Runtime tests (if services running)
# Check if services are running
if docker-compose ps | grep -q "Up"; then
# Test 7: Services running
echo -e "[7/10] Testing service status..."
running_count=$(docker-compose ps | grep -c "Up" || true)
if [ "$running_count" -ge 2 ]; then
echo -e "${GREEN}PASS${NC}: Services are running ($running_count services)"
inc_pass
else
echo -e "${YELLOW}SKIP${NC}: Not all services running"
inc_skip
fi
# Test 8: Network isolation
echo -e "[8/10] Testing network isolation..."
if docker exec lab02-web-public ping -c 1 -W 1 lab02-db-private > /dev/null 2>&1; then
echo -e "${RED}FAIL${NC}: Public network can reach private (isolation broken)"
inc_fail
else
echo -e "${GREEN}PASS${NC}: Public and private networks isolated"
inc_pass
fi
# Test 9: Same-network communication
echo -e "[9/10] Testing same-network communication..."
if docker exec lab02-api-tier ping -c 1 -W 1 lab02-db-private > /dev/null 2>&1; then
echo -e "${GREEN}PASS${NC}: API can reach database (same network)"
inc_pass
else
echo -e "${YELLOW}SKIP${NC}: Multi-homed container test skipped"
inc_skip
fi
# Test 10: Port bindings
echo -e "[10/10] Testing port bindings..."
if netstat -tlnp 2>/dev/null | grep -q "127.0.0.1:8080"; then
echo -e "${GREEN}PASS${NC}: Port 8080 bound to 127.0.0.1 (INF-02 compliant)"
inc_pass
else
echo -e "${YELLOW}SKIP${NC}: Port binding check skipped (netstat not available)"
inc_skip
fi
else
echo -e "${YELLOW}SKIP${NC}: Runtime tests skipped (services not running)"
inc_skip; inc_skip; inc_skip; inc_skip
fi
# Summary
echo ""
echo -e "${BLUE}========================================${NC}"
echo -e "${BLUE}Test Summary${NC}"
echo -e "${BLUE}========================================${NC}"
echo "Passed: $pass_count"
echo "Failed: $fail_count"
echo "Skipped: $skip_count"
echo ""
if [ $fail_count -eq 0 ]; then
echo -e "${GREEN}Infrastructure verification PASSED${NC}"
exit 0
else
echo -e "${RED}Infrastructure verification FAILED${NC}"
exit 1
fi
```
Expected: ~180 lines with 10 comprehensive tests
</action>
<verify>
<automated>bash labs/lab-02-network/tests/04-verify-infrastructure.sh</automated>
</verify>
<done>Infrastructure verification script validates docker-compose.yml, networks, INF-02 compliance, and service connectivity. All tests pass.</done>
</task>
</tasks>
<verification>
## Infrastructure Verification
After all tasks complete, verify:
1. **Files Created**:
- docker-compose.yml exists
- Dockerfile exists
- tests/04-verify-infrastructure.sh exists
2. **Compose Configuration**:
- `docker-compose config` succeeds (valid YAML)
- Two networks defined: vpc-public, vpc-private
- Correct subnets: 10.0.1.0/24, 10.0.2.0/24
- Three services: web, api, db
3. **INF-02 Compliance**:
- No 0.0.0.0 bindings in docker-compose config
- Public services use 127.0.0.1:PORT:PORT format
- Private services have no published ports
- vpc-private has internal: true flag
4. **Services Start Successfully**:
- `docker-compose up -d` succeeds
- All containers show "Up" status
- Containers have correct network attachments
5. **Network Isolation**:
- web (public) cannot ping db (private)
- api (multi-homed) can reach db (private)
- DNS resolution works within same network
6. **Tests Pass**:
- Infrastructure verification script passes
- All tests from Plan 03-01 should now pass (GREEN phase)
## Automated Validation Commands
```bash
# Verify compose configuration
cd labs/lab-02-network && docker-compose config
# Check for INF-02 violations (should return nothing)
cd labs/lab-02-network && docker-compose config | grep "0.0.0.0"
# Build services
cd labs/lab-02-network && docker-compose build
# Start services
cd labs/lab-02-network && docker-compose up -d
# Check service status
cd labs/lab-02-network && docker-compose ps
# Verify networks created
docker network ls | grep lab02
# Run infrastructure verification
bash labs/lab-02-network/tests/04-verify-infrastructure.sh
# Run full test suite (should all pass now)
bash labs/lab-02-network/tests/run-all-tests.sh
# Cleanup
cd labs/lab-02-network && docker-compose down -v
```
## Success Criteria
- [ ] docker-compose.yml is valid and configures VPC networks
- [ ] Two networks defined: vpc-public (10.0.1.0/24), vpc-private (10.0.2.0/24)
- [ ] vpc-private has internal: true flag
- [ ] No 0.0.0.0 port bindings (INF-02 compliant)
- [ ] Services start successfully with docker-compose up
- [ ] Network isolation verified (public cannot reach private)
- [ ] Infrastructure verification script passes all tests
- [ ] All tests from Plan 03-01 now pass (GREEN phase complete)
</verification>
<success_criteria>
1. docker-compose.yml implements VPC simulation with two networks (public, private)
2. Custom subnets configured (10.0.1.0/24, 10.0.2.0/24)
3. INF-02 compliance enforced (127.0.0.1 bindings only, no 0.0.0.0)
4. Private network uses internal: true flag
5. Services deployed in correct tiers (web→public, db→private, api→both)
6. Dockerfile creates non-root container with networking tools
7. Infrastructure verification script validates all requirements
8. All tests pass (GREEN phase complete - TDD cycle finished)
</success_criteria>
<output>
After completion, create `.planning/phases/03-lab-02-network-vpc/03-03-SUMMARY.md` with:
- docker-compose.yml structure and decisions
- Dockerfile specifications
- Infrastructure verification test results
- INF-02 compliance validation
- Network isolation verification
- TDD GREEN phase completion confirmation
</output>