OS updates: Update macOS version

[noahtalerman]

Goal

As a Mac admin using a Fleet Premium deployment, I want to specify what minimum version of macOS to support across my Fleet, and have that work in a way that minimizes annoyance to my users, but also helps us achieve better security and compliance by getting folks on appropriate versions of macOS.

Problem

Apple releases new versions of the macOS operating system (OS) about every month. New versions include important security updates.

Many organizations want to make sure all Macs have the latest macOS so that they have the latest security updates.

Encouraging end users to update their macOS is difficult. Updating can take 30 mins (on average) and disrupt a work day. Reporting on how macOS updates are going is also difficult.

Requirements

• Fleet Premium only
• Set minimum allowed OS version for all hosts on no team
• Set minimum allowed OS version for all hosts on a team
• Show end user Nudge window which tells them to update. The window pops up at increasing frequency specified in the "Nudge" section below.
• When end user sees the window, make sure there's always a macOS update ready to download/install. More context on this problem: https://fleetdm.slack.com/archives/C0389SEPLR3/p1671657149252519
• Docs for IT admin on how to set min. OS version. Docs also explain what the end user sees after this is set.
• Update the permissions documentation.

Design

UI

https://www.figma.com/file/hdALBDsrti77QuDNSzLdkx/%F0%9F%9A%A7-Fleet-EE-(dev-ready%2C-scratchpad)?node-id=11614%3A321739&t=YbOqoAwxkxZQZblI-0

API

TODO

CLI

Update config YAML file

Example config YAML file:

apiVersion: v1
kind: config
spec:
  macos_updates: 
    minimum_version: 13.0.1
    deadline: 2023-06-01
    ...

• Add a macos_updates top level key and minimum_version and deadline.
• minimum_version accepts version numbers only. (E.g., “13.0.1.”) NOT “Ventura 13” or “13.0.1 (22A400).”
• deadline accepts YYYY-MM-DD format only (E.g., “2023-06-01”). The exact deadline time is at 12:00 (Noon) Pacific Standard Time (GMT-8).

Empty

• If the user applies a config file with an empty macos_updates, minimum_version, and deadline Nudge doesn't show up for all hosts (for Premium: hosts on no team).

Errors

• Error if minimum is not a version number. Display this error message: minimum_version accepts version numbers only. (E.g., “13.0.1.”) NOT “Ventura 13” or “13.0.1 (22A400).”
• Error if deadline is not YYYY-MM-DD format. Display this error message: deadline accepts YYYY-MM-DD format only (E.g., “2023-06-01.”).

Update team YAML file

• Add a macos_updates top level key and minimum_version and deadline.
• This makes Nudge start to show up for all hosts assigned to the team.
• Use the same validation from the config YAML file (above).
• Use the same "Empty" behavior from the config YAML file (above).
• Use the same "Errors" behavior from the config YAML file (above).

Nudge

Nudge documentation is here: https://github.com/macadmins/nudge/wiki

Nudge UI:

• Use simple mode
• Change "More info" button so it links to fleetdm.com/docs/using-fleet/mobile-device-management#macos-updates

Nudge UX:

• Use this UX when more than 1 day from deadline:
  • Nudge window pops up and is focused every 24 hours. If the end user dismisses Nudge or leaves it open they'll still be forced to see it the next day.
• Use this UX when less than 1 day from deadline: Nudge window pops up and is focused every 2 hours. If the end user dismisses Nudge or leaves it open they'll still be forced to see it in 2 hours.
• Use this UX when past deadline: Nudge window pops up and is focused every 1 hour. If the end user dismisses Nudge or leaves it open they'll still be forced to see every 1 hour.

Docs

Noah: PR to docs is here:

• 9417

Add a new Mobile device management (MDM) page to the Using Fleet section of the docs

Link to page: fleetdm.com/docs/using-fleet/mobile-device-management

Add a new Controls > macOS updates section

URL for section: fleetdm.com/docs/using-fleet/mobile-device-management#macos-updates

Related

• Parent epic: #7726

Child issues

Frontend:

• https://app.zenhub.com/workspaces/-product-backlog-coming-soon-6192dd66ea2562000faea25c/issues/gh/fleetdm/fleet/9013

Back-end:

• https://github.com/fleetdm/fleet/issues/9093
• https://github.com/fleetdm/fleet/issues/9345
• https://github.com/fleetdm/fleet/issues/9346
• https://github.com/fleetdm/fleet/issues/9347
• https://github.com/fleetdm/fleet/issues/9348
• https://github.com/fleetdm/fleet/issues/9355

Documentation

• TODO

[noahtalerman]

Nudge settings

In Fleet, the IT admin decides what version of macOS is required (ex. latest or 13.0.1) and the deadline (number of days) at which they require their end users to update.

Nudge is a tool used to encourage the installation of macOS updates.

UPDATE: The chart below is outdated. See this issue's description for the latest settings (noahtalerman 2022-01-09).

The chart below illustrates the Nudge settings (behavior) that Fleet will use by default.

• Deadline: red
• 1 day before deadline: orange
• 1 week: yellow
• More than 1 week: grey

[roperzh]

A short summary of the options we considered and tried:

Munki

• Only supports upgrading minor macOS versions, this is a deal breaker

MDM

• In general all notifications to update can be easily dismissed without consequences (ie: there's no way to force an update or annoy the user hard enough)
• Sometimes it doesn't work as advertised, particularly, we tried sending a InstallAction = InstallForceRestart and while it prompted the user to install the update, it didn't force a restart.
• Things like MaxUserDeferrals only work for minor OS updates

Nudge

• Three components: the app, a config (can be JSON or a profile) and a LaunchAgent that ensures the application is running (by default each 30 minutes)
• Allows us to set up a deadline to update in the device (instead of having to poll the device like MDM requires)
• Highly configurable, it increases the levels of annoyance as you get closer to the deadline to update (see this chart for a detailed overview) until it takes over to the user screen
• If you click the "update device" button it takes you to the macOS UI to update. It can be configured to let an agent handle the callback instead, with a significant amount of work we could install the update and restart the computer using orbit.

[noahtalerman]

Hey @mike-j-thomas when you get the chance, can you please help me with the layout (and general UI design) for this page?

I'm linking to the Figma page here: https://www.figma.com/file/hdALBDsrti77QuDNSzLdkx/%F0%9F%9A%A7-Fleet-EE-(dev-ready%2C-scratchpad)?node-id=11614%3A321739&t=QG4cXcxGd9IJZmW6-1

I assigned you this issue and moved it into the #g-marketing board so that it's on your radar.

[mike-j-thomas]

Yes, will do! I'm currently working on a new design for fleetdm.com/platform, but should be able to get on this around the start of next week.

[noahtalerman]

@mike-j-thomas sounds good! Thank you.

[mike-j-thomas]

Sorry for the delay, @noahtalerman. Had to pivot to a web design priority. I'll definitely set aside time today to work on this and #8360 🙏🏻

[noahtalerman]

Notes from product design review on 2022-12-20

On the CLI experience:

• Match behavior for agent options: PUT instead of PATCH
• agent options, macos minimum version, and XML profiles are all siblings
• Roberto: Today, when you create a team, agent options are one-time copied down from global agent options. But if you then cut out the agent options from the team settings, the team will have no agent options.
  • Mike: So for consistency, this should match.

[noahtalerman]

@mike-j-thomas no worries! Thank you for you help :)

[noahtalerman]

Hey @mike-j-thomas can you please help me with the UI for #9013 as well?

I think it makes sense to take a pass at the UI for #9013 with the UI for #8360.

This is because the UI for #8360 has evolved (adding a secondary nav). This secondary nav is covered in: #9013

If it's helpful, I recorded a Loom video to walk you through this: https://www.loom.com/share/15c93bbc46de4dae9e24960d0cbab30e

[mike-j-thomas]

@noahtalerman, #8360, ~and https://github.com/fleetdm/fleet/issues/9013~ are ready for you to look at 👍🏻

[mike-j-thomas]

Sorry @noahtalerman, I'm in the wrong ticket. Working on this one next.

[mike-j-thomas]

@noahtalerman, I need a little more time to think through this new layout. I'll give you an update tomorrow 🙏🏻

[noahtalerman]

@mike-j-thomas sounds good! Thanks

[noahtalerman]

Hey @mike-j-thomas just checking in, have you had a chance to think about this layout?

[mike-j-thomas]

@noahtalerman. Yep, it's ready for you.

[noahtalerman]

@roperzh is it possible to customize the copy / buttons in the Nudge window in the following ways?

• Can we replace the large top line's copy?
• Can we replace the "Update Device" button copy?
• Can we remove some of the copy under "Important notes?"
• Can we make "Defer" button a simple button that closes the window instead of opening a dropdown?

If yes, I'd love to hop on a 30 min call to update the Nudge window and test these updates.

[roperzh]

@noahtalerman we can do most of that, I'd say let's jump on a call and explore

[noahtalerman]

During today's product design review call (2022-01-09) we decided to adjust the Nudge settings to the following:

• More than 1 day from deadline: Every 24 hours. No background blur. "One day" and "Later" deferral options.
• Less than 1 day from deadline: Every 2 hours. Yes background blur. "Later" deferral option.
• Past deadline: Every 1 hour. Yes background blur. No deferral option.

I updated this issue's description to reflect this^

@roberzh is it possible to only show certain deferral options in Nudge? See the desired deferral options above. I can't remember if we discovered that we can't do this.

[noahtalerman]

Hey @mike-j-thomas when you get the chance, can you please help me with the layout for this page? I assigned you and added this issue to the marketing board.

Linking to the Figma page here (screenshot below): https://www.figma.com/file/hdALBDsrti77QuDNSzLdkx/%F0%9F%9A%A7-Fleet-EE-(dev-ready%2C-scratchpad)?node-id=11539%3A321344

This Loom video walks through what we'd like to add + what changed since the last time you looked at this UI: https://www.loom.com/share/149050d7fb774741b028cc63921f8ac4

[noahtalerman]

@mike-j-thomas I unassigned you and removed the issue from the marketing board.

Context is here in Slack (internal): https://fleetdm.slack.com/archives/C01ALP02RB5/p1673404102816089

[lukeheath]

@noahtalerman This feature is partially blocked by not having the ability to install software on the host (i.e. Munki, or another solution if we choose.)

[lukeheath]

To clarify, for this feature we need the ability to install software that we control, like Orbit and Nudge.

It does not require installing packages provided by the IT admin.

[lukeheath]

Backend ballpark estimate: 13 (full sprint) Frontend ballpark estimate: 8-13

Total for epic ~21-26 points

[lukeheath]

@ghernandez345 - @roperzh and I put very ballpark estimates on the epic above ^

This is needed for the upcoming sprint. Would the two of you please work together to break this epic up until it's child issues? The child issues don't all need detailed specs, we just need to break them up for Monday. Thanks!

[lukeheath]

Per Zach's comment here, we will install Nudge using Orbit, which should unblock this effort.

[lukeheath]

@ghernandez345 @roperzh

we just need to break them up for Monday

More important than breaking this up for the sprint planning is us agreeing that 21 points for the epic is a reasonable estimate. We can break out individual technical tasks after we start the sprint.

[roperzh]

@noahtalerman a note, in the top level requirements it says:

Fleet Premium only

But in the descriptions below seems like this feature is available for non-premium deployments, for example:

For Fleet Free, this makes Nudge start to show up on all hosts. For Fleet Premium users this makes Nudge start to show up on all hosts with no team.

I'm moving forward with the assumption that we will allow Fleet Free users to use this feature as described, but please shout if I shouldn't.

[ghernandez345]

@noahtalerman is the figma link her the correct link? I see another in the comments that looks more related to this issue

[roperzh]

@ghernandez345 I think https://www.figma.com/file/hdALBDsrti77QuDNSzLdkx/%F0%9F%9A%A7-Fleet-EE-(dev-ready%2C-scratchpad)?node-id=11614%3A321739&t=YbOqoAwxkxZQZblI-0 is the right link. I will update the issue description.

[roperzh]

@noahtalerman another question, I can see activities when minimum_version is changed but not when deadline is changed, is this intentional?

[noahtalerman]

I'm moving forward with the assumption that we will allow Fleet Free users to use this feature as described, but please shout if I shouldn't.

@roperzh we won't allow Fleet Free users to use this feature. I removed the below sentence from the issue description. I missed updating the issue.

"For Fleet Free, this makes Nudge start to show up on all hosts. For Fleet Premium users this makes Nudge start to show up on all hosts with no team."

[noahtalerman]

I can see activities when minimum_version is changed but not when deadline is changed, is this intentional?

@roperzh users should see the activity feed item when minimum version OR deadline is changed.

[roperzh]

@roperzh users should see the activity feed item when minimum version OR deadline is changed.

@noahtalerman understood, thanks. A heads-up that the activity copy doesn't show the deadline, so if I go and edit the deadline multiple times it might look like there are repeated activities.

[noahtalerman]

heads-up that the activity copy doesn't show the deadline

Ah, great point. I think updating the copy to include deadline is valuable. Something like "...updated the minimum macOS version to 12.6.2 (Deadline: 2023-06-01)"

@ghernandez345 @roperzh what do you think? How much does this impact the estimate?

[noahtalerman]

@noahtalerman is the figma link her the correct link? I see another in the comments that looks more related to this issue

The link included in this issue's description is right one: https://www.figma.com/file/hdALBDsrti77QuDNSzLdkx/%F0%9F%9A%A7-Fleet-EE-(dev-ready%2C-scratchpad)?node-id=11614%3A321739&t=YbOqoAwxkxZQZblI-0

Please let me know if it still looks wrong. Just curious, what's the other Figma link you're referring to?

[roperzh]

Ah, great point. I think updating the copy to include deadline is valuable. Something like "...updated the minimum macOS version to 12.6.2 (Deadline: 2023-06-01)"

@noahtalerman it doesn't affect the back-end estimate, and I'm 99% it doesn't affect the UI estimate either.

It's the right one. Please let me know if it still looks wrong. Just curious, what's the other Figma link you're referring to?

I changed it! it used to be https://www.figma.com/file/hdALBDsrti77QuDNSzLdkx/%F0%9F%9A%A7-Fleet-EE-(dev-ready%252C-scratchpad)?node-id=10517%253A316027

[noahtalerman]

it doesn't affect the back-end estimate, and I'm 99% it doesn't affect the UI estimate either.

Got it 👍 @roperzh @ghernandez345 let's add deadline to the activity feed. I updated the Figma to include the deadline in the activity feed:

cc @lukeheath

[noahtalerman]

I changed it! it used to be https://www.figma.com/file/hdALBDsrti77QuDNSzLdkx/%F0%9F%9A%A7-Fleet-EE-(dev-ready%252C-scratchpad)?node-id=10517%253A316027

Ah! Roberto, thank you. Whoops from me

[noahtalerman]

@chris-mcgillicuddy if you get the chance, please let me know if you have any thoughts/feedback on the proposed copy (screenshot in the following comment): https://github.com/fleetdm/fleet/issues/9013#issuecomment-1384521892

[noahtalerman]

@lukeheath I expanded this story to include this Controls tab state (when the user hasn't connected Fleet to Apple): https://www.figma.com/file/hdALBDsrti77QuDNSzLdkx/%F0%9F%9A%A7-Fleet-EE-(dev-ready%2C-scratchpad)?node-id=12342%3A329710&t=VcuhiWf8kr6pnlJc-1

[roperzh]

@noahtalerman in the CLI, what happens if I provide minimum_version but I don't provide deadline or vice-versa? If it's an error, do you mind providing the error message?

[noahtalerman]

what happens if I provide minimum_version but I don't provide deadline or vice-versa?

@roperzh great catch. Yes, we should show the user an error in this case.

Error message if minimum_version is provided and deadline is not: "For macOS updates, a deadline is required (macos_updates.deadline) when a minimum version (macos_updates.minimum_version) is provided."

Error message if deadline is provided and minimum_version is not: "For macOS updates, a minimum version is required (macos_updates.minimum_version) when a deadline (macos_updates.deadline) is provided."

What do you think? How complex is having a different error for each case?

[roperzh]

What do you think? How complex is having a different error for each case?

@noahtalerman thank you! not complex at all, just needed the confirmation and the copy 💚

[fleet-release]

` indicates other attributes not related to this feature

Haiku: Updating macOS Easy, secure, with less worry Peace of mind restored

[fleet-release]

` indicates other fields which are not relevant to this ticket.

Haiku: Updates now secure, Macs run in harmony, user Peaceful compliance.