Apple OS updates: Only update new macOS hosts below the minimum version & better error messages

[noahtalerman]

Goal

User story
As an IT admin enforcing OS updates on my macOS hosts,
I want to update macOS hosts when they enroll to Fleet only if they're below my minimum version
so that end users can onboard faster if they're already on or above the minimum version.

Changes

Product

• macOS OS updates changes:

  • Minimum version set: Only update new hosts to the latest if they’re below the minimum version
    • Fleet updates host to the latest supported version for that host.
      • If there's no version supported for the host, don't require update
    • This will happen only if "Update new hosts to latest" checkbox is selected.
  • No minimum version set: Update all new hosts to latest

• UI changes:

  • For all Apple platforms (macOS, iOS, and iPadOS) show the following error messges:

    • If the minimum version isn't supported by Apple:
    • 
    • If the deadline isn't a real date:
    • 

  • On Controls > OS updates Target macOS section: update the tooltip for "Update new hosts to latest" to "During automated enrollment (ADE), hosts below the minimum version are updated to the latest version. If a minimum version isn't set, all hosts are updated to the latest version."

    • 

• CLI (fleetctl) usage changes: Expose the same errors specified under "UI changes" when running fleetctl apply and fleetctl gitops.

• YAML changes: No changes

• REST API changes: Expose the same errors specified under "UI changes" in the PATCH /config and the PATCH /teams/:id API endpoints.

• Fleet's agent (fleetd) changes: No changes

• Fleet server configuration changes: No changes

• Exposed, public API endpoint changes: Customers using OS updates will have to expose outbound traffic from their Fleet instance to this Apple resource: https://gdmf.apple.com/v2/pmv

• fleetdm.com changes: No changes

• GitOps mode UI changes: No changes

• GitOps generation changes: No changes

• Activity changes: No changes

• Permissions changes: No changes

• Changes to paid features or tiers: OS updates are Fleet Premium only

• My device and fleetdm.com/better changes: No changes

• Usage statistics: No changes

• Other reference documentation changes: No changes

• First draft of test plan added

• Once shipped, requester has been notified

• Once shipped, dogfooding issue has been filed

Engineering

• Test plan is finalized
• Contributor API changes: No changes
• Feature guide changes: [Guide] Apple OS updates: Only update new macOS hosts below the minimum version & better error messages #40826
• This is a premium only feature: Yes

ℹ️  Please read this issue carefully and understand it. Pay special attention to UI wireframes, especially "dev notes".

QA

Risk assessment

• Requires testing in a hosted environment: No
• Requires load testing: No
• Risk level: Low

Test plan

Make sure to go through the list and consider all events that might be related to this story, so we catch edge cases earlier.

• Engineering test: Does Apple only support versions listed here. What happens if you specify an unsupported version in a software update declaration?
• Apple lists available OS versions here. If I set a version that's not available, I should see the error in the UI and GitOps.
• Don't set a minimum macOS version in the UI, check the "update new hosts" checkbox. Enroll a mac running a version below the latest. Make sure it gets updated during enrollment
• Don't set a minimum macOS version in the UI, check the "update new hosts" checkbox. Enroll a mac running a version the latest macOS. Make sure it doesn't get prompted to update during enrollment
• Set a minimum macOS version in the UI and uncheck the "update new hosts" checkbox. Enroll a mac running a version of macOS lower than the minimum. Make sure it does not get updated during enrollment. Make sure it gets prompted after enrollment
• Set a minimum macOS version in the UI that is lower than the current latest version, check the "update new hosts" checkbox. Enroll a mac running a version of macOS lower than the minimum. Make sure it gets updated to the latest version of macOS during enrollment
• Set a minimum macOS version in the UI that is lower than the current latest version, check the "update new hosts" checkbox. Enroll a mac running a version of macOS equal to or higher than the minimum. Make sure it does not get updated to the latest version of macOS during enrollment
• Set a minimum version of iOS and iPadOS in the UI and uncheck the "update new hosts" checkbox on the macOS update settings tab. Enroll iOS and iPadOS devices running a version lower than the minimum. Verify they get updated as part of the enrollment
• Set the minimum iOS version to 26.3 or whatever the latest version is. Enroll an iPod Touch(or ask someone else to). Ensure it is able to enroll as long as it updates to the latest support version of iOS
• Set a non-existent(doesn't show up in gdmf list) version of macOS, iOS and iPadOS. Make sure you get the error specified
• Set a bad date for iOS, iPadOS and macOS, make sure you get the error specified

Testing notes

Additional notes to validation

• “latest supported for that host” vs “latest macOS in general”.

• “no supported version exists - don’t require update”

• Watch for compliance loops around enrollment-time update, post-enrollment prompts

• No minimum macOS; “update new hosts” checked; enroll Mac with no supported update available for model. Expected behavior: No update required, no error shown

• Minimum macOS set above host’s maximum supported; “update new hosts” unchecked; enroll Mac at its maximum supported OS. Expected behavior: No enrollment-time update, no post-enrollment prompt

Confirmation

1. Engineer: Added comment to user story confirming successful completion of test plan.
2. QA: Added comment to user story confirming successful completion of test plan.