From 3ca87532e60c9201231a5122ee80124cf96d2324 Mon Sep 17 00:00:00 2001
From: Michael Quigley <michael@quigley.com>
Date: Tue, 4 Apr 2023 15:25:12 -0400
Subject: [PATCH] configuring limits (#283)

---
 .../metrics-and-limits/configuring-limits.md  | 54 +++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 docs/guides/metrics-and-limits/configuring-limits.md

diff --git a/docs/guides/metrics-and-limits/configuring-limits.md b/docs/guides/metrics-and-limits/configuring-limits.md
new file mode 100644
index 00000000..3d472fc5
--- /dev/null
+++ b/docs/guides/metrics-and-limits/configuring-limits.md
@@ -0,0 +1,54 @@
+# Configuring Limits
+
+The limits facility in `zrok` is responsible for controlling the number of resources in use (environments, shares) and also for ensuring that any single account, environment, or share is held below the configured thresholds.
+
+Take this `zrok` controller configuration stanza as an example:
+
+```yaml
+limits:
+  enforcing:        true
+  cycle:            1m
+  environments:     -1
+  shares:           -1
+  bandwidth:
+    per_account:
+      period:       5m
+      warning:
+        rx:         -1
+        tx:         -1
+        total:      7242880
+      limit:
+        rx:         -1
+        tx:         -1
+        total:      10485760
+    per_environment:
+      period:       5m
+      warning:
+        rx:         -1
+        tx:         -1
+        total:      -1
+      limit:
+        rx:         -1
+        tx:         -1
+        total:      -1
+    per_share:
+      period:       5m
+      warning:
+        rx:         -1
+        tx:         -1
+        total:      -1
+      limit:
+        rx:         -1
+        tx:         -1
+        total:      -1
+```
+
+## The Global Controls
+
+The `enforcing` boolean will globally enable or disable limits for the controller.
+
+The `cycle` value controls how frequently the limits system will look for limited resources to re-enable.
+
+## Resource Counts
+
+The `environments` and `shares` values control the number of environments and shares that are allowed per-account. Any limit value can be set to `-1`, which means _unlimited_.
\ No newline at end of file