From 3cbf71dcf6e60ab4bfefc045ce60e0e8aeae454d Mon Sep 17 00:00:00 2001 From: Konstantin Sykulev Date: Thu, 21 Nov 2024 12:54:10 -0600 Subject: [PATCH] Updated docs around new label(s) validation As of https://github.com/fleetdm/fleet/pull/23834 specifying invalid label(s) raises an error. Modified docs to ensure this is clear. Specified in `fleetctl query` command usage that labels target hosts with "any of" the labels. --- cmd/fleetctl/query.go | 8 ++++- docs/Contributing/API-for-contributors.md | 37 +++++++++++++++++++++-- 2 files changed, 42 insertions(+), 3 deletions(-) diff --git a/cmd/fleetctl/query.go b/cmd/fleetctl/query.go index e54fbee2bc08..6866a5a5c1c9 100644 --- a/cmd/fleetctl/query.go +++ b/cmd/fleetctl/query.go @@ -24,6 +24,12 @@ func queryCommand() *cli.Command { Name: "query", Usage: "Run a live query", UsageText: `fleetctl query [options]`, + Description: `Runs the specified query as a live query on the specified targets. + +Using the --hosts flag individual hosts can be specified with the host's hostname. Groups of hosts can +specified by using labels. Note if both the --hosts and --labels flags are specified, the query will +be run on the union of the hosts and hosts with matching labels. + `, Flags: []cli.Flag{ &cli.StringFlag{ Name: "hosts", @@ -37,7 +43,7 @@ func queryCommand() *cli.Command { EnvVars: []string{"LABELS"}, Value: "", Destination: &flLabels, - Usage: "Comma-separated label names to target", + Usage: "Comma-separated label names to target. Hosts with any of the labels will be targeted.", }, &cli.BoolFlag{ Name: "quiet", diff --git a/docs/Contributing/API-for-contributors.md b/docs/Contributing/API-for-contributors.md index 18cfc569f63b..66fdd0dec576 100644 --- a/docs/Contributing/API-for-contributors.md +++ b/docs/Contributing/API-for-contributors.md @@ -2371,7 +2371,7 @@ Runs the specified saved query as a live query on the specified targets. Returns After the query has been initiated, [get results via WebSocket](#retrieve-live-query-results-standard-websocket-api). -`POST /api/v1/fleet/queries/run_by_names` +`POST /api/v1/fleet/queries/run_by_identifiers` #### Parameters @@ -2379,7 +2379,7 @@ After the query has been initiated, [get results via WebSocket](#retrieve-live-q | -------- | ------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | query | string | body | The SQL of the query. | | query_id | integer | body | The saved query (if any) that will be run. The `observer_can_run` property on the query effects which targets are included. | -| selected | object | body | **Required.** The object includes lists of selected hostnames (`selected.hosts`), label names (`labels`). When provided, builtin label names and custom label names become `AND` filters. Within each selector, selecting two or more builtin labels, or two or more custom labels, behave as `OR` filters. There's one special case for the builtin label `"All hosts"`, if such label is selected, then all other label and team selectors are ignored (and all hosts will be selected). If a host's hostname is explicitly included in `selected.hosts`, then it is assured that the query will be selected to run on it (no matter the contents of `selected.labels`). See examples below. | +| selected | object | body | **Required.** The object includes lists of selected hostnames (`selected.hosts`), label names (`labels`). When provided, builtin label names and custom label names become `AND` filters. Within each selector, selecting two or more builtin labels, or two or more custom labels, behave as `OR` filters. If a label provided could not be found in the database, a 400 bad request will be returned specifying which label is invalid. There's one special case for the builtin label `"All hosts"`, if such label is selected, then all other label and team selectors are ignored (and all hosts will be selected). If a host's hostname is explicitly included in `selected.hosts`, then it is assured that the query will be selected to run on it (no matter the contents of `selected.labels`). See examples below. | One of `query` and `query_id` must be specified. @@ -2461,6 +2461,39 @@ One of `query` and `query_id` must be specified. } ``` +#### Example with invalid label + +`POST /api/v1/fleet/queries/run_by_names` + +##### Request body + +```json +{ + "query": "SELECT instance_id FROM system_info", + "selected": { + "labels": ["Windows", "Banana", "Apple"] + } +} +``` + +##### Default response + +`Status: 400` + +```json +{ + "message": "Bad request", + "errors": [ + { + "name": "base", + "reason": "Invalid label name(s): Banana, Apple." + } + ], + "uuid": "303649f4-5e45-4379-bae9-64ec0ef56287" +} +``` + + ### Retrieve live query results (standard WebSocket API) You can retrieve the results of a live query using the [standard WebSocket API](#https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_client_applications).