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