Policy automations: install App Store apps on macOS

[marko-lisica]

Goal

User story
As an IT admin,
I want to install App Store apps automatically when a macOS host fails a policy
so that I can deploy App Store apps to many hosts without having to use 3rd party automation tool (e.g. Tines).

Key result

Fleet users can automatically install any software in Fleet w/o writing policies.

Original requests

• Software: automatically install, patch, and add custom targets (labels) #21825

Context

• Product designer: @marko-lisica

Changes

Product

• UI changes: Figma link
• CLI (fleetctl) usage changes: No changes.
• YAML changes: [API design / YAML changes] Policy automations: install App Store apps on macOS #24585
• REST API changes: [API design / YAML changes] Policy automations: install App Store apps on macOS #24585 Use comma-separation rather than multiple identical parameters for getting software titles from multiple platforms #25153
• Fleet's agent (fleetd) changes: No changes.
• Activity changes: Make sure that if App Store app install is triggered by policy actor_name is Fleet
• Permissions changes: No changes.
• Changes to paid features or tiers: Available in Fleet Premium only
• GitOps mode changes: No changes
• Transparency changes: No changes
• Other reference documentation changes: No changes
• First draft of test plan added: @noahtalerman: No draft test plan because we worked on this story before the new user story ritual
• Once shipped, dogfooding issue has been filed: https://github.com/fleetdm/confidential/issues/9555
• Once shipped, requester has been notified: Software: automatically install, patch, and add custom targets (labels) #21825 (comment)

Engineering

• Feature guide changes:
  • Update Automatic software install guide to reference App Store apps on macOS
  • Update Install App Store (VPP) apps guide to mention automatic install and link to guide above
• Database schema migrations: policy_id on VPP app installs, join table from policies to VPP apps
• Load testing: Not feasible (see below)

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

QA

Risk assessment

• Requires load testing: No (currently unfeasible to test VPP app distribution at load)
• Risk level: Low; this is similar to software installer automation, but without the bandwidth flood potential of hosting installers locally.

Manual testing steps

Feature does not automatically create policies to install App Store apps. Only makes App Store apps available to policy automations.

Happy path

1. Ensure there is a VPP Token added to Fleet and an existing policy to check for desired state
2. Manage Automations >> Install software >> add macOS App store app to policy, save
3. Ensure when policy goes from no result > Failed or Passed > Failed the software is queued for install
4. Ensure the software installs

Testing checks

• Manage automations >> Install Software modal loads quickly (even when there are a large number of software titles and teams) and spinner is shown in modal until software and policies are loaded.
• Manage automations >> Install Software modal only shows policies on current page, but all software available to install is in the dropdown
• In Manage automations >> Install Software modal, only the software available for the policy's supported platforms, for the current team, is shown in the dropdown

To test the above, set up a macOS custom package (or FMA), a macOS VPP app, and a Linux package. Set up one policy for Linux hosts only, one for Linux + macOS, one for Windows, and one for macOS hosts only. First policy should have one package (Linux one) available for automation. Second should have all three. Third should have none. Fourth should have the two macOS packages.

• In Manage automations >> Install Software modal, when an App Store app is displayed, show "macOS (App Store) · " below app name
• While software is being added to the Install Software modal, the button should have a spinner and there should be an overlay over contents of modal.
• When software is successfully added to the policy "Successfully updated policy automations" message is shown
• If software could not be successfully added to the policy "Could not update policy automations" message is shown created Error not surfaced in UI for adding Software automation if software no longer exists #25637
• If App Store App is used in an install software policy automation, the "Automatic install" pill is shown on the app list and app details page. Clicking on the pill on the details page opens a modal that displays the policies for which the software will be automatically installed. Clicking on the policy name takes you to the policy.
• If user tries to delete the App Store App when there is an associated policy automation, an error will be displayed "Couldn't delete. Policy automation uses this software. Please disable policy automation for this software and try again."
• In Activity feed on host details page, when app is queued for installation via policy automation, the activity entry will be "Fleet told Fleet to install <app name> on this host. Show details"
• In Activity feed on host details page, when app is successfully installed on the host via policy automation, the activity entry will be "Fleet installed <app name> on this host. Show details"
• In Activity feed on host details page, when app fails to install on the host via policy automation, the activity entry will be "Fleet failed to install <app name> on this host. Show details"
• In global activity feed, when app is successfully installed on the host via policy automation, the activity entry will be "Fleet installed <app name> on <hostname>. Show details"
• In global activity feed, when app fails to install on the host via policy automation, the activity entry will be "Fleet failed to install <app name> on <hostname>. Show details"
• Global activity feed >> Dev Tools, activities response shows created_at, id, actor_full_name, actor_email, type, details (status, host_id, policy_id, policy_name, app_store_id, command_uuid, self service, software_title, host_display_name)

The section formerly known as "build these out more"

• If I remove a team from my VPP token, any VPP automations for that team should get deleted (along with VPP apps for that team)
• If I delete a VPP token, any VPP automations associated with that token should get deleted (along with VPP apps listed for teams associated with that token)
• If I renew a VPP token, any VPP automations associated with that token should NOT get deleted
• If the VPP token doesn't have enough licenses to install the app the failure is logged server-side. Activity feed shows failed install and "Show details" contains additional details of failed install.
• If I have multiple VPP tokens - only apps from VPP token assigned to selected team will be available in install software automation dropdown

Database changes

• Upgrades with existing VPP apps, policies

API changes - New params? What can be done differently with the API now?

• PATCH /api/v1/fleet/teams/:team_id/policies/:policy_id endpoint accepts a title associated with a VPP app in software_title_id parameter.
• Software title includes policy automation details in the app_store_app -> automatic_install_policies field
• Software title search allows filtering by platform, with multiple platforms available by comma-separating the query
• GitOps should now allow app_store_app_id in policies ([YAML design] Policy automations: install App Store apps on macOS #25389 changed this to app_store_id)

Doc updates (check 4.63 docs branch)

• Automatic software install guide references App Store apps on macOS
• Install App Store (VPP) apps guide mentions automatic install and links to guide above

Testing notes

Confirmation

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

[sharon-fdm]

#23170 is a duplicate and was closed.

[ambrusps]

@noahtalerman adding some context here from customer-fourier: https://fleetdm.slack.com/archives/C07RX27HW4U/p1729724660779979

[marko-lisica]

@georgekarrv heads up, this is ready to spec.