Edit software - Usage docs

[RachelElysia]

Related to

#21840

Plan

• Update https://fleetdm.com/guides/deploy-security-agents (which is secretly an Install package guide) into an install package guide and include the major features (Uninstall packages #20320 and Edit packages #20404) into it

Key changes and additions

Changes

Title and introduction

• Change the title to "Deploy software"
• Rewrite the introduction to focus on adding general software packages rather than specifically security agents
• Rewrite "pre-enrollment osquery query" to use "pre-install query" to match UI

Prerequisites:

• Update the prerequisite from 4.50 to 4.57
• Keep all prerequisites, specific mention of fleetd with scripts enabled is key

Step-by-step instructions

• Reorder steps as install script is now under advanced options
• Rename pre-install condition to pre-install query
• Clean up instructions how to install software on a host

Throughout the document:

• Replace "security agent" or "security agents" with "software package" or "software packages"
• confirm: Remove specific mentions of security agent configuration, such as key and license deployment?

API and GitOps sections:

• Keep these sections but reword them to refer to software packages in general rather than security agents specifically

Conclusion:

• Rewrite to focus on the benefits of managing software packages with Fleet rather than specifically deploying security agents

Metadata:

• Update the article title, description, and other relevant metadata to reflect the new focus on adding, editing, uninstalling software packages

Additions (new additions in 4.57)

Title and introduction

• Include mention of uninstalling scripts
• Include mention of being able to edit software
• Include mention that 4.57 is required to edit or uninstall software

Step-by-step instructions

• In the "Add" section, add uninstall script
• In the "Add" section, mention of being able to edit later if need be
• Update to edit a software package to include instructions
• Mention when pending installations and uninstallations will be cancelled on edit
• Add link to learn more about install scripts (part of Default install script for .exe doesn't work in most cases #20000 / Uninstall packages #20320 )
• Add link to learn more about uninstall scripts (part of Uninstall packages #20320)
• Create a new "Uninstall" section with steps to uninstall software

Remove software sections:

• Add what happens to pending actions when a software package is removed
• Call out potential race conditions when cancelling pending installs/uninstalls.

API and GitOps sections:

• Add link to install and uninstall software API docs

[lukeheath]

@RachelElysia Thanks again for catching this!

The plan is @RachelElysia will get this started and then hand off to @iansltx to fill in any additional details. @iansltx will hand it off to @spokanemac who will update the https://fleetdm.com/guides/deploy-security-agents guide to be a "Deploy software" guide (or something similar that JD decides). This update will be made as part of 4.57.0. We'll use the same process for the uninstall software docs.

Thanks all! Let me know if there are any questions.

[iansltx]

Plan LGTM.

@spokanemac what format do you want me to hand off in, that'll make it easier for you to go the rest of the way. Was planning to just PR changes to the guide Markdown since it's not a long article, so your responsibility would just be doing a final pass on that?

Are we going to rename the article, and if so are we going to do anything to address link rot?

[spokanemac]

@iansltx Let's use https://docs.google.com/document/d/1aypfJZOUZN5q7PxOQXoBaHOfIYrml-JEGzcUvbB1rw8/edit . I pulled the latest version into here. As part of this, we'll update the verbiage to align with deploying software.

[iansltx]

• Need to remember to call out potential race conditions when cancelling pending installs/uninstalls.

[iansltx]

As a heads-up, the learn-more links listed above don't actually lead anywhere, so I've dropped them back out of the article, and reformatted the article to include anchors that are destinations for the learn-more links that we already have in the code.

Going to add an EI issue for auditing learn-more links so we don't ship stuff with broken links (and we fix any that are broken).

[fleet-release]

Fleet's improvements soar,
Software edits, installs, more.
Ease for all, encore.