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

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