Option to automatically migrate Windows workstations

[noahtalerman]

Goal

User story
As an IT admin,
I want to migrate my Windows workstations from my old MDM solution to Fleet
so that I can use Fleet to enforce disk encryption, OS updates, and other OS settings on these hosts.

Objective

Customer promises + renewal requests

Original request

• Migrate Windows hosts #13667

Context

• Product designer: @rachaelshaw

Changes

Product

• UI changes: Figma
• CLI (fleetctl) usage changes: No changes.
• YAML changes: PR
  • UPDATE: @noahtalerman: Follow up PR here: YAML files reference docs: windows_migration_enabled #24891
• REST API changes: PR (old PR with 1st draft here, for reference)
• Fleet's agent (fleetd) changes:
  • receive a notification to unenroll from the previous MDM provider
  • feature will require the latest fleetd version
• Activity changes: Draft PR
• Permissions changes: No changes.
• Changes to paid features or tiers: Fleet Premium
  • @noahtalerman: Pricing page language: An "on" button in Fleet so you have control over when Windows workstations switch.
• Other reference documentation changes: No changes.
• Once shipped, requester has been notified
• Once shipped, dogfooding issue has been filed (https://github.com/fleetdm/confidential/issues/9172)

Engineering

• Feature guide changes: WM: Guide #24842
• Database schema migrations: WM: DB schema changes #22895
• Load testing: None

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

QA

Risk assessment

• Requires load testing: No
• Risk level: Low / High TODO
• Risk description: TODO

Manual testing steps

1. Run Fleet with Windows MDM turned off
2. Enroll a Windows host into Fleet and enroll that Windows host in a third-party MDM solution
3. Validate that the Windows host reports being MDM-enrolled in a third-party
4. Turn on Windows MDM in Fleet
5. Verify that the Windows device stays enrolled in its third-party MDM solution (e.g. wait for the "last refetched" note on the host's page to be after Windows MDM was turned on)
6. Turn on Windows MDM migration in Fleet
7. Verify that the Windows devices unenrolls from the third-party MDM solution, and subsequently enrolls into Fleet MDM (this may go quickly, in 1-2 minutes, so you may have to refresh the host's page frequently to see the intermediate step)

Alternative tests that would be good to cover if possible:

• fleetctl gitops to enable MDM migration
• try to enable migration without a premium license (via UI, and via fleetctl)
• enroll the Windows device into a third-party MDM before adding it to Fleet
• turn on Windows MDM migration at the same time as Windows MDM is enabled
• try a migration from a Windows host enrolled in multiple third-party MDM solutions

Also, see testing notes below, and the results of my (@mna) QA of the feature branch here: #22075 (comment).

Testing notes

@mna :

I did a manual QA that worked fine with our POC MDM server as third-party MDM solution that the host migrated from. However I wasn't able to test with the host enrolled in multiple non-Fleet MDM solutions, which I believe is possible in Windows. I don't know how the unenrollment step of the migration would behave in this case, that's something we may want to try to cover in QA.

@noahtalerman:

Edge cases to consider:

• What about offline hosts?
• What happens in between toggling?
• What about the folks that have ‘Windows MDM turned on’
• What happens to those fleetd enrolled Windows hosts?
• What does the reporting look like? (status of hosts that have not transitioned yet, and which have. What if some never check in? How will I know which have and which haven't?)

Confirmation

1. Engineer (@____): Added comment to user story confirming successful completion of QA.
2. QA (@PezHub ): Added comment to user story confirming successful completion of QA.

[noahtalerman]

Moving this out of the issue description. This was used during design process. Please see the Figma in the issue description for the latest UI changes.

Flip this behavior:

[noahtalerman]

Hey @zayhanlon heads up, this user story didn't make it into the upcoming engineering sprint because we didn't get it estimated in time.

It's still prioritized. We left it on the drafting board so that it can be pulled into the next engineering sprint.

[noahtalerman]

Hey @georgekarrv just giving you a reminder that this story is ready to spec. Please let us know if we can help get this ready for estimation :)

cc @marko-lisica

[noahtalerman]

Hey @georgekarrv just giving you a ping! as a reminder that this story is ready to spec. Please let us know if we can help get this ready for estimation.

[mna]

@noahtalerman @georgekarrv @rachaelshaw just a heads-up that there are fleetd changes required for this story (to receive a notification to unenroll from the previous MDM provider), so that feature will require the latest fleetd version to be supported.

Mentioning because the story currently states Fleet's agent (fleetd) changes: N/A.

[rachaelshaw]

@mna thanks for calling that out! I updated the issue description to capture that.

@noahtalerman do you reckon that's worth calling out in the settings page copy or the docs? Or is it expected that users keep fleetd up-to-date?

[noahtalerman]

Thanks @rachaelshaw!

do you reckon that's worth calling out in the settings page copy or the docs? Or is it expected that users keep fleetd up-to-date?

Good thinking but I think no copy or doc changes needed. It's expected to keep Fleet up-to-date. Most users rely on our update servers so when we push this fleetd update all their computers will get it.

For users who manage fleetd version themselves (pin it to a lower version), they can check the releases page for which fleetd version corresponds to the latest Fleet features.

[mna]

@noahtalerman answering the questions you listed in the "QA -> Testing Notes" section of the story (not sure if that was for me/ the implementer of the solution or to be answered by QA, but in any case here are my answers now that the solution is implemented):

Edge cases to consider:

• What about offline hosts?

Migration requires the host to be online with fleetd communicating with Fleet. Offline hosts would receive the notification to start the migration when they come online.

• What happens in between toggling?

The migration is a two-step process: first unenroll from the old MDM, wait for confirmation on the server, then enroll in Fleet. So the host is either "still enrolled in the old MDM", "unenrolled from any MDM", or "enrolled in Fleet". From my tests, the switch is quite fast (a minute or two).

• What about the folks that have ‘Windows MDM turned on’

You mean Fleet instances that have Windows MDM turned on before upgrading to the version that supports migration? They will still have it on, but migration will be disabled after upgrade and will need to be explicitly enabled (either via UI or fleetctl).

• What happens to those fleetd enrolled Windows hosts?

Hosts that are already in Fleet MDM stay as-is, they won't execute any action for a migration.

• What does the reporting look like? (status of hosts that have not transitioned yet, and which have. What if some never check in? How will I know which have and which haven't?)

The MDM stats section of the dashboard show the details of hosts vs MDM solution, but those stats are generated in a cron job that runs every hour. The specific hosts' details page will show what MDM they are part of (or not in MDM) during the switch based on what the host reported.

[mna]

My QA of the feature branch now that all sub-tasks are implemented:

---

Windows MDM turned off, 2 Windows hosts enrolled, one already in a 3rd-party MDM before enrolling into Fleet, the other will be shortly, before MDM is turned on:

Then I enrolled the DreamQuest machine to the 3rd-party MDM, now that it is orbit-enrolled in Fleet. So now both Windows hosts are enrolled in a 3rd-party:

---

Now I turn on Windows MDM, but not the migration yet:

The "MDM turned on" activity gets created:

Both hosts remain in the 3rd-party MDM:

---

I turn on Windows migration via fleetctl apply:

apiVersion: v1
kind: config
spec:
  mdm:
    windows_enabled_and_configured: true
    windows_migration_enabled: true

[+] applied fleet config

The activity gets created and a host is already migrated:

And very soon after, both hosts are now enrolled into Fleet MDM:

---

Sent a trigger to speed up calculation of aggregated stats: $ ./build/fleetctl trigger -name cleanups_then_aggregation

(it says 3 because I have an ABM pending macOS host too)

Tooltip was properly updated on the "On (manually)" status:

---

Turning Windows migration off via fleetctl, gets properly reflected in the UI and the activity got created as expected:

---

Turning Windows MDM off altogether generates only that activity, not the Windows migration disabled one:

Note that Windows hosts do not properly unenroll from Fleet MDM, there's a distinct issue for that as this is a released bug unrelated to that story: #24209

---

I believe the frontend does not know about the new activities at the moment, as they show up as the generic layout, instead of what was designed in Figma. I'll create an issue to track that (#24269). The rest looks good to me.

[mna]

Video recording of the flow (@nonpunctual as you mentioned you wanted to see this):

https://drive.google.com/file/d/1WkViPyTrmdZVscjWsAwFVqRXcqbtiatM/view?usp=drive_link

[PezHub]

Additional QA tests and notes:

• Fleet UI design and copy match Figma
• Global Activity Feed is accurate
• GitOps workflow succeeded for turning mdm and migration on/off
• Confirmed migration option not available in Free Version

I also tested the following scenarios using a Surface Laptop enrolled in a 3rd Party MDM solution (from a different vendor):

1a. Enroll device in 3rd party mdm before adding to fleet ✅

• remove fleetd from host
• enroll in 3rd party mdm
• install fleetd while windows mdm is OFF in Fleet UI
• turn windows mdm on, wait...refetch
• turn migration on

1b. Enroll device in 3rd party mdm before adding to fleet ✅

• remove fleetd from host
• enroll in 3rd party mdm
• install fleetd while windows mdm is ON in Fleet UI
• refetch..wait
• turn migration on

2. turn on Windows MDM migration at the same time as Windows MDM is enabled ✅

• remove fleetd from host
• enroll in 3rd party mdm
• install fleetd while windows mdm is OFF in Fleet UI
• turn on windows mdm and migration at the same time
• refetch

3. add a windows host that is already enrolled in 3rd party mdm to Fleet with MDM and Migration already turned ON ✅

• remove fleetd from host
• enroll in 3rd party mdm
• install fleetd while windows mdm and migration is ON in Fleet UI
• refetch

Additional Note - I did not have time nor resources to test a migration from a Windows host enrolled in multiple third-party MDM solutions

[noahtalerman]

Hey @georgekarrv I think we missed guide updates for this user story. If that's right, can you please help me track a bug for guide updates?

cc @lukeheath

[georgekarrv]

#24842 Added as a subtask to this story

[noahtalerman]

Hey @mna what happens when I set windows_enabled_and_configured to false and windows_migration_enabled to true in my YAML?

Do we show an easy to understand error message?

[noahtalerman]

• YAML changes: PR
  • UPDATE: @noahtalerman: Follow up PR here: YAML files reference docs: windows_migration_enabled #24891

@rachaelshaw I noticed that we were missing YAML reference docs and I'm not sure why. Did we merge the docs into the wrong reference docs branch and then, later, the changes got stomped on?

I opened a PR to add the missing docs here: #24891

[PezHub]

Hi @noahtalerman , we do get a user friendly error when setting windows_enabled_and_configured to false and windows_migration_enabled to true in my YAML -

Error: applying fleet config: PATCH /api/latest/fleet/config received status 422 Validation Failed: Couldn't enable Windows MDM migration, Windows MDM is not enabled.

[noahtalerman]

Guide updates are merged! #24984

Closing this story.

[fleet-release]

Migrate with ease now,
Windows workstations find home,
Fleet's cloud secure, sound.