incus-contrib/.claude/rules/networking-storage.md

paths
notes/networking-guide.md notes/shared-storage-guide.md notes/migration-guide.md notes/utm-support.md

Networking, Storage, and Migration

OVN networking

• Bridge networks are node-local: same subnet but separate L2 domains.
• OVN: cross-node L2 overlay via Geneve tunnels. Sub-ms latency.
• IncusOS OVN services disabled by default: enable via /os/1.0/services/ovn on EVERY node.
• OVN service enable:

  incus query <remote>:/os/1.0/services/ovn --request PUT --data '{
    "config": {
      "database": "tcp:<SB_HOST>:6642",
      "enabled": true,
      "tunnel_address": "<THIS_NODE_LAN_IP>",
      "tunnel_protocol": "geneve"
    }, "state": {}
  }'
  

  database is southbound (6642), NOT northbound (6641).
• Setup sequence: deploy OVN container -> enable services -> set northbound connection -> add ovn-chassis roles -> create uplink -> create OVN network.
• Uplink: parent=mgmt (NOT ens18). ipv4.ovn.ranges + ipv4.gateway.
• LB/forward backends need IP addresses, not instance names.
• See notes/networking-guide.md for full tutorial.

Shared storage (iSCSI + lvmcluster)

• IncusOS-native: iSCSI initiator, lvmlockd, sanlock built in.
• iSCSI API: /os/1.0/services/iscsi. Field is "target" (NOT "iqn").
• LVM API: /os/1.0/services/lvm. system_id must be 1-2000 (not 0).
• lvmcluster: thick provisioning. Two-step cluster pattern for pool creation.
• Migration perf (1GbE): container 0.15s, VM non-live 1.8s, VM live ~6s.
• Proxy devices don't work for iSCSI (portal mismatch). Use direct paths.
• First live migration after stop/start may fail (transient sanlock). Retry works.
• Hybrid recommended: local ZFS + shared lvmcluster for HA VMs.
• See notes/shared-storage-guide.md for full walkthrough.

Migration into Incus

• incus-migrate: official import tool. qemu-img convert for format conversion.
• Workflow: convert disk -> incus storage volume import -> incus init --empty --vm -> attach -> start.
• Docker: docker export -> incus import.
• See notes/migration-guide.md for per-hypervisor procedures.

UTM support (future)

• Design doc at notes/utm-support.md.
• utmctl for start/stop but not VM creation (AppleScript or .utm bundle).
• No blockstat equivalent -- timeout + port polling for install detection.