docs: add Resource Quota specification page (hashicorp#24152)

and update some related pages Co-authored-by: Aimee Ukasick <[email protected]> Co-authored-by: Tim Gross <[email protected]>
channable · Oct 10, 2024 · 373aae7 · 373aae7
1 parent 278a2df
commit 373aae7
Show file tree

Hide file tree

Showing 7 changed files with 120 additions and 16 deletions.
diff --git a/website/content/docs/commands/quota/apply.mdx b/website/content/docs/commands/quota/apply.mdx
@@ -7,7 +7,7 @@ description: |
 
 # Command: quota apply
 
-The `quota apply` command is used to create or update quota specifications.
+The `quota apply` command is used to create or update [quota specifications][].
 
 ~> Quota commands are only available with Nomad Enterprise.
 
@@ -39,3 +39,5 @@ Create a new quota specification:
 $ nomad quota apply my-quota.hcl
 Successfully applied quota specification "my-quota"!
 ```
+
+[quota specifications]: /nomad/docs/other-specifications/quota
diff --git a/website/content/docs/commands/quota/init.mdx b/website/content/docs/commands/quota/init.mdx
@@ -7,8 +7,8 @@ description: |
 
 # 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.
+The `quota init` command is used to create an example [quota specification][]
+file that can be used as a starting point to customize further.
 
 ~> Quota commands are only available with Nomad Enterprise.
 
@@ -30,3 +30,5 @@ Create an example quota specification:
 $ nomad quota init
 Example quota specification written to spec.hcl
 ```
+
+[quota specification]: /nomad/docs/other-specifications/quota
diff --git a/website/content/docs/enterprise/index.mdx b/website/content/docs/enterprise/index.mdx
@@ -154,9 +154,10 @@ thorough overview.
 
 Resource Quotas enable an operator to limit resource consumption across teams
 or projects to reduce waste and align budgets. In Nomad Enterprise, 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.
+can define [quota specifications](/nomad/docs/other-specifications/quota)
+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.

diff --git a/website/content/docs/job-specification/resources.mdx b/website/content/docs/job-specification/resources.mdx
@@ -133,7 +133,7 @@ oversubscription support.
 
 Memory oversubscription is opt-in. Nomad operators can enable [Memory
 Oversubscription in the scheduler configuration][api_sched_config]. Enterprise
-customers can use [Resource Quotas][tutorial_quota] to limit the memory
+customers can use [Resource Quotas][quota_spec] to limit the memory
 oversubscription and enable or disable memory oversubscription per [node
 pool][np_sched_config].
 
@@ -157,6 +157,6 @@ resource utilization and considering the following suggestions:
 [docker_cpu]: /nomad/docs/drivers/docker#cpu
 [exec_cpu]: /nomad/docs/drivers/exec#cpu
 [np_sched_config]: /nomad/docs/other-specifications/node-pool#memory_oversubscription_enabled
-[tutorial_quota]: /nomad/tutorials/governance-and-policy/quotas
+[quota_spec]: /nomad/docs/other-specifications/quota
 [numa]: /nomad/docs/job-specification/numa 'Nomad NUMA Job Specification'
 [`secrets/`]: /nomad/docs/runtime/environment#secrets
diff --git a/website/content/docs/other-specifications/index.mdx b/website/content/docs/other-specifications/index.mdx
@@ -6,12 +6,13 @@ description: Learn about other specifications used in Nomad.
 
 # Other Specifications
 
-In addition to [jobs][job_spec] there are other objects that can be specified
-in Nomad.
+In addition to
+[Jobs](/nomad/docs/job-specification),
+there are other objects that can be specified in Nomad:
 
-- [ACL Policy][acl_policy_spec]
-- [Volume][volume_spec]
-
-[job_spec]: /nomad/docs/job-specification
-[acl_policy_spec]: /nomad/docs/other-specifications/acl-policy
-[volume_spec]: /nomad/docs/other-specifications/volume
+- [ACL Policy](/nomad/docs/other-specifications/acl-policy)
+- [Namespace](/nomad/docs/other-specifications/namespace)
+- [Node Pool](/nomad/docs/other-specifications/node-pool)
+- [Quota](/nomad/docs/other-specifications/quota)
+- [Variable](/nomad/docs/other-specifications/variables)
+- [Volume](/nomad/docs/other-specifications/volume)
diff --git a/website/content/docs/other-specifications/quota.mdx b/website/content/docs/other-specifications/quota.mdx
@@ -0,0 +1,94 @@
+---
+layout: docs
+page_title: Resource Quota Specification
+description: Learn about Nomad's Resource Quota specification.
+---
+
+# Resource Quota Specification
+
+<EnterpriseAlert>
+Resource Quotas are only available with Nomad Enterprise.
+</EnterpriseAlert>
+
+[Resource Quotas][] enable you to limit resource consumption across teams or
+projects to reduce waste and align budgets.
+
+You can manage quotas using the Nomad CLI via the [`quota`][] subcommands,
+or with Nomad's [Quota HTTP API][] directly.
+
+You may also follow a [Quotas tutorial][] for more example usage.
+
+## Example quota specification
+
+The CLI command `nomad quota init` generates an example `spec.hcl` file.
+
+```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 {
+    cores      = 0
+    cpu        = 2500
+    memory     = 1000
+    memory_max = 1000
+    device "nvidia/gpu/1080ti" {
+      count = 1
+    }
+  }
+  variables_limit = 1000
+}
+```
+
+## Quota specification parameters
+
+- `name` `(string)` - The name of the Quota. Nomad uses `name` to connect the
+quota a [`Namespace`][].
+- `description` `(string: <optional>)` - A human-readable description.
+- `limit` <code>([QuotaLimit](#limit-parameters))</code> - The resource limit
+in a Nomad region.
+
+### `limit` parameters
+
+- `region` `(string)` - The Nomad `region` that the limit applies to.
+- `region_limit` <code>([RegionLimit](#region_limit-parameters))</code> -
+Resources to limit.
+- `variables_limit` `(int: 0)` - Maximum total size of all Nomad
+[`variables`][] in MiB. The default `0` means unlimited, and `-1` means
+variables are fully disabled.
+
+### `region_limit` parameters
+
+Region limits define the limits on cumulative task [`resources`][] blocks for
+allocations in the namespace and region the quota is applied to.
+
+- `cores` `(int: <optional>)` - The limit on total number of CPU cores from all
+`resources.cores` in the namespace. The [CPU concepts][] documentation
+has more details on CPU resources.
+- `cpu` `(int: <optional>)` - The limit on total amount of CPU from all
+`resources.cpu` in the namespace.
+- `memory` `(int: <optional>)` - The limit on total mount of memory in MB from
+all `resources.memory` in the namespace.
+- `memory_max` `(int: <optional>)` - The limit on total mount of hard memory
+limits in MB from all `resources.memory_max` in the namespace.
+- `device` <code>([Device](#device-parameters): nil)</code>
+
+### `device` parameters
+
+The `device` label specifies which device(s) the quota applies to,
+equivalent to the [`device`][] block in a job specification.
+
+- `count` `(int)` - How many of this device may be used.
+
+[Resource Quotas]: /nomad/docs/enterprise#resource-quotas
+[`quota`]: /nomad/docs/commands/quota
+[Quota HTTP API]: /nomad/api-docs/quotas
+[Quotas tutorial]: /nomad/tutorials/governance-and-policy/quotas
+[`Namespace`]: /nomad/docs/other-specifications/namespace
+[`variables`]: /nomad/docs/concepts/variables
+[`resources`]: /nomad/docs/job-specification/resources
+[CPU concepts]: /nomad/docs/concepts/cpu
+[`device`]: /nomad/docs/job-specification/device#device-parameters
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
@@ -1915,6 +1915,10 @@
         "title": "Node Pool",
         "path": "other-specifications/node-pool"
       },
+      {
+        "title": "Resource Quota",
+        "path": "other-specifications/quota"
+      },
       {
         "title": "Variables",
         "path": "other-specifications/variables"