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 and required 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 used to filter the results. Consider using pagination to reduce resource used to serve the request.

Sample Request

$ nomad operator api '/v1/node/pools'

$ nomad operator api '/v1/node/pools?prefix=prod'

$ nomad operator api -filter 'Meta.env == "production"' '/v1/node/pools?per_page=5'

Sample Response

[
  {
    "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 and required ACLs.

Blocking Queries	ACL Required
`YES`	`node_pool:read`

Parameters

:node_pool (string: <required>)- Specifies the node pool to query.

Sample Request

$ nomad operator api /v1/node/pool/prod-eng

Sample Response

{
  "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` `/v1/node/pool`	`application/json`

The table below shows this endpoint's support for blocking queries and required 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.
BatchQueueConfig (BatchQueueConfig: <optional>) - Specifies the batch job queue for the node pool. Set one of DynamicPriority or Fifo. If omitted, the node pool does not queue batch jobs. You cannot set a batch job queue on the built-in default and all node pools. Refer to the batch_queue parameters for details about each field.
- Fifo (object: null) - Set to an empty object, {}, to use a FIFO queue.
- ConstraintTimeout (int: 0) - How long the queue waits for a job that Nomad cannot place because of its constraints, in nanoseconds. If 0, the queue waits until Nomad places the job or you stop it. Refer to constraint_timeout for details.
- DynamicPriority (object: null) - Configures a dynamic priority queue with the following fields. Duration fields are integers in nanoseconds.
  - CalcInterval (int: <required>) - How often the queue recalculates tenant fairshare and priorities, in nanoseconds.
  - TenantFairshare (object: <required>) - Configures tenants and the weight of each tenant's share of allocated resources.
    - TenantType (string: <required>) - Either namespace or metadata.
    - MetadataKey (string: "") - The job meta key that identifies a tenant. Required when TenantType is metadata.
    - CpuWeight (int: 0) - The weight of the tenant's share of allocated CPU.
    - MemoryWeight (int: 0) - The weight of the tenant's share of allocated memory.
    - ExcludeAllocStatuses (array<string>: []) - The allocation client statuses to exclude from each tenant's allocated resources.
  - Age (object: <optional>) - Configures the weight of job age.
    - Weight (int: 0) - The weight of job age.
    - Max (int: 0) - The job age, in nanoseconds, that receives the full Weight.
  - JobSize (object: <optional>) - Configures the weight of the resources that a job requests.
    - CpuWeight (int: 0) - The weight of requested CPU.
    - CpuMax (int: 0) - The requested CPU, in MHz, that receives none of the CpuWeight.
    - MemoryWeight (int: 0) - The weight of requested memory.
    - MemoryMax (int: 0) - The requested memory, in MB, that receives none of the MemoryWeight.

Sample Payload

{
  "Name": "prod-eng",
  "Description": "Production workloads",
  "Meta": {
    "env": "production",
    "team": "engineering"
  },
  "SchedulerConfiguration": {
    "SchedulerAlgorithm": "spread"
  }
}

This payload creates a node pool with a dynamic priority batch job queue.

{
  "Name": "batch-api",
  "Description": "Batch workloads with a dynamic priority queue",
  "BatchQueueConfig": {
    "DynamicPriority": {
      "CalcInterval": 30000000000,
      "TenantFairshare": {
        "TenantType": "namespace",
        "CpuWeight": 25,
        "MemoryWeight": 25
      },
      "Age": {
        "Weight": 10,
        "Max": 43200000000000
      }
    }
  }
}

Sample Request

$ cat pool.json | nomad operator api /v1/node/pools

$ 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 and required ACLs.

Blocking Queries	ACL Required
`NO`	`management`

Parameters

:node_pool (string: <required>)- Specifies the node pool to delete.

Sample Request

$ 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 and required ACLs.

Blocking Queries	ACL Required
`YES`	`node:read` `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 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

$ nomad operator api /v1/node/pool/prod-eng/nodes

$ nomad operator api /v1/node/pool/prod-eng/nodes?os=true

Sample Response

[
  {
    "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 and required ACLs.

Blocking Queries	ACL Required
`YES`	`namespace:read-job` `node_pool:read`

Parameters

:node_pool (string: <required>)- Specifies the node pool to list jobs.
filter (string: "") - Specifies the expression 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 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

$ nomad operator api /v1/node/pool/prod-eng/jobs

$ nomad operator api /v1/node/pool/prod-eng/jobs?namespace=prod

Sample Response

[
  {
    "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
  }
]