github.com/smintz/nomad@v0.8.3/website/source/api/quotas.html.md (about) 1 --- 2 layout: api 3 page_title: Quotas - HTTP API 4 sidebar_current: api-quotas 5 description: |- 6 The /quota endpoints are used to query for and interact with quotas. 7 --- 8 9 # Quota HTTP API 10 11 The `/quota` endpoints are used to query for and interact with quotas. 12 13 ~> **Enterprise Only!** This API endpoint and functionality only exists in 14 Nomad Enterprise. This is not present in the open source version of Nomad. 15 16 ## List Quota Specifications 17 18 This endpoint lists all quota specifications. 19 20 | Method | Path | Produces | 21 | ------ | ----------------- | ------------------ | 22 | `GET` | `/v1/quotas` | `application/json` | 23 24 The table below shows this endpoint's support for 25 [blocking queries](/api/index.html#blocking-queries) and 26 [required ACLs](/api/index.html#acls). 27 28 | Blocking Queries | ACL Required | 29 | ---------------- | ------------- | 30 | `YES` | `quota:read`<br>`namespace:*` if namespace has quota attached| 31 32 ### Parameters 33 34 - `prefix` `(string: "")`- Specifies a string to filter quota specifications on 35 based on an index prefix. This is specified as a querystring parameter. 36 37 ### Sample Request 38 39 ```text 40 $ curl \ 41 https://localhost:4646/v1/quotas 42 ``` 43 44 ```text 45 $ curl \ 46 https://localhost:4646/v1/quotas?prefix=sha 47 ``` 48 49 ### Sample Response 50 51 ```json 52 [ 53 { 54 "CreateIndex": 8, 55 "Description": "Limit the shared default namespace", 56 "Hash": "SgDCH7L5ZDqNSi2NmJlqdvczt/Q6mjyVwVJC0XjWglQ=", 57 "Limits": [ 58 { 59 "Hash": "NLOoV2WBU8ieJIrYXXx8NRb5C2xU61pVVWRDLEIMxlU=", 60 "Region": "global", 61 "RegionLimit": { 62 "CPU": 2500, 63 "DiskMB": 0, 64 "IOPS": 0, 65 "MemoryMB": 2000, 66 "Networks": null 67 } 68 } 69 ], 70 "ModifyIndex": 56, 71 "Name": "shared-quota" 72 } 73 ] 74 ``` 75 76 ## Read Quota Specification 77 78 This endpoint reads information about a specific quota specification. 79 80 | Method | Path | Produces | 81 | ------ | ------------------- | -------------------------- | 82 | `GET` | `/v1/quota/:quota` | `application/json` | 83 84 The table below shows this endpoint's support for 85 [blocking queries](/api/index.html#blocking-queries) and 86 [required ACLs](/api/index.html#acls). 87 88 | Blocking Queries | ACL Required | 89 | ---------------- | -------------------- | 90 | `YES` | `quota:read`<br>`namespace:*` if namespace has quota attached| 91 92 ### Parameters 93 94 - `:quota` `(string: <required>)`- Specifies the quota specification to query 95 where the identifier is the quota's name. 96 97 ### Sample Request 98 99 ```text 100 $ curl \ 101 https://localhost:4646/v1/quota/shared-quota 102 ``` 103 104 ### Sample Response 105 106 ```json 107 { 108 "CreateIndex": 8, 109 "Description": "Limit the shared default namespace", 110 "Hash": "SgDCH7L5ZDqNSi2NmJlqdvczt/Q6mjyVwVJC0XjWglQ=", 111 "Limits": [ 112 { 113 "Hash": "NLOoV2WBU8ieJIrYXXx8NRb5C2xU61pVVWRDLEIMxlU=", 114 "Region": "global", 115 "RegionLimit": { 116 "CPU": 2500, 117 "DiskMB": 0, 118 "IOPS": 0, 119 "MemoryMB": 2000, 120 "Networks": null 121 } 122 } 123 ], 124 "ModifyIndex": 56, 125 "Name": "shared-quota" 126 } 127 ``` 128 129 ## Create or Update Quota Specification 130 131 This endpoint is used to create or update a quota specification. 132 133 | Method | Path | Produces | 134 | ------- | ----------------------------------- | -------------------------- | 135 | `POST` | `/v1/quota/:quota` <br> `/v1/quota` | `application/json` | 136 137 The table below shows this endpoint's support for 138 [blocking queries](/api/index.html#blocking-queries) and 139 [required ACLs](/api/index.html#acls). 140 141 | Blocking Queries | ACL Required | 142 | ---------------- | ------------ | 143 | `NO` | `quota:write` | 144 145 ### Body 146 147 The request body contains a valid, JSON quota specification. View the api 148 package to see the definition of a [`QuotaSpec` 149 object](https://github.com/hashicorp/nomad/blob/master/api/quota.go#L100-L131). 150 151 ### Sample Payload 152 153 ```javascript 154 { 155 "Name": "shared-quota", 156 "Description": "Limit the shared default namespace", 157 "Limits": [ 158 { 159 "Region": "global", 160 "RegionLimit": { 161 "CPU": 2500, 162 "MemoryMB": 1000 163 } 164 } 165 ] 166 } 167 ``` 168 169 ### Sample Request 170 171 ```text 172 $ curl \ 173 --request POST \ 174 --data @spec.json \ 175 https://localhost:4646/v1/quota/shared-quota 176 ``` 177 178 ```text 179 $ curl \ 180 --request POST \ 181 --data @spec.json \ 182 https://localhost:4646/v1/quota 183 ``` 184 185 ## Delete Quota Specification 186 187 This endpoint is used to delete a quota specification. 188 189 | Method | Path | Produces | 190 | ------- | -------------------------- | -------------------------- | 191 | `DELETE` | `/v1/quota/:quota` | `application/json` | 192 193 The table below shows this endpoint's support for 194 [blocking queries](/api/index.html#blocking-queries) and 195 [required ACLs](/api/index.html#acls). 196 197 | Blocking Queries | ACL Required | 198 | ---------------- | ------------ | 199 | `NO` | `quota:write` | 200 201 ### Parameters 202 203 - `:quota` `(string: <required>)`- Specifies the quota specification to delete 204 where the identifier is the quota's name. 205 206 ### Sample Request 207 208 ```text 209 $ curl \ 210 --request DELETE \ 211 https://localhost:4646/v1/quota/shared-quota 212 ``` 213 214 ## List Quota Usages 215 216 This endpoint lists all quota usages. 217 218 | Method | Path | Produces | 219 | ------ | ----------------- | ------------------ | 220 | `GET` | `/v1/quota-usages` | `application/json` | 221 222 The table below shows this endpoint's support for 223 [blocking queries](/api/index.html#blocking-queries) and 224 [required ACLs](/api/index.html#acls). 225 226 | Blocking Queries | ACL Required | 227 | ---------------- | ------------- | 228 | `YES` | `quota:read`<br>`namespace:*` if namespace has quota attached| 229 230 ### Parameters 231 232 - `prefix` `(string: "")`- Specifies a string to filter quota specifications on 233 based on an index prefix. This is specified as a querystring parameter. 234 235 ### Sample Request 236 237 ```text 238 $ curl \ 239 https://localhost:4646/v1/quota-usages 240 ``` 241 242 ```text 243 $ curl \ 244 https://localhost:4646/v1/quota-usages?prefix=sha 245 ``` 246 247 ### Sample Response 248 249 ```json 250 [ 251 { 252 "Used": { 253 "NLOoV2WBU8ieJIrYXXx8NRb5C2xU61pVVWRDLEIMxlU=": { 254 "Region": "global", 255 "RegionLimit": { 256 "CPU": 500, 257 "MemoryMB": 256, 258 "DiskMB": 0, 259 "IOPS": 0, 260 "Networks": null 261 }, 262 "Hash": "NLOoV2WBU8ieJIrYXXx8NRb5C2xU61pVVWRDLEIMxlU=" 263 } 264 }, 265 "Name": "default", 266 "CreateIndex": 8, 267 "ModifyIndex": 56 268 } 269 ] 270 ``` 271 272 ## Read Quota Usage 273 274 This endpoint reads information about a specific quota usage. 275 276 | Method | Path | Produces | 277 | ------ | ------------------- | -------------------------- | 278 | `GET` | `/v1/quota/usage/:quota` | `application/json` | 279 280 The table below shows this endpoint's support for 281 [blocking queries](/api/index.html#blocking-queries) and 282 [required ACLs](/api/index.html#acls). 283 284 | Blocking Queries | ACL Required | 285 | ---------------- | -------------------- | 286 | `YES` | `quota:read`<br>`namespace:*` if namespace has quota attached| 287 288 ### Parameters 289 290 - `:quota` `(string: <required>)`- Specifies the quota specification to query 291 where the identifier is the quota's name. 292 293 ### Sample Request 294 295 ```text 296 $ curl \ 297 https://localhost:4646/v1/quota/shared-quota 298 ``` 299 300 ### Sample Response 301 302 ```json 303 { 304 "Used": { 305 "NLOoV2WBU8ieJIrYXXx8NRb5C2xU61pVVWRDLEIMxlU=": { 306 "Region": "global", 307 "RegionLimit": { 308 "CPU": 500, 309 "MemoryMB": 256, 310 "DiskMB": 0, 311 "IOPS": 0, 312 "Networks": null 313 }, 314 "Hash": "NLOoV2WBU8ieJIrYXXx8NRb5C2xU61pVVWRDLEIMxlU=" 315 } 316 }, 317 "Name": "default", 318 "CreateIndex": 8, 319 "ModifyIndex": 56 320 } 321 ```