github.com/iqoqo/nomad@v0.11.3-0.20200911112621-d7021c74d101/website/pages/api-docs/quotas.mdx (about)

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