e5ac6464f6
Move the secure variables quota enforcement calls into the state store to ensure quota checks are atomic with quota updates (in the same transaction). Switch to a machine-size int instead of a uint64 for quota tracking. The ENT-side quota spec is described as int, and negative values have a meaning as "not permitted at all". Using the same type for tracking will make it easier to the math around checks, and uint64 is infeasibly large anyways. Add secure vars to quota HTTP API and CLI outputs and API docs.
355 lines
8.6 KiB
Plaintext
355 lines
8.6 KiB
Plaintext
---
|
|
layout: api
|
|
page_title: Quotas - HTTP API
|
|
description: The /quota endpoints are used to query for and interact with quotas.
|
|
---
|
|
|
|
# Quota HTTP API
|
|
|
|
The `/quota` endpoints are used to query for and interact with quotas.
|
|
|
|
<EnterpriseAlert>
|
|
This API endpoint and functionality only exists in Nomad Enterprise. This is
|
|
not present in the open source version of Nomad.
|
|
</EnterpriseAlert>
|
|
|
|
## 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](/api-docs#blocking-queries) and
|
|
[required ACLs](/api-docs#acls).
|
|
|
|
| Blocking Queries | ACL Required |
|
|
| ---------------- | --------------------------------------------------------------- |
|
|
| `YES` | `quota:read`<br />`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
|
|
|
|
```shell-session
|
|
$ curl \
|
|
https://localhost:4646/v1/quotas
|
|
```
|
|
|
|
```shell-session
|
|
$ curl \
|
|
https://localhost:4646/v1/quotas?prefix=sha
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
[
|
|
{
|
|
"CreateIndex": 8,
|
|
"Description": "Limit the shared default namespace",
|
|
"Hash": "SgDCH7L5ZDqNSi2NmJlqdvczt/Q6mjyVwVJC0XjWglQ=",
|
|
"Limits": [
|
|
{
|
|
"Hash": "NLOoV2WBU8ieJIrYXXx8NRb5C2xU61pVVWRDLEIMxlU=",
|
|
"Region": "global",
|
|
"RegionLimit": {
|
|
"CPU": 2500,
|
|
"DiskMB": 0,
|
|
"MemoryMB": 2000,
|
|
"Networks": [
|
|
{
|
|
"CIDR": "",
|
|
"Device": "",
|
|
"DynamicPorts": null,
|
|
"IP": "",
|
|
"MBits": 50,
|
|
"Mode": "",
|
|
"ReservedPorts": null
|
|
}
|
|
]
|
|
},
|
|
"SecureVariablesLimit": 1000
|
|
}
|
|
],
|
|
"ModifyIndex": 56,
|
|
"Name": "shared-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](/api-docs#blocking-queries) and
|
|
[required ACLs](/api-docs#acls).
|
|
|
|
| Blocking Queries | ACL Required |
|
|
| ---------------- | --------------------------------------------------------------- |
|
|
| `YES` | `quota:read`<br />`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
|
|
|
|
```shell-session
|
|
$ curl \
|
|
https://localhost:4646/v1/quota/shared-quota
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"CreateIndex": 8,
|
|
"Description": "Limit the shared default namespace",
|
|
"Hash": "SgDCH7L5ZDqNSi2NmJlqdvczt/Q6mjyVwVJC0XjWglQ=",
|
|
"Limits": [
|
|
{
|
|
"Hash": "NLOoV2WBU8ieJIrYXXx8NRb5C2xU61pVVWRDLEIMxlU=",
|
|
"Region": "global",
|
|
"RegionLimit": {
|
|
"CPU": 2500,
|
|
"DiskMB": 0,
|
|
"MemoryMB": 2000,
|
|
"Networks": [
|
|
{
|
|
"CIDR": "",
|
|
"Device": "",
|
|
"DynamicPorts": null,
|
|
"IP": "",
|
|
"MBits": 50,
|
|
"Mode": "",
|
|
"ReservedPorts": null
|
|
}
|
|
]
|
|
},
|
|
"SecureVariablesLimit": 1000
|
|
}
|
|
],
|
|
"ModifyIndex": 56,
|
|
"Name": "shared-quota"
|
|
}
|
|
```
|
|
|
|
## Create or Update Quota Specification
|
|
|
|
This endpoint is used to create or update a quota specification.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------------------------------- | ------------------ |
|
|
| `POST` | `/v1/quota/:quota` <br /> `/v1/quota` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/api-docs#blocking-queries) and
|
|
[required ACLs](/api-docs#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](https://pkg.go.dev/github.com/hashicorp/nomad/api#QuotaSpec).
|
|
|
|
### Sample Payload
|
|
|
|
```javascript
|
|
{
|
|
"Name": "shared-quota",
|
|
"Description": "Limit the shared default namespace",
|
|
"Limits": [
|
|
{
|
|
"Region": "global",
|
|
"RegionLimit": {
|
|
"CPU": 2500,
|
|
"MemoryMB": 1000,
|
|
"Networks": [
|
|
{
|
|
"Mbits": 50
|
|
}
|
|
]
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
--data @spec.json \
|
|
https://localhost:4646/v1/quota/shared-quota
|
|
```
|
|
|
|
```shell-session
|
|
$ 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](/api-docs#blocking-queries) and
|
|
[required ACLs](/api-docs#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
|
|
|
|
```shell-session
|
|
$ 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](/api-docs#blocking-queries) and
|
|
[required ACLs](/api-docs#acls).
|
|
|
|
| Blocking Queries | ACL Required |
|
|
| ---------------- | --------------------------------------------------------------- |
|
|
| `YES` | `quota:read`<br />`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
|
|
|
|
```shell-session
|
|
$ curl \
|
|
https://localhost:4646/v1/quota-usages
|
|
```
|
|
|
|
```shell-session
|
|
$ curl \
|
|
https://localhost:4646/v1/quota-usages?prefix=sha
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
[
|
|
{
|
|
"Used": {
|
|
"NLOoV2WBU8ieJIrYXXx8NRb5C2xU61pVVWRDLEIMxlU=": {
|
|
"Region": "global",
|
|
"RegionLimit": {
|
|
"CPU": 500,
|
|
"MemoryMB": 256,
|
|
"DiskMB": 0,
|
|
"Networks": null
|
|
},
|
|
"Hash": "NLOoV2WBU8ieJIrYXXx8NRb5C2xU61pVVWRDLEIMxlU="
|
|
}
|
|
},
|
|
"Name": "default",
|
|
"CreateIndex": 8,
|
|
"ModifyIndex": 56
|
|
}
|
|
]
|
|
```
|
|
|
|
## 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](/api-docs#blocking-queries) and
|
|
[required ACLs](/api-docs#acls).
|
|
|
|
| Blocking Queries | ACL Required |
|
|
| ---------------- | --------------------------------------------------------------- |
|
|
| `YES` | `quota:read`<br />`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
|
|
|
|
```shell-session
|
|
$ curl \
|
|
https://localhost:4646/v1/quota/usage/shared-quota
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"Used": {
|
|
"NLOoV2WBU8ieJIrYXXx8NRb5C2xU61pVVWRDLEIMxlU=": {
|
|
"Region": "global",
|
|
"RegionLimit": {
|
|
"CPU": 500,
|
|
"MemoryMB": 256,
|
|
"DiskMB": 0,
|
|
"Networks": [
|
|
{
|
|
"CIDR": "",
|
|
"Device": "",
|
|
"DynamicPorts": null,
|
|
"IP": "",
|
|
"MBits": 50,
|
|
"Mode": "",
|
|
"ReservedPorts": null
|
|
}
|
|
]
|
|
},
|
|
"Hash": "NLOoV2WBU8ieJIrYXXx8NRb5C2xU61pVVWRDLEIMxlU="
|
|
}
|
|
},
|
|
"Name": "default",
|
|
"CreateIndex": 8,
|
|
"ModifyIndex": 56
|
|
}
|
|
```
|