23 KiB
23 KiB
phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, user_setup, must_haves
| phase | plan | type | wave | depends_on | files_modified | autonomous | requirements | user_setup | must_haves | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 03-lab-02-network-vpc | 02 | execute | 1 |
|
true |
|
|
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.
<execution_context> @/home/luca/.claude/get-shit-done/workflows/execute-plan.md @/home/luca/.claude/get-shit-done/templates/summary.md </execution_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.mdPhase 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/24for public,10.0.2.0/24for 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
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
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
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
**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
**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
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
After all tasks complete, verify:
-
All 4 Diátaxis Quadrants Present:
- Tutorial: 3 parts (01, 02, 03)
- How-to: 4 guides
- Reference: 3 documents
- Explanation: 1 document
-
Language and Style:
- Italian language throughout
- No emojis used
- Direct, simple language
-
Cross-References:
- Tutorials reference relevant how-to guides
- All documents reference related materials
- No orphan documents (all linked)
-
Cloud Nomenclature (PARA-02):
- VPC terminology used consistently
- Subnet naming follows cloud pattern
- CIDR blocks match AWS convention (10.0.x.0/24)
-
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
# 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
- Read Tutorial 01 and verify step-by-step format
- Read one how-to guide and verify it's standalone
- Check reference for table format
- Read explanation and verify comparison tables exist
- Verify all cross-references work (files exist)
<success_criteria>
- All 11 Diátaxis documents created (3 tutorials, 4 how-to, 3 reference, 1 explanation)
- Tutorial follows "little often" principle with verification after each step
- How-to guides are goal-oriented and independently readable
- Reference documents contain technical specifications in table format
- Explanation document includes cloud parallels (PARA-01), cloud nomenclature (PARA-02), differences (PARA-03), and command comparisons (PARA-04)
- All documents use Italian language with no emojis
- Cross-references between related documents
- VPC terminology used consistently throughout
- Total documentation: ~900+ lines across all files </success_criteria>