Make doc comments on InstanceUpdate body match InstanceCreate (#9055)

Followup to #9046

Author: david-crespo

nexus/types/src/external_api/params.rs

@@ -1293,18 +1293,27 @@ pub struct InstanceCreate {
 /// Parameters of an `Instance` that can be reconfigured after creation.
 #[derive(Clone, Debug, Deserialize, Serialize, JsonSchema)]
 pub struct InstanceUpdate {
-    /// The number of CPUs to assign to this instance.
+    /// The number of vCPUs to be allocated to the instance
     pub ncpus: InstanceCpuCount,
 
-    /// The amount of memory to assign to this instance.
+    /// The amount of RAM (in bytes) to be allocated to the instance
     pub memory: ByteCount,
 
-    /// Name or ID of the disk the instance should be instructed to boot from.
+    /// The disk the instance is configured to boot from.
+    ///
+    /// Setting 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. The boot disk counts against the disk
+    /// attachment limit.
     ///
-    /// A null value unsets the boot disk.
+    /// 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.
     pub boot_disk: Nullable<NameOrId>,
 
-    /// Sets the auto-restart policy for this instance.
+    /// The auto-restart policy for this instance.
     ///
     /// This policy determines whether the instance should be automatically
     /// restarted by the control plane on failure. If this is `null`, any
@@ -1321,7 +1330,9 @@ pub struct InstanceUpdate {
     pub auto_restart_policy: Nullable<InstanceAutoRestartPolicy>,
 
     /// The CPU platform to be used for this instance. If this is `null`, the
-    /// instance requires no particular CPU platform.
+    /// instance requires no particular CPU platform; when it is started the
+    /// instance will have the most general CPU platform supported by the sled
+    /// it is initially placed on.
     pub cpu_platform: Nullable<InstanceCpuPlatform>,
 }
 

openapi/nexus.json

@@ -20833,7 +20833,7 @@
         "properties": {
           "auto_restart_policy": {
             "nullable": true,
-            "description": "Sets the auto-restart policy for this instance.\n\nThis policy determines whether the instance should be automatically restarted by the control plane on failure. If this is `null`, any explicitly configured auto-restart policy will be unset, and the control plane will select the default policy when determining whether the instance can be automatically restarted.\n\nCurrently, the global default auto-restart policy is \"best-effort\", so instances with `null` auto-restart policies will be automatically restarted. However, in the future, the default policy may be configurable through other mechanisms, such as on a per-project basis. In that case, any configured default policy will be used if this is `null`.",
+            "description": "The auto-restart policy for this instance.\n\nThis policy determines whether the instance should be automatically restarted by the control plane on failure. If this is `null`, any explicitly configured auto-restart policy will be unset, and the control plane will select the default policy when determining whether the instance can be automatically restarted.\n\nCurrently, the global default auto-restart policy is \"best-effort\", so instances with `null` auto-restart policies will be automatically restarted. However, in the future, the default policy may be configurable through other mechanisms, such as on a per-project basis. In that case, any configured default policy will be used if this is `null`.",
             "allOf": [
               {
                 "$ref": "#/components/schemas/InstanceAutoRestartPolicy"
@@ -20842,7 +20842,7 @@
           },
           "boot_disk": {
             "nullable": true,
-            "description": "Name or ID of the disk the instance should be instructed to boot from.\n\nA null value unsets the boot disk.",
+            "description": "The disk the instance is configured to boot from.\n\nSetting 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. The boot disk counts against the disk attachment limit.\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.",
             "allOf": [
               {
                 "$ref": "#/components/schemas/NameOrId"
@@ -20851,23 +20851,23 @@
           },
           "cpu_platform": {
             "nullable": true,
-            "description": "The CPU platform to be used for this instance. If this is `null`, the instance requires no particular CPU platform.",
+            "description": "The CPU platform to be used for this instance. If this is `null`, the instance requires no particular CPU platform; when it is started the instance will have the most general CPU platform supported by the sled it is initially placed on.",
             "allOf": [
               {
                 "$ref": "#/components/schemas/InstanceCpuPlatform"
               }
             ]
           },
           "memory": {
-            "description": "The amount of memory to assign to this instance.",
+            "description": "The amount of RAM (in bytes) to be allocated to the instance",
             "allOf": [
               {
                 "$ref": "#/components/schemas/ByteCount"
               }
             ]
           },
           "ncpus": {
-            "description": "The number of CPUs to assign to this instance.",
+            "description": "The number of vCPUs to be allocated to the instance",
             "allOf": [
               {
                 "$ref": "#/components/schemas/InstanceCpuCount"