Alex Dadgar
GitHub
commit
fd5be6de76
|
|
@ -13,7 +13,7 @@ type NamespaceInspectCommand struct {
|
|||
|
||||
func (c *NamespaceInspectCommand) Help() string {
|
||||
helpText := `
|
||||
Usage: nomad namespace inspect [options] <quota>
|
||||
Usage: nomad namespace inspect [options] <namespace>
|
||||
|
||||
Inspect is used to view raw information about a particular namespace.
|
||||
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ func (c *QuotaDeleteCommand) Help() string {
|
|||
helpText := `
|
||||
Usage: nomad quota delete [options] <quota>
|
||||
|
||||
Delete is used to remove a quota.
|
||||
Delete is used to delete an existing quota specification.
|
||||
|
||||
General Options:
|
||||
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ func (c *QuotaListCommand) Help() string {
|
|||
helpText := `
|
||||
Usage: nomad quota list [options]
|
||||
|
||||
List is used to list available quotas.
|
||||
List is used to list available quota specifications.
|
||||
|
||||
General Options:
|
||||
|
||||
|
|
@ -26,10 +26,10 @@ General Options:
|
|||
List Options:
|
||||
|
||||
-json
|
||||
Output the namespaces in a JSON format.
|
||||
Output the quota specifications in a JSON format.
|
||||
|
||||
-t
|
||||
Format and display the namespaces using a Go template.
|
||||
Format and display the quota specifications using a Go template.
|
||||
`
|
||||
return strings.TrimSpace(helpText)
|
||||
}
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ func (c *QuotaStatusCommand) Help() string {
|
|||
helpText := `
|
||||
Usage: nomad quota status [options] <quota>
|
||||
|
||||
Status is used to view the status of a particular quota.
|
||||
Status is used to view the status of a particular quota specification.
|
||||
|
||||
General Options:
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,321 @@
|
|||
---
|
||||
layout: api
|
||||
page_title: Quotas - HTTP API
|
||||
sidebar_current: api-quotas
|
||||
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.
|
||||
|
||||
~> **Enterprise Only!** This API endpoint and functionality only exists in
|
||||
Nomad Enterprise. This is not present in the open source version of Nomad.
|
||||
|
||||
## 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/index.html#blocking-queries) and
|
||||
[required ACLs](/api/index.html#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 querystring parameter.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
https://nomad.rocks/v1/quotas
|
||||
```
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
https://nomad.rocks/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,
|
||||
"IOPS": 0,
|
||||
"MemoryMB": 2000,
|
||||
"Networks": null
|
||||
}
|
||||
}
|
||||
],
|
||||
"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/index.html#blocking-queries) and
|
||||
[required ACLs](/api/index.html#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
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
https://nomad.rocks/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,
|
||||
"IOPS": 0,
|
||||
"MemoryMB": 2000,
|
||||
"Networks": null
|
||||
}
|
||||
}
|
||||
],
|
||||
"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/index.html#blocking-queries) and
|
||||
[required ACLs](/api/index.html#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://github.com/hashicorp/nomad/blob/master/api/quota.go#L100-L131).
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```javascript
|
||||
{
|
||||
"Name": "shared-quota",
|
||||
"Description": "Limit the shared default namespace",
|
||||
"Limits": [
|
||||
{
|
||||
"Region": "global",
|
||||
"RegionLimit": {
|
||||
"CPU": 2500,
|
||||
"MemoryMB": 1000
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
--request POST \
|
||||
--data @spec.json \
|
||||
https://nomad.rocks/v1/quota/shared-quota
|
||||
```
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
--request POST \
|
||||
--data @spec.json \
|
||||
https://nomad.rocks/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/index.html#blocking-queries) and
|
||||
[required ACLs](/api/index.html#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
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
--request DELETE \
|
||||
https://nomad.rocks/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/index.html#blocking-queries) and
|
||||
[required ACLs](/api/index.html#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 querystring parameter.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
https://nomad.rocks/v1/quota-usages
|
||||
```
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
https://nomad.rocks/v1/quota-usages?prefix=sha
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"Used": {
|
||||
"NLOoV2WBU8ieJIrYXXx8NRb5C2xU61pVVWRDLEIMxlU=": {
|
||||
"Region": "global",
|
||||
"RegionLimit": {
|
||||
"CPU": 500,
|
||||
"MemoryMB": 256,
|
||||
"DiskMB": 0,
|
||||
"IOPS": 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/index.html#blocking-queries) and
|
||||
[required ACLs](/api/index.html#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
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
https://nomad.rocks/v1/quota/shared-quota
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"Used": {
|
||||
"NLOoV2WBU8ieJIrYXXx8NRb5C2xU61pVVWRDLEIMxlU=": {
|
||||
"Region": "global",
|
||||
"RegionLimit": {
|
||||
"CPU": 500,
|
||||
"MemoryMB": 256,
|
||||
"DiskMB": 0,
|
||||
"IOPS": 0,
|
||||
"Networks": null
|
||||
},
|
||||
"Hash": "NLOoV2WBU8ieJIrYXXx8NRb5C2xU61pVVWRDLEIMxlU="
|
||||
}
|
||||
},
|
||||
"Name": "default",
|
||||
"CreateIndex": 8,
|
||||
"ModifyIndex": 56
|
||||
}
|
||||
```
|
||||
|
|
@ -9,7 +9,8 @@ description: |-
|
|||
# Search HTTP API
|
||||
|
||||
The `/search` endpoint returns matches for a given prefix and context, where a
|
||||
context can be jobs, allocations, evaluations, nodes, or deployments.
|
||||
context can be jobs, allocations, evaluations, nodes, or deployments. When using
|
||||
Nomad Enterprise, the allowed contexts include quotas and namespaces.
|
||||
Additionally, a prefix can be searched for within every context.
|
||||
|
||||
| Method | Path | Produces |
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ layout: "docs"
|
|||
page_title: "Commands: acl"
|
||||
sidebar_current: "docs-commands-acl"
|
||||
description: >
|
||||
The deployment command is used to interact with ACL policies and tokens.
|
||||
The acl command is used to interact with ACL policies and tokens.
|
||||
---
|
||||
|
||||
# Nomad ACL
|
||||
|
|
|
|||
|
|
@ -24,7 +24,7 @@ The `acl policy delete` command requires the policy name as an argument.
|
|||
|
||||
## Examples
|
||||
|
||||
Delete a new ACL Policy:
|
||||
Delete an ACL Policy:
|
||||
|
||||
```
|
||||
$ nomad acl policy delete my-policy
|
||||
|
|
|
|||
|
|
@ -21,8 +21,12 @@ subcommands are available:
|
|||
|
||||
* [`namespace apply`][apply] - Create or update a namespace
|
||||
* [`namespace delete`][delete] - Delete a namespace
|
||||
* [`namespace inspect`][inspect] - Inspect a namespace
|
||||
* [`namespace list`][list] - List available namespaces
|
||||
* [`namespace status`][status] - Display a namespace's status
|
||||
|
||||
[apply]: /docs/commands/namespace/apply.html "Create or update a namespace"
|
||||
[delete]: /docs/commands/namespace/delete.html "Delete a namespace"
|
||||
[inspect]: /docs/commands/namespace/inspect.html "Inspect a namespace"
|
||||
[list]: /docs/commands/namespace/list.html "List available namespaces"
|
||||
[status]: /docs/commands/namespace/status.html "Display a namespace's status"
|
||||
|
|
|
|||
|
|
@ -0,0 +1,42 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: namespace inspect"
|
||||
sidebar_current: "docs-commands-namespace-inspect"
|
||||
description: >
|
||||
The namespace inspect command is used to view raw information about a particular
|
||||
namespace.
|
||||
---
|
||||
|
||||
# Command: namespace inspect
|
||||
|
||||
The `namespace inspect` command is used to view raw information about a particular
|
||||
namespace.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
nomad namespace inspect [options] <namespace_name>
|
||||
```
|
||||
|
||||
## General Options
|
||||
|
||||
<%= partial "docs/commands/_general_options" %>
|
||||
|
||||
## Inspect Options
|
||||
|
||||
* `-t` : Format and display the namespace using a Go template.
|
||||
|
||||
## Examples
|
||||
|
||||
Inspect a namespace:
|
||||
|
||||
```
|
||||
$ nomad namespace inspect default
|
||||
{
|
||||
"CreateIndex": 5,
|
||||
"Description": "Default shared namespace",
|
||||
"ModifyIndex": 38,
|
||||
"Name": "default",
|
||||
"Quota": "shared-default-quota"
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: namespace status"
|
||||
sidebar_current: "docs-commands-namespace-status"
|
||||
description: >
|
||||
The namespace status command is used to view the status of a particular
|
||||
namespace.
|
||||
---
|
||||
|
||||
# Command: namespace status
|
||||
|
||||
The `namespace status` command is used to view the status of a particular
|
||||
namespace.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
nomad namespace status [options] <namespace_name>
|
||||
```
|
||||
|
||||
## General Options
|
||||
|
||||
<%= partial "docs/commands/_general_options" %>
|
||||
|
||||
## Examples
|
||||
|
||||
View the status of a namespace:
|
||||
|
||||
```
|
||||
$ nomad namespace status default
|
||||
Name = default
|
||||
Description = Default shared namespace
|
||||
Quota = shared-default-quota
|
||||
|
||||
Quota Limits
|
||||
Region CPU Usage Memory Usage
|
||||
global 500 / 2500 256 / 2000
|
||||
```
|
||||
|
|
@ -0,0 +1,34 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: quota"
|
||||
sidebar_current: "docs-commands-quota"
|
||||
description: >
|
||||
The quota command is used to interact with quota specifications.
|
||||
---
|
||||
|
||||
# Nomad Quota
|
||||
|
||||
Command: `nomad quota`
|
||||
|
||||
The `quota` command is used to interact with quota specifications.
|
||||
|
||||
## Usage
|
||||
|
||||
Usage: `nomad quota <subcommand> [options]`
|
||||
|
||||
Run `nomad quota <subcommand> -h` for help on that subcommand. The following
|
||||
subcommands are available:
|
||||
|
||||
* [`quota apply`][quotaapply] - Create or update a quota specification
|
||||
* [`quota delete`][quotadelete] - Delete a quota specification
|
||||
* [`quota init`][quotainit] - Create an example quota specification file
|
||||
* [`quota inspect`][quotainspect] - Inspect a quota specification
|
||||
* [`quota list`][quotalist] - List quota specifications
|
||||
* [`quota status`][quotastatus] - Display a quota's status and current usage
|
||||
|
||||
[quotaapply]: /docs/commands/quota/apply.html
|
||||
[quotadelete]: /docs/commands/quota/delete.html
|
||||
[quotainit]: /docs/commands/quota/init.html
|
||||
[quotainspect]: /docs/commands/quota/inspect.html
|
||||
[quotalist]: /docs/commands/quota/list.html
|
||||
[quotastatus]: /docs/commands/quota/status.html
|
||||
|
|
@ -0,0 +1,37 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: quota apply"
|
||||
sidebar_current: "docs-commands-quota-apply"
|
||||
description: >
|
||||
The quota apply command is used to create or update quota specifications.
|
||||
---
|
||||
|
||||
# Command: quota apply
|
||||
|
||||
The `quota apply` command is used to create or update quota specifications.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
nomad quota apply [options] <name> <path>
|
||||
```
|
||||
|
||||
The `quota apply` command requires the path to the specification file. The
|
||||
specification can be read from stdin by setting the path to "-".
|
||||
|
||||
## General Options
|
||||
|
||||
<%= partial "docs/commands/_general_options" %>
|
||||
|
||||
## Apply Options
|
||||
|
||||
* `-json`: Parse the input as a JSON quota specification.
|
||||
|
||||
## Examples
|
||||
|
||||
Create a new quota specification:
|
||||
|
||||
```
|
||||
$ nomad quota apply my-quota.hcl
|
||||
Successfully applied quota specification "my-quota"!
|
||||
```
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: quota delete"
|
||||
sidebar_current: "docs-commands-quota-delete"
|
||||
description: >
|
||||
The quota delete command is used to delete an existing quota specification.
|
||||
---
|
||||
|
||||
# Command: quota delete
|
||||
|
||||
The `quota delete` command is used to delete an existing quota specification.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
nomad quota delete <quota_name>
|
||||
```
|
||||
|
||||
The `quota delete` command requires the quota specification name as an argument.
|
||||
|
||||
## General Options
|
||||
|
||||
<%= partial "docs/commands/_general_options" %>
|
||||
|
||||
## Examples
|
||||
|
||||
Delete a quota specification:
|
||||
|
||||
```
|
||||
$ nomad quota delete my-quota
|
||||
Successfully deleted quota "my-quota"!
|
||||
```
|
||||
|
|
@ -0,0 +1,31 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: quota init"
|
||||
sidebar_current: "docs-commands-quota-init"
|
||||
description: >
|
||||
Generate an example quota specification.
|
||||
---
|
||||
|
||||
# Command: quota init
|
||||
|
||||
The `quota init` command is used to create an example quota specification file
|
||||
that can be used as a starting point to customize further.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
nomad quota init
|
||||
```
|
||||
|
||||
## Init Options
|
||||
|
||||
* `-json`: Create an example JSON quota specification.
|
||||
|
||||
## Examples
|
||||
|
||||
Create an example quota specification:
|
||||
|
||||
```
|
||||
$ nomad quota init
|
||||
Example quota specification written to spec.hcl
|
||||
```
|
||||
|
|
@ -0,0 +1,77 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: quota inspect"
|
||||
sidebar_current: "docs-commands-quota-inspect"
|
||||
description: >
|
||||
The quota inspect command is used to view raw information about a particular
|
||||
quota specification.
|
||||
---
|
||||
|
||||
# Command: quota inspect
|
||||
|
||||
The `quota inspect` command is used to view raw information about a particular
|
||||
quota.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
nomad quota inspect [options] <quota_name>
|
||||
```
|
||||
|
||||
## General Options
|
||||
|
||||
<%= partial "docs/commands/_general_options" %>
|
||||
|
||||
## Inspect Options
|
||||
|
||||
* `-t` : Format and display the quota using a Go template.
|
||||
|
||||
## Examples
|
||||
|
||||
Inspect a quota specification:
|
||||
|
||||
```
|
||||
$ nomad quota inspect default-quota
|
||||
{
|
||||
"Spec": {
|
||||
"CreateIndex": 8,
|
||||
"Description": "Limit the shared default namespace",
|
||||
"Limits": [
|
||||
{
|
||||
"Hash": "NLOoV2WBU8ieJIrYXXx8NRb5C2xU61pVVWRDLEIMxlU=",
|
||||
"Region": "global",
|
||||
"RegionLimit": {
|
||||
"CPU": 2500,
|
||||
"DiskMB": 0,
|
||||
"IOPS": 0,
|
||||
"MemoryMB": 2000,
|
||||
"Networks": null
|
||||
}
|
||||
}
|
||||
],
|
||||
"ModifyIndex": 56,
|
||||
"Name": "default-quota"
|
||||
},
|
||||
"UsageLookupErrors": {},
|
||||
"Usages": {
|
||||
"global": {
|
||||
"CreateIndex": 8,
|
||||
"ModifyIndex": 56,
|
||||
"Name": "default-quota",
|
||||
"Used": {
|
||||
"NLOoV2WBU8ieJIrYXXx8NRb5C2xU61pVVWRDLEIMxlU=": {
|
||||
"Hash": "NLOoV2WBU8ieJIrYXXx8NRb5C2xU61pVVWRDLEIMxlU=",
|
||||
"Region": "global",
|
||||
"RegionLimit": {
|
||||
"CPU": 500,
|
||||
"DiskMB": 0,
|
||||
"IOPS": 0,
|
||||
"MemoryMB": 256,
|
||||
"Networks": null
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,37 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: quota list"
|
||||
sidebar_current: "docs-commands-quota-list"
|
||||
description: >
|
||||
The quota list command is used to list available quota specifications.
|
||||
---
|
||||
|
||||
# Command: quota list
|
||||
|
||||
The `quota list` command is used to list available quota specifications.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
nomad quota list
|
||||
```
|
||||
|
||||
## General Options
|
||||
|
||||
<%= partial "docs/commands/_general_options" %>
|
||||
|
||||
## List Options
|
||||
|
||||
* `-json`: Output the quota specifications in a JSON format.
|
||||
|
||||
* `-t`: Format and display the quotas specifications using a Go template.
|
||||
|
||||
## Examples
|
||||
|
||||
List all quota specifications:
|
||||
|
||||
```
|
||||
$ nomad quota list
|
||||
Name Description
|
||||
default Limit the shared default namespace
|
||||
```
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: quota status"
|
||||
sidebar_current: "docs-commands-quota-status"
|
||||
description: >
|
||||
The quota status command is used to view the status of a particular quota
|
||||
specification.
|
||||
---
|
||||
|
||||
# Command: quota status
|
||||
|
||||
The `quota status` command is used to view the status of a particular quota
|
||||
specification.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
nomad quota status [options] <quota_name>
|
||||
```
|
||||
|
||||
## General Options
|
||||
|
||||
<%= partial "docs/commands/_general_options" %>
|
||||
|
||||
## Examples
|
||||
|
||||
View the status of a quota specification:
|
||||
|
||||
```
|
||||
$ nomad quota status default-quota
|
||||
Name = default-quota
|
||||
Description = Limit the shared default namespace
|
||||
Limits = 1
|
||||
|
||||
Quota Limits
|
||||
Region CPU Usage Memory Usage
|
||||
global 500 / 2500 256 / 2000
|
||||
```
|
||||
|
|
@ -11,9 +11,9 @@ description: |-
|
|||
# Nomad Enterprise Resource Quotas
|
||||
|
||||
In [Nomad Enterprise](https://www.hashicorp.com/products/nomad/), operators can
|
||||
define quota specifications and apply them to namespaces. When a quota is
|
||||
attached to a namespace, the jobs within the namespace may not consume more
|
||||
resources than the quota specification allows.
|
||||
define [quota specifications](/guides/quotas.html) and apply them to namespaces.
|
||||
When a quota is attached to a namespace, the jobs within the namespace may not
|
||||
consume more resources than the quota specification allows.
|
||||
|
||||
This allows operators to partition a shared cluster and ensure that no single
|
||||
actor can consume the whole resources of the cluster.
|
||||
|
|
|
|||
|
|
@ -48,6 +48,7 @@ The following table summarizes the ACL Rules that are available for constructing
|
|||
| [agent](#agent-rules) | Utility operations in the Agent API |
|
||||
| [node](#node-rules) | Node-level catalog operations |
|
||||
| [operator](#operator-rules) | Cluster-level operations in the Operator API |
|
||||
| [quota](#quota-rules) | Quota specification related operations |
|
||||
|
||||
Constructing rules from these policies is covered in detail in the Rule Specification section below.
|
||||
|
||||
|
|
@ -178,6 +179,10 @@ agent {
|
|||
node {
|
||||
policy = "read"
|
||||
}
|
||||
|
||||
quota {
|
||||
policy = "read"
|
||||
}
|
||||
```
|
||||
|
||||
This is equivalent to the following JSON input:
|
||||
|
|
@ -197,6 +202,9 @@ This is equivalent to the following JSON input:
|
|||
},
|
||||
"node": {
|
||||
"policy": "read"
|
||||
},
|
||||
"quota": {
|
||||
"policy": "read"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -284,6 +292,19 @@ operator {
|
|||
|
||||
There's only one operator policy allowed per rule set, and its value is set to one of the policy dispositions. In the example above, the token could be used to query the operator endpoints for diagnostic purposes but not make any changes.
|
||||
|
||||
### Quota Rules
|
||||
|
||||
The `quota` policy controls access to the quota specification operations in the [Quota API](/api/quotas.html), such as quota creation and deletion.
|
||||
Quota rules are specified for all quotas using the `quota` key:
|
||||
|
||||
```
|
||||
agent {
|
||||
policy = "write"
|
||||
}
|
||||
```
|
||||
|
||||
There's only one quota policy allowed per rule set, and its value is set to one of the policy dispositions.
|
||||
|
||||
# Advanced Topics
|
||||
|
||||
### Outages and Mulit-Region Replication
|
||||
|
|
|
|||
|
|
@ -27,10 +27,10 @@ When combined with ACLs, the isolation of namespaces can be enforced, only
|
|||
allowing designated users access to read or modify the jobs and associated
|
||||
objects in a namespace.
|
||||
|
||||
When quotas are applied to a namespace they provide a means to limit resource
|
||||
consumption by the jobs in the namespace. This can prevent a single actor from
|
||||
consuming excessive cluster resources and negatively impacting other teams and
|
||||
applications sharing the cluster.
|
||||
When [resource quotas](/guides/qoutas.html) are applied to a namespace they
|
||||
provide a means to limit resource consumption by the jobs in the namespace. This
|
||||
can prevent a single actor from consuming excessive cluster resources and
|
||||
negatively impacting other teams and applications sharing the cluster.
|
||||
|
||||
## Namespaced Objects
|
||||
|
||||
|
|
@ -39,7 +39,8 @@ jobs, allocations, deployments, and evaluations.
|
|||
|
||||
Nomad does not namespace objects that are shared across multiple namespaces.
|
||||
This includes nodes, [ACL policies](/guides/acl.html), [Sentinel
|
||||
policies](/guides/sentinel-policy.html), and quota specifications.
|
||||
policies](/guides/sentinel-policy.html), and [quota
|
||||
specifications](/guides/quotas.html).
|
||||
|
||||
## Working with Namespaces
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,247 @@
|
|||
---
|
||||
layout: "guides"
|
||||
page_title: "Resource Quotas"
|
||||
sidebar_current: "guides-quotas"
|
||||
description: |-
|
||||
Nomad Enterprise provides support for resource quotas, which allows operators
|
||||
to restrict the aggregate resource usage of namespaces.
|
||||
---
|
||||
|
||||
# Resource Quotas
|
||||
|
||||
Nomad Enterprise provides support for resource quotas, which allows operators to
|
||||
restrict the aggregate resource usage of namespaces.
|
||||
|
||||
~> **Enterprise Only!** This functionality only exists in Nomad Enterprise.
|
||||
This is not present in the open source version of Nomad.
|
||||
|
||||
## Use Case
|
||||
|
||||
When many teams or users are sharing Nomad clusters, there is the concern that a
|
||||
single user could use more than their fair share of resources. Resource quotas
|
||||
provide a mechansim for cluster administrators to restrict the resources that a
|
||||
[namespace](/guides/namespace.html) has access to.
|
||||
|
||||
## Quotas Objects
|
||||
|
||||
Quota specifications are first class objects in Nomad. A quota specification
|
||||
has a unique name, an optional human readable description and a set of quota
|
||||
limits. The quota limits defines the allowed resource usage within a region.
|
||||
|
||||
Quota objects are shareable among namespaces. This allows an operator to define
|
||||
higher level quota specifications, such as a `prod-api` quota, and multiple
|
||||
namespaces can apply the `prod-api` quota specification.
|
||||
|
||||
When a quota specification is attached to a namespace, all resource usage by
|
||||
jobs in the namespaces are accounted toward the quota limits. If the resource is
|
||||
exhausted, allocations with the namespaces will be queued until resources become
|
||||
available by either other jobs finishing or the quota being expanded.
|
||||
|
||||
## Working with Quotas
|
||||
|
||||
For specific details about working with quotas, see the [quotas
|
||||
commands](/docs/commands/quotas.html) and [HTTP API](/api/quotas.html)
|
||||
documentation.
|
||||
|
||||
### Creating quotas:
|
||||
|
||||
Resource quotas can be interacted with using the `nomad quota` subcommand. To
|
||||
get started with creating a quota specification, run `nomad quota init` which
|
||||
produces an example quota specification:
|
||||
|
||||
```
|
||||
$ nomad quota init
|
||||
Example quota specification written to spec.hcl
|
||||
|
||||
$ cat spec.hcl
|
||||
name = "default-quota"
|
||||
description = "Limit the shared default namespace"
|
||||
|
||||
# Create a limit for the global region. Additional limits may
|
||||
# be specified in-order to limit other regions.
|
||||
limit {
|
||||
region = "global"
|
||||
region_limit {
|
||||
cpu = 2500
|
||||
memory = 1000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
A quota specification is composed of one or more resource limits. Each limit
|
||||
applies to a particular Nomad region. Within the limit object, operators can
|
||||
specify the allowed cpu and memory usage.
|
||||
|
||||
To create the particular quota, it is as simple as running:
|
||||
|
||||
```
|
||||
$ nomad quota apply spec.hcl
|
||||
Successfully applied quota specification "default-quota"!
|
||||
|
||||
$ nomad quota list
|
||||
Name Description
|
||||
default-quota Limit the shared default namespace
|
||||
api-prod Production instances of backend API servers
|
||||
api-qa QA instances of backend API servers
|
||||
web-prod Production instances of webservers
|
||||
web-qa QA instances of webservers
|
||||
```
|
||||
|
||||
### Attaching Quotas to Namespaces
|
||||
|
||||
In order for a quota to be enforced, we have to attach the quota specification
|
||||
to a namespace. This can be done using the `nomad namespace apply` command.
|
||||
We could add the quota specification we just created to the `default` namespace
|
||||
as follows:
|
||||
|
||||
```
|
||||
$ nomad namespace apply -quota default-quota default
|
||||
Successfully applied namespace "default"!
|
||||
```
|
||||
|
||||
### Viewing Quotas
|
||||
|
||||
Lets now run a job in the default namespace now that we have attached a quota:
|
||||
|
||||
```
|
||||
$ nomad init
|
||||
Example job file written to example.nomad
|
||||
|
||||
$ nomad run -detach example.nomad
|
||||
Job registration successful
|
||||
Evaluation ID: 985a1df8-0221-b891-5dc1-4d31ad4e2dc3
|
||||
|
||||
$ nomad quota status default-quota
|
||||
Name = default-quota
|
||||
Description = Limit the shared default namespace
|
||||
Limits = 1
|
||||
|
||||
Quota Limits
|
||||
Region CPU Usage Memory Usage
|
||||
global 500 / 2500 256 / 1000
|
||||
```
|
||||
|
||||
We can see the newly created job is accounted against the quota specification
|
||||
since it is being run in a namespace that has attached the quota. Now let us
|
||||
scale up the job from `count = 1` to `count = 4`:
|
||||
|
||||
```
|
||||
# Change count
|
||||
$ nomad run -detach example.nomad
|
||||
Job registration successful
|
||||
Evaluation ID: ce8e1941-0189-b866-3dc4-7cd92dc38a69
|
||||
|
||||
$ nomad status example
|
||||
ID = example
|
||||
Name = example
|
||||
Submit Date = 10/16/17 10:51:32 PDT
|
||||
Type = service
|
||||
Priority = 50
|
||||
Datacenters = dc1
|
||||
Status = running
|
||||
Periodic = false
|
||||
Parameterized = false
|
||||
|
||||
Summary
|
||||
Task Group Queued Starting Running Failed Complete Lost
|
||||
cache 1 0 3 0 0 0
|
||||
|
||||
Placement Failure
|
||||
Task Group "cache":
|
||||
* Quota limit hit "memory exhausted (1024 needed > 1000 limit)"
|
||||
|
||||
Latest Deployment
|
||||
ID = 7cd98a69
|
||||
Status = running
|
||||
Description = Deployment is running
|
||||
|
||||
Deployed
|
||||
Task Group Desired Placed Healthy Unhealthy
|
||||
cache 4 3 0 0
|
||||
|
||||
Allocations
|
||||
ID Node ID Task Group Version Desired Status Created At
|
||||
6d735236 81f72d90 cache 1 run running 10/16/17 10:51:32 PDT
|
||||
ce8e1941 81f72d90 cache 1 run running 10/16/17 10:51:32 PDT
|
||||
9b8e185e 81f72d90 cache 1 run running 10/16/17 10:51:24 PDT
|
||||
```
|
||||
|
||||
Here we can see Nomad created two more allocations but did not place the fourth
|
||||
allocation since that would cause the quota to be oversubscribed on memory.
|
||||
|
||||
### ACLs
|
||||
|
||||
Access to quotas can be restricted using [ACLs](/guides/acl.html). As an
|
||||
example we could create an ACL policy that allows read-only access to quotas.
|
||||
|
||||
```
|
||||
# Allow read only access to quotas.
|
||||
quota {
|
||||
policy = "read"
|
||||
}
|
||||
```
|
||||
|
||||
Creating or modifying quotas should typically be guarded by ACLs such that users
|
||||
can not bypass enforcement by simply increasing or removing the quota
|
||||
specification.
|
||||
|
||||
## Resource Limits
|
||||
|
||||
When specifying resource limits the following enforcement behaviors are defined:
|
||||
|
||||
* `limit < 0`: A limit less than zero disallows any access to the resource.
|
||||
|
||||
* `limit == 0`: A limit of zero allows unlimited access to the resource.
|
||||
|
||||
* `limit > 0`: A limit greater than zero enforces that the consumation is less
|
||||
than or equal to the given limit.
|
||||
|
||||
## Federation
|
||||
|
||||
Nomad makes working with quotas in a federated cluster simple by replicating
|
||||
quota specifications from the [authoratative Nomad
|
||||
region](/docs/agent/configuration/server.html#authoritative_region). This allows
|
||||
operators to interact with a single cluster but create quota specifications that
|
||||
apply to all Nomad clusters.
|
||||
|
||||
As an example, we can create a quota specification that applies to two regions:
|
||||
|
||||
```
|
||||
name = "federated-example"
|
||||
description = "A single quota spec effecting multiple regions"
|
||||
|
||||
# Create a limits for two regions
|
||||
limit {
|
||||
region = "europe"
|
||||
region_limit {
|
||||
cpu = 20000
|
||||
memory = 10000
|
||||
}
|
||||
}
|
||||
|
||||
limit {
|
||||
region = "asia"
|
||||
region_limit {
|
||||
cpu = 10000
|
||||
memory = 5000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If we apply this, and attach it to a namespace with jobs in each region, we can
|
||||
see how the enforcement applies across federated clusters.
|
||||
|
||||
```
|
||||
$ nomad quota apply spec.hcl
|
||||
Successfully applied quota specification "federated-example"!
|
||||
|
||||
$ nomad quota status federated example
|
||||
Name = federated-example
|
||||
Description = A single quota spec effecting multiple regions
|
||||
Limits = 2
|
||||
|
||||
Quota Limits
|
||||
Region CPU Usage Memory Usage
|
||||
asia 2500 / 10000 1000 / 5000
|
||||
europe 8800 / 20000 6000 / 10000
|
||||
```
|
||||
|
|
@ -63,6 +63,10 @@
|
|||
<a href="/api/operator.html">Operator</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("api-quotas") %>>
|
||||
<a href="/api/quotas.html">Quotas</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("api-regions") %>>
|
||||
<a href="/api/regions.html">Regions</a>
|
||||
</li>
|
||||
|
|
|
|||
|
|
@ -293,9 +293,15 @@
|
|||
<li<%= sidebar_current("docs-commands-namespace-delete") %>>
|
||||
<a href="/docs/commands/namespace/delete.html">namespace delete</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-namespace-inspect") %>>
|
||||
<a href="/docs/commands/namespace/inspect.html">namespace inspect</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-namespace-list") %>>
|
||||
<a href="/docs/commands/namespace/list.html">namespace list</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-namespace-status") %>>
|
||||
<a href="/docs/commands/namespace/status.html">namespace status</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-node-drain") %>>
|
||||
|
|
@ -318,6 +324,29 @@
|
|||
<li<%= sidebar_current("docs-commands-plan") %>>
|
||||
<a href="/docs/commands/plan.html">plan</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-quota") %>>
|
||||
<a href="/docs/commands/quota.html">quota</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("docs-commands-quota-apply") %>>
|
||||
<a href="/docs/commands/quota/apply.html">quota apply</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-quota-delete") %>>
|
||||
<a href="/docs/commands/quota/delete.html">quota delete</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-quota-init") %>>
|
||||
<a href="/docs/commands/quota/init.html">quota init</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-quota-inspect") %>>
|
||||
<a href="/docs/commands/quota/inspect.html">quota inspect</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-quota-list") %>>
|
||||
<a href="/docs/commands/quota/list.html">quota list</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-quota-status") %>>
|
||||
<a href="/docs/commands/quota/status.html">quota status</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-run") %>>
|
||||
<a href="/docs/commands/run.html">run</a>
|
||||
</li>
|
||||
|
|
|
|||
|
|
@ -62,6 +62,10 @@
|
|||
<a href="/guides/outage.html">Outage Recovery</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("guides-quotas") %>>
|
||||
<a href="/guides/quotas.html">Resource Quotas</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("guides-securing-nomad") %>>
|
||||
<a href="/guides/securing-nomad.html">Securing Nomad</a>
|
||||
</li>
|
||||
|
|
|
|||
Loading…
Reference in New Issue