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

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>