Fix V2K and N2K disk ordering bugs

dhslove · dhslove · commit 7085da11987d · 2026-06-01T22:29:49.000+09:00
diff --git a/docs/v2k_n2k_disk_order_bugfix_design.md b/docs/v2k_n2k_disk_order_bugfix_design.md
@@ -0,0 +1,33 @@
+# V2K/N2K 디스크 순서 보정 설계
+
+## 배경
+
+N2K wizard 테스트에서 Nutanix inventory 배열 첫 번째 디스크가 실제 `SCSI unit 0`이 아닌 `SCSI unit 1`로 내려왔고, n2k가 배열 첫 번째 디스크를 Cloud ROOT 볼륨으로 사용하면서 대상 VM의 root/data 디스크 역할이 뒤바뀌었다.
+
+V2K 코드도 Cloud cutover, libvirt XML 생성, Linux bootstrap 단계에서 `.disks[0]`을 root 디스크로 간주한다. VMware inventory는 `disk_id`를 `scsi0:0`처럼 주소 기반으로 만들지만, govc device 배열을 명시적으로 정렬하지 않으면 같은 계열의 오류가 발생할 수 있다.
+
+## 원칙
+
+- 외부 API가 반환한 디스크 배열 순서를 root 판정 근거로 사용하지 않는다.
+- 명시적인 boot disk 정보가 있으면 가장 우선한다.
+- boot disk 정보가 없으면 컨트롤러 타입, 버스, 유닛 번호 기준으로 안정 정렬한다.
+- 정렬 후 첫 번째 디스크는 `role=root`, 나머지는 `role=data`로 기록해 후속 분석과 로그 판독을 쉽게 한다.
+- wizard target map, manifest, phase1/phase2/full cutover가 동일한 정렬 결과를 공유하도록 inventory 정규화 단계에서 보정한다.
+
+## N2K 적용
+
+- Nutanix inventory 정규화 단계에서 `bootConfig.bootDevice.diskAddress`가 있으면 해당 디스크를 root로 우선 정렬한다.
+- boot 주소가 없으면 `controller.type`, `controller.bus`, `controller.unit/device_index`, 원본 배열 인덱스 순으로 정렬한다.
+- 정렬 후 fallback label과 `role`을 부여한다.
+
+## V2K 적용
+
+- VMware inventory 정규화 단계에서 `config.bootOptions.bootOrder[].deviceKey`가 있으면 해당 `VirtualDisk.key`를 가진 디스크를 root로 우선 정렬한다.
+- boot order가 없거나 디스크 항목이 없으면 `controller.type`, `controller.bus`, `controller.unit`, 원본 배열 인덱스 순으로 정렬한다.
+- 정렬 후 `role=root|data`와 `source_ordinal`을 기록한다.
+
+## 검증
+
+- N2K: Nutanix API 배열이 `unit 1`, `unit 0` 순서로 내려와도 `unit 0`이 `.disks[0]`이 되는 smoke test를 추가한다.
+- V2K: govc `device.info` 배열이 `scsi0:1`, `scsi0:0` 순서로 내려와도 `scsi0:0`이 `.disks[0]`이 되는 smoke test를 추가한다.
+- V2K: boot order가 `scsi0:1`의 `deviceKey`를 명시하면 `scsi0:1`을 root로 우선하는 smoke test를 추가한다.
diff --git a/lib/n2k/nutanix_api.sh b/lib/n2k/nutanix_api.sh
@@ -399,6 +399,39 @@ n2k_nutanix_inventory_from_raw() {
           and (((.device_properties.device_type // .deviceProperties.deviceType // .device_type // .deviceType // "DISK") | tostring | ascii_upcase) != "CDROM")
         ));
 
+    def address_bus($a):
+      ($a.busType // $a.bus_type // $a.adapter_type // $a.device_bus // "" | tostring | ascii_downcase);
+
+    def address_unit($a; $fallback):
+      (($a.index // $a.deviceIndex // $a.device_index // $a.deviceIndex // $fallback) | tonumber? // $fallback);
+
+    def controller_rank($type):
+      ($type | tostring | ascii_downcase) as $t
+      | if $t == "scsi" then 0
+        elif $t == "virtio" then 1
+        elif $t == "sata" then 2
+        elif $t == "ide" then 3
+        elif $t == "pci" then 4
+        else 9 end;
+
+    def boot_disk_address($r):
+      ($r.bootConfig.bootDevice.diskAddress
+       // $r.bootConfig.boot_device.disk_address
+       // $r.boot_config.bootDevice.diskAddress
+       // $r.boot_config.boot_device.disk_address
+       // $r.resources.boot_config.boot_device.disk_address
+       // $r.status.resources.boot_config.boot_device.disk_address
+       // {});
+
+    def boot_disk_match($disk; $boot):
+      if (($boot | type) != "object") or (($boot | length) == 0) then false
+      else
+        (address_bus($boot)) as $boot_bus
+        | (address_unit($boot; -1)) as $boot_unit
+        | (($disk.controller.type // "" | tostring | ascii_downcase) == $boot_bus
+           and (($disk.controller.unit // -2) == $boot_unit))
+      end;
+
     def nic_items($r):
       ($r.nics
        // $r.nic_list
@@ -521,9 +554,11 @@ n2k_nutanix_inventory_from_raw() {
 
     def normalize_disk($d; $idx):
       ($d.diskAddress // $d.disk_address // $d.device_properties.disk_address // $d.deviceProperties.diskAddress // {}) as $a
+      | first_nonempty([$d.name, $d.label, $a.disk_label]) as $disk_label
       | {
           disk_id: disk_id($d; $idx),
-          label: first_nonempty([$d.name, $d.label, $a.disk_label, ("Disk " + (($idx + 1) | tostring))]),
+          label: $disk_label,
+          source_ordinal: $idx,
           device_key: first_nonempty([$d.extId, $d.ext_id, $d.uuid, $d.device_uuid, $d.vdiskUuid, $d.vdisk_uuid, $a.device_uuid, $a.vmdisk_uuid, ($idx | tostring)]),
           controller: {
             type: first_nonempty([$a.busType, $a.bus_type, $a.adapter_type, $a.device_bus, $d.busType, $d.bus_type, "scsi"]),
@@ -540,6 +575,24 @@ n2k_nutanix_inventory_from_raw() {
           size_bytes: disk_size($d)
         };
 
+    def ordered_disks($r):
+      (boot_disk_address($r)) as $boot_addr
+      | (disk_items($r) | to_entries | map(normalize_disk(.value; .key)))
+      | sort_by([
+          (if boot_disk_match(.; $boot_addr) then 0 else 1 end),
+          controller_rank(.controller.type // ""),
+          (.controller.bus // 0),
+          (.controller.unit // 0),
+          (.source_ordinal // 0)
+        ])
+      | to_entries
+      | map(
+          . as $entry
+          | .value
+          | .label = (if ((.label // "") | tostring | length) > 0 then .label else ("Disk " + (($entry.key + 1) | tostring)) end)
+          | .role = (if $entry.key == 0 then "root" else "data" end)
+        );
+
     def normalize_nic($n; $idx):
       {
         key: ($idx | tostring),
@@ -575,7 +628,7 @@ n2k_nutanix_inventory_from_raw() {
           guestId: first_nonempty([$r.guestCustomization.guestOs, $r.guest_customization.guest_os, $r.guestTools.guestOs, $r.guest_tools.guest_os]),
           guestFamily: first_nonempty([$r.guestFamily, $r.guest_family])
         },
-        disks: (disk_items($r) | to_entries | map(normalize_disk(.value; .key)))
+        disks: ordered_disks($r)
       }
   '
 }
diff --git a/lib/n2k/target_cloud.sh b/lib/n2k/target_cloud.sh
@@ -246,6 +246,8 @@ n2k_cloud_target_source_deploy_params_json() {
     | {}
       + (if $cpu > 0 then {"details[0].cpuNumber": ($cpu | floor | tostring)} else {} end)
       + {"details[0].cpuSpeed": $cpu_speed}
+      + {"details[0].io.policy": "io_uring"}
+      + {"details[0].iothreads": "true"}
       + (if $memory_mb > 0 then {"details[0].memory": ($memory_mb | floor | tostring)} else {} end)
       + (if $root_size_gib > 0 then {"details[0].rootdisksize": ($root_size_gib | tostring)} else {} end)
       + (if ($source_mac | length) > 0 then {macaddress:$source_mac} else {} end)
diff --git a/lib/v2k/target_cloud.sh b/lib/v2k/target_cloud.sh
@@ -228,6 +228,8 @@ v2k_cloud_target_source_deploy_params_json() {
     | {}
       + (if $cpu > 0 then {"details[0].cpuNumber": ($cpu | floor | tostring)} else {} end)
       + {"details[0].cpuSpeed": $cpu_speed}
+      + {"details[0].io.policy": "io_uring"}
+      + {"details[0].iothreads": "true"}
       + (if $memory_mb > 0 then {"details[0].memory": ($memory_mb | floor | tostring)} else {} end)
       + (if $root_size_gib > 0 then {"details[0].rootdisksize": ($root_size_gib | tostring)} else {} end)
       + (if ($root_controller | length) > 0 then {"details[0].rootDiskController": $root_controller} else {} end)
diff --git a/lib/v2k/vmware_govc.sh b/lib/v2k/vmware_govc.sh
@@ -394,11 +394,28 @@ v2k_vmware_inventory_json() {
           })
       );
 
+    def controller_rank($type; $ctrl_label):
+      (($ctrl_label // "") | tostring | ascii_downcase) as $lbl
+      | (($type // "") | tostring) as $typ
+      | if ($lbl | test("^scsi controller")) or ($typ | test("SCSIController$|LsiLogic|ParaVirtualSCSI|BusLogic")) then 0
+        elif ($lbl | test("^sata controller")) or ($typ | test("SATA"; "i")) then 1
+        elif ($lbl | test("^nvme controller")) or ($typ | test("NVME|NVMe|Nvme")) then 2
+        else 9 end;
+
+    def boot_disk_device_keys:
+      (BOOT.bootOrder // BOOT.boot_order // [])
+      | map((.deviceKey // .device_key // .key // empty) | tostring);
+
+    def boot_rank($disk; $boot_keys):
+      ([$boot_keys | to_entries[]? | select(.value == (($disk.device_key // "") | tostring)) | .key] | .[0] // 9999);
+
     def disks($ctls):
       (DEVICES
-        | map(select(.type=="VirtualDisk"))
+        | to_entries
+        | map(select(.value.type=="VirtualDisk"))
         | map(
-            . as $d
+            . as $entry
+            | .value as $d
             | ($ctls | map(select(.key==$d.controllerKey)) | .[0]) as $c
             | {
                 disk_id: (
@@ -413,6 +430,7 @@ v2k_vmware_inventory_json() {
                   end
                 ),
                 label: ($d.deviceInfo?.label // $d.label // "VirtualDisk"),
+                source_ordinal: $entry.key,
                 device_key: ($d.key|tostring),
                 controller: (
                   if $c!=null then
@@ -425,6 +443,16 @@ v2k_vmware_inventory_json() {
                 size_bytes: ($d.capacityInBytes // 0)
               }
           )
+        | boot_disk_device_keys as $boot_keys
+        | sort_by([
+            boot_rank(.; $boot_keys),
+            controller_rank(.controller.type // ""; .controller.label // ""),
+            (.controller.bus // 0),
+            (.controller.unit // 0),
+            (.source_ordinal // 0)
+          ])
+        | to_entries
+        | map(.value + {role:(if .key == 0 then "root" else "data" end)})
       );
 
     {
diff --git a/tests/n2k_cloud_target_runtime_smoke.sh b/tests/n2k_cloud_target_runtime_smoke.sh
@@ -62,6 +62,8 @@ params="$(n2k_cloud_target_source_deploy_params_json "${manifest}")"
 jq -e '
   .["details[0].cpuNumber"] == "2"
   and .["details[0].cpuSpeed"] == "1000"
+  and .["details[0].io.policy"] == "io_uring"
+  and .["details[0].iothreads"] == "true"
   and .["details[0].memory"] == "4096"
   and .["details[0].rootdisksize"] == "30"
   and .["details[0].rootDiskController"] == "scsi"
diff --git a/tests/n2k_inventory_disk_order_smoke.sh b/tests/n2k_inventory_disk_order_smoke.sh
@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+require_cmd() {
+  command -v "$1" >/dev/null 2>&1 || {
+    echo "[ERR] Missing command: $1" >&2
+    exit 2
+  }
+}
+
+require_cmd jq
+
+# shellcheck source=/dev/null
+source "${ROOT_DIR}/lib/n2k/nutanix_api.sh"
+
+inventory_fallback="$(n2k_nutanix_inventory_from_raw '{
+  "name": "out-of-order",
+  "powerState": "OFF",
+  "disks": [
+    {
+      "extId": "unit-1",
+      "sizeBytes": 1073741824000,
+      "diskAddress": {"adapter_type": "SCSI", "device_index": 1}
+    },
+    {
+      "extId": "unit-0",
+      "sizeBytes": 536870912000,
+      "diskAddress": {"adapter_type": "SCSI", "device_index": 0}
+    }
+  ]
+}' "out-of-order")"
+
+jq -e '
+  .disks[0].disk_id == "unit-0"
+  and .disks[0].controller.unit == 0
+  and .disks[0].label == "Disk 1"
+  and .disks[0].role == "root"
+  and .disks[1].disk_id == "unit-1"
+  and .disks[1].controller.unit == 1
+  and .disks[1].label == "Disk 2"
+  and .disks[1].role == "data"
+' <<<"${inventory_fallback}" >/dev/null || {
+  echo "[ERR] Nutanix disk inventory was not ordered by controller unit fallback" >&2
+  printf '%s\n' "${inventory_fallback}" >&2
+  exit 1
+}
+
+inventory_boot="$(n2k_nutanix_inventory_from_raw '{
+  "name": "boot-address",
+  "powerState": "OFF",
+  "bootConfig": {
+    "bootDevice": {
+      "diskAddress": {"busType": "SCSI", "index": 1}
+    }
+  },
+  "disks": [
+    {
+      "extId": "unit-0",
+      "name": "Data disk",
+      "sizeBytes": 536870912000,
+      "diskAddress": {"busType": "SCSI", "index": 0}
+    },
+    {
+      "extId": "unit-1",
+      "name": "Boot disk",
+      "sizeBytes": 1073741824000,
+      "diskAddress": {"busType": "SCSI", "index": 1}
+    }
+  ]
+}' "boot-address")"
+
+jq -e '
+  .disks[0].disk_id == "unit-1"
+  and .disks[0].label == "Boot disk"
+  and .disks[0].role == "root"
+  and .disks[1].disk_id == "unit-0"
+  and .disks[1].label == "Data disk"
+  and .disks[1].role == "data"
+' <<<"${inventory_boot}" >/dev/null || {
+  echo "[ERR] Nutanix explicit boot disk address did not take precedence" >&2
+  printf '%s\n' "${inventory_boot}" >&2
+  exit 1
+}
+
+echo "[OK] n2k Nutanix inventory disk ordering passed"
diff --git a/tests/v2k_compat_installer_runtime_smoke.sh b/tests/v2k_compat_installer_runtime_smoke.sh
@@ -295,6 +295,8 @@ EOF
   jq -e '
     .["details[0].cpuNumber"] == "2"
     and .["details[0].cpuSpeed"] == "1000"
+    and .["details[0].io.policy"] == "io_uring"
+    and .["details[0].iothreads"] == "true"
     and .["details[0].memory"] == "4096"
     and .["details[0].rootdisksize"] == "30"
     and .["details[0].rootDiskController"] == "scsi"
diff --git a/tests/v2k_inventory_disk_order_smoke.sh b/tests/v2k_inventory_disk_order_smoke.sh
