API endpoint for updating a host's labels #16767

dherder · 2024-02-13T02:05:17Z

Goal

User story
As an IT admin building a Tines automation to receive "group update" webhooks from my Identity Provider (ex. Okta),
I want to hit a Fleet API endpoint to update a host's labels
so that I can target this host with configuration profiles and scheduled queries specific to the IdP group.

Context

Requestor(s): @dherder
Product designer: @marko-lisica

Here's a flow chart that describes how would user use new endpoints to add label based on IdP groups.

Changes

Product

REST API changes: API design: API endpoint for updating a host's manual labels #16979
- Errors: Figma link
- Add labels API returns success If a host already has labels that are specified in the API call
- Remove labels API returns success if a host doesn't have labels that are specified in the API call
Permissions changes: Admin, Maintainer, and GitOps roles should be able to update the host's labels. Team users should be able to update labels for hosts that belong to the teams they are assigned to.
Outdated documentation changes: TODO: Article
Changes to paid features or tiers: Available for Free and Premium.

Engineering

Database schema migrations: TODO
Load testing: TODO

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

QA

Manual labels do not have a "SQL query", they are set to hosts manually using the new API.
In 4.49.0 we added the UI to create manual labels (previously only possible via fleetctl apply): #17031.

Following are the APIs (to QA) to add/delete a manual label/s to/from a host:

curl -k -v -X POST -H "Authorization: Bearer $TEST_TOKEN" https://localhost:8080/api/latest/fleet/hosts/1/labels -d '{"labels": ["Manually Managed Example"]}'

curl -k -v -X DELETE -H "Authorization: Bearer $TEST_TOKEN" https://localhost:8080/api/latest/fleet/hosts/1/labels -d '{"labels": ["Manually Managed Example"]}'

Expected behavior and error codes are in the Figma link.

Risk assessment

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

Manual testing steps

Step 1
Step 2
Step 3

Testing notes

Confirmation

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

The text was updated successfully, but these errors were encountered:

noahtalerman · 2024-02-13T14:06:55Z

other solution would be to cache all the mappings to a yaml file and then apply them in a single config

@dherder this is the best practice.

More context in Slack here (internal): https://fleetdm.slack.com/archives/C02A8BRABB5/p1707832511131959?thread_ts=1707790448.922139&cid=C02A8BRABB5

Happy to chat about this during a call.

Removing this from feature fest for now. Please let me know if the best practice YAML file won't work. I could be wrong.

dherder · 2024-02-13T23:20:34Z

For purposes of rate limiting calls from Okta, it would be desirable to PATCH from an event detected in Okta to Tines (or some other automation tool), then to Fleet. @noahtalerman fyi

noahtalerman · 2024-02-19T18:43:56Z

Original issue description from @dherder:

Documentation for applying manual labels: https://github.com/fleetdm/fleet/blob/main/docs/Contributing/API-for-contributors.md#apply-labels

There is no way to PATCH or DELETE to an existing label, which means a CPE will have to enumerate all hosts when sync'ing IdP groups to labels. In the workflow described in #15633, updating will be mandatory.

Problem

Need to support PATCH and DELETE to https://github.com/fleetdm/fleet/blob/main/docs/Contributing/API-for-contributors.md#apply-labels

dherder · 2024-02-21T01:26:17Z

@noahtalerman and @marko-lisica do you think we would also be able to modify the labels with fields like serial_number, uuid, host_id? Feedback from prospect-rosner is that using hostname is pretty fragile, as hostnames can change quite frequently.

marko-lisica · 2024-02-21T15:41:55Z

@noahtalerman and @marko-lisica do you think we would also be able to modify the labels with fields like serial_number, uuid, host_id? Feedback from prospect-rosner is that using hostname is pretty fragile, as hostnames can change quite frequently.

Hey @dherder, thanks for raising this. I think this is very good feedback. I discussed this with @noahtalerman, and we think this should be a separate story. Here's the feature request: #17031

noahtalerman · 2024-02-22T19:45:53Z

Hey @marko-lisica, it looks like the current Create label only supports dynamic (query based) labels.

Is that right? Is there no way to create a manual label via an endpoint in the user facing docs?

(I know we have an endpoint for fleetctl in the contributor docs)

marko-lisica · 2024-02-26T11:55:40Z

Hey @marko-lisica, it looks like the current Create label only supports dynamic (query based) labels.

Is that right? Is there no way to create a manual label via an endpoint in the user facing docs?

(I know we have an endpoint for fleetctl in the contributor docs)

As far as I know, it's only possible to create manual label through POST /api/v1/fleet/spec/labels

noahtalerman · 2024-02-27T23:26:17Z

Hey @marko-lisica your "New employee hired" flow makes sense to me! I think we can move this issue to "Settled."

You're right that Fleet doesn't have a webhook for this yet:

This is tracked in a feature request here: #14722

Sending webhooks at enrollment time is core to Fleet (play nice w/ other tools). We'll weigh it at the upcoming feature fest.

cc @n8felton @dherder

noahtalerman · 2024-02-27T23:26:30Z

@marko-lisica when you get the chance, can you please add the link to the Figma page w/ your workflows?

This way, other contributors can check them out to understand the full flow.

A good spot for that could be the "Context" section of the issue.

georgekarrv · 2024-03-06T17:24:40Z

Hey team! Please add your planning poker estimate with Zenhub @dantecatalfamo @ghernandez345 @gillespi314 @jahzielv @mna @roperzh

noahtalerman · 2024-04-01T19:52:08Z

Hey @dherder, heads up, this feature won't make it into the upcoming 4.48 release.

Plan is to ship this in the 4.49 release.

cc ~~@georgekarrv~~ Whoops meant to tag @sharon-fdm

noahtalerman · 2024-04-01T19:52:55Z

FYI @Patagonia121 ^

noahtalerman · 2024-04-01T20:26:32Z

this feature won't make it into the upcoming 4.48 release.

Plan is to ship this in the 4.49 release.

Also, FYI @spokanemac for the release article.

georgekarrv · 2024-04-15T20:34:03Z

#18268 This is the ticket we have for MDM this sprint, did we duplicate work needlessly?

georgekarrv · 2024-04-15T20:35:03Z

On the surface they sounds the same. I could be wrong though

#16767 To create a manual label: ```sh cat labels.yml --- apiVersion: v1 kind: label spec: name: Manually Managed Example label_membership_type: manual hosts: - lucass-macbook-pro.local ``` To add/delete a manual label to/from a host: ``` curl -k -v -X POST -H "Authorization: Bearer $TEST_TOKEN" https://localhost:8080/api/latest/fleet/hosts/1/labels -d '{"labels": ["Manually Managed Example"]}' curl -k -v -X DELETE -H "Authorization: Bearer $TEST_TOKEN" https://localhost:8080/api/latest/fleet/hosts/1/labels -d '{"labels": ["Manually Managed Example"]}' ``` API draft changes: https://github.com/fleetdm/fleet/pull/16979/files Figma with error strings: https://www.figma.com/file/JiWoAiuHlkt76s3o3Uyz6h/%2316767-API-endpoint-for-updating-a-host's-manual-labels?type=design&node-id=2-130&mode=design&t=pxRPhrn6E1bOCrEd-0 - [X] Changes file added for user-visible changes in `changes/`, `orbit/changes/` or `ee/fleetd-chrome/changes`. See [Changes files](https://fleetdm.com/docs/contributing/committing-changes#changes-files) for more information. - [X] Input data is properly validated, `SELECT *` is avoided, SQL injection is prevented (using placeholders for values in statements) ~- [ ] Added support on fleet's osquery simulator `cmd/osquery-perf` for new osquery data ingestion features.~ - [X] Added/updated tests - ~[ ] If database migrations are included, checked table schema to confirm autoupdate~ - ~For database migrations:~ - ~[ ] Checked schema for all modified table for columns that will auto-update timestamps during migration.~ - ~[ ] Confirmed that updating the timestamps is acceptable, and will not cause unwanted side effects.~ - ~[ ] Ensured the correct collation is explicitly set for character columns (`COLLATE utf8mb4_unicode_ci`).~ - [x] Manual QA for all new/changed functionality - ~For Orbit and Fleet Desktop changes:~ - ~[ ] Manual QA must be performed in the three main OSs, macOS, Windows and Linux.~ - ~[ ] Auto-update manual QA, from released version of component to new version (see [tools/tuf/test](../tools/tuf/test/README.md)).~

lucasmrod · 2024-04-18T16:06:20Z

@xpkoala I've added QA notes to the description.

rachaelshaw · 2024-04-25T18:33:46Z

@dherder @Patagonia121 this was shipped in v4.49.0

rachaelshaw · 2024-04-25T18:34:37Z

PR to the docs is here: #16979

API design for: - #16767 --------- Co-authored-by: Rachael Shaw <r@rachael.wtf>

fleet-release · 2024-05-02T18:32:56Z

API endpoint blooms,
Labels adjust with ease, like
Clouds in glass cities.

dherder added :product Product Design department (shows up on 🦢 Drafting board) ~feature fest Will be reviewed at next Feature Fest customer-rosner labels Feb 13, 2024

noahtalerman removed :product Product Design department (shows up on 🦢 Drafting board) ~feature fest Will be reviewed at next Feature Fest customer-rosner labels Feb 13, 2024

dherder added customer-rosner ~feature fest Will be reviewed at next Feature Fest labels Feb 13, 2024

noahtalerman added the story A user story defining an entire feature label Feb 15, 2024

noahtalerman changed the title ~~Add PATCH for updating manual labels~~ API endpoint for updating a host's manual labels Feb 15, 2024

noahtalerman added customer-sarahwu :product Product Design department (shows up on 🦢 Drafting board) and removed ~feature fest Will be reviewed at next Feature Fest labels Feb 16, 2024

noahtalerman assigned rachaelshaw and marko-lisica and unassigned rachaelshaw Feb 16, 2024

marko-lisica mentioned this issue Feb 20, 2024

API design: API endpoint for updating a host's manual labels #16979

Merged

noahtalerman changed the title ~~API endpoint for updating a host's manual labels~~ API endpoint for updating a host's labels Feb 22, 2024

marko-lisica assigned georgekarrv and unassigned marko-lisica Feb 28, 2024

georgekarrv added the #g-mdm MDM product group label Feb 28, 2024

sharon-fdm added #g-endpoint-ops Endpoint ops product group and removed #g-mdm MDM product group labels Mar 11, 2024

sharon-fdm assigned lucasmrod and unassigned georgekarrv Mar 11, 2024

sharon-fdm added :release Ready to write code. Scheduled in a release. See "Making changes" in handbook. and removed :product Product Design department (shows up on 🦢 Drafting board) labels Mar 11, 2024

lukeheath added this to the 4.48.0-tentative milestone Mar 11, 2024

spokanemac mentioned this issue Mar 11, 2024

Release article: v4.48.0 #17531

Closed

1 task

sharon-fdm modified the milestones: 4.48.0-tentative, 4.49.0-tentative Apr 1, 2024

lucasmrod mentioned this issue Apr 15, 2024

New APIs to add/remove manual labels to/from a host #18283

Merged

4 tasks

nonpunctual added ~csa Issue was created by or deemed important by the Customer Solutions Architect. ~feature fest Will be reviewed at next Feature Fest labels Apr 22, 2024

lukeheath added :product Product Design department (shows up on 🦢 Drafting board) #g-endpoint-ops Endpoint ops product group and removed ~feature fest Will be reviewed at next Feature Fest #g-endpoint-ops Endpoint ops product group labels Apr 24, 2024

rachaelshaw added a commit that referenced this issue Apr 25, 2024

API design: API endpoint for updating a host's manual labels (#16979)

a0a8579

API design for: - #16767 --------- Co-authored-by: Rachael Shaw <r@rachael.wtf>

rachaelshaw closed this as completed May 2, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API endpoint for updating a host's labels #16767

API endpoint for updating a host's labels #16767

dherder commented Feb 13, 2024 •

edited by lucasmrod

Loading

noahtalerman commented Feb 13, 2024

dherder commented Feb 13, 2024

noahtalerman commented Feb 19, 2024

dherder commented Feb 21, 2024

marko-lisica commented Feb 21, 2024

noahtalerman commented Feb 22, 2024

marko-lisica commented Feb 26, 2024

noahtalerman commented Feb 27, 2024

noahtalerman commented Feb 27, 2024

georgekarrv commented Mar 6, 2024

noahtalerman commented Apr 1, 2024 •

edited

Loading

noahtalerman commented Apr 1, 2024

noahtalerman commented Apr 1, 2024

georgekarrv commented Apr 15, 2024

georgekarrv commented Apr 15, 2024

lucasmrod commented Apr 18, 2024

rachaelshaw commented Apr 25, 2024

rachaelshaw commented Apr 25, 2024

fleet-release commented May 2, 2024

API endpoint for updating a host's labels #16767

API endpoint for updating a host's labels #16767

Comments

dherder commented Feb 13, 2024 • edited by lucasmrod Loading

Goal

Context

Changes

Product

Engineering

QA

Risk assessment

Manual testing steps

Testing notes

Confirmation

noahtalerman commented Feb 13, 2024

dherder commented Feb 13, 2024

noahtalerman commented Feb 19, 2024

Problem

dherder commented Feb 21, 2024

marko-lisica commented Feb 21, 2024

noahtalerman commented Feb 22, 2024

marko-lisica commented Feb 26, 2024

noahtalerman commented Feb 27, 2024

noahtalerman commented Feb 27, 2024

georgekarrv commented Mar 6, 2024

noahtalerman commented Apr 1, 2024 • edited Loading

noahtalerman commented Apr 1, 2024

noahtalerman commented Apr 1, 2024

georgekarrv commented Apr 15, 2024

georgekarrv commented Apr 15, 2024

lucasmrod commented Apr 18, 2024

rachaelshaw commented Apr 25, 2024

rachaelshaw commented Apr 25, 2024

fleet-release commented May 2, 2024

dherder commented Feb 13, 2024 •

edited by lucasmrod

Loading

noahtalerman commented Apr 1, 2024 •

edited

Loading