Merge pull request #5458 from robhoes/feature/update-guidance-improve…

…ment

Merge feature/update-guidance-improvement branch to master

ocaml/idl/datamodel.ml

@@ -7966,6 +7966,7 @@ let emergency_calls =
   ; (Datamodel_host.t, Datamodel_host.emergency_reset_server_certificate)
   ; (Datamodel_host.t, Datamodel_host.emergency_disable_tls_verification)
   ; (Datamodel_host.t, Datamodel_host.emergency_reenable_tls_verification)
+  ; (Datamodel_host.t, Datamodel_host.emergency_clear_mandatory_guidance)
   ]
 
 (** Whitelist of calls that will not get forwarded from the slave to master via the unix domain socket *)

ocaml/idl/datamodel_common.ml

@@ -10,7 +10,7 @@ open Datamodel_roles
               to leave a gap for potential hotfixes needing to increment the schema version.*)
 let schema_major_vsn = 5
 
-let schema_minor_vsn = 774
+let schema_minor_vsn = 775
 
 (* Historical schema versions just in case this is useful later *)
 let rio_schema_major_vsn = 5
@@ -134,6 +134,10 @@ let yangtze_release_schema_major_vsn = 5
 
 let yangtze_release_schema_minor_vsn = 602
 
+let nile_release_schema_major_vsn = 5
+
+let nile_release_schema_minor_vsn = 775
+
 (* List of tech-preview releases. Fields in these releases are not guaranteed to be retained when
  * upgrading to a full release. *)
 let tech_preview_releases =
@@ -151,7 +155,7 @@ let tech_preview_releases =
  * but there are exceptions: please consult the XenCenter maintainers if in doubt. *)
 let api_version_major = 2L
 
-let api_version_minor = 20L
+let api_version_minor = 21L
 
 let api_version_string =
   Printf.sprintf "%Ld.%Ld" api_version_major api_version_minor
@@ -316,6 +320,14 @@ let update_guidances =
         , "Indicates the updated host should reboot as soon as possible since \
            one or more livepatch(es) failed to be applied."
         )
+      ; ( "reboot_host_on_kernel_livepatch_failure"
+        , "Indicates the updated host should reboot as soon as possible since \
+           one or more kernel livepatch(es) failed to be applied."
+        )
+      ; ( "reboot_host_on_xen_livepatch_failure"
+        , "Indicates the updated host should reboot as soon as possible since \
+           one or more xen livepatch(es) failed to be applied."
+        )
       ; ( "restart_toolstack"
         , "Indicates the Toolstack running on the updated host should restart \
            as soon as possible"
@@ -324,6 +336,7 @@ let update_guidances =
         , "Indicates the device model of a running VM should restart as soon \
            as possible"
         )
+      ; ("restart_vm", "Indicates the VM should restart as soon as possible")
       ]
     )
 

ocaml/idl/datamodel_errors.ml

@@ -1942,10 +1942,6 @@ let _ =
     ~doc:"The repository domain allowlist has some invalid domains." () ;
   error Api_errors.apply_livepatch_failed ["livepatch"]
     ~doc:"Failed to apply a livepatch." () ;
-  error Api_errors.updates_require_recommended_guidance ["recommended_guidance"]
-    ~doc:"Requires recommended guidance after applying updates." () ;
-  error Api_errors.update_guidance_changed ["guidance"]
-    ~doc:"Guidance for the update has changed" () ;
 
   error Api_errors.vtpm_max_amount_reached ["amount"]
     ~doc:"The VM cannot be associated with more VTPMs." () ;
@@ -1963,6 +1959,15 @@ let _ =
   error Api_errors.no_repositories_configured []
     ~doc:"No update repositories have been configured." () ;
 
+  error Api_errors.host_pending_mandatory_guidances_not_empty ["host"]
+    ~doc:
+      "Operation could not be performed on the host because there is pending \
+       mandatory update guidance on it."
+    () ;
+
+  error Api_errors.host_evacuation_is_required ["host"]
+    ~doc:"Host evacuation is required before applying updates." () ;
+
   message
     (fst Api_messages.ha_pool_overcommitted)
     ~doc:

ocaml/idl/datamodel_host.ml

@@ -1263,6 +1263,7 @@ let operations =
       ; ("vm_resume", "This host is resuming a VM")
       ; ("vm_migrate", "This host is the migration target of a VM")
       ; ("apply_updates", "Indicates this host is being updated")
+      ; ("enable", "Indicates this host is in the process of enabling")
       ]
     )
 
@@ -1809,6 +1810,12 @@ let apply_recommended_guidances =
       ]
     ~allowed_roles:_R_POOL_OP ()
 
+let emergency_clear_mandatory_guidance =
+  call ~flags:[`Session] ~name:"emergency_clear_mandatory_guidance"
+    ~lifecycle:[] ~in_oss_since:None ~params:[]
+    ~doc:"Clear the pending mandatory guidance on this host"
+    ~allowed_roles:_R_LOCAL_ROOT_ONLY ()
+
 let latest_synced_updates_applied_state =
   Enum
     ( "latest_synced_updates_applied_state"
@@ -1963,6 +1970,7 @@ let t =
       ; copy_primary_host_certs
       ; set_https_only
       ; apply_recommended_guidances
+      ; emergency_clear_mandatory_guidance
       ]
     ~contents:
       ([
@@ -2173,7 +2181,8 @@ let t =
         ; field ~qualifier:DynamicRO ~in_product_since:"1.303.0"
             ~ty:(Set update_guidances) "pending_guidances"
             ~default_value:(Some (VSet []))
-            "The set of pending guidances after applying updates"
+            "The set of pending mandatory guidances after applying updates, \
+             which must be applied, as otherwise there may be e.g. VM failures"
         ; field ~qualifier:DynamicRO ~in_product_since:"1.313.0" ~ty:Bool
             "tls_verification_enabled" ~default_value:(Some (VBool false))
             "True if this host has TLS verifcation enabled"
@@ -2199,6 +2208,21 @@ let t =
             "numa_affinity_policy"
             ~default_value:(Some (VEnum "default_policy"))
             "NUMA-aware VM memory and vCPU placement policy"
+        ; field ~qualifier:DynamicRO ~lifecycle:[] ~ty:(Set update_guidances)
+            "pending_guidances_recommended" ~default_value:(Some (VSet []))
+            "The set of pending recommended guidances after applying updates, \
+             which most users should follow to make the updates effective, but \
+             if not followed, will not cause a failure"
+        ; field ~qualifier:DynamicRO ~lifecycle:[] ~ty:(Set update_guidances)
+            "pending_guidances_full" ~default_value:(Some (VSet []))
+            "The set of pending full guidances after applying updates, which a \
+             user should follow to make some updates, e.g. specific hardware \
+             drivers or CPU features, fully effective, but the 'average user' \
+             doesn't need to"
+        ; field ~qualifier:DynamicRO ~lifecycle:[] ~ty:String
+            ~default_value:(Some (VString "")) "last_update_hash"
+            "The SHA256 checksum of updateinfo of the most recently applied \
+             update on the host"
         ]
       )
     ()

ocaml/idl/datamodel_lifecycle.ml

@@ -39,6 +39,12 @@ let prototyped_of_field = function
       Some "22.26.0"
   | "VTPM", "persistence_backend" ->
       Some "22.26.0"
+  | "host", "last_update_hash" ->
+      Some "24.10.0"
+  | "host", "pending_guidances_full" ->
+      Some "24.10.0"
+  | "host", "pending_guidances_recommended" ->
+      Some "24.10.0"
   | "host", "numa_affinity_policy" ->
       Some "24.0.0"
   | "host", "latest_synced_updates_applied" ->
@@ -49,6 +55,10 @@ let prototyped_of_field = function
       Some "22.27.0"
   | "host", "last_software_update" ->
       Some "22.20.0"
+  | "VM", "pending_guidances_full" ->
+      Some "24.10.0"
+  | "VM", "pending_guidances_recommended" ->
+      Some "24.10.0"
   | "VM", "recommended_guidances" ->
       Some "23.18.0"
   | "VM", "actions__after_softreboot" ->
@@ -109,6 +119,8 @@ let prototyped_of_message = function
       Some "22.26.0"
   | "VTPM", "create" ->
       Some "22.26.0"
+  | "host", "emergency_clear_mandatory_guidance" ->
+      Some "24.10.0"
   | "host", "apply_recommended_guidances" ->
       Some "23.18.0"
   | "host", "set_https_only" ->

ocaml/idl/datamodel_types.ml

@@ -97,6 +97,10 @@ let rel_stockholm = "stockholm"
 
 let rel_stockholm_psr = "stockholm_psr"
 
+let rel_nile_preview = "nile-preview"
+
+let rel_nile = "nile"
+
 type api_release = {
     code_name: string option
   ; version_major: int
@@ -335,12 +339,19 @@ let release_order_full =
     ; release_date= Some "November 2020"
     }
   ; {
-      code_name= Some "nile-preview"
+      code_name= Some rel_nile_preview
     ; version_major= 2
     ; version_minor= 20
     ; branding= "XenServer 8 Preview"
     ; release_date= Some "August 2023"
     }
+  ; {
+      code_name= Some rel_nile
+    ; version_major= 2
+    ; version_minor= 21
+    ; branding= "XenServer 8"
+    ; release_date= None
+    }
   ]
 (* When you add a new release, use the version number of the latest release, "Unreleased"
    for the branding, and Some "" for the release date, until the actual values are finalised. *)

ocaml/idl/datamodel_vm.ml

@@ -1687,8 +1687,9 @@ let set_NVRAM_EFI_variables =
     ~hide_from_docs:true ~allowed_roles:_R_LOCAL_ROOT_ONLY ()
 
 let restart_device_models =
-  call ~flags:[`Session] ~name:"restart_device_models" ~lifecycle:[]
+  call ~name:"restart_device_models" ~lifecycle:[]
     ~params:[(Ref _vm, "self", "The VM")]
+    ~doc:"Restart device models of the VM"
     ~errs:
       [
         Api_errors.vm_bad_power_state
@@ -2155,12 +2156,24 @@ let t =
         ; field ~qualifier:DynamicRO ~in_product_since:"1.303.0"
             ~ty:(Set update_guidances) "pending_guidances"
             ~default_value:(Some (VSet []))
-            "The set of pending guidances after applying updates"
+            "The set of pending mandatory guidances after applying updates, \
+             which must be applied, as otherwise there may be e.g. VM failures"
         ; field ~qualifier:DynamicRO ~internal_only:true
             ~lifecycle:[(Prototyped, "23.18.0", ""); (Removed, "23.24.0", "")]
             ~ty:(Set update_guidances) "recommended_guidances"
             ~default_value:(Some (VSet []))
             "The set of recommended guidances after applying updates"
+        ; field ~qualifier:DynamicRO ~lifecycle:[] ~ty:(Set update_guidances)
+            "pending_guidances_recommended" ~default_value:(Some (VSet []))
+            "The set of pending recommended guidances after applying updates, \
+             which most users should follow to make the updates effective, but \
+             if not followed, will not cause a failure"
+        ; field ~qualifier:DynamicRO ~lifecycle:[] ~ty:(Set update_guidances)
+            "pending_guidances_full" ~default_value:(Some (VSet []))
+            "The set of pending full guidances after applying updates, which a \
+             user should follow to make some updates, e.g. specific hardware \
+             drivers or CPU features, fully effective, but the 'average user' \
+             doesn't need to"
         ]
       )
     ()

ocaml/idl/schematest.ml

@@ -3,7 +3,7 @@ let hash x = Digest.string x |> Digest.to_hex
 (* BEWARE: if this changes, check that schema has been bumped accordingly in
    ocaml/idl/datamodel_common.ml, usually schema_minor_vsn *)
 
-let last_known_schema_hash = "a99342e7a24557948df221c8da46ae71"
+let last_known_schema_hash = "186131ad48f40dff30246e8e0c0dbf0a"
 
 let current_schema_hash : string =
   let open Datamodel_types in

ocaml/tests/common/test_common.ml

@@ -210,7 +210,9 @@ let make_host2 ~__context ?(ref = Ref.make ()) ?(uuid = make_uuid ())
     ~multipathing:false ~uefi_certificates:"" ~editions:[] ~pending_guidances:[]
     ~tls_verification_enabled ~numa_affinity_policy:`default_policy
     ~last_software_update:(Xapi_host.get_servertime ~__context ~host:ref)
-    ~recommended_guidances:[] ~latest_synced_updates_applied:`unknown ;
+    ~recommended_guidances:[] ~latest_synced_updates_applied:`unknown
+    ~pending_guidances_recommended:[] ~pending_guidances_full:[]
+    ~last_update_hash:"" ;
   ref
 
 let make_pif ~__context ~network ~host ?(device = "eth0")