637 lines
12 KiB
Plaintext
637 lines
12 KiB
Plaintext
---
|
|
layout: api
|
|
page_title: Search - HTTP API
|
|
description: The /search endpoint is used to search for Nomad objects
|
|
---
|
|
|
|
# Search HTTP API
|
|
|
|
## Prefix Searching
|
|
|
|
The `/search` endpoint returns matches for a given prefix and context, where a
|
|
context can be jobs, allocations, evaluations, nodes, node pools, deployments,
|
|
plugins, namespaces, or volumes. When using Nomad Enterprise, the allowed
|
|
contexts include quotas. Additionally, a prefix can be searched for within
|
|
every context.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------ | ------------------ |
|
|
| `POST` | `/v1/search` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/nomad/api-docs#blocking-queries) and
|
|
[required ACLs](/nomad/api-docs#acls).
|
|
|
|
| Blocking Queries | ACL Required |
|
|
| ---------------- | ------------------------------------------------ |
|
|
| `NO` | `node:read, node_pool:read, namespace:read-jobs` |
|
|
|
|
When ACLs are enabled, requests must have a token valid for `node:read`,
|
|
`node_pool:read`, or `namespace:read-jobs` roles. If the token is only valid
|
|
for a portion of these capabilities, then results will include results
|
|
including only data readable with the given token.
|
|
|
|
### Parameters
|
|
|
|
- `Prefix` `(string: <required>)` - Specifies the identifier against which
|
|
matches will be found. For example, if the given prefix were "a", potential
|
|
matches might be "abcd", or "aabb".
|
|
- `Context` `(string: <required>)` - Defines the scope in which a search for a
|
|
prefix operates. Contexts can be: "jobs", "evals", "allocs", "nodes",
|
|
"node_pools", "deployment", "plugins", "volumes" or "all", where "all" means
|
|
every context will be searched.
|
|
|
|
### Sample Payload (for all contexts)
|
|
|
|
```json
|
|
{
|
|
"Prefix": "abc",
|
|
"Context": "all"
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
--data @payload.json \
|
|
https://localhost:4646/v1/search
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"Matches": {
|
|
"allocs": null,
|
|
"deployment": null,
|
|
"evals": ["abc2fdc0-e1fd-2536-67d8-43af8ca798ac"],
|
|
"jobs": ["abcde"],
|
|
"nodes": null,
|
|
"plugins": null,
|
|
"volumes": null
|
|
},
|
|
"Truncations": {
|
|
"allocs": "false",
|
|
"deployment": "false",
|
|
"evals": "false",
|
|
"jobs": "false",
|
|
"nodes": "false",
|
|
"plugins": "false",
|
|
"volumes": "false"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Field Reference
|
|
|
|
- `Matches` - A map of contexts to matching arrays of identifiers.
|
|
|
|
- `Truncations` - Search results are capped at 20; if more matches were found for a particular context, it will be `true`.
|
|
|
|
### Sample Payload (for a specific context)
|
|
|
|
```json
|
|
{
|
|
"Prefix": "abc",
|
|
"Context": "evals"
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
--data @payload.json \
|
|
https://localhost:4646/v1/search
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"Matches": {
|
|
"evals": ["abc2fdc0-e1fd-2536-67d8-43af8ca798ac"]
|
|
},
|
|
"Truncations": {
|
|
"evals": "false"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Fuzzy Searching
|
|
|
|
The `/search/fuzzy` endpoint returns partial substring matches for a given
|
|
search term and context, where a context can be jobs, allocations, nodes, node
|
|
pools, plugins, or namespaces. Additionally, fuzzy searching can be done across
|
|
all contexts. For better control over the performance implications of fuzzy
|
|
searching on Nomad servers, aspects of fuzzy searching can be tuned through
|
|
the <code>[search]</code> block in Nomad agent config.
|
|
|
|
Fuzzy search results are ordered starting with closest matching terms. Items of
|
|
a name that exactly matches the search term are listed first.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------------ | ------------------ |
|
|
| `POST` | `/v1/search/fuzzy` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/nomad/api-docs#blocking-queries) and
|
|
[required ACLs](/nomad/api-docs#acls).
|
|
|
|
| Blocking Queries | ACL Required |
|
|
| ---------------- | --------------------------------------------------------------------------- |
|
|
| `NO` | `node:read, node_pool:read, namespace:read-jobs, namespace:csi-list-plugin` |
|
|
|
|
When ACLs are enabled, requests must have a token valid for `node:read`,
|
|
`node_pool:read`, `plugin:read`, or `namespace:read-jobs` roles. If the token
|
|
is only valid for a portion of these capabilities, then results will include
|
|
results including only data readable with the given token.
|
|
|
|
### Parameters
|
|
|
|
- `Text` `(string: <required>)` - Specifies the identifier against which
|
|
matches will be found. For example, if the given text were "py", potential
|
|
fuzzy matches might be "python", "spying", or "happy".
|
|
|
|
- `Context` `(string: <required>)` - Defines the scope in which a search for a
|
|
prefix operates. Contexts can be: "jobs", "allocs", "nodes", "node_pools",
|
|
"plugins", or "all", where "all" means every context will be searched. When
|
|
"all" is selected, additional prefix matches will be included for the
|
|
"deployments", "evals", and "volumes" types. When searching in the "jobs"
|
|
context, results that fuzzy match "groups", "services", "tasks", "images",
|
|
"commands", and "classes" are also included in the results.
|
|
|
|
### Scope
|
|
|
|
Fuzzy match results are accompanied with a `Scope` field which is used to uniquely
|
|
identify the matched object, in a way that the Nomad API can be queried again for
|
|
additional information. The data provided by scope varies depending on the type
|
|
of matched object, described below.
|
|
|
|
### Sample Payload (for jobs)
|
|
|
|
```json
|
|
{
|
|
"Text": "py",
|
|
"Context": "jobs"
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
--data @payload.json \
|
|
https://localhost:4646/v1/search/fuzzy
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"Index": 90,
|
|
"KnownLeader": true,
|
|
"LastContact": 0,
|
|
"Matches": {
|
|
"services": [
|
|
{
|
|
"ID": "python-logger",
|
|
"Scope": [
|
|
"default",
|
|
"example-python",
|
|
"my-spy-app",
|
|
"my-python-task"
|
|
]
|
|
},
|
|
{
|
|
"ID": "super-spy-service",
|
|
"Scope": [
|
|
"default",
|
|
"example-python",
|
|
"my-spy-app"
|
|
]
|
|
}
|
|
],
|
|
"tasks": [
|
|
{
|
|
"ID": "my-python-task",
|
|
"Scope": [
|
|
"default",
|
|
"example-python",
|
|
"my-spy-app"
|
|
]
|
|
}
|
|
],
|
|
"images": [
|
|
{
|
|
"ID": "python:3",
|
|
"Scope": [
|
|
"default",
|
|
"example-python",
|
|
"my-spy-app",
|
|
"my-python-task"
|
|
]
|
|
}
|
|
],
|
|
"jobs": [
|
|
{
|
|
"ID": "example-python",
|
|
"Scope": [
|
|
"default"
|
|
]
|
|
}
|
|
],
|
|
"groups": [
|
|
{
|
|
"ID": "my-spy-app",
|
|
"Scope": [
|
|
"default",
|
|
"example-python"
|
|
]
|
|
}
|
|
]
|
|
},
|
|
"Truncations": {
|
|
"jobs": false
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Scope (jobs)
|
|
|
|
- `Scope[0]` : Namespace
|
|
- `Scope[1]` : Job ID
|
|
|
|
#### Scope (groups)
|
|
|
|
- `Scope[0]` : Namespace
|
|
- `Scope[1]` : Job ID
|
|
|
|
#### Scope (tasks)
|
|
|
|
- `Scope[0]` : Namespace
|
|
- `Scope[1]` : Job ID
|
|
- `Scope[2]` : Group
|
|
|
|
#### Scope (group services)
|
|
|
|
- `Scope[0]` : Namespace
|
|
- `Scope[1]` : Group
|
|
|
|
#### Scope (task services)
|
|
|
|
- `Scope[0]` : Namespace
|
|
- `Scope[1]` : Job ID
|
|
- `Scope[2]` : Group
|
|
- `Scope[3]` : Task
|
|
|
|
#### Scope (commands/images/classes)
|
|
|
|
- `Scope[0]` : Namespace
|
|
- `Scope[1]` : Job ID
|
|
- `Scope[2]` : Group
|
|
- `Scope[3]` : Task
|
|
|
|
### Sample Payload (for nodes)
|
|
|
|
```json
|
|
{
|
|
"Text": "lab",
|
|
"Context": "nodes"
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
--data @payload.json \
|
|
https://localhost:4646/v1/search/fuzzy
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"Index": 9,
|
|
"KnownLeader": true,
|
|
"LastContact": 0,
|
|
"Matches": {
|
|
"nodes": [
|
|
{
|
|
"ID": "nomad-lab1",
|
|
"Scope": [
|
|
"c48cd39f-dfe1-9cc0-9c62-617d199854be"
|
|
]
|
|
}
|
|
]
|
|
},
|
|
"Truncations": {
|
|
"nodes": false
|
|
}
|
|
}
|
|
```
|
|
|
|
##### Scope (nodes)
|
|
|
|
- `Scope[0]` : Node ID
|
|
|
|
### Sample Payload (for node pools)
|
|
|
|
```json
|
|
{
|
|
"Text": "lab",
|
|
"Context": "node_pools"
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
--data @payload.json \
|
|
https://localhost:4646/v1/search/fuzzy
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"Index": 9,
|
|
"KnownLeader": true,
|
|
"LastContact": 0,
|
|
"Matches": {
|
|
"node_pools": [
|
|
{
|
|
"ID": "dev-lab1",
|
|
"Scope": [
|
|
"dev-lab1"
|
|
]
|
|
}
|
|
]
|
|
},
|
|
"Truncations": {
|
|
"nodes": false
|
|
}
|
|
}
|
|
```
|
|
|
|
##### Scope (node pools)
|
|
|
|
- `Scope[0]` : Node Pool Name
|
|
|
|
### Sample Payload (for allocs)
|
|
|
|
```json
|
|
{
|
|
"Text":"py",
|
|
"Context":"allocs"
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
--data @payload.json \
|
|
https://localhost:4646/v1/search/fuzzy
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"Index": 136,
|
|
"KnownLeader": true,
|
|
"LastContact": 0,
|
|
"Matches": {
|
|
"allocs": [
|
|
{
|
|
"ID": "example-python.my-spy-app[0]",
|
|
"Scope": [
|
|
"default",
|
|
"0fb703d1-ba4d-116f-13aa-27f31f046858"
|
|
]
|
|
}
|
|
]
|
|
},
|
|
"Truncations": {
|
|
"allocs": false
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Scope (allocs)
|
|
|
|
- `Scope[0]` : Namespace
|
|
- `Scope[1]` : Alloc ID
|
|
|
|
|
|
### Sample Payload (for plugins)
|
|
|
|
```json
|
|
{
|
|
"Text": "aws",
|
|
"Context": "plugins"
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
--data @payload.json \
|
|
https://localhost:4646/v1/search/fuzzy
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"Index": 0,
|
|
"KnownLeader": true,
|
|
"LastContact": 0,
|
|
"Matches": {
|
|
"plugins": [
|
|
{
|
|
"ID": "aws-efs0"
|
|
}
|
|
]
|
|
},
|
|
"Truncations": {
|
|
"plugins": false
|
|
}
|
|
}
|
|
```
|
|
|
|
### Sample Payload (for all)
|
|
|
|
```json
|
|
{
|
|
"Index": 260,
|
|
"KnownLeader": true,
|
|
"LastContact": 0,
|
|
"Matches": {
|
|
"services": [
|
|
{
|
|
"ID": "python-logger",
|
|
"Scope": [
|
|
"default",
|
|
"example-python",
|
|
"my-spy-app",
|
|
"my-python-task"
|
|
]
|
|
},
|
|
{
|
|
"ID": "super-spy-service",
|
|
"Scope": [
|
|
"default",
|
|
"example-python",
|
|
"my-spy-app"
|
|
]
|
|
}
|
|
],
|
|
"tasks": [
|
|
{
|
|
"ID": "my-python-task",
|
|
"Scope": [
|
|
"default",
|
|
"example-python",
|
|
"my-spy-app"
|
|
]
|
|
}
|
|
],
|
|
"jobs": [
|
|
{
|
|
"ID": "example-python",
|
|
"Scope": [
|
|
"default"
|
|
]
|
|
}
|
|
],
|
|
"evals": [],
|
|
"scaling_policy": [],
|
|
"groups": [
|
|
{
|
|
"ID": "my-spy-app",
|
|
"Scope": [
|
|
"default",
|
|
"example-python"
|
|
]
|
|
}
|
|
],
|
|
"images": [
|
|
{
|
|
"ID": "python:3",
|
|
"Scope": [
|
|
"default",
|
|
"example-python",
|
|
"my-spy-app",
|
|
"my-python-task"
|
|
]
|
|
}
|
|
],
|
|
"plugins": [
|
|
{
|
|
"ID": "aws-spy-plugin"
|
|
}
|
|
],
|
|
"deployment": [],
|
|
"volumes": [],
|
|
"allocs": [
|
|
{
|
|
"ID": "example-python.my-spy-app[0]",
|
|
"Scope": [
|
|
"default",
|
|
"48608246-4c28-0446-f3d1-c67e3bc650ad"
|
|
]
|
|
}
|
|
]
|
|
},
|
|
"Truncations": {
|
|
"deployment": false,
|
|
"volumes": false,
|
|
"plugins": false,
|
|
"namespaces": false,
|
|
"scaling_policy": false,
|
|
"evals": false,
|
|
"allocs": false,
|
|
"jobs": false,
|
|
"nodes": false
|
|
}
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
--data @payload.json \
|
|
https://localhost:4646/v1/search/fuzzy
|
|
```
|
|
|
|
### Prefix matching when fuzzy searching
|
|
|
|
If the search Context is `all` when fuzzy searching, the object types that are
|
|
identified only with UUIDs are also concurrently prefix-searched. Those types include
|
|
deployments, evals, volumes, and quotas (Enterprise).
|
|
|
|
### Sample Payload (prefix match)
|
|
|
|
```json
|
|
{
|
|
"Text":"cc",
|
|
"Context":"all"
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
--data @payload.json \
|
|
https://localhost:4646/v1/search/fuzzy
|
|
```
|
|
|
|
### Sample Result
|
|
```json
|
|
{
|
|
"Index": 267,
|
|
"KnownLeader": true,
|
|
"LastContact": 0,
|
|
"Matches": {
|
|
"scaling_policy": [],
|
|
"evals": [],
|
|
"deployment": [
|
|
{
|
|
"ID": "cc786388-e071-31ec-5821-b829839f9681"
|
|
}
|
|
],
|
|
"volumes": []
|
|
},
|
|
"Truncations": {
|
|
"deployment": false,
|
|
"volumes": false,
|
|
"plugins": false,
|
|
"namespaces": false,
|
|
"scaling_policy": false,
|
|
"evals": false,
|
|
"allocs": false,
|
|
"jobs": false,
|
|
"nodes": false
|
|
}
|
|
}
|
|
```
|
|
|
|
[search]: /nomad/docs/configuration/search
|