kemko/nomad
1
0
Fork 0
mirror of https://github.com/kemko/nomad.git synced 2026-01-01 16:05:42 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
b286a8ee9cabb1dced8e6be7c3b60ff869cbca09
nomad/website/content/api-docs/node-pools.mdx

438 lines
12 KiB
Plaintext
Raw Blame History

---
layout: api
page_title: Node Pools - HTTP API
description: The /node/pool endpoints are used to query for and interact with node pools.
---
# Node Pools HTTP API
The `/node/pool` endpoints are used to query for and interact with node pools.
## List Node Pools
This endpoint list all node pools.
| Method | Path | Produces |
| ------ | ---------------- | ------------------ |
| `GET` | `/v1/node/pools` | `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 |
| ---------------- | ----------------- |
| `YES` | `node_pool:read` |
### Parameters
- `prefix` `(string: "")`- Specifies a string to filter node pools based on a
name prefix. This is specified as a query string parameter.
- `next_token` `(string: "")` - This endpoint supports paging. The `next_token`
parameter accepts a string which identifies the next expected node pool. This
value can be obtained from the `X-Nomad-NextToken` header from the previous
response.
- `per_page` `(int: 0)` - Specifies a maximum number of node pools to return
for this request. If omitted, the response is not paginated. The value of the
`X-Nomad-NextToken` header of the last response can be used as the
`next_token` of the next request to fetch additional pages.
- `filter` `(string: "")` - Specifies the [expression](/nomad/api-docs#filtering)
used to filter the results. Consider using pagination to reduce resource used
to serve the request.
### Sample Request
```shell-session
$ nomad operator api '/v1/node/pools'
```
```shell-session
$ nomad operator api '/v1/node/pools?prefix=prod'
```
```shell-session
$ nomad operator api -filter 'Meta.env == "production"' '/v1/node/pools?per_page=5'
```
### Sample Response
```json
[
{
"CreateIndex": 11,
"Description": "Production workloads",
"Meta": {
"env": "production",
"team": "engineering"
},
"ModifyIndex": 11,
"Name": "prod-eng",
"SchedulerConfiguration": {
"SchedulerAlgorithm": "spread"
}
}
]
```
## Read Node Pool
This endpoint queries information about a node pool.
| Method | Path | Produces |
| ------ | -------------------------- | ------------------ |
| `GET` | `/v1/node/pool/:node_pool` | `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 |
| ---------------- | ----------------- |
| `YES` | `node_pool:read` |
### Parameters
- `:node_pool` `(string: <required>)`- Specifies the node pool to query.
### Sample Request
```shell-session
$ nomad operator api /v1/node/pool/prod-eng
```
### Sample Response
```json
{
"CreateIndex": 11,
"Description": "Production workloads",
"Meta": {
"env": "production",
"team": "engineering"
},
"ModifyIndex": 11,
"Name": "prod-eng",
"SchedulerConfiguration": {
"SchedulerAlgorithm": "spread"
}
}
```
## Create or Update Node Pool
This endpoint is used to create or update a node pool.
| Method | Path | Produces |
| ------ | ------------------------------------------------- | ------------------ |
| `POST` | `/v1/node/pool/:node_pool` <br /> `/v1/node/pool` | `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_pool:write` |
### Parameters
- `Name` `(string: <required>)` - Specifies the node pool to create or update.
Must have fewer than 128 characters. Only alphanumeric, `-`, and `_` are
allowed.
- `Description` `(string: "")` - Specifies the optional human-readable
description of the node pool. Must have fewer than 256 characters.
- `Meta` `(object: null)` - Optional object with string keys and values of
metadata to attach to the node pool. Node pool metadata is not used by
Nomad and is intended for use by operators and third party tools.
- `SchedulerConfiguration` `(SchedulerConfiguration: <optional>)` - Specifies
custom configuration applied when scheduling allocations in the node pool.
- `SchedulerAlgorithm` `(string: ""`) - The algorithm used by the scheduler
when scoring nodes. Possible values are `binpack` or `spread`. If not
specified the [global cluster configuration value][api_scheduler_algo] is used.
### Sample Payload
```json
{
"Name": "prod-eng",
"Description": "Production workloads",
"Meta": {
"env": "production",
"team": "engineering"
},
"SchedulerConfiguration": {
"SchedulerAlgorithm": "spread"
}
}
```
### Sample Request
```shell-session
$ cat pool.json | nomad operator api /v1/node/pools
```
```shell-session
$ cat pool.json | nomad operator api /v1/node/pool/prod-eng
```
## Delete Node Pool
This endpoint is used to delete a node pool.
| Method | Path | Produces |
| -------- | -------------------------- | ------------------ |
| `DELETE` | `/v1/node/pool/:node_pool` | `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` | `management` |
### Parameters
- `:node_pool` `(string: <required>)`- Specifies the node pool to delete.
### Sample Request
```shell-session
$ nomad operator api -X DELETE /v1/node/pool/prod-eng
```
## List Node Pool Nodes
This endpoint list the nodes in a node pool.
| Method | Path | Produces |
| ------ | -------------------------------- | ------------------ |
| `GET` | `/v1/node/pool/:node_pool/nodes` | `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 |
| ---------------- | ----------------------------------- |
| `YES` | `node:read` <br /> `node_pool:read` |
### Parameters
- `:node_pool` `(string: <required>)`- Specifies the node pool to list nodes.
- `next_token` `(string: "")` - This endpoint supports paging. The `next_token`
parameter accepts a string which identifies the next expected node. This
value can be obtained from the `X-Nomad-NextToken` header from the previous
response.
- `per_page` `(int: 0)` - Specifies a maximum number of nodes to return for
this request. If omitted, the response is not paginated. The value of the
`X-Nomad-NextToken` header of the last response can be used as the
`next_token` of the next request to fetch additional pages.
- `filter` `(string: "")` - Specifies the [expression](/nomad/api-docs#filtering)
used to filter the results. Consider using pagination to reduce resource used
to serve the request.
- `resources` `(bool: false)` - Specifies whether or not to include the
`NodeResources` and `ReservedResources` fields in the response.
- `os` `(bool: false)` - Specifies whether or not to include special attributes
such as operating system name in the response.
### Sample Request
```shell-session
$ nomad operator api /v1/node/pool/prod-eng/nodes
```
```shell-session
$ nomad operator api /v1/node/pool/prod-eng/nodes?os=true
```
### Sample Response
```json
[
{
"Address": "10.138.0.5",
"Attributes": {
"os.name": "ubuntu"
},
"CreateIndex": 6,
"Datacenter": "dc1",
"Drain": false,
"Drivers": {
"java": {
"Attributes": {
"driver.java.runtime": "OpenJDK Runtime Environment (build 1.8.0_162-8u162-b12-1~deb9u1-b12)",
"driver.java.vm": "OpenJDK 64-Bit Server VM (build 25.162-b12, mixed mode)",
"driver.java.version": "openjdk version \"1.8.0_162"
},
"Detected": true,
"HealthDescription": "",
"Healthy": true,
"UpdateTime": "2018-04-11T23:33:48.781948669Z"
},
"qemu": {
"Attributes": null,
"Detected": false,
"HealthDescription": "",
"Healthy": false,
"UpdateTime": "2018-04-11T23:33:48.7819898Z"
},
"rkt": {
"Attributes": {
"driver.rkt.appc.version": "0.8.11",
"driver.rkt.volumes.enabled": "1",
"driver.rkt.version": "1.29.0"
},
"Detected": true,
"HealthDescription": "Driver rkt is detected: true",
"Healthy": true,
"UpdateTime": "2018-04-11T23:34:48.81079772Z"
},
"docker": {
"Attributes": {
"driver.docker.bridge_ip": "172.17.0.1",
"driver.docker.version": "18.03.0-ce",
"driver.docker.volumes.enabled": "1"
},
"Detected": true,
"HealthDescription": "Driver is available and responsive",
"Healthy": true,
"UpdateTime": "2018-04-11T23:34:48.713720323Z"
},
"exec": {
"Attributes": {},
"Detected": true,
"HealthDescription": "Driver exec is detected: true",
"Healthy": true,
"UpdateTime": "2018-04-11T23:34:48.711026521Z"
},
"raw_exec": {
"Attributes": {},
"Detected": true,
"HealthDescription": "",
"Healthy": true,
"UpdateTime": "2018-04-11T23:33:48.710448534Z"
}
},
"ID": "f7476465-4d6e-c0de-26d0-e383c49be941",
"LastDrain": null,
"ModifyIndex": 2526,
"Name": "nomad-4",
"NodeClass": "",
"NodePool": "prod-eng",
"SchedulingEligibility": "eligible",
"Status": "ready",
"StatusDescription": "",
"Version": "0.8.0-rc1"
}
]
```
# List Node Pool Jobs
This endpoint lists the jobs in a node pool.
| Method | Path | Produces |
| ------ | -------------------------------- | ------------------ |
| `GET` | `/v1/node/pool/:node_pool/jobs` | `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 |
| ---------------- | -------------------------------------------- |
| `YES` | `namespace:read-job` <br /> `node_pool:read` |
### Parameters
- `:node_pool` `(string: <required>)`- Specifies the node pool to list jobs.
- `filter` `(string: "")` - Specifies the [expression](/nomad/api-docs#filtering)
used to filter the results. Consider using pagination to reduce resource used
to serve the request.
- `meta` `(bool: false)` - If set, jobs returned will include a
[meta](/nomad/docs/job-specification/meta) field containing key-value pairs
provided in the job specification's `meta` block.
- `namespace` `(string: "default")` - Specifies the target namespace. Specifying
`*` will return all jobs across all the authorized namespaces.
- `next_token` `(string: "")` - This endpoint supports paging. The `next_token`
parameter accepts a string which identifies the next expected job. This value
can be obtained from the `X-Nomad-NextToken` header from the previous
response.
- `per_page` `(int: 0)` - Specifies a maximum number of jobs to return for this
request. If omitted, the response is not paginated. The value of the
`X-Nomad-NextToken` header of the last response can be used as the
`next_token` of the next request to fetch additional pages.
### Sample Request
```shell-session
$ nomad operator api /v1/node/pool/prod-eng/jobs
```
```shell-session
$ nomad operator api /v1/node/pool/prod-eng/jobs?namespace=prod
```
### Sample Response
```json
[
{
"ID": "example",
"ParentID": "",
"Name": "example",
"Type": "service",
"Priority": 50,
"Status": "pending",
"StatusDescription": "",
"JobSummary": {
"JobID": "example",
"Namespace": "default",
"Summary": {
"cache": {
"Queued": 1,
"Complete": 1,
"Failed": 0,
"Running": 0,
"Starting": 0,
"Lost": 0
}
},
"Children": {
"Pending": 0,
"Running": 0,
"Dead": 0
},
"CreateIndex": 52,
"ModifyIndex": 96
},
"CreateIndex": 52,
"ModifyIndex": 93,
"JobModifyIndex": 52
}
]
```
[api_scheduler_alog]: /nomad/api-docs/operator/scheduler#scheduleralgorithm
Reference in New Issue View Git Blame Copy Permalink