Quota HTTP API

The /quota endpoints are used to query for and interact with quotas.

This feature requires Nomad Enterprise(opens in new tab).

List Quota Specifications

This endpoint lists all quota specifications.

Method	Path	Produces
`GET`	`/v1/quotas`	`application/json`

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`YES`	`quota:read` `namespace:*` if namespace has quota attached

Parameters

prefix (string: "")- Specifies a string to filter quota specifications on based on an index prefix. This is specified as a query string parameter.

Sample Request

$ curl \
    https://localhost:4646/v1/quotas

$ curl \
    https://localhost:4646/v1/quotas?prefix=sha

Sample Response

[
  {
    "CreateIndex": 11,
    "Description": "Limit the shared default namespace",
    "Hash": "uTIBStF55xKqUMGdI23rdP+W+hsvZ2WEfRWU11j7CzQ=",
    "Limits": [
      {
        "Hash": "fTSnZHxUyDQcRT2Q7L3Hlu3vWpwSt0LWu7JVd3neK9k=",
        "Region": "global",
        "RegionLimit": {
          "CPU": 2500,
          "Cores": 0,
          "Devices": [
            {
              "Affinities": null,
              "Constraints": null,
              "Count": 1,
              "Name": "nvidia/gpu/Tesla M60"
            }
          ],
          "DiskMB": 0,
          "IOPS": 0,
          "MemoryMB": 2000,
          "MemoryMaxMB": 2000,
          "NUMA": null,
          "Networks": [
            {
              "CIDR": "",
              "Device": "",
              "DynamicPorts": null,
              "IP": "",
              "MBits": 50,
              "Mode": "",
              "ReservedPorts": null
            }
          ],
          "SecretsMB": 0
        },
        "VariablesLimit": 1000
      }
    ],
    "ModifyIndex": 11,
    "Name": "default-quota"
  }
]

Read Quota Specification

This endpoint reads information about a specific quota specification.

Method	Path	Produces
`GET`	`/v1/quota/:quota`	`application/json`

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`YES`	`quota:read` `namespace:*` if namespace has quota attached

Parameters

:quota (string: <required>)- Specifies the quota specification to query where the identifier is the quota's name.

Sample Request

$ curl \
    https://localhost:4646/v1/quota/shared-quota

Sample Response

{
  "CreateIndex": 11,
  "Description": "Limit the shared default namespace",
  "Hash": "uTIBStF55xKqUMGdI23rdP+W+hsvZ2WEfRWU11j7CzQ=",
  "Limits": [
    {
      "Hash": "fTSnZHxUyDQcRT2Q7L3Hlu3vWpwSt0LWu7JVd3neK9k=",
      "Region": "global",
      "RegionLimit": {
        "CPU": 2500,
        "Cores": 0,
        "Devices": [
          {
            "Affinities": null,
            "Constraints": null,
            "Count": 1,
            "Name": "nvidia/gpu/Tesla M60"
          }
        ],
        "DiskMB": 0,
        "IOPS": 0,
        "MemoryMB": 2000,
        "MemoryMaxMB": 2000,
        "NUMA": null,
        "Networks": [
          {
            "CIDR": "",
            "Device": "",
            "DynamicPorts": null,
            "IP": "",
            "MBits": 50,
            "Mode": "",
            "ReservedPorts": null
          }
        ],
        "SecretsMB": 0
      },
      "VariablesLimit": 1000
    }
  ],
  "ModifyIndex": 11,
  "Name": "default-quota"
}

Create or Update Quota Specification

This endpoint is used to create or update a quota specification.

Method	Path	Produces
`POST`	`/v1/quota/:quota` `/v1/quota`	`application/json`

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`quota:write`

Body

The request body contains a valid, JSON quota specification. View the api package to see the definition of a QuotaSpec object.

Sample Payload

{
  "Name": "default-quota",
  "Description": "Limit the shared default namespace",
  "Limits": [
    {
      "Region": "global",
      "RegionLimit": {
        "CPU": 2500,
        "MemoryMB": 2000,
        "MemoryMaxMB": 2000,
        "Devices": [
          {
            "Name": "nvidia/gpu/Tesla M60",
            "Count": 1
          }
        ],
        "VariablesLimit": 1000
      }
    }
  ]
}

Sample Request

$ curl \
    --request POST \
    --data @spec.json \
    https://localhost:4646/v1/quota/shared-quota

$ curl \
    --request POST \
    --data @spec.json \
    https://localhost:4646/v1/quota

Delete Quota Specification

This endpoint is used to delete a quota specification.

Method	Path	Produces
`DELETE`	`/v1/quota/:quota`	`application/json`

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`quota:write`

Parameters

:quota (string: <required>)- Specifies the quota specification to delete where the identifier is the quota's name.

Sample Request

$ curl \
    --request DELETE \
    https://localhost:4646/v1/quota/shared-quota

List Quota Usages

This endpoint lists all quota usages.

Method	Path	Produces
`GET`	`/v1/quota-usages`	`application/json`

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`YES`	`quota:read` `namespace:*` if namespace has quota attached

Parameters

prefix (string: "")- Specifies a string to filter quota specifications on based on an index prefix. This is specified as a query string parameter.

Sample Request

$ curl \
    https://localhost:4646/v1/quota-usages

$ curl \
    https://localhost:4646/v1/quota-usages?prefix=sha

Sample Response

[
  {
    "Used": {
      "+kpaU440830Btn3/a0VUL4ROJCQyBOE55xwRR8rlFpc=": {
        "Region": "global",
        "RegionLimit": {
          "CPU": 500,
          "Cores": 0,
          "MemoryMB": 256,
          "MemoryMaxMB": 256,
          "DiskMB": 0,
          "IOPS": 0,
          "Networks": [
            {
              "CIDR": "",
              "Device": "",
              "DynamicPorts": null,
              "IP": "",
              "MBits": 50,
              "Mode": "",
              "ReservedPorts": null
            }
          ],
          "Devices": [
            {
              "Name": "nvidia/gpu/Tesla M60",
              "Count": 1,
              "Constraints": null,
              "Affinities": null
            }
          ],
          "NUMA": null,
          "SecretsMB": 0
        },
        "VariablesLimit": 0,
        "Hash": "+kpaU440830Btn3/a0VUL4ROJCQyBOE55xwRR8rlFpc="
      }
    },
    "Name": "default-quota",
    "CreateIndex": 11,
    "ModifyIndex": 38
  }
]

Read Quota Usage

This endpoint reads information about a specific quota usage.

Method	Path	Produces
`GET`	`/v1/quota/usage/:quota`	`application/json`

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`YES`	`quota:read` `namespace:*` if namespace has quota attached

Parameters

:quota (string: <required>)- Specifies the quota specification to query where the identifier is the quota's name.

Sample Request

$ curl \
    https://localhost:4646/v1/quota/usage/shared-quota

Sample Response

{
  "Used": {
    "+kpaU440830Btn3/a0VUL4ROJCQyBOE55xwRR8rlFpc=": {
      "Region": "global",
      "RegionLimit": {
        "CPU": 500,
        "Cores": 0,
        "MemoryMB": 256,
        "MemoryMaxMB": 256,
        "DiskMB": 0,
        "IOPS": 0,
        "Networks": [
          {
            "CIDR": "",
            "Device": "",
            "DynamicPorts": null,
            "IP": "",
            "MBits": 50,
            "Mode": "",
            "ReservedPorts": null
          }
        ],
        "Devices": [
          {
            "Name": "nvidia/gpu/Tesla M60",
            "Count": 1,
            "Constraints": null,
            "Affinities": null
          }
        ],
        "NUMA": null,
        "SecretsMB": 0
      },
      "VariablesLimit": 0,
      "Hash": "+kpaU440830Btn3/a0VUL4ROJCQyBOE55xwRR8rlFpc="
    }
  },
  "Name": "default-quota",
  "CreateIndex": 11,
  "ModifyIndex": 38
}