nexus: update InstanceCreate documentation

Updated the documentation for the `InstanceCreate` fields `disks` and
`boot_disk` to better clarify what they are and the implications of
configuring them.

Closes #8089.

Author: sudomateo

nexus/types/src/external_api/params.rs

@@ -1172,23 +1172,30 @@ pub struct InstanceCreate {
     #[serde(default)]
     pub external_ips: Vec<ExternalIpCreate>,
 
-    /// The disks to be created or attached for this instance.
+    /// A list of disks to be attached to the instance.
+    ///
+    /// Disk attachments of type "create" will be created, while those of type
+    /// "attach" must already exist.
+    ///
+    /// The order of this list does not guarantee a boot order for the
+    /// instance. Use the boot_disk attribute to specify a boot disk.
     #[serde(default)]
     pub disks: Vec<InstanceDiskAttachment>,
 
-    /// The disk this instance should boot into. This disk can either be
-    /// attached if it already exists, or created, if it should be a new disk.
+    /// The disk the instance is configured to boot from.
+    ///
+    /// This disk can either be attached if it already exists or created along
+    /// with the instance.
     ///
-    /// It is strongly recommended to either provide a boot disk at instance
-    /// creation, or update the instance after creation to set a boot disk.
+    /// Specifying a boot disk is optional but recommended to ensure predictable
+    /// boot behavior. The boot disk can be set during instance creation or
+    /// later if the instance is stopped.
     ///
-    /// An instance without an explicit boot disk can be booted: the options are
-    /// as managed by UEFI, and as controlled by the guest OS, but with some
-    /// risk.  If this instance later has a disk attached or detached, it is
-    /// possible that boot options can end up reordered, with the intended boot
-    /// disk moved after the EFI shell in boot priority. This may result in an
-    /// instance that only boots to the EFI shell until the desired disk is set
-    /// as an explicit boot disk and the instance rebooted.
+    /// An instance that does not have a boot disk set will use the boot
+    /// options specified in its UEFI settings, which are controlled by both the
+    /// instance's UEFI firmware and the guest operating system. Boot options
+    /// can change as disks are attached and detached, which may result in an
+    /// instance that only boots to the EFI shell until a boot disk is set.
     #[serde(default)]
     pub boot_disk: Option<InstanceDiskAttachment>,
 

openapi/nexus.json

@@ -18765,7 +18765,7 @@
           },
           "boot_disk": {
             "nullable": true,
-            "description": "The disk this instance should boot into. This disk can either be attached if it already exists, or created, if it should be a new disk.\n\nIt is strongly recommended to either provide a boot disk at instance creation, or update the instance after creation to set a boot disk.\n\nAn instance without an explicit boot disk can be booted: the options are as managed by UEFI, and as controlled by the guest OS, but with some risk.  If this instance later has a disk attached or detached, it is possible that boot options can end up reordered, with the intended boot disk moved after the EFI shell in boot priority. This may result in an instance that only boots to the EFI shell until the desired disk is set as an explicit boot disk and the instance rebooted.",
+            "description": "The disk the instance is configured to boot from.\n\nThis disk can either be attached if it already exists or created along with the instance.\n\nSpecifying a boot disk is optional but recommended to ensure predictable boot behavior. The boot disk can be set during instance creation or later if the instance is stopped.\n\nAn instance that does not have a boot disk set will use the boot options specified in its UEFI settings, which are controlled by both the instance's UEFI firmware and the guest operating system. Boot options can change as disks are attached and detached, which may result in an instance that only boots to the EFI shell until a boot disk is set.",
             "default": null,
             "allOf": [
               {
@@ -18777,7 +18777,7 @@
             "type": "string"
           },
           "disks": {
-            "description": "The disks to be created or attached for this instance.",
+            "description": "A list of disks to be attached to the instance.\n\nDisk attachments of type \"create\" will be created, while those of type \"attach\" must already exist.\n\nThe order of this list does not guarantee a boot order for the instance. Use the boot_disk attribute to specify a boot disk.",
             "default": [],
             "type": "array",
             "items": {