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,32 @@ 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.
+    ///
+    /// Each disk can either be attached if it already exists or created along
+    /// with the instance.
+    ///
+    /// The ordering of the disks does not guarantee the boot order for the
+    /// instance. Use the boot_disk attribute to configure the disk the instance
+    /// should boot from.
     #[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.
+    /// This attribute cannot be modified on a running instance so it is
+    /// recommended to configure this attribute during instance creation or when
+    /// it is acceptable to stop the instance for modification.
     ///
-    /// 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 this attribute configured 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 to the instance,
+    /// which may result in an instance that only boots to the EFI shell until
+    /// this attribute is configured to use a desired boot disk.
     #[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\nThis attribute cannot be modified on a running instance so it is recommended to configure this attribute during instance creation or when it is acceptable to stop the instance for modification.\n\nAn instance that does not have this attribute configured 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 to the instance, which may result in an instance that only boots to the EFI shell until this attribute is configured to use a desired boot disk.",
             "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\nEach disk can either be attached if it already exists or created along with the instance.\n\nThe ordering of the disks does not guarantee the boot order for the instance. Use the boot_disk attribute to configure the disk the instance should boot from.",
             "default": [],
             "type": "array",
             "items": {