Deploy custom Software Update enforcement declaration (DDM) and Windows profiles

[noahtalerman]

- Revisit changing default to 7pm. UPDATE: Decided not to do this and leave as is (default noon)
- Consider adding a variable like $FLEET_VAR_LATEST_MACOS_VERSION and $FLEET_VAR_LATEST_MACOS_DEADLINE so customers who use a custom profile get the benefit of this: #20500

Goal

User story
As an IT admin,
I want to deploy my custom Software Update enforcement declaration (DDM) profile
so that I customize the enforcement time (Fleet defaults to noon).

Changes

Product

• Changes:
  • Support for macOS, iOS, iPadOS, and Windows.
  • Decouple the current feature flag (enable_custom_os_updates_and_filevault) so that users can update os settings without disrupting filevault settings. Keep enable_custom_os_updates_and_filevault for backwards compatibility.
    • Remove the custom os updates restrictions and allow by default.
    • new: enable_custom_filevault
  • Errors (Apple):
    • User tries to set OS updates settings, but custom DDM profile already exists: Couldn't update OS updates settings. A custom OS updates declaration profile already exists. Remove the custom profile first.
    • User tries to upload custom OS update DDM profile, but Fleet OS update settings already configured: Couldn't add profile. OS updates are already configured. Remove the OS updates settings first.
  • Errors (Windows):
    • User tries to set OS updates settings, but custom Windows XML profile targeting Windows Update CSPs already exists: Couldn't update OS updates settings. A custom OS updates profile already exists. Remove the custom profile first.
    • User tries to upload custom Windows XML profile targeting Windows Update CSPs, but Fleet OS update settings already configured: Couldn't add profile. OS updates are already configured. Remove the OS updates settings first.
• UI changes: No changes
• CLI (fleetctl) usage changes: No changes
• YAML changes: No changes
• REST API changes: No changes
• Fleet's agent (fleetd) changes: No changes
• Fleet server configuration changes: [Server config] Revise MDM configuration options in documentation #44425
• Exposed, public API endpoint changes: No changes
• 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: No changes
• 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: Add an overview of the rules and basic profiles/declarations to https://fleetdm.com/guides/enforce-os-updates
• Database schema migrations: See subtasks
• This is a premium only feature: Yes

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

Risk assessment

• 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.

Core flow

Feature flag decoupling

• Custom OS updates allowed by default:
  • With no feature flags set, user can upload a custom OS update DDM profile (macOS, iOS, iPadOS)
  • With no feature flags set, user can upload a custom OS update SyncML profile (Windows)
  • Custom OS update profiles are no longer gated behind any feature flag
• New enable_custom_filevault flag:
  • With enable_custom_filevault enabled, user can upload a custom FileVault profile
  • With enable_custom_filevault disabled (or unset), user cannot upload a custom FileVault profile
• Backwards compatibility:
  • With enable_custom_os_updates_and_filevault enabled, both custom OS update profiles and custom FileVault profiles are accepted
  • With enable_custom_os_updates_and_filevault disabled and enable_custom_filevault enabled, custom FileVault profiles are still accepted (new flag takes precedence)
  • With both flags disabled, custom FileVault profiles are rejected; custom OS update profiles are still allowed

OS update settings vs custom profile

• Any Apple settings that already exist individually in the UI will block a DDM profile for all Apple products and vice versa.
• If OS updates already configured:
  • macOS: Configure minimum_version + deadline → attempt to upload custom OS update DDM profile → error: Couldn't add profile. OS updates are already configured. Remove the OS updates settings first.
  • iOS: Same as above
  • iPadOS: Same as above
  • Windows: Configure deadline_days + grace_period_days → attempt to upload a Windows XML profile targeting Update CSPs → error: Couldn't add profile. OS updates are already configured. Remove the OS updates settings first.
• If profile already uploaded:
  • macOS: Upload custom OS update DDM profile → attempt to set OS updates settings → error: Couldn't update OS updates settings. A custom OS updates declaration profile already exists. Remove the custom profile first.
  • iOS: Same as above
  • iPadOS: Same as above
  • Windows: Upload Windows XML profile targeting Windows Update CSPs → attempt to set OS updates settings → error: Couldn't update OS updates settings. A custom OS updates profile already exists. Remove the custom profile first.
• Remove and re-config:
  • After removing custom profile, OS update settings can be configured again
  • After removing OS update settings, custom profile can be uploaded again
• Detection logic
  • Upload a Windows XML profile targeting a non-Update CSP → OS update settings can still be configured (no conflict)
  • Upload a Windows XML profile targeting an Update CSP → mutual exclusion kicks in
• If old feature flag is set, confirm it doesn't conflict with OS update settings.
• GitOps shouldn't allow you to set conflicting settings
  • test on Apple
  • test on Windows

API

• Test all API endpoints added or modified in the API changes section of this issue
• Verify any new API endpoints appear in the list when adding an API-only user. The API endpoints display name, method, and path is the same as listed in the API reference docs
• Verify error handling for invalid inputs where applicable

GitOps (generate + run)

• Configure the feature through the UI and run fleetctl generate-gitops
• Confirm the generated .yml includes the expected fields (compare with YAML changes in the Product section)
• Modify the generated .yml and run fleetctl gitops
• Confirm the configuration updates correctly in Fleet
• Enable GitOps mode and verify the feature behaves correctly
• fleetctl gitops with a custom OS update profile and no OS update settings → succeeds
• fleetctl gitops with both a custom OS update profile and OS update settings in the same YAML → returns appropriate error
• fleetctl apply removing OS update settings, then re-running with custom profile → succeeds

Fleet Free

• Ensure update settings cannot be set on fleet free and update profiles/declarations cannot be uploaded

Permissions

• Global admin can upload/remove custom OS update profiles
• Team admin can upload/remove custom OS update profiles for their team
• Team maintainer can upload/remove custom OS update profiles for their team
• Observer / Observer+ cannot upload custom OS update profiles
• GitOps user can manage custom OS update profiles via fleetctl gitops

Edge cases

• Test and doc(comment on this ticket is fine) what happens if a user on a prior version of fleet sets the old option to allow these profiles/declarations, uploads the profile/declaration, sets conflicting upgrade settings(since we called it experimental before) then upgrades fleet. Are they blocked from uploading more profiles or changing team/appconfig settings? What sort of errors do you get? We'll want to make support aware once we release this

Supplemental testing

Testing notes

Confirmation

1. Engineer: Added comment to user story confirming successful completion of test plan (include any special setup, test data, or configuration used during development/testing if applicable).
2. QA: Added comment to user story confirming successful completion of test plan.

[georgekarrv]

This is already available via the env var removing ddm limitations correct? Adding an XS since this sounds like making support easier but not a large technical lift

[lashomb]

One of the challenges with the env var is it also co-mingles disk encryption with it. I'm not willing to jeopardIze that for testing an experimental software update setting.

It would also be nice if it could be allowed per team, and it didn't need to be set globally.