Add iOS/iPadOS updates to example GitOps YAML, reference OS update GitOps YAML from OS update enforcement guide (#23320)

#21998

While looking through this I noticed a few other issues:

1. We seem to be inconsistent about what time we pick for OS update
deadlines. For profiles [it's noon local
time](https://github.com/fleetdm/fleet/blob/2e5bf75b6d40d65c5f05b0f58665375dbb71e650/ee/server/service/mdm.go#L1096),
while for Nudge [it appears to be 4am...server time or
UTC](https://github.com/fleetdm/fleet/blob/2e5bf75b6d40d65c5f05b0f58665375dbb71e650/server/fleet/nudge.go#L53-L57)?
#9013 also mentions "noon UTC-8/Pacific Standard Time", which is neither
of the above (and means that, if implemented as spec'd, the deadline
would shift by an hour during DST), while docs prior to this PR
mentioned 4am UTC-8. Maybe we don't care enough to fix the Nudge
behavior since macOS 14 (which no longer requires Nudge) came out over a
year ago, but we should at least agree on desired behavior for DDM and
document that (which is what I've done for iOS/iPad OS since they don't
use Nudge).
2. The [REST API
docs](https://github.com/fleetdm/fleet/blob/2e5bf75b6d40d65c5f05b0f58665375dbb71e650/docs/REST%20API/rest-api.md?plain=1#L1720-L1757)
don't seem to match the description of macOS behavior in the article;
the former indicates that OS updates pop up with increasing frequency
post-deadline, rather than having an impassible dialog. This may be
because behavior changed from Nudge to DDM, but iOS/iPadOS got
copy-pasted from the macOS REST docs and they never used Nudge. My guess
is that we should describe DDM behavior here.

Tagging in @mna as he looks to have implemented DDM OS updates so should
have some context here, and @noahtalerman to confirm desired behavior,
particularly on the deadline side.

---------

Co-authored-by: Rachael Shaw <r@rachael.wtf>

articles/enforce-os-updates.md

@@ -2,9 +2,11 @@
 
 _Available in Fleet Premium_
 
-In Fleet, you can enforce OS updates on your macOS, Windows, iOS, and iPadOS hosts remotely using the Fleet UI, Fleet API, or [Fleet's GitOps workflow](https://github.com/fleetdm/fleet-gitops).
+In Fleet, you can enforce OS updates on your macOS, Windows, iOS, and iPadOS hosts remotely using the Fleet UI, Fleet API, or Fleet's GitOps workflow.
 
-Fleet UI:
+## Turning on enforcement
+
+### Fleet UI
 
 1. Head to the **Controls** > **OS updates** tab.
 
@@ -12,13 +14,27 @@ Fleet UI:
 
 3. For Windows, select **Windows** and set a **Deadline** and **Grace period**.
 
-Fleet API: API documentation is [here](https://fleetdm.com/docs/rest-api/rest-api#modify-team).
+### Fleet API
+
+Use the [modify team endpoint](https://fleetdm.com/docs/rest-api/rest-api#modify-team) to turn on minimum OS version enforcement. The relevant payload keys in the `mdm` object are:
++ `macos_updates`
++ `ios_updates`
++ `ipados_updates`
++ `windows_updates`
+
+### GitOps
+
+OS version enforcement options are declared within the [controls](https://fleetdm.com/docs/configuration/yaml-files#controls) section of a Fleet GitOps YAML file, using the following keys: 
++ [macos_updates](https://fleetdm.com/docs/configuration/yaml-files#macos-updates)
++ [ios_updates](https://fleetdm.com/docs/configuration/yaml-files#ios-updates)
++ [ipados_updates](https://fleetdm.com/docs/configuration/yaml-files#ipados-updates)
++ [windows_updates](https://fleetdm.com/docs/configuration/yaml-files#windows-updates)
 
 ## End user experience
 
 ### macOS
 
-When a minimum version is enforced, the end users see a native macOS notification (DDM) once per day. Users can choose to update ahead of the deadline or schedule it for that night. 24 hours before the deadline, the notification appears hourly and ignores Do Not Disturb. One hour before the deadline, the notification appears every 30 minutes and then every 10 minutes.   
+When a minimum version is enforced, end users see a native macOS notification (DDM) once per day. Users can choose to update ahead of the deadline or schedule it for that night. 24 hours before the deadline, the notification appears hourly and ignores Do Not Disturb. One hour before the deadline, the notification appears every 30 minutes and then every 10 minutes.   
 
 If the host was turned off when the deadline passed, the update will be scheduled an hour after it’s turned on.
 

docs/Configuration/yaml-files.md

@@ -215,8 +215,14 @@ controls:
   windows_enabled_and_configured: true
   enable_disk_encryption: true # Available in Fleet Premium
   macos_updates: # Available in Fleet Premium
-    deadline: "2023-06-13"
-    minimum_version: 13.4.1
+    deadline: "2024-12-31"
+    minimum_version: 15.1
+  ios_updates: # Available in Fleet Premium
+    deadline: "2024-12-31"
+    minimum_version: 18.1
+  ipados_updates: # Available in Fleet Premium
+    deadline: "2024-12-31"
+    minimum_version: 18.1
   windows_updates: # Available in Fleet Premium
     deadline_days: 5
     grace_period_days: 2
@@ -244,24 +250,24 @@ controls:
 
 ### macos_updates
 
-- `deadline` specifies the deadline in the form of `YYYY-MM-DD`. The exact deadline time is at 04:00:00 (UTC-8) (default: `""`).
+- `deadline` specifies the deadline in `YYYY-MM-DD` format. The exact deadline is set to noon local time for hosts on macOS 14 and above, 20:00 UTC for hosts on older macOS versions. (default: `""`).
 - `minimum_version` specifies the minimum required macOS version (default: `""`).
 
-### windows_updates
-
-- `deadline_days` (default: null)
-- `grace_period_days` (default: null)
-
 ### ios_updates
 
-- `deadline` specifies the deadline in the form of `YYYY-MM-DD`. The exact deadline time is at 04:00:00 (UTC-8) (default: `""`).
+- `deadline` specifies the deadline in `YYYY-MM-DD` format; the exact deadline is set to noon local time. (default: `""`).
 - `minimum_version` specifies the minimum required iOS version (default: `""`).
 
 ### ipados_updates
 
-- `deadline` specifies the deadline in the form of `YYYY-MM-DD`. The exact deadline time is at 04:00:00 (UTC-8) (default: `""`).
+- `deadline` specifies the deadline in `YYYY-MM-DD` format; the exact deadline is set to noon local time. (default: `""`).
 - `minimum_version` specifies the minimum required iPadOS version (default: `""`).
 
+### windows_updates
+
+- `deadline_days` specifies the number of days before Windows installs updates (default: `null`)
+- `grace_period_days` specifies the number of days before Windows restarts to install updates (default: `null`)
+
 ### macos_settings and windows_settings
 
 - `macos_settings.custom_settings` is a list of paths to macOS configuration profiles (.mobileconfig) or declaration profiles (.json).