Discharge7443/fleet
1
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

Remove support property from fleetctl docs. Edit run queries by name endpoint in api docs (#429)

Browse Source 
This PR includes two documentation fixes.

1. Remove the support property from the osquery queries spec in the fleetctl docs. The support property is not a feature of osquery or Fleet.
2. Edit the api/v1/fleet/queries/run_by_names with accurate examples. This endpoint sends query targets (hosts and labels) by name (hostname and label name). Contrast this with the api/v1/fleet/queries/run which sends query targets by id (host id and label id)

Resolves #409
This commit is contained in:
noahtalerman
2021-03-09 15:41:10 -08:00
committed by GitHub
parent b93b2c5b6a
commit 06dc4c53f7
2 changed files with 66 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/1-Using-Fleet/2-fleetctl-CLI.md
-8
View File
@@ -275,11 +275,6 @@ spec:
name: docker_processes
description: The docker containers processes that are running on a system.
query: select * from docker_container_processes;
support:
osquery: 2.9.0
platforms:
- linux
- darwin
```
To define multiple queries in a file, concatenate multiple `query` resources together in a single file with `---`. For example, consider a file that you might store at `queries/osquery_monitoring.yml`:
@@ -291,9 +286,6 @@ spec:
name: osquery_version
description: The version of the Launcher and Osquery process
query: select launcher.version, osquery.version from kolide_launcher_info launcher, osquery_info osquery;
support:
launcher: 0.3.0
osquery: 2.9.0
---
apiVersion: v1
kind: query
docs/1-Using-Fleet/3-REST-API.md
+66 -17
View File
@@ -2378,7 +2378,7 @@ Runs the specified query as a live query on the specified hosts or group of host
| Name | Type | In | Description |
| ---------- | ------- | ---- | ------------------------------------------------ |
| query | string | body | **Required.** The SQL of the query |
| selected | object | body | **Required.** The desired targets for the query. This object must contain `hosts` and `labels` properties. See example below |
| selected | object | body | **Required.** The desired targets for the query specified by ID. This object can contain `hosts` and/or `labels` properties. See examples below. |
#### Example with one host targeted by ID
@@ -2389,7 +2389,9 @@ Runs the specified query as a live query on the specified hosts or group of host
```
{
"query": "select instance_id from system_info;",
"selected": { "hosts": [171], "labels": []}
"selected": {
"hosts": [171]
}
}
```
@@ -2409,8 +2411,8 @@ Runs the specified query as a live query on the specified hosts or group of host
"MissingInActionHosts": 0,
"NewHosts": 1
},
"id": 273,
"query_id": 293,
"id": 1,
"query_id": 3,
"status": 0,
"user_id": 1
}
@@ -2426,7 +2428,9 @@ Runs the specified query as a live query on the specified hosts or group of host
```
{
"query": "select instance_id from system_info;",
"selected": { "hosts": [171], "labels": []}
"selected": {
"labels": [7]
}
}
```
@@ -2440,23 +2444,23 @@ Runs the specified query as a live query on the specified hosts or group of host
"created_at": "0001-01-01T00:00:00Z",
"updated_at": "0001-01-01T00:00:00Z",
"Metrics": {
"TotalHosts": 1,
"TotalHosts": 102,
"OnlineHosts": 0,
"OfflineHosts": 1,
"OfflineHosts": 24,
"MissingInActionHosts": 0,
"NewHosts": 1
"NewHosts": 0
},
"id": 273,
"query_id": 293,
"id": 2,
"query_id": 3,
"status": 0,
"user_id": 1
}
}
```
### Run live query by query name
### Run live query by name
Runs the specified query by name as a live query on the specified hosts or group of hosts. Returns a new live query campaign. Individual hosts must be specified with the host's ID. Groups of hosts are specified by label.
Runs the specified query as a live query on the specified hosts or group of hosts. Returns a new live query campaign. Individual hosts must be specified with the host's hostname. Groups of hosts are specified by label name.
`POST /api/v1/fleet/queries/run_by_names`
@@ -2465,9 +2469,9 @@ Runs the specified query by name as a live query on the specified hosts or group
| Name | Type | In | Description |
| ---------- | ------- | ---- | ------------------------------------------------ |
| name | string | body | **Required.** The name of the query. |
| selected | object | body | **Required.** The desired targets for the query. This object must contain `hosts` and `labels` properties. See example below. |
| selected | object | body | **Required.** The desired targets for the query specified by name. This object can contain `hosts` and/or `labels` properties. See examples below. |
#### Example with one host targeted
#### Example with one host targeted by hostname
`POST /api/v1/fleet/queries/run_by_names`
@@ -2476,7 +2480,11 @@ Runs the specified query by name as a live query on the specified hosts or group
```
{
"name": "instance_id",
"selected": { "hosts": [171], "labels": [] }
"selected": {
"hosts": [
"macbook-pro.local",
]
}
}
```
@@ -2496,8 +2504,49 @@ Runs the specified query by name as a live query on the specified hosts or group
"MissingInActionHosts": 0,
"NewHosts": 1
},
"id": 275,
"query_id": 295,
"id": 1,
"query_id": 3,
"status": 0,
"user_id": 1
}
}
```
#### Example with multiple hosts targeted by label name
`POST /api/v1/fleet/queries/run_by_names`
##### Request body
```
{
"name": "instance_id",
"selected": {
"labels": [
"All Hosts"
]
}
}
```
##### Default response
`Status: 200`
```
{
"campaign": {
"created_at": "0001-01-01T00:00:00Z",
"updated_at": "0001-01-01T00:00:00Z",
"Metrics": {
"TotalHosts": 102,
"OnlineHosts": 0,
"OfflineHosts": 24,
"MissingInActionHosts": 0,
"NewHosts": 1
},
"id": 2,
"query_id": 3,
"status": 0,
"user_id": 1
}