diff --git a/command/namespace_list.go b/command/namespace_list.go index 1d916b371..7f199fc23 100644 --- a/command/namespace_list.go +++ b/command/namespace_list.go @@ -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) } diff --git a/command/quota_delete.go b/command/quota_delete.go index 632619ccf..7c6e1fd97 100644 --- a/command/quota_delete.go +++ b/command/quota_delete.go @@ -15,7 +15,7 @@ func (c *QuotaDeleteCommand) Help() string { helpText := ` Usage: nomad quota delete [options] - Delete is used to remove a quota. + Delete is used to delete an existing quota specification. General Options: diff --git a/command/quota_list.go b/command/quota_list.go index 5bdfe12d5..1ec811209 100644 --- a/command/quota_list.go +++ b/command/quota_list.go @@ -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: diff --git a/command/quota_status.go b/command/quota_status.go index b921a746a..a19ba35f9 100644 --- a/command/quota_status.go +++ b/command/quota_status.go @@ -19,7 +19,7 @@ func (c *QuotaStatusCommand) Help() string { helpText := ` Usage: nomad quota status [options] - 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: diff --git a/website/source/api/quotas.html.md b/website/source/api/quotas.html.md new file mode 100644 index 000000000..601f00831 --- /dev/null +++ b/website/source/api/quotas.html.md @@ -0,0 +1,182 @@ +--- +layout: api +page_title: Namespace - HTTP API +sidebar_current: api-namespaces +description: |- + The /namespace endpoints are used to query for and interact with namespaces. +--- + +# Namespace HTTP API + +The `/namespace` endpoints are used to query for and interact with namespaces. + +~> **Enterprise Only!** This API endpoint and functionality only exists in +Nomad Enterprise. This is not present in the open source version of Nomad. + +## List Namespaces + +This endpoint lists all namespaces. + +| Method | Path | Produces | +| ------ | ----------------- | ------------------ | +| `GET` | `/v1/namespaces` | `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` | `namespace:*`
Any capability on the namespace authorizes the endpoint | + +### Parameters + +- `prefix` `(string: "")`- Specifies a string to filter namespaces on based on + an index prefix. This is specified as a querystring parameter. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/namespaces +``` + +```text +$ curl \ + https://nomad.rocks/v1/namespaces?prefix=prod +``` + +### Sample Response + +```json +[ + { + "CreateIndex": 31, + "Description": "Production API Servers", + "ModifyIndex": 31, + "Name": "api-prod" + }, + { + "CreateIndex": 5, + "Description": "Default shared namespace", + "ModifyIndex": 5, + "Name": "default" + } +] +``` + +## Read Namespace + +This endpoint reads information about a specific namespace. + +| Method | Path | Produces | +| ------ | --------------------------- | -------------------------- | +| `GET` | `/v1/namespace/:namespace` | `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` | `namespace:*`
Any capability on the namespace authorizes the endpoint | + +### Parameters + +- `:namespace` `(string: )`- Specifies the namespace to query. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/namespace/api-prod +``` + +### Sample Response + +```json +{ + "CreateIndex": 31, + "Description": "Production API Servers", + "Hash": "N8WvePwqkp6J354eLJMKyhvsFdPELAos0VuBfMoVKoU=", + "ModifyIndex": 31, + "Name": "api-prod" +} +``` + +## Create or Update Namespace + +This endpoint is used to create or update a namespace. + +| Method | Path | Produces | +| ------- | ----------------------------------------------- | -------------------------- | +| `POST` | `/v1/namespace/:namespace`
`/v1/namespace` | `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` | `management` | + +### Parameters + +- `Namespace` `(string: )`- Specifies the namespace to create or + update. + +- `Description` `(string: "")` - Specifies an optional human-readable + description of the namespace. + +### Sample Payload + +```javascript +{ + "Namespace": "api-prod", + "Description": "Production API Servers" +} +``` + +### Sample Request + +```text +$ curl \ + --request POST \ + --data @namespace.json \ + https://nomad.rocks/v1/namespace/api-prod +``` + +```text +$ curl \ + --request POST \ + --data @namespace.json \ + https://nomad.rocks/v1/namespace +``` + +## Delete Namespace + +This endpoint is used to delete a namespace. + +| Method | Path | Produces | +| ------- | -------------------------- | -------------------------- | +| `DELETE` | `/v1/namespace/:namespace` | `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` | `management` | + +### Parameters + +- `:namespace` `(string: )`- Specifies the namespace to delete. + +### Sample Request + +```text +$ curl \ + --request DELETE \ + https://nomad.rocks/v1/namespace/api-prod +``` diff --git a/website/source/docs/commands/acl.html.md.erb b/website/source/docs/commands/acl.html.md.erb index 30c33c047..0e2665ccc 100644 --- a/website/source/docs/commands/acl.html.md.erb +++ b/website/source/docs/commands/acl.html.md.erb @@ -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 diff --git a/website/source/docs/commands/acl/policy-delete.html.md.erb b/website/source/docs/commands/acl/policy-delete.html.md.erb index f7dcb396e..e05c7a57a 100644 --- a/website/source/docs/commands/acl/policy-delete.html.md.erb +++ b/website/source/docs/commands/acl/policy-delete.html.md.erb @@ -24,7 +24,7 @@ The `acl policy delete` command requires the policy name as an argument. ## Examples -Delete a new ACL Policy: +Delete a ACL Policy: ``` $ nomad acl policy delete my-policy diff --git a/website/source/docs/commands/quota.html.md.erb b/website/source/docs/commands/quota.html.md.erb new file mode 100644 index 000000000..52463b1ab --- /dev/null +++ b/website/source/docs/commands/quota.html.md.erb @@ -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 [options]` + +Run `nomad quota -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 diff --git a/website/source/docs/commands/quota/apply.html.md.erb b/website/source/docs/commands/quota/apply.html.md.erb new file mode 100644 index 000000000..af738b25d --- /dev/null +++ b/website/source/docs/commands/quota/apply.html.md.erb @@ -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] +``` + +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"! +``` diff --git a/website/source/docs/commands/quota/delete.html.md.erb b/website/source/docs/commands/quota/delete.html.md.erb new file mode 100644 index 000000000..8f5b13d15 --- /dev/null +++ b/website/source/docs/commands/quota/delete.html.md.erb @@ -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 +``` + +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"! +``` diff --git a/website/source/docs/commands/quota/init.html.md.erb b/website/source/docs/commands/quota/init.html.md.erb new file mode 100644 index 000000000..1f80d2bcc --- /dev/null +++ b/website/source/docs/commands/quota/init.html.md.erb @@ -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 +``` diff --git a/website/source/docs/commands/quota/inspect.html.md.erb b/website/source/docs/commands/quota/inspect.html.md.erb new file mode 100644 index 000000000..529bbb585 --- /dev/null +++ b/website/source/docs/commands/quota/inspect.html.md.erb @@ -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] +``` + +## General Options + +<%= partial "docs/commands/_general_options" %> + +## Inspect Options + +* `-t` : Format and display the job 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 + } + } + } + } + } +} +``` diff --git a/website/source/docs/commands/quota/list.html.md.erb b/website/source/docs/commands/quota/list.html.md.erb new file mode 100644 index 000000000..63365966e --- /dev/null +++ b/website/source/docs/commands/quota/list.html.md.erb @@ -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 +``` diff --git a/website/source/docs/commands/quota/status.html.md.erb b/website/source/docs/commands/quota/status.html.md.erb new file mode 100644 index 000000000..2734e9220 --- /dev/null +++ b/website/source/docs/commands/quota/status.html.md.erb @@ -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] +``` + +## 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 +``` diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index dd9b0ba08..5ab940eb5 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -297,6 +297,29 @@ > plan + > + quota + + > run