id: T015
name: Overlay Networking Specification
status: complete
goal: Design multi-tenant overlay network architecture for VM isolation
priority: P0
owner: peerA (strategy) + peerB (research/spec)
created: 2025-12-08
depends_on: [T014]

context: |
  PROJECT.md item 11 specifies overlay networking:
  "マルチテナントでもうまく動くためには、ユーザーの中でアクセスできるネットワークなど、
   考えなければいけないことが山ほどある。これを処理するものも必要。
   とりあえずネットワーク部分自体の実装はOVNとかで良い。"

  PlasmaVMC now has:
  - KVM + FireCracker backends (T011, T014)
  - Multi-tenant scoping (T012)
  - ChainFire persistence (T013)

  Network isolation is critical before production use:
  - Tenant VMs must not see other tenants' traffic
  - VMs within same tenant/project should have private networking
  - External connectivity via controlled gateway

acceptance:
  - Specification document covering architecture, components, APIs
  - OVN integration design (or alternative justification)
  - Tenant network isolation model defined
  - Integration points with PlasmaVMC documented
  - Security model for network policies

steps:
  - step: S1
    action: Research OVN and alternatives
    priority: P0
    status: complete
    owner: peerB
    completed: 2025-12-08
    notes: |
      Study OVN (Open Virtual Network) architecture.
      Evaluate alternatives: Cilium, Calico, custom eBPF.
      Assess complexity vs. capability tradeoffs.
    deliverables:
      - research summary comparing options
      - recommendation with rationale
    evidence:
      - research-summary.md: OVN、Cilium、Calico、カスタムeBPFの比較分析、OVN推奨と根拠

  - step: S2
    action: Design tenant network model
    priority: P0
    status: complete
    owner: peerB
    completed: 2025-12-08
    notes: |
      Define how tenant networks are isolated.
      Design: per-project VPC, subnet allocation, DHCP.
      Consider: security groups, network policies, NAT.
    deliverables:
      - tenant network model document
      - API sketch for network operations
    evidence:
      - tenant-network-model.md: テナントネットワークモデル設計完了、VPC/サブネット/DHCP/セキュリティグループ/NAT設計、APIスケッチ

  - step: S3
    action: Write specification document
    priority: P0
    status: complete
    owner: peerB
    completed: 2025-12-08
    notes: |
      Create specifications/overlay-network/README.md.
      Follow TEMPLATE.md format.
      Include: architecture, data flow, APIs, security model.
    deliverables:
      - specifications/overlay-network/README.md
      - consistent with other component specs
    evidence:
      - specifications/overlay-network/README.md: 仕様ドキュメント作成完了、TEMPLATE.mdフォーマット準拠、アーキテクチャ/データフロー/API/セキュリティモデル含む

  - step: S4
    action: PlasmaVMC integration design
    priority: P1
    status: complete
    owner: peerB
    completed: 2025-12-08
    notes: |
      Define how VmService attaches VMs to tenant networks.
      Design VmConfig network fields.
      Plan for: port creation, IP assignment, security group binding.
    deliverables:
      - integration design note
      - VmConfig network schema extension
    evidence:
      - plasmavmc-integration.md: PlasmaVMC統合設計完了、VmService統合フロー、NetworkSpec拡張、ポート作成/IP割り当て/SGバインディング設計

blockers: []

evidence:
  - research-summary.md: S1完了 - OVNと代替案の調査、OVN推奨
  - tenant-network-model.md: S2完了 - テナントネットワークモデル設計、VPC/サブネット/IPAM/DHCP/セキュリティグループ/NAT設計、APIスケッチ
  - specifications/overlay-network/README.md: S3完了 - 仕様ドキュメント作成、TEMPLATE.mdフォーマット準拠
  - plasmavmc-integration.md: S4完了 - PlasmaVMC統合設計、VmService統合フロー、NetworkSpec拡張

notes: |
  Key considerations:
  - OVN is mature but complex (requires ovsdb, ovn-controller)
  - eBPF-based solutions (Cilium) are modern but may need more custom work
  - Start with OVN for proven multi-tenant isolation, consider optimization later

  Risk: OVN complexity may slow adoption.
  Mitigation: Abstract via clean API, allow pluggable backends later.