From 34b81bdee770b084739e4a254a6f0a3568da9727 Mon Sep 17 00:00:00 2001
From: Luke Okraszewski <lukasz.okraszewski@goteleport.com>
Date: Wed, 15 Apr 2026 10:59:20 +0100
Subject: [PATCH] [docs] add agent resource sizing guidance (#62485)

---
 docs/cspell.json                            |  1 +
 docs/pages/reference/deployment/scaling.mdx | 66 +++++++++++++++++++++
 2 files changed, 67 insertions(+)

diff --git a/docs/cspell.json b/docs/cspell.json
index f08b891cca3..1979ca2573e 100644
--- a/docs/cspell.json
+++ b/docs/cspell.json
@@ -723,6 +723,7 @@
     "microservices",
     "minikube",
     "minikube's",
+    "millicores",
     "mkstore",
     "mlock",
     "mlockall",
diff --git a/docs/pages/reference/deployment/scaling.mdx b/docs/pages/reference/deployment/scaling.mdx
index e446f4559ed..3aa52e20596 100644
--- a/docs/pages/reference/deployment/scaling.mdx
+++ b/docs/pages/reference/deployment/scaling.mdx
@@ -156,3 +156,69 @@ your resource usage, and then scaling resources based on measured outcomes.
 
 Note that you are not limited to a single `windows_desktop_service`, and can connect multiple to your cluster in order to
 spread resources out over multiple logical machines.
+
+## Teleport SSH Service resource utilization
+
+The SSH Service resource utilization can vary significantly based on workload, user behavior, and environment. For this reason it is challenging to provide absolute CPU and RAM requirements. This worked example is an illustration of one potential approach in determining the resource limits for a given SSH Service.
+
+There are three primary factors that influence resource utilization by the SSH Service:
+1. User workload.
+1. Number of concurrent sessions.
+1. Number of new sessions per second.
+
+<Admonition
+  type="note"
+  title="Note"
+>
+  The figures listed in this guide are illustrative only using a synthetic workload. Always measure your specific workload in a representative environment before setting production limits.
+</Admonition>
+
+### Long lived sessions
+
+| concurrent sessions | RAM usage (MiB)  |
+| ------------------ | ---------------- |
+| 1                  | 300              |
+| 2                  | 350              |
+| 4                  | 500              |
+| 8                  | 700              |
+| 16                 | 1200             |
+| 32                 | 2200             |
+| 64                 | 4250             |
+| 128                | 8200             |
+
+For a typical agent RAM usage increases linearly with the number of concurrent sessions.
+
+### New session requests
+
+| sessions per second |  CPU peak (millicores) |
+| ------------------ |  -------------------- |
+| 1                  |  200                  |
+| 2                  |  400                  |
+| 4                  |  900                  |
+| 8                  |  1800                 |
+| 16                 |  3800                 |
+| 32                 |  8500                 |
+
+The primary driver of CPU usage by the SSH Service is the burst usage when new sessions are established.
+
+### Estimating resource requirements
+
+To estimate the resource requirements for the SSH Service:
+1. Determine the worst case resource requirements of a typical user workload.
+1. Determine the maximum number of concurrent sessions.
+1. Determine the maximum number of new sessions per second.
+
+Using `tsh bench`, simulate session activity to measure resource usage under expected conditions.
+Use the findings to set resource limits with an added margin (e.g., 20-50%) for safety.
+
+For example to spawn 32 requests per second for 2 minutes against a specific agent:
+```sh
+tsh bench ssh --rate=32 --duration=2m user@node-agent -- ls
+```
+
+Similarly to test 64 concurrent sessions against a single agent:
+```sh
+tsh bench web ssh --max=64 --duration=2m user@node-agent ls
+```
+
+The payload can be customized to represent a typical use case.
\ No newline at end of file