[api] Improve instance auto_restart_policy docs (#6959)

Currently, the documentation for the `auto_restart_policy` field in the
`params::InstanceCreate` and `params::InstanceUpdate` types doesn't
really explain the meaning of a `null` auto-restart policy. The comment
on the `AutoRestartStatus` type in the instance *view* API does explain
that `null` means "use whatever the default currently is", but this
isn't obvious on the APIs where a user would actually *set* the policy
to `null`.

This was an oversight on my part, and this commit corrects it. Thanks
@david-crespo for noticing!

Fixes #6957

Author: hawkw

common/src/api/external/mod.rs

@@ -1225,13 +1225,16 @@ pub struct InstanceAutoRestartStatus {
     #[serde(rename = "auto_restart_enabled")]
     pub enabled: bool,
 
-    /// The auto-restart policy configured for this instance, or `None` if no
-    /// explicit policy is configured.
+    /// The auto-restart policy configured for this instance, or `null` if no
+    /// explicit policy has been configured.
     ///
-    /// If this is not present, then this instance uses the default auto-restart
-    /// policy, which may or may not allow it to be restarted. The
-    /// `auto_restart_enabled` field indicates whether the instance will be
-    /// automatically restarted.
+    /// This policy determines whether the instance should be automatically
+    /// restarted by the control plane on failure. If this is `null`, the
+    /// control plane will use the default policy when determining whether or
+    /// not to automatically restart this instance, which may or may not allow
+    /// it to be restarted. The value of the `auto_restart_enabled` field
+    /// indicates whether the instance will be auto-restarted, based on its
+    /// current policy or the default if it has no configured policy.
     //
     // Rename this field, as the struct is `#[serde(flatten)]`ed into the
     // `Instance` type, and we would like the field to be prefixed with

nexus/db-model/src/instance.rs

@@ -259,7 +259,9 @@ pub struct InstanceAutoRestart {
     ///
     /// This indicates whether the instance should be automatically restarted by
     /// the control plane on failure. If this is `NULL`, no auto-restart policy
-    /// has been configured for this instance by the user.
+    /// has been configured for this instance by the user. In that case, the
+    /// control plane will use the default policy when determining whether
+    /// this instance can be automatically restarted.
     #[diesel(column_name = auto_restart_policy)]
     #[serde(default)]
     pub policy: Option<InstanceAutoRestartPolicy>,

nexus/types/src/external_api/params.rs

@@ -1137,9 +1137,18 @@ pub struct InstanceCreate {
 
     /// The auto-restart policy for this instance.
     ///
-    /// This indicates whether the instance should be automatically restarted by
-    /// the control plane on failure. If this is `null`, no auto-restart policy
-    /// has been configured for this instance by the user.
+    /// This policy determines whether the instance should be automatically
+    /// restarted by the control plane on failure. If this is `null`, no
+    /// auto-restart policy will be explicitly configured for this instance, and
+    /// the control plane will select the default policy when determining
+    /// whether the instance can be automatically restarted.
+    ///
+    /// Currently, 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`.
     #[serde(default)]
     pub auto_restart_policy: Option<InstanceAutoRestartPolicy>,
 }
@@ -1152,9 +1161,20 @@ pub struct InstanceUpdate {
     /// If not provided, unset the instance's boot disk.
     pub boot_disk: Option<NameOrId>,
 
-    /// The auto-restart policy for this instance.
+    /// Sets 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
+    /// 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.
     ///
-    /// If not provided, unset the instance's auto-restart policy.
+    /// Currently, 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`.
     pub auto_restart_policy: Option<InstanceAutoRestartPolicy>,
 }
 

openapi/nexus-internal.json

@@ -3532,7 +3532,7 @@
           },
           "auto_restart_policy": {
             "nullable": true,
-            "description": "The auto-restart policy configured for this instance, or `None` if no explicit policy is configured.\n\nIf this is not present, then this instance uses the default auto-restart policy, which may or may not allow it to be restarted. The `auto_restart_enabled` field indicates whether the instance will be automatically restarted.",
+            "description": "The auto-restart policy configured for this instance, or `null` if no explicit policy has been configured.\n\nThis policy determines whether the instance should be automatically restarted by the control plane on failure. If this is `null`, the control plane will use the default policy when determining whether or not to automatically restart this instance, which may or may not allow it to be restarted. The value of the `auto_restart_enabled` field indicates whether the instance will be auto-restarted, based on its current policy or the default if it has no configured policy.",
             "allOf": [
               {
                 "$ref": "#/components/schemas/InstanceAutoRestartPolicy"

openapi/nexus.json

@@ -15816,7 +15816,7 @@
           },
           "auto_restart_policy": {
             "nullable": true,
-            "description": "The auto-restart policy configured for this instance, or `None` if no explicit policy is configured.\n\nIf this is not present, then this instance uses the default auto-restart policy, which may or may not allow it to be restarted. The `auto_restart_enabled` field indicates whether the instance will be automatically restarted.",
+            "description": "The auto-restart policy configured for this instance, or `null` if no explicit policy has been configured.\n\nThis policy determines whether the instance should be automatically restarted by the control plane on failure. If this is `null`, the control plane will use the default policy when determining whether or not to automatically restart this instance, which may or may not allow it to be restarted. The value of the `auto_restart_enabled` field indicates whether the instance will be auto-restarted, based on its current policy or the default if it has no configured policy.",
             "allOf": [
               {
                 "$ref": "#/components/schemas/InstanceAutoRestartPolicy"
@@ -15941,7 +15941,7 @@
         "properties": {
           "auto_restart_policy": {
             "nullable": true,
-            "description": "The auto-restart policy for this instance.\n\nThis indicates whether the instance should be automatically restarted by the control plane on failure. If this is `null`, no auto-restart policy has been configured for this instance by the user.",
+            "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`, no auto-restart policy will be explicitly configured for this instance, 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`.",
             "default": null,
             "allOf": [
               {
@@ -16476,7 +16476,7 @@
         "properties": {
           "auto_restart_policy": {
             "nullable": true,
-            "description": "The auto-restart policy for this instance.\n\nIf not provided, unset the instance's auto-restart policy.",
+            "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`.",
             "allOf": [
               {
                 "$ref": "#/components/schemas/InstanceAutoRestartPolicy"