API design: Uninstall software #21548

marko-lisica · 2024-08-26T13:12:40Z

UPDATE: I closed this PR and opened a new one here (w/ same changes) against the docs-v4.57.0 branch.

As of 4.57.0, each minor release has it's own reference docs branch as part of a new process to make sure that every change to how Fleet is used is reflected live on the website in reference documentation at release day: https://github.com/fleetdm/fleet/pull/22284/files#diff-d426c2ae6cac2a2baffd54adae00ad7bb936dbb17a873f93a327d5763f7fb574R141

API design for: #20320

RachelElysia · 2024-08-28T01:28:16Z

docs/REST API/rest-api.md

+
+#### Example
+
+`POST /api/v1/fleet/hosts/123/software/uinstall/3435`


typo *uninstall

TODO: change this to
POST /api/v1/fleet/hosts/123/software/3435/uninstall

And breaking change (because this is experimental) for existing install as well
POST /api/v1/fleet/hosts/123/software/3435/install

RachelElysia · 2024-08-28T02:21:02Z

docs/REST API/rest-api.md

 | pre_install_query  | string | form | Query that is pre-install condition. If the query doesn't return any result, Fleet won't proceed to install. |
 | post_install_script | string | form | The contents of the script to run after install. If the specified script fails (exit code non-zero) software install will be marked as failed and rolled back. |
 | self_service | boolean | form | Self-service software is optional and can be installed by the end user. |
+| uninstall_script  | string | form | Script that Fleet runs to uninstall software. If not specified Fleet runs [default uninstall script](https://github.com/fleetdm/fleet/tree/f71a1f183cc6736205510580c8366153ea083a8d/pkg/file/scripts) for each package type. |
+


Should we add uninstall_script to the example below?

#### Example `POST /api/v1/fleet/software/package`

RachelElysia · 2024-08-28T02:23:55Z

docs/REST API/rest-api.md

+##### Default response
+
+`Status: 202`
+


Should we add uninstall_script_output to the default response below?

RachelElysia

We should update API-for-contributors.md in several spots as well:

POST /api/v1/fleet/spec/teams
1. software.packages description
2. Example request body
POST /api/v1/fleet/software/batch
3. software.packages description

…install and /uninstall in API

docs/REST API/rest-api.md

RachelElysia · 2024-08-30T20:18:01Z

docs/REST API/rest-api.md

@@ -9172,7 +9249,32 @@ _Available in Fleet Premium._

 Install software (package or App Store app) on a macOS, iOS, iPadOS, Windows, or Linux (Ubuntu) host. Software title must have a `software_package` or `app_store_app` added to be installed.

-`POST /api/v1/fleet/hosts/:id/software/install/:software_title_id`
+`POST /api/v1/fleet/hosts/:id/software/:software_title_id/install`


Proposed breaking change

Interpreting "proposed" as we want to do it, making the change now. If proposed means there is still conversation around it let us know please.

^ @noahtalerman

@jacobshandling Yes, we are breaking this.

@rachaelshaw will do a final pass on API docs

docs/REST API/rest-api.md

Co-authored-by: Rachael Shaw <r@rachael.wtf>

docs/REST API/rest-api.md

Co-authored-by: Rachael Shaw <r@rachael.wtf>

docs/REST API/rest-api.md

Co-authored-by: jacobshandling <61553566+jacobshandling@users.noreply.github.com>

RachelElysia · 2024-09-06T14:23:35Z

docs/REST API/rest-api.md

+        "failed_install": 0,
+        "pending_uninstall": 2,
+        "failed_uninstall": 1
+      }
        "installed": 3,


TODO @RachelElysia: commit to remove old status (just applied Jacob's suggested changes that added correct statuses but didn't remove old status)

jacobshandling · 2024-09-10T00:37:53Z

docs/REST API/rest-api.md

+        "host_display_name": "Marko’s MacBook Pro",
+        "software_title": "Adobe Acrobat.app",
+        "script_execution_id": "ecf22dba-07dc-40a9-b122-5480e948b756",
+        "status": "failed"


@getvictor @noahtalerman this "failed" value throws a bit of a curveball – having the potential values here match those from software titles / below would both make intuitive sense and help simplify/unify the frontend code:
export const SOFTWARE_INSTALL_STATUSES = [ "installed", "uninstalled", "pending_install", "failed_install", "pending_uninstall", "failed_uninstall", ] as const;

Does that make sense from your points of view?

Well, uninstalled is not a software install status. After software is uninstalled, the status goes to null, which means available for install.

So I'll pull that out of this array. Do you think changing failed to failed_uninstall will work here?

I'm OK with failed_uninstall. But what do you want as the activity status when uninstall succeeded?

uninstalled?

which is what it currently is:

The array above, by the way, is being used by the frontend in a number of ways, including generating types for activities, not just to define the API response types

Hey @jacobshandling and @getvictor heads up that I think we went w/ one failed to be consistent w/ configuration profile status.

Failed install and failed removal for profiles are both failed:

Not sure if that still makes sense here but just wanted to call it out.

@noahtalerman thanks for the added context. I'll look into making it work as specified with "failed" today

Okay, should work with "failed" here cc @getvictor, no need to change it. Thanks all.

jacobshandling · 2024-09-10T20:22:44Z

docs/REST API/rest-api.md

@@ -9183,7 +9290,7 @@ Install software (package or App Store app) on a macOS, iOS, iPadOS, Windows, or

 #### Example

-`POST /api/v1/fleet/hosts/123/software/install/3435`
+`POST /api/v1/fleet/hosts/123/software/3435/uninstall`


jacobshandling · 2024-09-10T20:23:06Z

docs/REST API/rest-api.md

@@ -9193,7 +9300,7 @@ Install software (package or App Store app) on a macOS, iOS, iPadOS, Windows, or

 _Available in Fleet Premium._

-`GET /api/v1/fleet/software/install/results/:install_uuid`
+`GET /api/v1/fleet/software/install/:install_uuid/results`


noahtalerman · 2024-09-23T20:28:20Z

Hey @marko-lisica heads up, I closed this PR and opened a new one here (w/ same changes)

Update rest-api.md

fb99735

marko-lisica had a problem deploying to Docker Hub August 26, 2024 13:12 — with GitHub Actions Error

Update rest-api.md

16ba73b

marko-lisica had a problem deploying to Docker Hub August 26, 2024 13:18 — with GitHub Actions Error

Update rest-api.md

fa2ccb3

marko-lisica had a problem deploying to Docker Hub August 26, 2024 13:21 — with GitHub Actions Error

Update rest-api.md

ddab6f3

marko-lisica had a problem deploying to Docker Hub August 26, 2024 13:23 — with GitHub Actions Error

Update rest-api.md

a344dcc

marko-lisica temporarily deployed to Docker Hub August 26, 2024 13:24 — with GitHub Actions Inactive

marko-lisica mentioned this pull request Aug 26, 2024

Uninstall packages #20320

Closed

10 tasks

Update rest-api.md

c80aa43

marko-lisica temporarily deployed to Docker Hub August 27, 2024 13:32 — with GitHub Actions Inactive

RachelElysia reviewed Aug 28, 2024

View reviewed changes

Add API design for activities into draft API PR as source of truth

b71647f

RachelElysia had a problem deploying to Docker Hub August 30, 2024 19:51 — with GitHub Actions Error

Update docs with breaking change to have software identifier before /…

3819390

…install and /uninstall in API

RachelElysia temporarily deployed to Docker Hub August 30, 2024 19:58 — with GitHub Actions Inactive

RachelElysia reviewed Aug 30, 2024

View reviewed changes

docs/REST API/rest-api.md Outdated Show resolved Hide resolved

RachelElysia reviewed Aug 30, 2024

View reviewed changes

rachaelshaw requested changes Sep 3, 2024

View reviewed changes

docs/REST API/rest-api.md Outdated Show resolved Hide resolved

rachaelshaw mentioned this pull request Sep 3, 2024

Update "Resend host's configuration profile" API URL #21795

Open

15 tasks

Update docs/REST API/rest-api.md

2c5cfc7

Co-authored-by: Rachael Shaw <r@rachael.wtf>

RachelElysia temporarily deployed to Docker Hub September 4, 2024 15:35 — with GitHub Actions Inactive

rachaelshaw requested changes Sep 4, 2024

View reviewed changes

docs/REST API/rest-api.md Outdated Show resolved Hide resolved

Update docs/REST API/rest-api.md

e0047ac

Co-authored-by: Rachael Shaw <r@rachael.wtf>

RachelElysia temporarily deployed to Docker Hub September 4, 2024 18:07 — with GitHub Actions Inactive

jacobshandling reviewed Sep 5, 2024

View reviewed changes

docs/REST API/rest-api.md Show resolved Hide resolved

jacobshandling reviewed Sep 5, 2024

View reviewed changes

docs/REST API/rest-api.md Show resolved Hide resolved

Update status responses (breaking change)

5ef8abf

Co-authored-by: jacobshandling <61553566+jacobshandling@users.noreply.github.com>

RachelElysia temporarily deployed to Docker Hub September 6, 2024 14:21 — with GitHub Actions Inactive

RachelElysia reviewed Sep 6, 2024

View reviewed changes

Update uninstall activities in rest-api.md

5e71c0a

jacobshandling reviewed Sep 10, 2024

View reviewed changes

Added created_at to script results.

8270c57

noahtalerman closed this Sep 23, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API design: Uninstall software #21548

API design: Uninstall software #21548

marko-lisica commented Aug 26, 2024 •

edited by noahtalerman

Loading

RachelElysia Aug 28, 2024

RachelElysia Aug 30, 2024

RachelElysia Aug 28, 2024

RachelElysia Aug 28, 2024

RachelElysia left a comment

RachelElysia Aug 30, 2024

jacobshandling Sep 7, 2024

jacobshandling Sep 7, 2024

RachelElysia Sep 9, 2024

RachelElysia Sep 6, 2024

jacobshandling Sep 10, 2024

getvictor Sep 10, 2024

jacobshandling Sep 10, 2024 •

edited

Loading

getvictor Sep 10, 2024

jacobshandling Sep 10, 2024

jacobshandling Sep 10, 2024

jacobshandling Sep 10, 2024

noahtalerman Sep 11, 2024

jacobshandling Sep 11, 2024

jacobshandling Sep 11, 2024

jacobshandling Sep 10, 2024

jacobshandling Sep 10, 2024

noahtalerman commented Sep 23, 2024


		#### Example

		`POST /api/v1/fleet/hosts/123/software/uinstall/3435`

API design: Uninstall software #21548

API design: Uninstall software #21548

Conversation

marko-lisica commented Aug 26, 2024 • edited by noahtalerman Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

RachelElysia left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jacobshandling Sep 10, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

noahtalerman commented Sep 23, 2024

marko-lisica commented Aug 26, 2024 •

edited by noahtalerman

Loading

jacobshandling Sep 10, 2024 •

edited

Loading