laboratori-cloud/.planning/phases/03-lab-02-network-vpc/03-02-PLAN.md

---
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>