From 7ea6edd85743171efef4b807e516c31991aca72c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= <joerg@thalheim.io>
Date: Tue, 24 Dec 2024 14:45:19 +0100
Subject: [PATCH] zfs-with-vdevs: add an example for using absolute device
 paths

This is the only way to assign devices rather than fixed gpt partitions.
Without reading the code it's not very obvious how disko actually
assigns devices to zpools.
---
 example/zfs-with-vdevs.nix |  9 ++++++---
 lib/types/zpool.nix        | 38 ++++++++++++++++++++++++++++++++++++++
 tests/zfs-with-vdevs.nix   |  4 ++--
 3 files changed, 46 insertions(+), 5 deletions(-)

diff --git a/example/zfs-with-vdevs.nix b/example/zfs-with-vdevs.nix
index 985e082..effe53e 100644
--- a/example/zfs-with-vdevs.nix
+++ b/example/zfs-with-vdevs.nix
@@ -244,11 +244,14 @@
             type = "topology";
             vdev = [
               {
-                mode = "mirror";
-                members = [ "data1" "data2" ];
+                # This syntax expects a disk called 'data3' with a gpt partition called 'zfs'.
+                members = [ "data1" ];
+                # It's also possible to use the full path of the device or partition
+                # members = [ "/dev/disk/by-id/wwn-0x5000c500af8b2a14" ];
               }
               {
-                members = [ "data3" ];
+                mode = "mirror";
+                members = [ "data2" "data3" ];
               }
             ];
             spare = [ "spare" ];
diff --git a/lib/types/zpool.nix b/lib/types/zpool.nix
index 9e0d5b2..8034048 100644
--- a/lib/types/zpool.nix
+++ b/lib/types/zpool.nix
@@ -25,6 +25,44 @@ in
     };
     mode = lib.mkOption {
       default = "";
+      example = {
+        mode = {
+          topology = {
+            type = "topology";
+            vdev = [
+              {
+                # Members can be either specified by a full path or by a disk name
+                # This is example uses the full path
+                members = [ "/dev/disk/by-id/wwn-0x5000c500af8b2a14" ];
+              }
+            ];
+            log = [
+              {
+                # Example using gpt partition labels
+                # This expects an disk called `ssd` with a gpt partition called `zfs`
+                #   disko.devices.disk.ssd = {
+                #    type = "disk";
+                #    device = "/dev/nvme0n1";
+                #    content = {
+                #      type = "gpt";
+                #      partitions = {
+                #        zfs = {
+                #          size = "100%";
+                #          content = {
+                #            type = "zfs";
+                #            # use your own pool name here
+                #            pool = "zroot";
+                #          };
+                #        };
+                #      };
+                #    };
+                #  };
+                members = [ "ssd" ];
+              }
+            ];
+          };
+        };
+      };
       type = (lib.types.oneOf [
         (lib.types.enum modeOptions)
         (lib.types.attrsOf (diskoLib.subType {
diff --git a/tests/zfs-with-vdevs.nix b/tests/zfs-with-vdevs.nix
index 704a173..6b9e2d5 100644
--- a/tests/zfs-with-vdevs.nix
+++ b/tests/zfs-with-vdevs.nix
@@ -57,9 +57,9 @@ diskoLib.testLib.makeDiskoTest {
             vdev = ""
     actual.sort()
     expected=sorted([
-      'zroot /dev/disk/by-partlabel/disk-data3-zfs',
-      'zroot mirror /dev/disk/by-partlabel/disk-data1-zfs',
+      'zroot /dev/disk/by-partlabel/disk-data1-zfs',
       'zroot mirror /dev/disk/by-partlabel/disk-data2-zfs',
+      'zroot mirror /dev/disk/by-partlabel/disk-data3-zfs',
       'dedup /dev/disk/by-partlabel/disk-dedup3-zfs',
       'dedup mirror /dev/disk/by-partlabel/disk-dedup1-zfs',
       'dedup mirror /dev/disk/by-partlabel/disk-dedup2-zfs',