Support "bootstrap" package via CLI

[noahtalerman]

Goal

As an IT admin, I want to be able to install a custom package on new Macs in Apple Business Manager, when they're unboxed, so that I can deploy software and scripts to these Macs using my tool of choice (Munki, Chef, Puppet, etc.).

IT admins call this a "bootstrap" package.

Changes

• [ ] Fleet Premium only
• [ ] Fleet admins and maintainers (global and team) can add a bootstrap package to each team (and "No team"). This package is installed on hosts that automatically enroll to the team or no team
• [ ] In addition to the custom package, Fleet also installs fleetd package. This is covered in a separate story: #9459
• [ ] If IT admin removes the bootstrap package for a team, Fleet only installs the fleetd package on hosts that automatically enroll to that team
• [ ] If a host is transferred to a not-default team before it automatically enrolls, it uses the bootstrap for the not-default team when it automatically enrolls
• [ ] Config option in config and team YAML to point to relative path where a package lives.

[noahtalerman]

Related tools:

• DEP notify: https://gitlab.com/Mactroll/DEPNotify#basic-usage
• hello: https://github.com/erikng/hello
• InstallApplications demo: https://github.com/erikng/installapplicationsdemo/blob/main/installapplications/demo.json
• Munki DEP package: https://groups.google.com/g/munki-discuss/c/kldzA1ZhqtI

Other resources:

• MacAdmin talking about the MDM solution's role in custom DEP (snippet from Gong recording - internal): https://us-65885.app.gong.io/call?id=1731851542158155837&highlights=%5B%7B%22type%22%3A%22SHARE%22%2C%22from%22%3A1231%2C%22to%22%3A1256%7D%5D
• Example bootstrapping set up with Chef + MicroMDM: https://docs.chef.io/desktop/zero_touch/macos/#initial-app-deployment-to-a-node

[lukeheath]

@noahtalerman Is this story still in drafting?

[noahtalerman]

• [ ] Roberto: We would need to build a way to specify which profiles get installed during unboxing
  • Noah: We can add a flag in the YAML that says this a profile that should be installed during unboxing (?)

Punt on this^ context is here in Slack: https://fleetdm.slack.com/archives/C02A8BRABB5/p1677794729473579

[noahtalerman]

• Dave and Noah: It's up to the IT admin to get fleetd and Munki in an InstallApplications package: https://github.com/macadmins/installapplications
  • All packages inside InstallApplications have to get signed
  • Dave: I can create the InstallApplications package for testing

Moving this^ out the issue description so we have it tracked. It's not related to the changes we need to make

[noahtalerman]

@noahtalerman Is this story still in drafting?

@lukeheath I think yes. We haven't decided how Fleet will know what package to install:

We can add a config option in YAML to point to package (?)

EDIT: It looks like we built a fleetctl apple-mdm installers command:

I'm not sure if this allows the user to upload a package that Fleet will install during unboxing. If it does, maybe we don't have to do more work now.

Goal is to provide prospective customer with a "backdoor" (not pretty UX) way to successfully install a package during unboxing.

[noahtalerman]

Roberto: This issue + #10518 estimated at an 8

[noahtalerman]

@lukeheath I assigned you this issue and #10518. Can you please adds specs with the names for the config options.

[noahtalerman]

@lukeheath FYI I brought this story back to drafting so that we can take proposed UI changes to design review. This story is planned for next sprint (4.30.0).

We want to draft UI changes before we start CLI/API work.

I carved these two stories out of this story:

• 10518

• 10577

These stories^ are in drafting and aren't planned for next sprint.

[noahtalerman]

Hey @zhumo and @roperzh we talked about the requirements and UI for this issue during our "Bootstrap package UX" call today (2022-03-23)

I want to bring the UI changes to tomorrow's design review w/ Mike.

When you get the chance can you please take a look at the proposed UI (Figma link here) and CLI (wireframes are in issue description) ?

Feedback I'm looking for:

• Does the workflow / user journey make sense?
• Any copy, UI, IA, or layout suggestions

[noahtalerman]

@roperzh I have a couple more technical questions for you:

• Can Fleet detect when the user tries to upload an unsigned package? I think we want to show an error message when the user tries to do this. This is because the package won't install during set up.
• I think we want the YAML to accept a relative path of a package. This way, the UX is consistent with the profiles (relative path to profile). How would this work?
• It looks like the InstallEnterpriseApplication command takes in a manifest URL. What is that? https://developer.apple.com/documentation/devicemanagement/install_an_enterprise_app

[roperzh]

@noahtalerman

Can Fleet detect when the user tries to upload an unsigned package? I think we want to show an error message when the user tries to do this. This is because the package won't install during set up.

I have confirmed that we can!

I think we want the YAML to accept a relative path of a package. This way, the UX is consistent with the profiles (relative path to profile). How would this work?

For this to work, fleetctl would have to upload the package to the Fleet server, and the server would have to store the package somewhere.

Ideally we would use a blob storage, but for the MVP we could do the same ugly thing we did for the PoC: use the database to store the installer.

Once the installer is uploaded, Fleet provides a public URL that can be accessed only if you have a token to "serve" the installer. This is the URL that the InstallEnterpriseApplication command will use.

It looks like the InstallEnterpriseApplication command takes in a manifest URL. What is that? https://developer.apple.com/documentation/devicemanagement/install_an_enterprise_app

That is an XML with metadata about the package, we can (and IMO should) build that automagically, it's something that micromdm provides and it's already done in the PoC.

[roperzh]

@noahtalerman an afterthought: the relative path is handy for profiles because these are plain text files and work well with source control (like git).

It's worth double checking with IT admins, because having the installer checked in source control sounds very painful (since those are "big" binary files)

[zhumo]

• Repeated "macos macos macos" across the top is getting weird... Not a big deal, I think.
• Title of the section is non-intuitive to me. What we're doing here is allowing IT admins to customize what happens during the unboxing experience, right? Calling it "automatic enrollment" seems too broad... "setup UX" "DEP UX" "enrollment experience"?
• Why "this feature is coming soon"? Why not just not have that?
• Explanation under "custom package" seems underwhelming:
  1. When will this run?
  2. What should I put in here? Do I have to put something in here?
  3. Why would I do this?
  4. How do I make one of these pkgs?
  5. Doesn't discuss using the pkg to run a script, which I understand is a major potential option
  6. If I run it, will the screen be locked up or will the user move on first?
  7. I'm not sure which of those things above need to be said here, but I think the current message is not telling me what I need/want to know at this moment.

[noahtalerman]

TODO Noah: Make a GIF of the user going through the setup. YouTube video

[noahtalerman]

During a "macOS setup problems" @zhumo @roperzh and I decided that in the team and config YAML document, the IT admin should supply a URL where the package lives instead of a relative path to the package.

Why?

• Relative path to the package requires committing the package to a git repo.
  • This will make the GitHub action that deploying the package to Fleet take a long time (action clones the repo and the package is large).
  • This time increases every time you commit changes to package (all previous versions have to be stored in the repo).
  • IT admins who use GitOps aren't used to storing packages in a git repo. They use another solution like S3 instead.
• It's ok if the URL to the package is accessible to the public. Apple's InstallEnterpriseApplication command requires that the package is accessible.

cc @lukeheath

[noahtalerman]

Do not start work on this story yet. Product is taking back ground the design process.

• TODO: @noahtalerman Remove this when ready.

Hey @lukeheath the CLI for this story is designed. I think we're ready to implement the CLI this sprint as soon as the specs are reviewed/updated. I removed the above notice from the issue description.

The UI was brought to today's design review. I'm brining the UI to another design review tomorrow for a 2nd pass. The UI is not quite ready for specs.

The plan is to implement the UI in the next sprint. Do we need a separate story for the UI?

[noahtalerman]

During today's design review we decide to call the bootstrap package a "Custom setup package" in the CLI and UI.

Options:

• Bootstrap package
• Setup package
• Custom package
• Custom agent
• Custom setup package

Reasoning:

• While "Bootstrap package" is similar to what VMWare calls their "Custom bootstrap package" feature, we think bootstrap package seems too technical and only WS1 users would easily understand the naming.
• We think "Custom package" is too vague. When is this package installed? What's it used for?
• We think "Custom agent" can confuse users. Does adding a custom agent replace the fleetd agent?
• We think "Setup package" doesn't clarify that this package is optional/not required.
• "Custom setup package" indicates that the package is installed during setup and it's used to set the device up for use. The "custom" word also explains that the package is only necessary if you want to install something extra: a configuration management tool or a script to pull down dependencies.

cc @lukeheath @roperzh @georgekarrv @mikermcneil @zhumo

[noahtalerman]

@lukeheath the UI is ready for specs. While we only carved out room for the CLI this sprint, it would be great if we can estimate and bring the UI into this sprint.

The UI is the next priority (after WIP) for MDM team.

I think it makes sense to hop on a call, after the UI is estimated, to see if we have room this sprint. What do you think?

[mikermcneil]

Thanks for documenting the reasoning!

[noahtalerman]

As an IT admin, I want to reinstall the custom setup package (Munki client) because it wasn't installed during setup for some reason (failed install, something else).

Hey @roperzh can the IT admin achieve this^ by running a custom InstallEnterpriseApplication command using fleetctl mdm run-command command? (fleetctl command spec'd here: #96433)

They would need to know the manifest URL for the package right? How would they get this?

[noahtalerman]

Hey @mike-j-thomas when you get the chance, can you please help me create 2 new icons for the Fleet UI? (I used the .mobileconfig icons as placeholders below)

1. Icon for a PDF file (.pdf)

2. Icon for a package file (.pkg)

Loom video that gives more context on why we're adding the ability to add these files: https://www.loom.com/share/0e462a254c0e4bdc8077cdaf5372e632

[noahtalerman]

New problem:

To run the InstallEnterpriseApplication command, we need to build an XML that contains a SHA256/MD5 checksum of the file to be installed. If the IT admin provides an URL, we could download that file and calculate the checksum, but that kind of defeats the purpose of having a checksum in the first place, right? optionally we could also ask the IT admin to provide the checksum, but that's adds burden to the IT admin.

More discussion here in Slack (internal).

@roperzh, @gillespi314 , and I just met and we decided to ask IT admin to add only a URL for where the bootstrap package lives. We can checksum configuration later as per customer request.

Reasoning:

• Adds an additional step for IT admin
• Adds more work now
• It isn’t harder to add checksum feature later
• We think risk is low. Requiring that the package is signed might even cover some of the risk.
• My understanding is that this is mostly about Fleet not using the checksum as designed (checksum is generated by Fleet but not used to verify package is correct). So, Fleet has to trust that it is receiving the correct, untampered package.

cc @zwass @zhumo @dherder

(2023-04-04)

[zwass]

When we want to support checksums, we can start using the TUF tooling we already have. The Fleet server would be able to securely grab an up to date checksum and download url.

[noahtalerman]

UPDATE: During today's design review we decide to call the bootstrap package a "Bootstrap package" in the CLI and UI.

This is an update from the decision to call the package a "Custom setup package." Earlier decision is documented here: https://github.com/fleetdm/fleet/issues/10213#issuecomment-1490596106

@lukeheath @roperzh @georgekarrv heads up, I updated the CLI specs in this subtask to use the new bootstrap_package name. I think this story tracking UI/API changes might need a similar change: #10936

Reasoning:

• We think our target users (IT admins at large orgs that use open source tools like MicroMDM, MDMDirector, Munki, etc.) will have an easier time recognizing "Bootstrap package." We think they'll have an easier time understanding what this feature is for: bootstrapping automatically enrolled (DEP) hosts.
• Earlier we chose "Custom setup package" naming to appeal to users who aren't familiar with terms like "bootstrapping a device." We want to prioritize the UX for IT admins at large orgs over these users.

cc @zhumo @mikermcneil

[noahtalerman]

We decided to not address, as part of this story, that this feature will slow down the speed of the IT admin's CI. We will come back to this later.

cc @roperzh @georgekarrv @lukeheath

Conversation from Slack (internal) is below:

Roberto: what I'm thinking of is that CI times will be very slow even if you're not modifying the package, because we have to download the package every time

but that's something we can come back to

Noah: How slow? Like a minute on average? 5 minutes? (with good connection)

Roberto: hard to tell, will depend on the size of the bootstrap package and the upload/download network speed of the computer running fleetctl

but my gut feeling is that will make something go orders of magnitude up, eg: from 2 seconds to 5 minutes

(maybe 2 minutes?) something like that

Noah: Hmm, ok. Yeah that’s a big jump. Agree we can come back to addressing the slow CI

[mike-j-thomas]

Hey @mike-j-thomas when you get the chance, can you please help me create 2 new icons for the Fleet UI?

Hey, @noahtalerman, I've updated the file icon component to include the new file types.

[mike-j-thomas]

@noahtalerman, I also have a version here where the pkg is in its correct box. It becomes a little illegible at the smallest size, though. Do you think the pkg icon is still clear out of its box?

[noahtalerman]

@mike-j-thomas I don't think the package is clear out of the box. I like the package in the box because it's recognizable, even at the small size. What do you think?

[fleet-release]

Bootstrap package blooms, Macs in Apple's cloud realm thrive, Fleet aids, empowers.

[noahtalerman]

@noahtalerman docs for how to use bootstrap package CLI

[fleet-release]

Unboxed Macs in bloom, Custom bootstrap package gives, Ease for IT minds.