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